mkt.databases.oncokb

OncoKB API client for therapeutic levels, protein-change annotations, and the cancer gene list.

Provides OncoKBInfo and OncoKBProteinChange REST clients plus helpers (get_oncokb_levels(), adjudicate_prefix()) for OncoKB therapeutic-level and variant annotations, and OncoKBCancerGeneList for fetching/caching the OncoKB cancer gene list.

Module Attributes

DICT_ONCOKB_PREFIXES	Mapping of OncoKB level prefixes to their corresponding keys in the highest level dictionary.
LIST_COLUMNS	Record keys whose values are lists; json-encoded when writing to CSV.

Functions

adjudicate_prefix(str_in)	Adjudicate the prefix for a given level string.
get_oncokb_levels()	Query the OncoKB API for the current levels of evidence.

Classes

OncoKB(url, header)	OncoKB API client.
OncoKBCancerGeneList([url])	Client for the OncoKB cancer gene list endpoint.
OncoKBInfo(url, header)	OncoKB API client for OncoKB information.
OncoKBProteinChange(url, header, gene_name, ...)	OncoKB API client for protein changes.

mkt.databases.oncokb.DICT_ONCOKB_PREFIXES = {'Diagnostic_Implication': 'LEVEL_Dx', 'FDA': 'LEVEL_Fda', 'Prognostic_Implication': 'LEVEL_Px', 'Resistance': 'LEVEL_R', 'Sensitive': 'LEVEL_'}

Mapping of OncoKB level prefixes to their corresponding keys in the highest level dictionary.

mkt.databases.oncokb.LIST_COLUMNS = ('geneAliases',)

Record keys whose values are lists; json-encoded when writing to CSV.

class mkt.databases.oncokb.OncoKB(url: str = 'https://www.oncokb.org/api/v1', header: dict = <factory>)

Bases: APIKeyRESTAPIClient, ABC

OncoKB API client.

__init__(url: str = 'https://www.oncokb.org/api/v1', header: dict = <factory>) → None

static extract_level_as_int(str_in: str | None) → int | None

Extract the level from a string and convert it to an integer.

Parameters:

str_in (str | None) – String containing the level information

Returns:

Level as integer if found, otherwise None

Return type:

int | None

has_json() → dict | None

Get the JSON response from the OncoKB API query.

Returns:

JSON response if available, otherwise None

Return type:

dict | None

header: dict

OncoKB API token, if available.

maybe_get_token() → str | None

Get API token, if available.

Returns:

API token if available; None otherwise

Return type:

str | None

query_api()

Query the OncoKB API for a given URL.

abstract update_url()

url: str = 'https://www.oncokb.org/api/v1'

Base URL for the OncoKB API.

url_query: str | None = None

URL to update for specific queries.

class mkt.databases.oncokb.OncoKBCancerGeneList(url: str = 'https://www.oncokb.org/api/v1/utils/cancerGeneList')

Bases: RESTAPIClient

Client for the OncoKB cancer gene list endpoint.

Fetches the full OncoKB cancer gene list (/utils/cancerGeneList) in a single network call, exposing the raw JSON in _json and a tidy table in _df. The endpoint is public (no token required), so this subclasses the plain RESTAPIClient rather than the token-bearing OncoKB hierarchy used for therapeutic-level/variant annotations. Mirrors the cancerhotspots client: query once, filter client-side via get_gene(), and round-trip to CSV via to_csv() / from_csv().

__init__(url: str = 'https://www.oncokb.org/api/v1/utils/cancerGeneList') → None

property df: DataFrame | None

Cancer gene list as a DataFrame (one row per gene).

classmethod from_csv(path: str) → OncoKBCancerGeneList

Build a client from a CSV written by to_csv(), without querying.

Parameters:

path (str) – Path to a CSV previously written by to_csv().

Returns:

Instance backed by the cached table.

Return type:

OncoKBCancerGeneList

classmethod from_dataframe(df: DataFrame) → OncoKBCancerGeneList

Build a client from an existing table without querying the API.

Bypasses __post_init__ (which would issue the network query) via object.__new__ and sets _df directly, so cached data can be reloaded offline. _json is left None.

Parameters:

df (pd.DataFrame) – Cancer gene list table (e.g. from read_csv() or df).

Returns:

Instance backed by df; get_gene() works as usual.

Return type:

OncoKBCancerGeneList

get_gene(hugo_symbol: str) → DataFrame

Return the cancer gene list record(s) for a single gene.

Parameters:

hugo_symbol (str) – HGNC gene symbol to filter on (e.g. "BRAF").

Returns:

Rows of df whose hugoSymbol matches; empty if none.

Return type:

pd.DataFrame

query_api() → None

Query the OncoKB cancer gene list endpoint and populate _json and _df.

static read_csv(path: str) → DataFrame

Read a cancer gene list written by to_csv() back into a DataFrame.

Inverts to_csv(): json-decodes the list-valued columns.

Parameters:

path (str) – Path to a CSV previously written by to_csv().

Returns:

Cancer gene list equivalent to df.

Return type:

pd.DataFrame

to_csv(path: str) → None

Write the cancer gene list to CSV, json-encoding list-valued columns.

Parameters:

path (str) – Output CSV path.

url: str = 'https://www.oncokb.org/api/v1/utils/cancerGeneList'

URL for the OncoKB cancer gene list endpoint.

class mkt.databases.oncokb.OncoKBInfo(url: str = 'https://www.oncokb.org/api/v1', header: dict = <factory>)

Bases: OncoKB

OncoKB API client for OncoKB information.

update_url()

Update the URL for the OncoKB API query based on the gene name.

class mkt.databases.oncokb.OncoKBProteinChange(url: str = 'https://www.oncokb.org/api/v1', header: dict = <factory>, gene_name: str | None = None, alteration: str | None = None, dict_highest_level: dict[str, int] = <factory>, list_treatment: list[str] = <factory>, oncogenic: str | None = None, vus: bool | None = None, known_effect: str | None = None, verbose: bool = True)

Bases: OncoKB

OncoKB API client for protein changes.

__init__(url: str = 'https://www.oncokb.org/api/v1', header: dict = <factory>, gene_name: str | None = None, alteration: str | None = None, dict_highest_level: dict[str, int] = <factory>, list_treatment: list[str] = <factory>, oncogenic: str | None = None, vus: bool | None = None, known_effect: str | None = None, verbose: bool = True) → None

alteration: str | None = None

Alteration type (e.g., V600E if BRAF is gene).

annotate_highest_level()

Annotate the highest level of evidence for the protein change.

dict_highest_level: dict[str, int]

Dictionary to store the highest level of evidence for each alteration.

gene_name: str | None = None

Gene associated with the protein change.

get_treatments()

Get the list of treatments associated with the alteration.

known_effect: str | None = None

Effect of the mutation on the protein (e.g., missense, nonsense).

list_treatment: list[str]

List of treatments associated with the alteration.

oncogenic: str | None = None

Oncogenic status of the alteration.

update_url()

Update the URL for the OncoKB API query based on the UniProt ID.

verbose: bool = True

Whether to log warnings for missing data.

vus: bool | None = None

Whether the alteration is a Variant of Uncertain Significance (VUS).

mkt.databases.oncokb.adjudicate_prefix(str_in: str) → str | None

Adjudicate the prefix for a given level string.

Parameters:

str_in (str) – String containing the level information (e.g., “LEVEL_1_SENSITIVE”)

Returns:

Prefix of the level string (e.g., “Sensitive”) if found, otherwise None

Return type:

str | None

mkt.databases.oncokb.get_oncokb_levels() → dict[str, str] | None

Query the OncoKB API for the current levels of evidence.

Returns:

Mapping of level string (e.g. “LEVEL_1”) to its description, or None if the levels could not be retrieved from the API.

Return type:

dict[str, str] | None