mkt.databases.protvar

ProtVar API client for variant pathogenicity scores.

Provides ProtvarScoreQuery and the ProtvarVariant model for retrieving variant pathogenicity scores, with a ScoreDatabase enumeration of supported score sources.

Module Attributes

DICT_SCORE_KEY	Key holding the numeric score within each database's score dict; databases absent from this mapping (e.g. popEVE) have no single scalar score.
DICT_CLASS_KEY	Key holding the categorical classification; only EVE and AlphaMissense have one.
TUPLE_VARIANT_DATABASES	Variant-level databases (one score per substitution); Conservation is excluded as it is residue- rather than variant-level.

Functions

_coerce_database(database)

Coerce a ScoreDatabase or its value (e.g. "AM") to a ScoreDatabase, or None.

Classes

ProtvarScoreQuery(uniprot_id, pos, mut, url, ...)	Class to interact with the ProtVar score API.
ProtvarVariant(mt, scores)	Scores for a single variant (one mutant residue) at a position.
ScoreDatabase(value)	Enum class to define the score databases returned by ProtVar.

mkt.databases.protvar.DICT_CLASS_KEY = {ScoreDatabase.AlphaMissense: 'amClass', ScoreDatabase.EVE: 'eveClass'}

Key holding the categorical classification; only EVE and AlphaMissense have one.

Type:

dict[ScoreDatabase, str]

mkt.databases.protvar.DICT_SCORE_KEY = {ScoreDatabase.AlphaMissense: 'amPathogenicity', ScoreDatabase.Conservation: 'score', ScoreDatabase.ESM1b: 'score', ScoreDatabase.EVE: 'score'}

Key holding the numeric score within each database’s score dict; databases absent from this mapping (e.g. popEVE) have no single scalar score.

Type:

dict[ScoreDatabase, str]

class mkt.databases.protvar.ProtvarScoreQuery(uniprot_id: str, pos: int, mut: str | None = None, url: str = 'https://www.ebi.ac.uk/ProtVar/api/score/<UNIPROT>/<POS>?mt=<MUT>', header: dict = <factory>)

Bases: RESTAPIClient

Class to interact with the ProtVar score API.

A single query returns scores for every available database (Conservation, EVE, ESM1b, AlphaMissense, popEVE). The response is parsed into ProtvarVariant objects exposed via variants:

• mut supplied -> a single variant keyed by that residue.

• mut is None -> one variant per possible substitution (keyed by residue).

Residue identity for the variant-level databases is recovered from popEVE, the only database whose payload carries the mutant residue (mt).

_build_variants() → None

Parse the flat score list into per-variant ProtvarVariant objects.

create_query_url()

Create URL for Protvar score API query.

get_scores() → list[dict] | None

Return all raw score dicts retained from the query.

Returns:

All score dicts returned by the api, or None if the query failed.

Return type:

list[dict] | None

get_variant(mt: str | None = None) → ProtvarVariant | None

Return a single variant by mutant residue.

Parameters:

mt (str | None, optional) – Mutant residue to retrieve. If None and the query targeted a single variant, that sole variant is returned; otherwise None.

Returns:

The requested variant, or None if absent.

Return type:

ProtvarVariant | None

header: dict

Header for the API request.

mut: str | None = None

Mutant residue (1 or 3 letter code); optional. If None, scores for every possible substitution at this position are returned.

pos: int

Position in the protein where mutation resides.

query_api() → None

Query the ProtVar score API and parse the response into variants.

uniprot_id: str

Uniprot ID.

url: str = 'https://www.ebi.ac.uk/ProtVar/api/score/<UNIPROT>/<POS>?mt=<MUT>'

URL for Protvar score API query.

class mkt.databases.protvar.ProtvarVariant(mt: str | None, scores: dict = <factory>)

Bases: object

Scores for a single variant (one mutant residue) at a position.

Built by ProtvarScoreQuery; holds the raw per-database score dict for this variant and exposes scalar accessors. Conservation, which is residue- rather than variant-level, is shared across all variants at the position.

get_classification(database: ScoreDatabase | str)

Return the categorical classification for a database, or None.

Parameters:

database (ScoreDatabase | str) – Database to retrieve, as a ScoreDatabase member or its value (e.g. “AM”).

Returns:

The classification (“eveClass” for EVE, “amClass” for AlphaMissense); None for databases without one (Conservation, ESM1b, popEVE) or when the database is absent for this variant.

Return type:

str | None

get_popeve() → dict | None

Return the standalone popEVE payload for this variant, or None.

Returns:

The full popEVE score dict (multiple keys, retained verbatim), or None if popEVE was not returned for this variant.

Return type:

dict | None

get_score(database: ScoreDatabase | str)

Return the numeric score for a database, or None if not present.

Parameters:

database (ScoreDatabase | str) – Database to retrieve, as a ScoreDatabase member or its value (e.g. “AM”).

Returns:

The score (“score” for Conservation/EVE/ESM1b, “amPathogenicity” for AlphaMissense); None for popEVE (use get_popeve()) or when the database is absent for this variant.

Return type:

float | None

mt: str | None

Mutant residue (1-letter code) this variant represents; None if unknown.

scores: dict

Mapping of ScoreDatabase to its raw score dict for this variant.

class mkt.databases.protvar.ScoreDatabase(value)

Bases: str, Enum

Enum class to define the score databases returned by ProtVar.

AlphaMissense = 'AM'

Conservation = 'CONSERV'

ESM1b = 'ESM'

EVE = 'EVE'

popEVE = 'POPEVE'

mkt.databases.protvar.TUPLE_VARIANT_DATABASES = (ScoreDatabase.EVE, ScoreDatabase.ESM1b, ScoreDatabase.AlphaMissense, ScoreDatabase.popEVE)

Variant-level databases (one score per substitution); Conservation is excluded as it is residue- rather than variant-level.

Type:

tuple[ScoreDatabase, …]

mkt.databases.protvar._coerce_database(database: ScoreDatabase | str | None) → ScoreDatabase | None

Coerce a ScoreDatabase or its value (e.g. “AM”) to a ScoreDatabase, or None.