Gene scores

Gene score resources associate values with individual genes, identified by their gene symbols. Each resource contains a table with one row per gene and one or more columns of scores, such as gene constraint measures or rankings. GAIn provides the GeneScore Python class for accessing and processing these values.

Unlike position, allele, and fragment scores, gene scores are not associated with genomic coordinates. The GeneScore class is therefore separate from the GenomicScore class described in Genomic scores. However, both provide similar functionality for accessing score definitions and histograms.

Accessing a gene score

A GeneScore object can be built from a resource ID and a repository using build_gene_score_from_resource_id():

import gain.grr as grr

repo = grr.build_genomic_resource_repository()
gene_score = grr.build_gene_score_from_resource_id(
    "gene_properties/gene_scores/LGD", repo
)

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

resource = repo.get_resource("gene_properties/gene_scores/LGD")
gene_score = grr.build_gene_score_from_resource(resource)

Both builder functions are available through gain.grr.

Unlike genomic scores, a GeneScore object does not require open() or close(). The builder loads the entire gene score table into memory, so the resulting object is ready to use immediately.

Retrieving gene scores

get_gene_value() retrieves the value of a specified score for a gene symbol. For example:

print(gene_score.get_gene_value("LGD_rank", "CHD8"))

83.0

The method returns None if the gene is absent from the table, its score value is missing, or the specified score ID is unknown. Other methods for reading gene scores raise ValueError when given an unknown score ID.

Several methods provide access to the score values in different forms:

to_dict() returns a dictionary mapping gene symbols to their score values, excluding genes with missing values.
get_score_df() returns a pandas DataFrame containing the columns gene and the requested score, excluding rows with missing values.
get_min() and get_max() return the minimum and maximum values of a score.
get_values() returns a list of all values for a score.

For example, the first five rows of the gene-score DataFrame can be displayed as follows:

print(gene_score.get_score_df("LGD_rank").head())

    gene  LGD_rank
 LRP1       1.0
TRRAP       3.0
ANKRD11      5.0
ZFHX3       8.0
HERC2      25.0

Finding genes by score

get_genes() retrieves gene symbols whose score values satisfy specified criteria. The score_min and score_max arguments define an inclusive range, meaning genes with scores equal to either boundary are included. If either argument is omitted, the corresponding end of the range is unrestricted.

For example, to retrieve genes with an LGD_rank between 0 and 100:

genes = gene_score.get_genes(
    "LGD_rank", score_min=0, score_max=100
)
print(sorted(genes)[:10])

['ACTG1', 'ANK2', 'ANKHD1', 'ANKRD11', 'ANKRD17', 'ARID1A', 'ASH1L', 'BAHCC1', 'BCL9L', 'BPTF']

The method returns a set of gene symbols. Alternatively, the values argument can be used to select genes whose scores match any of the specified values rather than a numerical range. Genes with missing score values are excluded from the results.

Score definitions and histograms

Each gene score resource defines its scores in the scores: block of the resource definition, as described in Genomic resources and repositories. In Python, each score is represented by a GeneScoreDef object.

The available definitions can be inspected through score_definitions, or an individual definition can be retrieved using get_score_definition():

print(list(gene_score.score_definitions))
score_def = gene_score.get_score_definition("LGD_rank")

For this resource, the first statement returns:

['LGD_score', 'LGD_rank']

Gene scores can also have histograms describing the distribution of their values across genes. The get_score_histogram() method retrieves the histogram associated with a score:

hist = gene_score.get_score_histogram("LGD_rank")

The result may be a numeric, categorical, or null histogram, as described in Histograms. For gene scores, histogram bins count genes rather than genomic positions or alleles.

When a resource defines only one score, the score ID can be omitted from get_score_histogram(), get_histogram_config(), and get_score_range(). These methods then use the resource’s single score automatically.

API

The classes below are defined in the module gain.gene_scores.gene_scores. GeneScore is also exported by gain.grr, as grr.GeneScore. The builders build_gene_score_from_resource_id and build_gene_score_from_resource are defined in the same module. They are also exported by gain.grr, as grr.build_gene_score_from_resource_id and grr.build_gene_score_from_resource.

`build_gene_score_from_resource`(resource)	Build the gene score of a genomic resource.
`build_gene_score_from_resource_id`(resource_id)	Build the gene score of the resource with a given id.
`GeneScore`(resource)	The scores of a gene score resource, one value for each gene.
`GeneScore.HISTOGRAM_COUNT_UNIT`	genes.
`GeneScore.build_score_help`(score_id)	Return the Markdown help text for one score.
`GeneScore.files`	The names of the data files of the resource.
`GeneScore.get_gene_value`(score_id, gene_symbol)	Return the value of a score for one gene.
`GeneScore.get_genes`(score_id[, score_min, ...])	Return the genes whose value of a score matches a condition.
`GeneScore.get_max`(score_id)	Return the largest value of a score.
`GeneScore.get_min`(score_id)	Return the smallest value of a score.
`GeneScore.get_schema`()	Return the schema that validates the resource configuration.
`GeneScore.get_score_df`(score_id)	Return the values of a score as a table.
`GeneScore.get_values`(score_id)	Return the values of a score.
`GeneScore.get_x_scale`(score_id)	Return the scale of the X axis of the histogram of a score.
`GeneScore.get_y_scale`(score_id)	Return the scale of the Y axis of the histogram of a score.
`GeneScore.to_dict`(score_id)	Return the values of a score keyed by gene symbol.
`GeneScore.to_tsv`([score_id])	Return the data of one score as lines of tab-separated text.
`GeneScoreDef`(score_id, value_type, desc, ...)	The definition of one score of a gene score resource.

build_gene_score_from_resource(resource: GenomicResource) → GeneScore[source]

Build the gene score of a genomic resource.

The function reads the data file on the first call for a resource. Later calls with the same resource return the same object.

Parameters:: resource (GenomicResource) – A resource of type gene_score.
Returns:: The gene score of the resource. It is ready to use.
Return type:: GeneScore
Raises:: ValueError – If resource is None or is not of type gene_score.

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

Build the gene score of the resource with a given id.

The function reads the data file on the first call for a resource. Later calls that find the same resource return the same object.

Parameters:

resource_id (str) – The id of a resource of type gene_score in the repository.
grr (GenomicResourceRepo | None) – The repository that resolves resource_id. When it is None, the function builds the default repository with build_genomic_resource_repository().

Returns:

The gene score of the resource. It is ready to use.

Return type:

GeneScore

Raises:

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

class GeneScore(resource: GenomicResource)[source]

The scores of a gene score resource, one value for each gene.

The constructor reads the whole data file into memory. A gene score has no open and no close. Build one with build_gene_score_from_resource_id or build_gene_score_from_resource.

A read with an unknown score id raises ValueError, except get_gene_value.

HISTOGRAM_COUNT_UNIT: ClassVar[str] = 'genes'

genes.

Type:: The noun that the n of a histogram counts

build_score_help(score_id: str) → str[source]

Return the Markdown help text for one score.

The text has the id and the description of the score, the summary of the resource and a link to its info page. When the score has a histogram image, the text embeds the image by its public address.

Parameters:: score_id (str) – The id of a score of this resource.
Returns:: The Markdown text.
Return type:: str
Raises:: ValueError – If the resource does not define score_id.

property files: set[str]: The names of the data files of the resource.

get_gene_value(score_id: str, gene_symbol: str) → float | None[source]

Return the value of a score for one gene.

Parameters:

score_id (str) – The id of a score of this resource.
gene_symbol (str) – The symbol of the gene.

Returns:

The value. None when the gene is not in the data file, when its value is missing, or when score_id is not a score of this resource. The function does not raise ValueError for an unknown score_id.

Return type:

float | None

get_genes(score_id: str, score_min: float | None = None, score_max: float | None = None, values: list[str] | None = None) → set[str][source]

Return the genes whose value of a score matches a condition.

With values the condition is membership in that list. Without it, the condition is a range with both limits included.

Parameters:

score_id (str) – The id of a score of this resource.
score_min (float | None) – The lower limit. None leaves the range open below.
score_max (float | None) – The upper limit. None leaves the range open above.
values (list[str] | None) – The values to select. Each item must convert to a float. When it is given, the function ignores score_min and score_max.

Returns:

The gene symbols that match. Genes without a value never match. The set is empty when no gene matches.

Return type:

set[str]

Raises:

ValueError – If the resource does not define score_id, or if an item of values is not a number.

get_max(score_id: str) → float[source]

Return the largest value of a score.

Parameters:: score_id (str) – The id of a score of this resource.
Returns:: The largest value. Genes without a value do not count. It is nan when no gene has a value.
Return type:: float
Raises:: ValueError – If the resource does not define score_id.

get_min(score_id: str) → float[source]

Return the smallest value of a score.

Parameters:: score_id (str) – The id of a score of this resource.
Returns:: The smallest value. Genes without a value do not count. It is nan when no gene has a value.
Return type:: float
Raises:: ValueError – If the resource does not define score_id.

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

Return the schema that validates the resource configuration.

Returns:: The schema, in the Cerberus format.
Return type:: dict

get_score_df(score_id: str) → DataFrame[source]

Return the values of a score as a table.

Parameters:: score_id (str) – The id of a score of this resource.
Returns:: The columns gene and score_id. The rows without a value are dropped. The table is empty when no gene has a value.
Return type:: pandas.DataFrame
Raises:: ValueError – If the resource does not define score_id.

get_values(score_id: str) → list[Any][source]

Return the values of a score.

Parameters:: score_id (str) – The id of a score of this resource.
Returns:: One value for each gene of the data file, in file order. A numeric score gives floats and a categorical score gives strings. A gene without a value gives nan. The list is empty when the file has no genes.
Return type:: list
Raises:: ValueError – If the resource does not define score_id.

get_x_scale(score_id: str) → str | None[source]

Return the scale of the X axis of the histogram of a score.

Parameters:: score_id (str) – The id of a score of this resource.
Returns:: "log" or "linear". None when the histogram of the score is not a number histogram.
Return type:: str | None
Raises:: ValueError – If the resource does not define score_id.

get_y_scale(score_id: str) → str | None[source]

Return the scale of the Y axis of the histogram of a score.

Parameters:: score_id (str) – The id of a score of this resource.
Returns:: "log" or "linear". None when the histogram of the score is not a number histogram.
Return type:: str | None
Raises:: ValueError – If the resource does not define score_id.

to_dict(score_id: str) → dict[str, float][source]

Return the values of a score keyed by gene symbol.

Parameters:: score_id (str) – The id of a score of this resource.
Returns:: The map from gene symbol to value. Genes without a value are left out. The map is empty when no gene has a value.
Return type:: dict[str, float]
Raises:: ValueError – If the resource does not define score_id.

to_tsv(score_id: str | None = None) → list[str][source]

Return the data of one score as lines of tab-separated text.

Parameters:

score_id (str | None) – The id of a score of this resource. The function needs it in practice: None fails an assertion.

Returns:

The lines, each with its line ending. The first line is the header gene and score_id. Genes without a value are left out.

Return type:

list[str]

Raises:

AssertionError – If score_id is None.
ValueError – If the resource does not define score_id.

class GeneScoreDef(score_id: str, value_type: str, desc: str, small_values_desc: str | None, large_values_desc: str | None, hist_conf: HistogramConfig | None, column_name: str)[source]

The definition of one score of a gene score resource.

The loader builds one definition for each entry of the scores: block of the resource.

Variables:

score_id (str) – The id of the score.
value_type (str) – The type of the values, such as float.
desc (str) – The description of the score. It is empty when the resource gives none.
small_values_desc (str | None) – What a small value means, or None when the resource gives none.
large_values_desc (str | None) – What a large value means, or None when the resource gives none.
hist_conf (HistogramConfig | None) – The histogram configuration of the score.
column_name (str) – The name of the column of the data file that holds the score.