mkt.databases.cancer_hotspots

Client and parser for the Cancer Hotspots database.

Provides CancerHotspotsQuery to fetch hotspot records and CancerHotspots to parse them, with HotspotVersion and HotspotTier enumerations for versioning and tier classification.

Module Attributes

DICT_COLUMNS	Record keys whose values are dicts; json-encoded when writing to CSV.
TIER_COLUMN	Name of the row-level annotation column added by CancerHotspots.

Classes

CancerHotspots()	Harmonize cancerhotspots.org publication tiers into one annotated table.
CancerHotspotsQuery([version, url])	Single-version query against the cancerhotspots.org single-residue API.
HotspotTier(value)	Earliest publication that called a given hotspot.
HotspotVersion(value)	cancerhotspots.org publication tiers exposed by the API.

class mkt.databases.cancer_hotspots.CancerHotspots

Bases: object

Harmonize cancerhotspots.org publication tiers into one annotated table.

Combines the Chang (v2) and Bandlamudi 2026 (v3) queries and, because v2 is a strict subset of v3, builds a single DataFrame (_df) from the v3 superset with a row-level TIER_COLUMN annotation: each record is labelled HotspotTier.CHANG if its (hugoSymbol, residue) also appears in v2, otherwise HotspotTier.BANDLAMUDI. This is the main entry point; the per-version CancerHotspotsQuery objects remain available via query_chang / query_bandlamudi for provenance (query_datetime / from_cache).

The row-level annotation is residue-keyed, so the Bandlamudi 2026 tier holds the 164 (gene, residue) pairs reported by cancerhotspots.org. For a position-keyed collapse (e.g. coloring a lollipop x-axis), use first_occurrence_map(), which yields 161 — see its docstring.

_annotate() → DataFrame | None

Annotate the v3 superset with a row-level publication tier.

property df: DataFrame | None

Harmonized, tier-annotated DataFrame (one row per v3 record).

first_occurrence_map(single_residue_only: bool = False) → dict[tuple[str, int], str]

Map (hugoSymbol, positionStart) to the earliest hotspot tier.

Collapses the residue-level df to one label per residue position: HotspotTier.CHANG if any record at that position is in the Chang tier, otherwise HotspotTier.BANDLAMUDI. Positions absent from both tiers are simply not keyed (treat as “not a hotspot”).

This keys on position rather than the full residue string because the downstream lollipop colors residue positions on its x-axis. As a result the Bandlamudi 2026 tier holds 161 positions, not the 164 new (gene, residue) pairs in df: three v3-only residues (FOXA1 D249, MTOR Y1450, TP53 E224) sit at positions already called in v2, so they collapse into existing Chang positions. Use df (residue level) if you need the headline 164.

Parameters:

single_residue_only (bool, optional) – If True, exclude in-frame indel records (type != "single residue") before collapsing, so the map only covers single-residue hotspots. Default False (all records).

Returns:

Mapping of (hugoSymbol, positionStart) to a HotspotTier value; empty if the harmonized table is unavailable.

Return type:

dict[tuple[str, int], str]

classmethod from_csv(path: str) → CancerHotspots

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:

CancerHotspots

classmethod from_dataframe(df: DataFrame) → CancerHotspots

Build a client from an already-harmonized table without querying the API.

Bypasses __post_init__ (which would issue the per-tier network queries) via object.__new__ and sets _df directly, so cached data can be reloaded offline. The per-tier provenance objects (query_chang / query_bandlamudi) are set to None.

Parameters:

df (pd.DataFrame) – Tier-annotated table (e.g. from read_csv() or df).

Returns:

Instance backed by df; get_gene() and first_occurrence_map() work as usual.

Return type:

CancerHotspots

get_gene(hugo_symbol: str) → DataFrame

Return tier-annotated hotspot records 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

static read_csv(path: str) → DataFrame

Read a harmonized table written by to_csv() back into a DataFrame.

Inverts to_csv(): json-decodes the dict-valued columns and restores the nullable integer position columns.

Parameters:

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

Returns:

Tier-annotated table equivalent to df.

Return type:

pd.DataFrame

to_csv(path: str) → None

Write the harmonized table to CSV, json-encoding dict-valued columns.

Parameters:

path (str) – Output CSV path.

class mkt.databases.cancer_hotspots.CancerHotspotsQuery(version: HotspotVersion = HotspotVersion.BANDLAMUDI, url: str = 'https://www.cancerhotspots.org/api/hotspots/single')

Bases: RESTAPIClient

Single-version query against the cancerhotspots.org single-residue API.

One instance == one network call for one publication tier. There is no working per-gene endpoint upstream, so the full payload (~1300 records) is fetched once and filtered client-side via get_gene(). The raw JSON is kept in _json and a tidy table in _df.

For the harmonized, tier-annotated table combining both versions, use CancerHotspots instead.

static _to_dataframe(records: list[dict]) → DataFrame

Flatten raw hotspot records into a tidy DataFrame.

Parameters:

records (list[dict]) – Raw JSON records from the single-residue hotspots endpoint.

Returns:

One row per record; aminoAcidPosition is flattened into positionStart/positionEnd integer columns and the dict-valued columns (variant amino acids, tumor type composition) are retained.

Return type:

pd.DataFrame

get_gene(hugo_symbol: str) → DataFrame

Return hotspot records 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 cancerhotspots.org API and populate _json and _df.

url: str = 'https://www.cancerhotspots.org/api/hotspots/single'

URL for the cancerhotspots.org single-residue hotspots API.

version: HotspotVersion = 'v3'

Publication tier to query; defaults to the most inclusive (Bandlamudi 2026).

mkt.databases.cancer_hotspots.DICT_COLUMNS = ('variantAminoAcid', 'tumorTypeComposition')

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

class mkt.databases.cancer_hotspots.HotspotTier(value)

Bases: str, Enum

Earliest publication that called a given hotspot.

BANDLAMUDI = 'Bandlamudi 2026'

First called in the Bandlamudi 2026 tier (API version=v3 only).

CHANG = 'Chang'

Present in the Chang tier (API version=v2).

class mkt.databases.cancer_hotspots.HotspotVersion(value)

Bases: str, Enum

cancerhotspots.org publication tiers exposed by the API.

Note: V1 and V2 return identical payloads from the API; V2 is a strict subset of V3 (V3 adds the 164 new Bandlamudi 2026 hotspots).

BANDLAMUDI = 'v3'

Bandlamudi 2026 (== v2 plus the 164 newly called hotspots).

CHANG = 'v2'

Chang 2016/2017 (the API returns identical payloads for v1 and v2).

mkt.databases.cancer_hotspots.TIER_COLUMN = 'tier'

Name of the row-level annotation column added by CancerHotspots.