mkt.databases.three_d_hotspots

Loader and parser for the 3D Hotspots database.

Provides ThreeDHotspots to load and parse the residue-level 3D hotspot calls (Table S2) published by 3dhotspots.org, with the HotspotClass enumeration for the per-residue classification.

Unlike mkt.databases.cancer_hotspots, 3dhotspots.org exposes no API: the data ship as a single XLSX workbook (3d_hotspots.xls). Following the pattern in mkt.databases.oncotree, the loader reads a local copy under <repo_root>/data when present and otherwise downloads DEFAULT_URL.

Module Attributes

DEFAULT_FILENAME	Default filename for the 3D Hotspots workbook, relative to <repo_root>/data.
DEFAULT_URL	Upstream URL for the 3D Hotspots workbook; used when no local file is found.
RESIDUE_SHEET	Workbook sheet holding the per-residue hotspot calls.
LICENSE_COL_PREFIX	Prefix of the ODbL license-boilerplate column upstream appends to every sheet.
COLUMN_RENAME	Rename map from the raw Table S2 headers to camelCase columns.
RESIDUE_RE	Regex capturing the integer position from a "<ref-AA><position>" residue.

Classes

HotspotClass(value)	Per-residue 3D hotspot classification from Table S2.
ThreeDHotspots(*[, filepath])	Loader for the residue-level 3D hotspot calls from 3dhotspots.org.

mkt.databases.three_d_hotspots.COLUMN_RENAME = {'#Mutations': 'mutationCount', 'Class': 'hotspotClass', 'Gene': 'hugoSymbol', 'Residue': 'residue', 'p-value': 'pValue'}

Rename map from the raw Table S2 headers to camelCase columns.

hugoSymbol / residue mirror mkt.databases.cancer_hotspots so the two hotspot resources share a column vocabulary.

mkt.databases.three_d_hotspots.DEFAULT_FILENAME = '3d_hotspots.xls'

Default filename for the 3D Hotspots workbook, relative to <repo_root>/data.

mkt.databases.three_d_hotspots.DEFAULT_URL = 'https://www.3dhotspots.org/files/3d_hotspots.xls'

Upstream URL for the 3D Hotspots workbook; used when no local file is found.

class mkt.databases.three_d_hotspots.HotspotClass(value)

Bases: str, Enum

Per-residue 3D hotspot classification from Table S2.

CLUSTER_EXCLUSIVE = 'Cluster-exclusive'

3D-cluster residue not otherwise called as a linear hotspot.

HOTSPOT = 'Hotspot'

Recurrently mutated residue also called as a linear (single-residue) hotspot.

HOTSPOT_LINKED = 'Hotspot-linked'

3D-cluster residue sharing a cluster with a linear hotspot residue.

mkt.databases.three_d_hotspots.LICENSE_COL_PREFIX = 'Data available under ODC'

Prefix of the ODbL license-boilerplate column upstream appends to every sheet.

mkt.databases.three_d_hotspots.RESIDUE_RE = re.compile('^[A-Za-z]+(\\d+)$')

Regex capturing the integer position from a "<ref-AA><position>" residue.

mkt.databases.three_d_hotspots.RESIDUE_SHEET = 'Table S2'

Workbook sheet holding the per-residue hotspot calls.

class mkt.databases.three_d_hotspots.ThreeDHotspots(*, filepath: str | None = None)

Bases: BaseModel

Loader for the residue-level 3D hotspot calls from 3dhotspots.org.

Source: https://www.3dhotspots.org/files/3d_hotspots.xls (Table S2)

The workbook’s Table S2 sheet lists one row per hotspot residue with its gene, mutation count, p-value, and HotspotClass. The loader drops the trailing ODbL license-boilerplate column, renames the headers to the camelCase vocabulary shared with mkt.databases.cancer_hotspots (hugoSymbol / residue), and derives a nullable-integer positionStart from each residue label. The cleaned table is exposed via the df property and filtered per gene with get_gene().

Parameters:

filepath (str | None) – Optional path to the 3D Hotspots workbook. If unset, the loader looks for <repo_root>/data/3d_hotspots.xls and falls back to downloading DEFAULT_URL when no local file exists.

_load() → DataFrame

Read Table S2 and derive positionStart.

Returns:

Columns, in order: hugoSymbol, residue, positionStart, mutationCount, pValue, hotspotClass.

Return type:

pd.DataFrame

static _read_bytes(source: str) → bytes

Return the raw workbook bytes from a local path or http(s) URL.

_resolve_source() → str

Resolve the source path or URL to read.

Returns:

self.filepath if set; otherwise the repo-bundled default path if it exists on disk; otherwise DEFAULT_URL.

Return type:

str

property df: DataFrame

Cleaned residue-level 3D hotspot table populated at instantiation.

filepath: str | None

classmethod from_csv(path: str) → ThreeDHotspots

Build a loader from a CSV written by to_csv(), without downloading.

Parameters:

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

Returns:

Instance backed by the cached table.

Return type:

ThreeDHotspots

classmethod from_dataframe(df: DataFrame) → ThreeDHotspots

Build a loader from an already-cleaned table without reading the workbook.

Bypasses model_post_init (which would read/download the workbook) and sets _df directly, so cached data can be reloaded offline.

Parameters:

df (pd.DataFrame) – Cleaned table (e.g. from read_csv() or df).

Returns:

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

Return type:

ThreeDHotspots

get_gene(hugo_symbol: str) → DataFrame

Return 3D hotspot residues 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 table written by to_csv() back into a DataFrame.

Restores the nullable-integer positionStart column and keeps pValue as text.

Parameters:

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

Returns:

Cleaned table equivalent to df.

Return type:

pd.DataFrame

to_csv(path: str) → None

Write the cleaned table to CSV.

Parameters:

path (str) – Output CSV path.