mkt.databases.oncotree.OncoTree

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

Bases: BaseModel

Loader for the OncoTree tumor-type hierarchy.

Source: https://oncotree.mskcc.org/api/tumor_types.txt

The raw TSV ships hierarchy columns (level_1 through level_N; the upstream API currently emits six, older local snapshots emit seven), five metadata columns, and labels in the form "Display Name (CODE)". Upstream rows are ragged: shallow entries only emit tabs up to their deepest populated level, so a depth-1 row has six fields rather than eleven. The loader pads those rows so the metadata columns realign, then exposes a cleaned DataFrame via the df property with four derived columns added between the levels and metadata: depth (count of populated level cells), name (the deepest label with its (CODE) suffix stripped), code (the OncoTree code parsed from that suffix), and parent (the immediately shallower level label, empty at depth 1).

Parameters:: filepath (str | None) – Optional path to the OncoTree TSV. If unset, the loader looks for <repo_root>/data/tumor_types.txt and falls back to fetching 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

`_build_level_code_map`()	Map every OncoTree code -> the codes of its ancestors, level 1 first.
`_load`()	Read the OncoTree TSV and derive `depth`, `name`, `code`, `parent`.
`_parse_ragged_tsv`(text)	Parse the ragged OncoTree TSV into a rectangular DataFrame.
`_read_text`(source)	Return the raw TSV text from a local path or http(s) URL.
`_resolve_source`()	Resolve the source path or URL to read.
`ancestor_code_at_level`(code, level)	Roll an OncoTree `code` up to its ancestor at `level`.
`resolve_code`(code)	Map a retired/renamed OncoTree code to its current equivalent.
`return_df_tissue_drop`()	Return the OncoTree DataFrame with the tissue-level rows dropped.
`roll_up_map`(level[, codes])	Build a `{code: ancestor_code_at_level}` map for many codes.

Attributes

`df`	Cleaned OncoTree DataFrame populated at instantiation.
`dict_code_color`	Map OncoTree code -> curated plotting color.
`dict_code_metacolor`	Map OncoTree code -> upstream metacolor.
`dict_code_name`	Map every OncoTree code -> its display name (`(CODE)` suffix stripped).
`known_codes`	Set of every OncoTree code in the loaded snapshot.
`filepath`
`_df`
`_level_code_map`

_build_level_code_map() → dict[str, list[str | None]][source]

Map every OncoTree code -> the codes of its ancestors, level 1 first.

For each row, walk its populated level_* cells and capture the (CODE) from each, giving that node’s full lineage (its own code is the last entry). Used by ancestor_code_at_level() to roll a code up to a coarser level.

Returns:: {code: [level_1_code, ..., level_depth_code]}.
Return type:: dict[str, list[str | None]]

_load() → DataFrame[source]

Read the OncoTree TSV and derive depth, name, code, parent.

Returns:: Columns, in order: level_1 … level_N, depth, name, code, parent, then the five metadata columns. N is the number of level_* columns in the source file.
Return type:: pd.DataFrame

static _parse_ragged_tsv(text: str) → DataFrame[source]

Parse the ragged OncoTree TSV into a rectangular DataFrame.

Shallow rows omit trailing empty level cells, so the populated fields are [*levels, *metadata] with no padding between. Padding is inserted between the levels and the trailing metadata block so every row has len(header) cells.

Parameters:: text (str) – Raw TSV contents, including the header line.
Returns:: String-typed DataFrame matching the TSV header.
Return type:: pd.DataFrame

static _read_text(source: str) → str[source]: Return the raw TSV text 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

ancestor_code_at_level(code: str, level: int) → str | None[source]

Roll an OncoTree code up to its ancestor at level.

Levels are 1-indexed (level=1 is the tissue root). A node shallower than level has no ancestor there, so its own (deepest) code is returned instead.

Parameters:

code (str) – OncoTree code to roll up.
level (int) – Target hierarchy level (>= 1).

Returns:

The ancestor code at level (or the node’s own code if it is shallower than level); None if code is unknown.

Return type:

str | None

property df: DataFrame: Cleaned OncoTree DataFrame populated at instantiation.

property dict_code_color: dict[str, str]

Map OncoTree code -> curated plotting color.

The curated color is the tissue-level default from DICT_TISSUE_COLOR (keyed by level_1), overridden by DICT_CODE_COLOR_OVERRIDE for codes whose biology differs from their administrative parent tissue (GIST under Soft Tissue, parathyroid carcinomas under Head and Neck, PSEC under Peritoneum).

Returns:: {code: color} for every non-tissue row. A tissue absent from DICT_TISSUE_COLOR logs a warning and falls back to the upstream metacolor so the mapping still covers every code.
Return type:: dict[str, str]

property dict_code_metacolor: dict[str, str]

Map OncoTree code -> upstream metacolor.

Tissue-level (depth == 1) rows are dropped so the keys are unique leaf codes.

Returns:: {code: metacolor} for every non-tissue row.
Return type:: dict[str, str]

property dict_code_name: dict[str, str]

Map every OncoTree code -> its display name ((CODE) suffix stripped).

Covers all nodes (each code is the deepest label of exactly one row), so it resolves both leaf and internal (rolled-up) codes to a label.

Returns:: {code: name}.
Return type:: dict[str, str]

filepath: str | None

property known_codes: set[str]: Set of every OncoTree code in the loaded snapshot.

resolve_code(code: str) → str[source]

Map a retired/renamed OncoTree code to its current equivalent.

Applies DICT_ONCOTREE_LEGACY_ALIAS (e.g. GBM -> GB); codes already current, or absent from the alias map, are returned unchanged. This does not guarantee the result exists in the snapshot – check known_codes for that.

Parameters:: code (str) – OncoTree code as stored (possibly legacy).
Returns:: The current-equivalent code.
Return type:: str

return_df_tissue_drop() → DataFrame[source]: Return the OncoTree DataFrame with the tissue-level rows dropped.

roll_up_map(level: int, codes: list[str] | None = None) → dict[str, str | None][source]

Build a {code: ancestor_code_at_level} map for many codes.

Parameters:

level (int) – Target hierarchy level (>= 1); see ancestor_code_at_level().
codes (list[str] | None) – Codes to roll up; when None, every known OncoTree code is used.

Returns:

{code: ancestor_code} (value None for unknown codes).

Return type:

dict[str, str | None]