Fragment scores

Fragment score resources associate values with genomic intervals. Each record describes a fragment with its own start and end coordinates and one or more attributes. Examples include copy-number variants, ATAC fragments, and other region annotations. Unlike position scores, which describe values at genomic positions, fragment scores preserve the extent of each interval. Different fragments may also overlap one another.

GAIn provides the FragmentScore Python class for retrieving and processing these records. FragmentScore inherits the functionality described in Genomic scores and adds methods for querying fragments according to their positions relative to a genomic interval or position. The resource configuration is described in the Fragment scores section of the GRR documentation.

Accessing a fragment score

A FragmentScore object can be built from a resource ID and a repository using build_fragment_score_from_resource_id():

import gain.grr as grr

repo = grr.build_genomic_resource_repository()
score = grr.build_fragment_score_from_resource_id(
    "hg38/scores/my_CNVcollection", repo
)

If you already have a GenomicResource object, use build_fragment_score_from_resource() instead:

resource = repo.get_resource("hg38/scores/my_CNVcollection")
score = grr.build_fragment_score_from_resource(resource)

Both builder functions are available through gain.grr. The generic build_score_from_resource_id() function also returns a FragmentScore object when the specified resource is a fragment score.

Fragment score resources use type: fragment_score in their resource definitions. The older type name cnv_collection is still accepted, but produces a deprecation warning.

Opening and closing a fragment score

A FragmentScore object is initially closed and must be opened before reading its values. As with other genomic scores, call open() explicitly and use a with block to close the object afterward:

with grr.build_fragment_score_from_resource_id(
    "hg38/scores/my_CNVcollection", repo
).open() as score:
    for begin, end, values in score.get_fragment_scores_overlapping_region(
        "chr1", 1_000_000, 2_000_000
    ):
        print(begin, end, values)

This example retrieves fragments that overlap the specified region, reporting each fragment’s start and end coordinates and its associated score values. The opening and closing behavior is described in more detail in Genomic scores.

Retrieving fragment scores

Fragment scores provide three ways to select records according to their genomic locations:

Overlapping a region: retrieve fragments that intersect the query interval, including fragments that extend beyond its boundaries.
Covering a position: retrieve fragments that contain the specified genomic position.
Starting in a region: retrieve fragments whose starting coordinates fall within the query interval, even if they extend beyond it.

Most query methods have plural and singular forms. Plural methods, named get_fragment_scores_..., take a list of score IDs (scores) and return values in the corresponding order for each matching fragment. Singular methods, named get_fragment_score_..., take one score ID (score) and return its value for each matching fragment. The genomic location is supplied through positional arguments, while the remaining arguments are supplied by keyword.

Fragment score query methods
Query	Methods	Result
Overlapping a region	`get_fragment_scores_overlapping_region()`, `get_fragment_score_overlapping_region()`	`(begin, end, values)` for each overlapping fragment
Covering a position	`get_fragment_scores_at_position()`, `get_fragment_score_at_position()`	Fragments containing the specified position
Starting in a region	`get_fragment_scores_starting_in_region()`, `get_fragment_score_starting_in_region()`	Fragments whose starts fall within the region
Aggregated region	`get_fragment_scores_overlapping_region_agg()`, `get_fragment_score_overlapping_region_agg()`	Aggregated values and the number of matching fragments
Binned region	`get_scores_in_bins()`	Aggregated values for fixed-width bins

The distinction between overlapping and starting in a region matters when analyzing adjacent genomic windows. A fragment extending across the boundary of two windows appears in the results of both overlapping-region queries. Counting or summing these results across windows can therefore count the same fragment more than once. With starting_in_region queries, each fragment belongs to the window containing its starting coordinate, so adjacent nonoverlapping windows can divide the fragments without duplication.

Methods that return individual fragments accept an optional score_filter, created using compile_filter(). Overlapping-region reads also accept min_region_overlap_fraction and min_fragment_overlap_fraction to restrict results according to how much a fragment overlaps the query region. The general filtering interface is explained in Genomic scores.

Aggregating fragment scores

When you need a summary of the fragments overlapping a genomic region rather than the individual records, use get_fragment_scores_overlapping_region_agg() or its singular counterpart, get_fragment_score_overlapping_region_agg().

These methods combine the matching score values using the requested aggregators and return a FragmentAggregate object. The result contains an aggregated value for each query and the number of fragments seen. The shared aggregation interface is described in Genomic scores.

Retrieving scores in bins

get_scores_in_bins() divides a query region into fixed-width bins and calculates aggregated scores for each bin. Instead of returning the individual fragments or a single aggregate for the entire region, it provides a series of summaries across the interval. This is useful when displaying or analyzing fragment scores at a chosen genomic resolution.

API

The classes below are defined in the module gain.genomic_resources.genomic_scores. FragmentScore is also exported by gain.grr, as grr.FragmentScore.

The builders build_fragment_score_from_resource_id and build_fragment_score_from_resource build a closed score. They are defined in the module gain.genomic_resources.genomic_scores.builders and are imported from gain.genomic_resources.genomic_scores. They are also exported by gain.grr, as grr.build_fragment_score_from_resource_id and grr.build_fragment_score_from_resource.

`build_fragment_score_from_resource`(resource)	Build a fragment score from a fragment-score resource.
`build_fragment_score_from_resource_id`(...[, grr])	Build a fragment score from the id of a fragment-score resource.
`FragmentScore`(resource)	A genomic score over fragments: intervals that carry attributes.
`FragmentScore.DEFAULT_AGGREGATORS`	The default aggregator for each value type, for a score whose configuration states no `aggregator`: `max` for `float` and `int`, `join(,)` for `str` and none for `bool`.
`FragmentScore.HISTOGRAM_COUNT_UNIT`	`"fragments"`.
`FragmentScore.get_fragment_score_at_position`(...)	Return the fragments that cover a position, with the value of one score.
`FragmentScore.get_fragment_score_overlapping_region`(...)	Yield the fragments that overlap a region, with the value of one score.
`FragmentScore.get_fragment_score_overlapping_region_agg`(...)	Reduce the fragments that overlap a region to one value for one score.
`FragmentScore.get_fragment_score_starting_in_region`(...)	Yield the fragments that begin in a region, with the value of one score.
`FragmentScore.get_fragment_scores_at_position`(...)	Return the fragments that cover a position.
`FragmentScore.get_fragment_scores_overlapping_region`(...)	Yield the fragments that overlap a region.
`FragmentScore.get_fragment_scores_overlapping_region_agg`(...)	Reduce the fragments that overlap a region to one value for each query.
`FragmentScore.get_fragment_scores_starting_in_region`(...)	Yield the fragments that begin in a region.
`FragmentScore.get_schema`()	Return the configuration schema of a fragment score resource.
`FragmentScore.get_scores_in_bins`(chrom, ...)	Reduce the fragments that start in each bin, one column for each query.
`FragmentAggregate`(count, values)	One reduction of the fragments in a region, and the fragment count.

Inherited from GenomicScore. The entries link to the page Genomic scores.

`GenomicScore.chrom_length_source`	Return the source of chromosome lengths in the score's own table.
`GenomicScore.chrom_length_sources`	The sources that the score can answer a length from, best first.
`GenomicScore.close`()	Close the underlying table and mark the score not open.
`GenomicScore.compile_filter`(expression)	Compile a boolean expression into a filter over this score.
`GenomicScore.fetch_records`(chrom, pos_begin, ...)	Yield the records of a region, optionally filtered.
`GenomicScore.fetch_region_segments_scores`(chrom)	Yield `(begin, end, values)` for each record that touches a region.
`GenomicScore.fetch_region_value_arrays`(...)	Fetch a region as column arrays, without a record for each row.
`GenomicScore.get_all_chrom_lengths`([source])	Return the length of every chromosome.
`GenomicScore.get_all_chromosomes`()	Return the chromosome names that the score's table holds.
`GenomicScore.get_chrom_length`(chrom[, source])	Return the length of a chromosome.
`GenomicScore.get_chrom_length_source`(chrom)	Return the source that answers `get_chrom_length()`.
`GenomicScore.get_config`()	Return the configuration of the score.
`GenomicScore.get_score_value_from_record`(...)	Read one score off a record of this score's table.
`GenomicScore.has_chromosome`(chrom)	Report whether the score's table carries a chromosome.
`GenomicScore.is_open`()	Report whether the score is open.
`GenomicScore.open`()	Open the score for reading and return it.
`GenomicScore.supports_region_value_arrays`(scores)	Report whether `fetch_region_value_arrays()` serves these scores.

build_fragment_score_from_resource(resource: GenomicResource) → FragmentScore[source]

Build a fragment score from a fragment-score resource.

Every call builds a new score. You own the score and can close it without any effect on other scores built from the same resource. The score is closed: call open() before the first read.

Parameters:: resource (GenomicResource) – A resource of type fragment_score, or of the older type cnv_collection, which gives a deprecation warning.
Returns:: A new, closed fragment score.
Return type:: FragmentScore
Raises:: ValueError – If the type of the resource is not a fragment score type.

build_fragment_score_from_resource_id(resource_id: str, grr: GenomicResourceRepo | None = None) → FragmentScore[source]

Build a fragment score from the id of a fragment-score resource.

Parameters:

resource_id (str) – The id of a resource of type fragment_score, or of the older type cnv_collection, which gives a deprecation warning.
grr (GenomicResourceRepo | None, default None) – The repository that holds the resource. None builds the default repository.

Returns:

A new, closed fragment score. Call open() before the first read.

Return type:

FragmentScore

Raises:

FileNotFoundError – If the repository has no resource with this id.
ValueError – If the type of the resource is not a fragment score type.

class FragmentScore(resource: GenomicResource)[source]

A genomic score over fragments: intervals that carry attributes.

A fragment keeps its own begin and end, and fragments may overlap. A copy-number variant collection is one use of this kind. The resource type is fragment_score. The older type name cnv_collection is still accepted, with a deprecation warning.

Build a fragment score with build_fragment_score_from_resource_id(). The score is built closed. Call open() before the first read.

The reads come in pairs. The plural form takes a scores list and returns values parallel to it. The singular form takes one score.

Parameters:: resource (GenomicResource) – The resource of type fragment_score or cnv_collection.
Raises:: ValueError – If the type of the resource is not a fragment score type.

DEFAULT_AGGREGATORS: ClassVar[dict[str, str | None]] = {'bool': None, 'float': 'max', 'int': 'max', 'str': 'join(,)'}: The default aggregator for each value type, for a score whose configuration states no aggregator: max for float and int, join(,) for str and none for bool.

HISTOGRAM_COUNT_UNIT: ClassVar[str] = 'fragments'

"fragments".

Type:: The unit that the histograms of this kind count

Return the fragments that cover a position, with the value of one score.

This is the singular form of get_fragment_scores_at_position().

Parameters:

chrom (str) – The contig name.
pos (int) – The position (1-based).
score (str | None, default None) – The score id. None is valid only when the resource defines exactly one score.
score_filter (ScoreFilter | None, default None) – A filter from compile_filter(). None keeps every fragment.

Returns:

One (begin, end, value) tuple for each fragment. The list is empty when no fragment covers the position.

Return type:

Sequence[tuple[int, int, ScoreValue]]

Raises:

ValueError – If score is None and the resource defines more than one score, or for any reason that get_fragment_scores_at_position() lists.

Yield the fragments that overlap a region, with the value of one score.

This is the singular form of get_fragment_scores_overlapping_region(). The same limits apply.

Parameters:

chrom (str) – The contig name.
start (int) – The first position of the region (1-based, inclusive).
end (int) – The last position of the region (1-based, inclusive).
score (str | None, default None) – The score id. None is valid only when the resource defines exactly one score.
score_filter (ScoreFilter | None, default None) – A filter from compile_filter(). None keeps every fragment.
min_region_overlap_fraction (float | None, default None) – The fragment must cover at least this fraction of the region. None sets no threshold.
min_fragment_overlap_fraction (float | None, default None) – At least this fraction of the fragment must fall in the region. None sets no threshold.

Returns:

One (begin, end, value) tuple for each fragment. The value is None when the fragment has no value for the score. The generator is empty when no fragment overlaps the region.

Return type:

Generator[tuple[int, int, ScoreValue], None, None]

Raises:

ValueError – If score is None and the resource defines more than one score, or for any reason that get_fragment_scores_overlapping_region() lists.

get_fragment_score_overlapping_region_agg(chrom: str, start: int, end: int, *, score: str | None = None, aggregator: str | None = None, min_region_overlap_fraction: float | None = None, min_fragment_overlap_fraction: float | None = None, score_filter: ScoreFilter | None = None) → FragmentAggregate[source]

Reduce the fragments that overlap a region to one value for one score.

This is the singular form of get_fragment_scores_overlapping_region_agg(). It returns the same FragmentAggregate, and values has one element.

Parameters:

chrom (str) – The contig name.
start (int) – The first position of the region (1-based, inclusive).
end (int) – The last position of the region (1-based, inclusive).
score (str | None, default None) – The score id. None is valid only when the resource defines exactly one score.
aggregator (str | None, default None) – The aggregator. None uses the default aggregator of the score.
min_region_overlap_fraction (float | None, default None) – The fragment must cover at least this fraction of the region. None sets no threshold.
min_fragment_overlap_fraction (float | None, default None) – At least this fraction of the fragment must fall in the region. None sets no threshold.
score_filter (ScoreFilter | None, default None) – A filter from compile_filter(). None keeps every fragment.

Returns:

The number of fragments that the read saw, and a tuple with the one reduced value.

Return type:

FragmentAggregate

Raises:

ValueError – If score is None and the resource defines more than one score, or for any reason that get_fragment_scores_overlapping_region_agg() lists.

Yield the fragments that begin in a region, with the value of one score.

This is the singular form of get_fragment_scores_starting_in_region(). The same partition and the same limits apply.

Parameters:

chrom (str) – The contig name.
start (int) – The first position of the region (1-based, inclusive).
end (int) – The last position of the region (1-based, inclusive).
score (str | None, default None) – The score id. None is valid only when the resource defines exactly one score.
score_filter (ScoreFilter | None, default None) – A filter from compile_filter(). None keeps every fragment.

Returns:

One (begin, end, value) tuple for each fragment. The generator is empty when no fragment begins in the region.

Return type:

Generator[tuple[int, int, ScoreValue], None, None]

Raises:

ValueError – If score is None and the resource defines more than one score, or for any reason that get_fragment_scores_starting_in_region() lists.

Return the fragments that cover a position.

Each fragment is reported at its full extent, not clipped to the position.

Parameters:

chrom (str) – The contig name.
pos (int) – The position (1-based).
scores (list[str] | None, default None) – The score ids to read. None reads every score of the resource.
score_filter (ScoreFilter | None, default None) – A filter from compile_filter(). None keeps every fragment.

Returns:

One (begin, end, values) tuple for each fragment. The list is empty when no fragment covers the position. You can keep the list across a later read.

Return type:

Sequence[tuple[int, int, tuple[ScoreValue, …]]]

Raises:

ValueError – If pos is below 1, or for any other reason that get_fragment_scores_overlapping_region() lists.

Yield the fragments that overlap a region.

Each fragment is reported at its own extent. The extent is not clipped to the region, also where the fragment runs past it. The fragments come in table order.

The reads check the request when you call them, and read the data later. A closed score, an unknown contig, an unknown score id, an invalid region and an overlap fraction outside the range from 0 to 1 raise before the first next().

A score serves one region read at a time. Starting a second read invalidates a read that you still consume, and a tabix-backed table then answers with the records of the other read and no error. Close a held generator, or call list(...) on it, before the next read.

Parameters:

chrom (str) – The contig name.
start (int) – The first position of the region (1-based, inclusive).
end (int) – The last position of the region (1-based, inclusive).
scores (list[str] | None, default None) – The score ids to read. None reads every score of the resource.
score_filter (ScoreFilter | None, default None) – A filter from compile_filter(). The read drops the fragments that the filter rejects. The filter may name a score that is not in scores. None keeps every fragment.
min_region_overlap_fraction (float | None, default None) – The fragment must cover at least this fraction of the region. None sets no threshold.
min_fragment_overlap_fraction (float | None, default None) – At least this fraction of the fragment must fall in the region. None sets no threshold.

Returns:

One (begin, end, values) tuple for each fragment. values is parallel to scores. A value is None when the fragment has no value for that score. The generator is empty when no fragment overlaps the region.

Return type:

Generator[tuple[int, int, tuple[ScoreValue, …]], None, None]

Raises:

ValueError – If the score is closed, the contig or a score id is unknown, start is below 1, end is before start, or an overlap fraction is outside the range from 0 to 1.

get_fragment_scores_overlapping_region_agg(chrom: str, start: int, end: int, *, queries: Sequence[ScoreAggregationQuery] | None = None, min_region_overlap_fraction: float | None = None, min_fragment_overlap_fraction: float | None = None, score_filter: ScoreFilter | None = None) → FragmentAggregate[source]

Reduce the fragments that overlap a region to one value for each query.

The read selects the fragments as get_fragment_scores_overlapping_region() does. The overlap fractions and score_filter have the same meaning. Each fragment counts once, however long it is. The read folds the fragments as they arrive and does not keep them. A few aggregators keep one entry for each fragment while they run: list, median, concatenate and join. The default aggregator of a str score is join(,), which is one of them.

The count of the result counts fragments. A query with the count aggregator counts the non-null values instead, and gives 0 for an empty region.

Parameters:

chrom (str) – The contig name.
start (int) – The first position of the region (1-based, inclusive).
end (int) – The last position of the region (1-based, inclusive).
queries (Sequence[ScoreAggregationQuery] | None, default None) – The scores to reduce, each with an aggregator. A query with no aggregator uses the default of the score. None reduces every score of the resource with its default aggregator.
min_region_overlap_fraction (float | None, default None) – The fragment must cover at least this fraction of the region. None sets no threshold.
min_fragment_overlap_fraction (float | None, default None) – At least this fraction of the fragment must fall in the region. None sets no threshold.
score_filter (ScoreFilter | None, default None) – A filter from compile_filter(). None keeps every fragment.

Returns:

The number of fragments that the read saw, and one reduced value for each query. When no fragment overlaps the region, count is 0.

Return type:

FragmentAggregate

Raises:

ValueError – If a query names an unknown score or an aggregator that the score does not accept, or for any reason that get_fragment_scores_overlapping_region() lists.

Yield the fragments that begin in a region.

The read yields the fragments whose begin lies in [start, end]. A set of adjacent windows answers each fragment from exactly one window, with no duplicate and no gap. Use this read for chunked and parallel work. get_fragment_scores_overlapping_region() answers a fragment from every window that it reaches into.

Each fragment is reported at its own extent. The limit of one live read per score applies, as for get_fragment_scores_overlapping_region(). The read has no overlap fractions, because a fraction filter could let a fragment fall out of every window.

Parameters:

chrom (str) – The contig name.
start (int) – The first position of the region (1-based, inclusive).
end (int) – The last position of the region (1-based, inclusive).
scores (list[str] | None, default None) – The score ids to read. None reads every score of the resource.
score_filter (ScoreFilter | None, default None) – A filter from compile_filter(). None keeps every fragment.

Returns:

One (begin, end, values) tuple for each fragment. values is parallel to scores. The generator is empty when no fragment begins in the region.

Return type:

Generator[tuple[int, int, tuple[ScoreValue, …]], None, None]

Raises:

ValueError – If start is below 1, end is before start, the score is closed, or the contig or a score id is unknown.

static get_schema() → dict[str, Any][source]

Return the configuration schema of a fragment score resource.

Returns:: The schema of a genomic score, with an aggregator entry added to each score definition.
Return type:: dict[str, Any]

get_scores_in_bins(chrom: str, start: int, end: int, bin_size: int, queries: Sequence[ScoreAggregationQuery]) → ndarray[source]

Reduce the fragments that start in each bin, one column for each query.

The grid is global and starts at position 1. Row i is the bin with index calc_bin_index(bin_size, start) + i. The rows are whole bins. The read does not clip them to the region.

A fragment belongs to the bin that holds its begin, however far it runs. The blocks of two adjacent calls that split on a bin edge stack into the block of their union. The fragments are those that get_fragment_scores_starting_in_region() yields for [start, end].

The fragment count of a bin is the query ScoreAggregationQuery(<score>, "count"). It counts the fragments that start in the bin and have a value for the score. For a score that every fragment carries, it is the number of fragments that start in the bin.

The read answers all queries from one read of the region. It materialises the block, so the limit of one live read applies for the duration of the call only.

Parameters:

chrom (str) – The contig name. A contig that the resource lacks gives the block of empty cells, not an error.
start (int) – The first position of the region (1-based, inclusive).
end (int) – The last position of the region (1-based, inclusive).
bin_size (int) – The width of a bin in positions. It must be at least 1.
queries (Sequence[ScoreAggregationQuery]) – The scores to reduce, each with an aggregator. A query with no aggregator uses the default of the score.

Returns:

A float64 array of shape (n_bins, len(queries)). Column j reduces queries[j]. An empty cell is 0 for count and sum. It is NaN for mean, max, min, median and product.

Return type:

numpy.ndarray

Raises:

ValueError – If start is below 1, end is before start, bin_size is below 1, a score is unknown, or an aggregator is not accepted for the score. The read raises before it reads the first fragment.

class FragmentAggregate(count: int, values: tuple[str | int | float | bool | None, ...])[source]

One reduction of the fragments in a region, and the fragment count.

Variables:

count (int) – The number of fragments that the read saw: the fragments that overlap the region, that pass the overlap fractions and that score_filter keeps. A region with no fragments gives 0. A filter that rejects every fragment gives 0 too.
values (tuple[ScoreValue, ...]) – One reduced value for each query, in the order of the queries. The same score asked twice with two aggregators gives two values. A value is None when its aggregator has nothing to reduce.