gain.gene_scores package

Subpackages

Submodules

gain.gene_scores.gene_scores module

class GeneScore(resource: GenomicResource)[source]

Bases: ScoreResource[GeneScoreDef]

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]

Bases: ScoreDef

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.

column_name: str
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.

Module contents