Entries

An entry is one item of the binners list of a run definition. A fragment_score_binner entry reduces, in each bin, the values of the fragments of the fragment_score resources that its query matches. GAIn provides the spec classes of the package gain.binning to build such an entry in Python. FragmentEntry is the entry itself, and the other spec classes are its blocks. binning_tool reads the same classes from the YAML of a run definition, so a spec class and a YAML key have the same meaning.

Building an entry

A FragmentEntry needs only a resource query. Each other field has a default:

from gain.binning import FragmentEntry

entry = FragmentEntry("frags/*")

The entry above pools every resource that matches frags/* into one set of tracks. Each fragment adds 1 to the bin that holds its start, so each track counts fragments. pool=False makes one job for each resource, and search_term narrows the query with the full-text index of the repository. name gives the base of the names of the tracks, in place of the query.

Two blocks decide what a bin holds:

  • value is what one fragment adds. A ConstantContribution adds a constant number, and its default, 1, counts fragments. A ScoreContribution adds the value of a numeric fragment score.

  • aggregate is an Aggregate. Its mode picks the fragments that reach a bin: fragment_start, fragment_length or coverage_profile. Its aggregator is the fold over the values of a bin, and uncovered_value is what a base without fragments adds.

The entry below sums the count score of the fragments as a coverage profile, and reduces each bin by its mean:

from gain.binning import Aggregate, FragmentEntry, ScoreContribution

entry = FragmentEntry(
    "frags/*",
    name="coverage",
    value=ScoreContribution("count"),
    aggregate=Aggregate(mode="coverage_profile", aggregator="mean"),
)

Aggregate keeps the uncovered_value that the caller gave, so dataclasses.replace() derives the default of a new mode. effective_uncovered_value gives the value that a bin uses. The user page Binning infrastructure describes the modes, the aggregators of each mode and the empty bins.

Grouping the cells of an entry

The group of an entry is the rule that puts each fragment into a group, and each group makes one track. GAIn provides three spec classes for the rule:

  • ConstantGroup puts each fragment into one group with a constant name.

  • CellGrouping finds the group of the cell barcode of a fragment in a cell metadata table.

  • ValueGrouping uses the value of a str fragment score as the group.

When group is None, the labels of the resources decide. A resource with the cell_meta_resource_id label is grouped as by CellGrouping(), and any other resource is the one group all.

The meta of an entry is a MetaSource, and it names the cell metadata table of a cell grouping. The table comes from a data_frame resource (resource_id), from the data_frame resource that a label of each fragment resource names (resource_label) or from a local file (file_name). A MetaSource keeps the file_format that the caller gave, and effective_file_format gives the format that GAIn reads.

The filters of a MetaSource select the rows of the table for each fragment resource. Each MetaFilter is one conjunct: the column of the table equals a literal value, or the value of the label of the fragment resource. A filter on a label selects the own rows of each sample from one shared table, and operand() gives the text that a column must equal for one resource.

The example below builds a pooled entry over the fragment resources frags/*. GAIn groups each cell by the class column of the cell metadata table meta/cells, and the filter selects the rows of the sample of each resource:

from gain.binning import CellGrouping, FragmentEntry, MetaFilter, MetaSource

entry = FragmentEntry(
    "frags/*",
    group=CellGrouping(),
    meta=MetaSource(
        resource_id="meta/cells",
        filters=(MetaFilter("sample_id", label="sample_id"),),
    ),
)

A meta goes only with a cell grouping, or with no group on a resource that the convention groups by its cells. The user page Binning infrastructure describes the single-cell convention and the local metadata files.

Refusals

Each spec class checks its fields when it is built. A malformed field raises RunDefinitionError, and so does a meta that goes with a constant group or a value grouping. A check that needs the repository, for example the type of a score, runs later, when GAIn resolves the entry. The functions of Groups and tracks and binning_tool raise the same error for such a refusal.

API

The names below are exported by the package gain.binning.

FragmentEntry(resource_query, search_term, ...)

A fragment_score_binner entry of a run definition.

ScoreContribution(score_id)

What one fragment adds: its value of a numeric score.

ConstantContribution([value])

What one fragment adds: a constant.

Aggregate([mode, aggregator, uncovered_value])

How a bin reduces the values of its fragments.

Aggregate.effective_uncovered_value

the given value, or the default.

ConstantGroup(name)

One track, with a constant group name.

CellGrouping([cell_score_id, ...])

One track per group of a cell metadata table.

ValueGrouping(score_id)

One track per distinct value of a str fragment score.

MetaSource([resource_id, resource_label, ...])

The cell metadata table of a cell grouping, and its row filter.

MetaSource.effective_file_format

the given one, or the suffix's.

MetaFilter(column[, value, label])

One conjunct of a meta filter: column equals an operand.

MetaFilter.operand(resource)

The text this conjunct's column must equal, for resource.

RunDefinitionError

A run definition that cannot be resolved into a run.

class FragmentEntry(resource_query: str, search_term: str | None = None, pool: bool = True, name: str | None = None, value: ScoreContribution | ConstantContribution = ConstantContribution(value=1), aggregate: Aggregate = Aggregate(mode='fragment_start', aggregator='sum', uncovered_value=<_ModeDefault.MODE: 'mode'>), group: ConstantGroup | CellGrouping | ValueGrouping | None = None, meta: MetaSource | None = None)[source]

A fragment_score_binner entry of a run definition.

Variables:
  • resource_query (str) – The repository search for the fragment_score resources.

  • search_term (str or None) – The filter of the full-text index, conjoined with the query. None, or a blank string, filters nothing.

  • pool (bool) – True merges every match into one job. False makes one job for each resource.

  • name (str or None) – The base of the names of the tracks. None names the tracks by the query, or by the resource ids when not pooled.

  • value (ScoreContribution or ConstantContribution) – What one fragment adds.

  • aggregate (Aggregate) – How a bin reduces the values of its fragments.

  • group (ConstantGroup, CellGrouping, ValueGrouping or None) – How a fragment becomes a group. None lets the labels of the resources decide: a resource with the CELL_META_RESOURCE_ID_LABEL label is grouped as by CellGrouping(), and any other is the one group all.

  • meta (MetaSource or None) – The cell metadata table of a cell grouping. None is the table of the convention.

Raises:

RunDefinitionError – When a field is malformed, or meta goes with a constant group or a value grouping.

class ScoreContribution(score_id: str)[source]

What one fragment adds: its value of a numeric score.

Variables:

score_id (str) – The fragment score whose value each fragment adds. Each resource of the entry must have it as an int or a float score; the resources are checked when the entry is resolved.

Raises:

RunDefinitionError – When score_id is not a non-empty string.

class ConstantContribution(value: float = 1)[source]

What one fragment adds: a constant.

The default, 1, makes the sum of a bin its count of fragments.

Variables:

value (float) – The number each fragment adds.

Raises:

RunDefinitionError – When value is not an int or a float. A bool is not a number here.

class Aggregate(mode: str = 'fragment_start', aggregator: str = 'sum', uncovered_value: float | _ModeDefault | None = _ModeDefault.MODE)[source]

How a bin reduces the values of its fragments.

Variables:
  • mode (str) – Which fragments reach a bin: FRAGMENT_START, FRAGMENT_LENGTH or COVERAGE_PROFILE.

  • aggregator (str) – The fold over the values of a bin. The two length modes take only LENGTH_AGGREGATORS.

  • uncovered_value (float or None) – What an uncovered base adds, with a weight of 1 bp, as a float; None adds nothing. When it is not given, it is 0 in COVERAGE_PROFILE mode and None in the other modes. FRAGMENT_START mode takes none, not even None. The field keeps what the caller gave, or a private marker when the caller gave nothing, so dataclasses.replace() derives the default of the new mode. Read effective_uncovered_value, the value a bin uses.

Raises:

RunDefinitionError – When the mode is unknown, the aggregator is not one that the mode accepts, or uncovered_value is not a finite number or None.

property effective_uncovered_value: float | None

the given value, or the default.

Type:

What an uncovered base adds

class ConstantGroup(name: str)[source]

One track, with a constant group name.

Variables:

name (str) – The group.

Raises:

RunDefinitionError – When name is not a non-empty string.

class CellGrouping(cell_score_id: str = 'cell', cell_meta_column: str = 'barcode', group_meta_column: str = 'class')[source]

One track per group of a cell metadata table.

The meta of the entry names the table. Without a meta, the table is the one of the convention.

Variables:
  • cell_score_id (str) – The fragment score that carries the barcode of a fragment.

  • cell_meta_column (str) – The column of the table that holds the barcode of a cell.

  • group_meta_column (str) – The column of the table that holds the group of a cell.

Raises:

RunDefinitionError – When a field is not a non-empty string.

class ValueGrouping(score_id: str)[source]

One track per distinct value of a str fragment score.

The values are read from the full categorical histogram of the score when the entry is resolved. In a pooled entry whose resources carry the sample_id label, the group of a value is <sample_id>:<value>. Otherwise the group is the value.

Variables:

score_id (str) – The str fragment score whose values are the groups.

Raises:

RunDefinitionError – When score_id is not a non-empty string.

class MetaSource(resource_id: str | None = None, resource_label: str | None = None, file_name: str | None = None, file_format: str | None = None, file_separator: str | None = None, filters: tuple[MetaFilter, ...] = ())[source]

The cell metadata table of a cell grouping, and its row filter.

Give exactly one source: resource_id, resource_label or file_name.

Variables:
  • resource_id (str or None) – A data_frame resource.

  • resource_label (str or None) – A label of each fragment resource. The value of the label is the id of the data_frame resource of that fragment resource.

  • file_name (str or None) – A local table, as given. A relative name is read from the base_dir that resolves the entry, or from the current directory without one.

  • file_format (str or None) – The format of the local table: csv, tsv or excel. When it is not given, the suffix of file_name decides: .tsv is tsv, .xls and .xlsx are excel, and any other suffix is csv. The field keeps what the caller gave, so dataclasses.replace() derives the format of a new file_name. effective_file_format is the format read.

  • file_separator (str or None) – The separator of a csv or tsv table; None is the separator of the format.

  • filters (tuple of MetaFilter) – The conjuncts that select the rows of a fragment resource. No filter selects every row.

Raises:

RunDefinitionError – When the source is not exactly one, a file key goes with a source that is not a file, or a field is malformed.

property effective_file_format: str | None

the given one, or the suffix’s.

None without file_name.

Type:

The format of the local table

class MetaFilter(column: str, value: str | None = None, label: str | None = None)[source]

One conjunct of a meta filter: column equals an operand.

A cell matches by its text: a number matches as its text, and a missing or empty cell has none.

Variables:
  • column (str) – The column of the cell metadata table.

  • value (str or None) – A literal operand.

  • label (str or None) – A label of the fragment resource whose rows are selected. The value of that label is the operand. Give exactly one of value or label.

Raises:

RunDefinitionError – When column or label is not a non-empty string, value is empty or not a string, or not exactly one of value and label is given.

operand(resource: GenomicResource) → str | None[source]

The text this conjunct’s column must equal, for resource.

class RunDefinitionError[source]

A run definition that cannot be resolved into a run.