mkt.databases.cancer_hotspots.CancerHotspots

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.

__init__(*args: Any, **kwargs: Any) → None

Methods

__eq__(other)	Return self==value.
__post_init__()
_annotate()	Annotate the v3 superset with a row-level publication tier.
first_occurrence_map([single_residue_only])	Map (hugoSymbol, positionStart) to the earliest hotspot tier.
from_csv(path)	Build a client from a CSV written by to_csv(), without querying.
from_dataframe(df)	Build a client from an already-harmonized table without querying the API.
get_gene(hugo_symbol)	Return tier-annotated hotspot records for a single gene.
read_csv(path)	Read a harmonized table written by to_csv() back into a DataFrame.
to_csv(path)	Write the harmonized table to CSV, json-encoding dict-valued columns.

Attributes

__dataclass_fields__
__dataclass_params__
__match_args__
__pydantic_config__
df	Harmonized, tier-annotated DataFrame (one row per v3 record).

_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.