Source code for gain.binning.fragment_api

"""The groups and the tracks of a ``fragment_score_binner`` entry.

A notebook user reads what ``binning_tool`` would bin for one entry,
without a run: :func:`cell_groups` gives the group of each cell, and
:func:`fragment_tracks` gives the ``/tracks`` rows of the entry.  Each
function resolves the entry with the code that ``binning_tool`` runs,
so the defaults and the refusals are the same.
"""
from __future__ import annotations

from typing import Any

import pandas as pd

from gain.binning.binners import BinningJob, tracks_frame
from gain.binning.fragment_binner import (
    FragmentBinningJob,
    FragmentScoreBinner,
    job_track_maps,
)
from gain.binning.fragment_grouping import FragmentEntry
from gain.binning.run_definition import name_job_tracks
from gain.genomic_resources.repository import GenomicResourceRepo

__all__ = ["CELL_GROUPS_COLUMNS", "cell_groups", "fragment_tracks"]

#: The columns of :func:`cell_groups`.
CELL_GROUPS_COLUMNS = ("resource_id", "score_value", "group")


def _entry_jobs(
    label: str, entry: FragmentEntry | dict[str, Any],
    repo: GenomicResourceRepo, base_dir: str | None,
) -> list[BinningJob]:
    """Resolve ``entry``, read from a dict when it is one, into its jobs."""
    if not isinstance(entry, FragmentEntry):
        entry = FragmentScoreBinner.entry_from_config(label, entry)
    return FragmentScoreBinner.entry_jobs(
        label, entry, repo, base_dir=base_dir)


def _job_groups(
    job: BinningJob, repo: GenomicResourceRepo,
) -> list[tuple[str, str, str]]:
    """Give the (resource id, key, group) rows of one job, key-sorted."""
    assert isinstance(job, FragmentBinningJob)
    track_maps = job_track_maps(job, repo)
    if track_maps is None:
        return []
    return [
        (resource_id, key, job.tracks[index].group)
        for resource_id, track_map in zip(
            job.resource_ids, track_maps, strict=True)
        for key, index in sorted(track_map.items())
    ]


[docs] def cell_groups( repo: GenomicResourceRepo, entry: FragmentEntry | dict[str, Any], *, base_dir: str | None = None, ) -> pd.DataFrame: """Give the group that ``binning_tool`` puts each key of ``entry`` in. The key of a cell grouping is the barcode of a cell. The key of a value grouping is a value of its score. A fragment with a key that no row lists reaches no track. Each refusal names the entry as ``binners[0]``. Parameters ---------- repo The repository that the query of the entry searches. entry The entry, or the mapping under the ``fragment_score_binner`` key of an entry in a run definition. base_dir The directory that a relative local ``meta`` file is read from. ``None`` is the current directory. Returns ------- pandas.DataFrame The columns of :data:`CELL_GROUPS_COLUMNS`: one row for each key of each resource, in the order of the resources and then of the keys. An entry with a constant group gives no row. Raises ------ RunDefinitionError When ``binning_tool`` refuses the entry. """ jobs = _entry_jobs("binners[0]", entry, repo, base_dir) return pd.DataFrame( [row for job in jobs for row in _job_groups(job, repo)], columns=list(CELL_GROUPS_COLUMNS))
[docs] def fragment_tracks( repo: GenomicResourceRepo, entry: FragmentEntry | dict[str, Any], *, binner_index: int = 0, base_dir: str | None = None, ) -> pd.DataFrame: """Give the ``/tracks`` rows that ``binning_tool`` writes for ``entry``. The function reads ``entry`` alone. A run names the tracks of all its entries together, but the ``/tracks`` rows hold no name, so a sibling entry does not change these rows. The function does not see the other entries of a run: when a sibling entry produces a track with the same name, group and aggregator, ``binning_tool`` refuses the run, and this function still gives the rows. Parameters ---------- repo The repository that the query of the entry searches. entry The entry, or the mapping under the ``fragment_score_binner`` key of an entry in a run definition. binner_index The position of the entry in the ``binners`` list. It is the ``binner_index`` of each row, and each refusal names the entry as ``binners[<binner_index>]``. base_dir The directory that a relative local ``meta`` file is read from. ``None`` is the current directory. Returns ------- pandas.DataFrame The columns of the ``/tracks`` table of the file, one row for each track of the entry, in output order. Raises ------ RunDefinitionError When ``binning_tool`` refuses the entry. """ label = f"binners[{binner_index}]" jobs = _entry_jobs(label, entry, repo, base_dir) return tracks_frame(name_job_tracks([(label, job) for job in jobs]))