mkt.databases.three_d_hotspots.ThreeDHotspots

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

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.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Methods

`_load`()	Read `Table S2` and derive `positionStart`.
`_read_bytes`(source)	Return the raw workbook bytes from a local path or http(s) URL.
`_resolve_source`()	Resolve the source path or URL to read.
`from_csv`(path)	Build a loader from a CSV written by `to_csv()`, without downloading.
`from_dataframe`(df)	Build a loader from an already-cleaned table without reading the workbook.
`get_gene`(hugo_symbol)	Return 3D hotspot residues for a single gene.
`read_csv`(path)	Read a table written by `to_csv()` back into a DataFrame.
`to_csv`(path)	Write the cleaned table to CSV.

Attributes

`df`	Cleaned residue-level 3D hotspot table populated at instantiation.
`filepath`
`_df`

_load() → DataFrame[source]

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[source]: Return the raw workbook bytes from a local path or http(s) URL.

_resolve_source() → str[source]

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[source]

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[source]

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[source]

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[source]

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[source]

Write the cleaned table to CSV.

Parameters:: path (str) – Output CSV path.