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:
valueis what one fragment adds. AConstantContributionadds a constant number, and its default, 1, counts fragments. AScoreContributionadds the value of a numeric fragment score.aggregateis anAggregate. Itsmodepicks the fragments that reach a bin:fragment_start,fragment_lengthorcoverage_profile. Itsaggregatoris the fold over the values of a bin, anduncovered_valueis 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:
ConstantGroupputs each fragment into one group with a constant name.CellGroupingfinds the group of the cell barcode of a fragment in a cell metadata table.ValueGroupinguses the value of astrfragment 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.
|
A |
|
What one fragment adds: its value of a numeric score. |
|
What one fragment adds: a constant. |
|
How a bin reduces the values of its fragments. |
the given value, or the default. |
|
|
One track, with a constant group name. |
|
One track per group of a cell metadata table. |
|
One track per distinct value of a |
|
The cell metadata table of a cell grouping, and its row filter. |
the given one, or the suffix's. |
|
|
One conjunct of a |
|
The text this conjunct's column must equal, for |
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_binnerentry of a run definition.- Variables:
resource_query (str) – The repository search for the
fragment_scoreresources.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) –
Truemerges every match into one job.Falsemakes one job for each resource.name (str or None) – The base of the names of the tracks.
Nonenames 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.
Nonelets the labels of the resources decide: a resource with theCELL_META_RESOURCE_ID_LABELlabel is grouped as byCellGrouping(), and any other is the one groupall.meta (MetaSource or None) – The cell metadata table of a cell grouping.
Noneis the table of the convention.
- Raises:
RunDefinitionError – When a field is malformed, or
metagoes 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
intor afloatscore; the resources are checked when the entry is resolved.- Raises:
RunDefinitionError – When
score_idis not a non-empty string.
- class ConstantContribution(value: float = 1)[source]
What one fragment adds: a constant.
The default, 1, makes the
sumof a bin its count of fragments.- Variables:
value (float) – The number each fragment adds.
- Raises:
RunDefinitionError – When
valueis not anintor afloat. Aboolis 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_LENGTHorCOVERAGE_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;Noneadds nothing. When it is not given, it is 0 inCOVERAGE_PROFILEmode andNonein the other modes.FRAGMENT_STARTmode takes none, not evenNone. The field keeps what the caller gave, or a private marker when the caller gave nothing, sodataclasses.replace()derives the default of the new mode. Readeffective_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_valueis not a finite number orNone.
- 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
nameis 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
metaof the entry names the table. Without ameta, 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
strfragment 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_idlabel, the group of a value is<sample_id>:<value>. Otherwise the group is the value.- Variables:
score_id (str) – The
strfragment score whose values are the groups.- Raises:
RunDefinitionError – When
score_idis 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_labelorfile_name.- Variables:
resource_id (str or None) – A
data_frameresource.resource_label (str or None) – A label of each fragment resource. The value of the label is the id of the
data_frameresource of that fragment resource.file_name (str or None) – A local table, as given. A relative name is read from the
base_dirthat resolves the entry, or from the current directory without one.file_format (str or None) – The format of the local table:
csv,tsvorexcel. When it is not given, the suffix offile_namedecides:.tsvistsv,.xlsand.xlsxareexcel, and any other suffix iscsv. The field keeps what the caller gave, sodataclasses.replace()derives the format of a newfile_name.effective_file_formatis the format read.file_separator (str or None) – The separator of a
csvortsvtable;Noneis 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.
Nonewithoutfile_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
metafilter:columnequals 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
valueorlabel.
- Raises:
RunDefinitionError – When
columnorlabelis not a non-empty string,valueis empty or not a string, or not exactly one ofvalueandlabelis given.
- operand(resource: GenomicResource) str | None[source]
The text this conjunct’s column must equal, for
resource.