gain.binning package

Submodules

gain.binning.binners module

Binner kinds: how a run-definition entry becomes tracks and values.

Kinds are discovered through the gain.binning.binners entry-point group, so a second kind – a fragment-score binner, an external plugin – registers the way every other gain plugin does, without editing the tool.

class gain.binning.binners.Binner(*args, **kwargs)

Bases: Protocol

What a registered binner kind provides.

static bin_track(track: Track, regions: list[BedRegion], bin_size: int, grr: GenomicResourceRepo) → Generator[ndarray[tuple[Any, ...], dtype[float64]], None, None]

Reduce track to one float64 per grid bin, region by region.

Yields one array per region of regions, in the order given – a bundle is regions binned side by side, never one run of bins across them. Yielding rather than returning them all is what lets the caller save each array as it arrives, so a bundle of any size costs one region of memory.

The bundle is the unit an implementation opens its resource for: one open per call, however many regions the bundle holds.

A generator rather than any iterator, because holding a resource open across the yields makes closing part of the contract: the caller closes what it does not exhaust, and only a generator can be closed.

kind: ClassVar[str]

classmethod parse_entry(label: str, config: dict[str, Any], grr: GenomicResourceRepo) → list[Track]

Resolve one run-definition entry into tracks.

label names the entry in error messages (binners[2]). Raises RunDefinitionError for an entry that cannot be resolved, an entry matching nothing included.

class gain.binning.binners.PositionScoreBinner

Bases: object

Bins position_score resources matched by a resource_query.

ENTRY_KEYS: ClassVar[frozenset[str]] = frozenset({'aggregator', 'none_value_replacement', 'resource_query', 'search_term'})

static bin_track(track: Track, regions: list[BedRegion], bin_size: int, grr: GenomicResourceRepo) → Generator[ndarray[tuple[Any, ...], dtype[float64]], None, None]

Reduce track to one float64 per grid bin, region by region.

Consumes PositionScore.get_score_in_bins() unchanged: it is the semantic reference for the global grid, the boundary split and first-record-wins. A bin no record covers comes back None and is stored as NaN, unless the track’s replacement made it count.

Unconditionally, a chromosome the score never mentions included: that read folds an absent contig as one uncovered run of its own (gain#1211), so a genome-wide run over a track that skips a chromosome needs no case here. This method used to carry one, and with it a second copy of the fold; the read owning both is D14.

The read is folded straight into the array rather than through a list of boxed floats. A suspended generator keeps its locals alive, so an intermediate list would sit beside the array – at roughly four times its size – for as long as the caller takes to save it; fromiter leaves nothing to keep.

kind: ClassVar[str] = 'position_score_binner'

classmethod parse_entry(label: str, config: dict[str, Any], grr: GenomicResourceRepo) → list[Track]

Resolve one entry’s resource_query into tracks.

The query is always a repository search – an exact id is the search that matches one resource – restricted to position scores by the search’s own resource_type filter, and ordered by resource id, so the track order is deterministic whatever the repository yields. That filter needs no index of its own (gain#1212). A search_term is the full-text index’s filter, conjoined with the query (D7), and the one key that needs the index.

exception gain.binning.binners.RunDefinitionError

Bases: ValueError

A run definition that cannot be resolved into a run.

class gain.binning.binners.Track(name: str, resource_id: str, score_id: str, aggregator: str, none_value_replacement: float | None, binner: str)

Bases: object

One column of the output: a score of a resource, reduced one way.

binner names the kind that produces the column; it is how the task graph finds the binner and is not written to the file.

aggregator: str

binner: str

name: str

none_value_replacement: float | None

resource_id: str

score_id: str

gain.binning.binners.check_keys(label: str, config: Any, known: frozenset[str]) → None

Refuse a mapping with keys outside known.

A mistyped key is refused rather than dropped, so what the user wrote never silently changes what the run does.

gain.binning.binners.discover_binner_kinds() → dict[str, type[Binner]]

Map every registered binner kind to its class, by the class’s kind.

gain.binning.binners.numeric_aggregators() → list[str]

The registered aggregators whose result is a number (D11).

Read off each aggregator’s declared output type, so a numeric aggregator added to the registry is accepted here without a list to keep in step; one that declares no output type of its own (mode, which answers in the input’s type) is not among them.

gain.binning.cli module

binning_tool: bin position scores into a fixed genome grid.

One task per (track, bundle of consecutive regions) writes a column chunk per region as a .npy vector in the work directory; one serial writer task assembles the HDF5 file region by region. HDF5 has a single writer, so no task other than the writer touches the file, and a rerun with the same work directory reuses the finished chunks and reruns only the writer.

gain.binning.cli.cli(argv: list[str] | None = None) → None

Entry point of binning_tool.

gain.binning.run_definition module

The binning_tool run definition: parsing and resolution.

class gain.binning.run_definition.RunDefinition(input_reference_genome: str, bin_size: int, regions: list[BedRegion], tracks: list[Track])

Bases: object

A parsed run definition with every query resolved.

bin_size: int

input_reference_genome: str

regions: list[BedRegion]

tracks: list[Track]

gain.binning.run_definition.parse_run_definition(config: dict[str, Any], grr: GenomicResourceRepo, genome: ReferenceGenome) → RunDefinition

Resolve config against grr and genome.

Every key is checked: a mistyped key is an error, never a silently applied default. Raises RunDefinitionError naming the offending entry.

Module contents

Bin position scores into a fixed genome grid (binning_tool).