mkt.databases.cancer_hotspots.CancerHotspotsQuery

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.

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

Methods

__eq__(other)	Return self==value.
__post_init__()
_stamp_from_response(res)	Record query datetime + cache provenance from a requests-cache response.
_stamp_now()	Record current UTC datetime; cache provenance unknown.
_to_dataframe(records)	Flatten raw hotspot records into a tidy DataFrame.
check_response(res)	Check the response status code for errors.
get_gene(hugo_symbol)	Return hotspot records for a single gene.
query_api()	Query the cancerhotspots.org API and populate _json and _df.

Attributes

__dataclass_fields__
__dataclass_params__
__match_args__
__pydantic_config__
from_cache	Whether the most recent response was served from requests-cache.
query_datetime	UTC datetime the underlying network query was made (cache creation time if served from cache).
url	URL for the cancerhotspots.org single-residue hotspots API.
version	Publication tier to query; defaults to the most inclusive (Bandlamudi 2026).

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