mkt.databases.oncotree

OncoTree cancer-type ontology model and parsing.

Provides the OncoTree model for loading and navigating the OncoTree cancer-type hierarchy.

Module Attributes

DEFAULT_FILENAME	Default filename for the OncoTree dump, relative to <repo_root>/data.
DEFAULT_URL	Upstream URL for the OncoTree dump; used when no local file is found.
LEVEL_PREFIX	Prefix used by OncoTree's hierarchy columns; count varies by snapshot.
META_COLS	Metadata columns in the raw OncoTree TSV.
CODE_RE	Regex capturing the trailing (CODE) suffix on every OncoTree label.
DICT_ONCOTREE_LEGACY_ALIAS	Curated map of retired/renamed OncoTree codes still present in clinical data to their current equivalents.
DICT_TISSUE_COLOR	Curated mapping from OncoTree tissue (level_1 label) to plotting color.
DICT_CODE_COLOR_OVERRIDE	Per-code color overrides where biology diverges from the parent tissue.
DICT_COLOR_CATEGORY	Curated color to short category-label mapping (suitable for legends).

Classes

OncoTree(*[, filepath])

Loader for the OncoTree tumor-type hierarchy.

mkt.databases.oncotree.CODE_RE = re.compile('\\s*\\(([^()]+)\\)\\s*$')

Regex capturing the trailing (CODE) suffix on every OncoTree label.

mkt.databases.oncotree.DEFAULT_FILENAME = 'tumor_types.txt'

Default filename for the OncoTree dump, relative to <repo_root>/data.

mkt.databases.oncotree.DEFAULT_URL = 'https://oncotree.mskcc.org/api/tumor_types.txt'

Upstream URL for the OncoTree dump; used when no local file is found.

mkt.databases.oncotree.DICT_CODE_COLOR_OVERRIDE = {'GIST': 'SaddleBrown', 'PSEC': 'Orange', 'PTH': 'Cyan', 'PTHC': 'Cyan'}

Per-code color overrides where biology diverges from the parent tissue.

mkt.databases.oncotree.DICT_COLOR_CATEGORY = {'Black': 'Skin', 'Blue': 'Male Reproductive', 'Cyan': 'Endocrine', 'DarkRed': 'Head and Neck', 'DimGray': 'Other', 'Green': 'Eye', 'HotPink': 'Breast', 'LightGray': 'CNS/PNS', 'LightSalmon': 'Myeloid', 'LightYellow': 'Soft Tissue', 'LimeGreen': 'Lymphoid', 'Orange': 'Gynecologic', 'Purple': 'GI Developmental', 'Red': 'Thoracic', 'SaddleBrown': 'GI Core', 'White': 'Bone', 'Yellow': 'Urologic'}

Curated color to short category-label mapping (suitable for legends).

mkt.databases.oncotree.DICT_ONCOTREE_LEGACY_ALIAS = {'GBM': 'GB'}

Curated map of retired/renamed OncoTree codes still present in clinical data to their current equivalents. Extend as further legacy codes are encountered.

mkt.databases.oncotree.DICT_TISSUE_COLOR = {'Adrenal Gland (ADRENAL_GLAND)': 'Cyan', 'Ampulla of Vater (AMPULLA_OF_VATER)': 'Purple', 'Biliary Tract (BILIARY_TRACT)': 'Purple', 'Bladder/Urinary Tract (BLADDER)': 'Yellow', 'Bone (BONE)': 'White', 'Bowel (BOWEL)': 'SaddleBrown', 'Breast (BREAST)': 'HotPink', 'CNS/Brain (BRAIN)': 'LightGray', 'Cervix (CERVIX)': 'Orange', 'Esophagus/Stomach (STOMACH)': 'SaddleBrown', 'Eye (EYE)': 'Green', 'Head and Neck (HEAD_NECK)': 'DarkRed', 'Kidney (KIDNEY)': 'Yellow', 'Liver (LIVER)': 'Purple', 'Lung (LUNG)': 'Red', 'Lymphoid (LYMPH)': 'LimeGreen', 'Myeloid (MYELOID)': 'LightSalmon', 'Other (OTHER)': 'DimGray', 'Ovary/Fallopian Tube (OVARY)': 'Orange', 'Pancreas (PANCREAS)': 'Purple', 'Penis (PENIS)': 'Blue', 'Peripheral Nervous System (PNS)': 'LightGray', 'Peritoneum (PERITONEUM)': 'Red', 'Pleura (PLEURA)': 'Red', 'Prostate (PROSTATE)': 'Blue', 'Skin (SKIN)': 'Black', 'Soft Tissue (SOFT_TISSUE)': 'LightYellow', 'Testis (TESTIS)': 'Blue', 'Thymus (THYMUS)': 'Red', 'Thyroid (THYROID)': 'Cyan', 'Uterus (UTERUS)': 'Orange', 'Vulva/Vagina (VULVA)': 'Orange'}

Curated mapping from OncoTree tissue (level_1 label) to plotting color.

mkt.databases.oncotree.LEVEL_PREFIX = 'level_'

Prefix used by OncoTree’s hierarchy columns; count varies by snapshot.

mkt.databases.oncotree.META_COLS = ['metamaintype', 'metacolor', 'metanci', 'metaumls', 'history']

Metadata columns in the raw OncoTree TSV.

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

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.

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

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

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

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

Return the raw TSV text 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

ancestor_code_at_level(code: str, level: int) → str | None

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

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

Return the OncoTree DataFrame with the tissue-level rows dropped.

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

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]