ctkit 0.1.0__py3-none-any.whl

ctkit/datasets.py

@@ -0,0 +1,216 @@
+"""The catalog of datasets this package knows how to fetch and process.
+
+Two groups:
+
+* the TCGA and CPTAC collections in
+  :data:`~ctkit.constants.tcia_dataset_to_info`, which
+  carry curated processing settings (organs to segment, clipping window,
+  output dimensions);
+* widely used public CT collections in :data:`EXTRA_CT_COLLECTIONS`, which are
+  listed for convenience and download the same way.
+
+Any TCIA collection can be downloaded whether or not it appears here — see
+:func:`~ctkit.tcia.list_collections`, which queries
+the archive directly.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .constants import tcia_dataset_to_info
+
+#: Public CT collections that are commonly used as benchmarks or pretraining
+#: corpora. ``clip_min,clip_max`` follows the same convention as the curated
+#: TCGA/CPTAC entries: the window to clip to before feature extraction.
+EXTRA_CT_COLLECTIONS = {
+    "lidc-idri": {
+        "collection": "LIDC-IDRI",
+        "project": "tcia",
+        "cancer_organ": "lung",
+        "cancer_type": "lung nodules (screening)",
+        "description": "1,010 thoracic CT scans with annotated lung nodules.",
+        "totalsegmentator_organs": [
+            "lung_upper_lobe_left", "lung_lower_lobe_left", "lung_upper_lobe_right",
+            "lung_middle_lobe_right", "lung_lower_lobe_right",
+        ],
+        "clip_min,clip_max": (-1000, 400),
+    },
+    "nsclc-radiomics": {
+        "collection": "NSCLC-Radiomics",
+        "project": "tcia",
+        "cancer_organ": "lung",
+        "cancer_type": "non-small cell lung cancer",
+        "description": "422 NSCLC CT scans with manual tumor delineations (Aerts Lung1).",
+        "totalsegmentator_organs": [
+            "lung_upper_lobe_left", "lung_lower_lobe_left", "lung_upper_lobe_right",
+            "lung_middle_lobe_right", "lung_lower_lobe_right",
+        ],
+        "clip_min,clip_max": (-1000, 400),
+    },
+    "nsclc-radiogenomics": {
+        "collection": "NSCLC Radiogenomics",
+        "project": "tcia",
+        "cancer_organ": "lung",
+        "cancer_type": "non-small cell lung cancer",
+        "description": "CT/PET with matched RNA-seq and mutation data.",
+        "totalsegmentator_organs": [
+            "lung_upper_lobe_left", "lung_lower_lobe_left", "lung_upper_lobe_right",
+            "lung_middle_lobe_right", "lung_lower_lobe_right",
+        ],
+        "clip_min,clip_max": (-1000, 400),
+    },
+    "pancreas-ct": {
+        "collection": "Pancreas-CT",
+        "project": "tcia",
+        "cancer_organ": "pancreas",
+        "cancer_type": "healthy pancreas (segmentation benchmark)",
+        "description": "82 contrast-enhanced abdominal CT scans with pancreas masks.",
+        "totalsegmentator_organs": ["pancreas"],
+        "clip_min,clip_max": (-200, 300),
+    },
+    "hcc-tace-seg": {
+        "collection": "HCC-TACE-Seg",
+        "project": "tcia",
+        "cancer_organ": "liver",
+        "cancer_type": "hepatocellular carcinoma",
+        "description": "Liver CT before/after transarterial chemoembolization, with masks.",
+        "totalsegmentator_organs": ["liver"],
+        "clip_min,clip_max": (-200, 400),
+    },
+    "colorectal-liver-metastases": {
+        "collection": "Colorectal-Liver-Metastases",
+        "project": "tcia",
+        "cancer_organ": "liver",
+        "cancer_type": "colorectal liver metastases",
+        "description": "Preoperative liver CT with tumor and liver segmentations.",
+        "totalsegmentator_organs": ["liver"],
+        "clip_min,clip_max": (-200, 400),
+    },
+    "stageii-colorectal-ct": {
+        "collection": "StageII-Colorectal-CT",
+        "project": "tcia",
+        "cancer_organ": "colon",
+        "cancer_type": "stage II colorectal cancer",
+        "description": "Preoperative CT for stage II colorectal cancer.",
+        "totalsegmentator_organs": ["colon"],
+        "clip_min,clip_max": (-200, 300),
+    },
+    "lungct-diagnosis": {
+        "collection": "LungCT-Diagnosis",
+        "project": "tcia",
+        "cancer_organ": "lung",
+        "cancer_type": "lung adenocarcinoma",
+        "description": "Diagnostic chest CT with survival outcomes.",
+        "totalsegmentator_organs": [
+            "lung_upper_lobe_left", "lung_lower_lobe_left", "lung_upper_lobe_right",
+            "lung_middle_lobe_right", "lung_lower_lobe_right",
+        ],
+        "clip_min,clip_max": (-1000, 400),
+    },
+    "rider-lung-ct": {
+        "collection": "RIDER Lung CT",
+        "project": "tcia",
+        "cancer_organ": "lung",
+        "cancer_type": "non-small cell lung cancer (test-retest)",
+        "description": "Same-day repeat CT scans — the standard set for testing "
+                       "whether a feature is reproducible.",
+        "totalsegmentator_organs": [
+            "lung_upper_lobe_left", "lung_lower_lobe_left", "lung_upper_lobe_right",
+            "lung_middle_lobe_right", "lung_lower_lobe_right",
+        ],
+        "clip_min,clip_max": (-1000, 400),
+    },
+    "ct-colonography": {
+        "collection": "CT COLONOGRAPHY",
+        "project": "tcia",
+        "cancer_organ": "colon",
+        "cancer_type": "colorectal polyps (screening)",
+        "description": "825 CT colonography cases; large and mostly healthy anatomy.",
+        "totalsegmentator_organs": ["colon"],
+        "clip_min,clip_max": (-1000, 400),
+    },
+}
+
+#: Extra files that go with a collection but live outside TCIA.
+SUPPLEMENTARY_DOWNLOADS = {
+    "tcga-kirc": {
+        "segmentations": {
+            "url": "https://zenodo.org/records/13244892/files/kidney-ct.zip?download=1",
+            "description": "AI and radiologist-reviewed kidney/tumor segmentations "
+                           "(Scientific Reports, 2024).",
+            "filename": "kidney-ct.zip",
+        },
+    },
+}
+
+
+def all_datasets() -> dict:
+    """Every cataloged dataset, keyed by its short name."""
+    catalog = {}
+    for key, info in tcia_dataset_to_info.items():
+        entry = dict(info)
+        entry.setdefault("collection", key.upper())
+        entry.setdefault("curated", True)
+        catalog[key] = entry
+    for key, info in EXTRA_CT_COLLECTIONS.items():
+        entry = dict(info)
+        entry.setdefault("curated", False)
+        catalog[key] = entry
+    return catalog
+
+
+def normalize_name(name: str) -> str:
+    """Accept ``TCGA-KIRC``, ``tcga_kirc`` or ``TCGA KIRC`` for the same dataset."""
+    return str(name).strip().lower().replace("_", "-").replace(" ", "-")
+
+
+def get_dataset_info(name: str) -> dict:
+    """Look up one dataset. Raises :class:`KeyError` with suggestions."""
+    catalog = all_datasets()
+    key = normalize_name(name)
+    if key in catalog:
+        return {"name": key, **catalog[key]}
+
+    # Allow the TCIA collection name itself, e.g. "NSCLC-Radiomics".
+    for candidate, info in catalog.items():
+        if normalize_name(info.get("collection", candidate)) == key:
+            return {"name": candidate, **info}
+
+    close = [candidate for candidate in catalog if key in candidate or candidate in key]
+    hint = f" Did you mean: {', '.join(sorted(close))}?" if close else ""
+    raise KeyError(
+        f"Unknown dataset {name!r}.{hint} Use list_datasets() to see the catalog, "
+        "or pass any TCIA collection name directly to download()."
+    )
+
+
+def collection_for(name: str) -> str:
+    """The TCIA collection name for a dataset (falls back to the name itself)."""
+    try:
+        return get_dataset_info(name)["collection"]
+    except KeyError:
+        return str(name)
+
+
+def list_datasets(project: Optional[str] = None):
+    """The catalog as a DataFrame: name, collection, organ, cancer type."""
+    import pandas as pd
+
+    rows = []
+    for key, info in sorted(all_datasets().items()):
+        rows.append({
+            "name": key,
+            "collection": info.get("collection", key.upper()),
+            "project": info.get("project", ""),
+            "organ": info.get("cancer_organ", ""),
+            "cancer_type": info.get("cancer_type", ""),
+            "curated_settings": bool(info.get("curated")),
+            "organs_to_segment": ", ".join(info.get("totalsegmentator_organs") or []),
+            "clip_window": str(info.get("clip_min,clip_max", "")),
+            "description": info.get("description", ""),
+        })
+    frame = pd.DataFrame(rows)
+    if project:
+        frame = frame[frame["project"] == project].reset_index(drop=True)
+    return frame

ctkit/features.py

@@ -0,0 +1,177 @@
+"""Radiomic feature extraction with PyRadiomics.
+
+PyRadiomics accepts SimpleITK images directly, so features are computed from
+the in-memory volume without writing the processed image to disk first.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import tempfile
+from typing import TYPE_CHECKING, Any, Optional, Union
+
+import numpy as np
+
+from .validation import Labels
+
+if TYPE_CHECKING:  # pragma: no cover - import only for type checkers
+    from .image import RadiologyImage
+
+logger = logging.getLogger(__name__)
+
+#: PyRadiomics settings used in the protocol. ``resampledPixelSpacing`` is set
+#: per call from the image dimensionality.
+DEFAULT_RADIOMICS_PARAMS = {
+    "imageType": {"Original": {}},
+    "setting": {
+        "binWidth": 25,
+        "resampledPixelSpacing": [1, 1, 1],
+        "interpolator": "sitkBSpline",
+        "normalize": False,
+        "padDistance": 5,
+    },
+}
+
+
+def default_params(dimensionality: str = "3D") -> dict:
+    """Protocol defaults, with the resampling grid matched to `dimensionality`."""
+    params = {
+        "imageType": {key: dict(value) for key, value in DEFAULT_RADIOMICS_PARAMS["imageType"].items()},
+        "setting": dict(DEFAULT_RADIOMICS_PARAMS["setting"]),
+    }
+    if dimensionality == "2D":
+        params["setting"]["resampledPixelSpacing"] = [1, 1]
+        params["setting"]["force2D"] = True
+    return params
+
+
+def extract_features(
+    image: Union["RadiologyImage", Any],
+    labels: Labels = (1, 2),
+    params: Optional[Union[str, dict]] = None,
+    mask: Optional[Any] = None,
+    drop_diagnostics: bool = False,
+) -> dict:
+    """Extract features from one image/mask pair.
+
+    Parameters
+    ----------
+    image:
+        A :class:`~ctkit.image.RadiologyImage`, or anything
+        :func:`~ctkit.io.load_image` accepts.
+    labels:
+        Mask values that make up the region of interest. Several values are
+        merged into a single region before extraction, so ``(1, 2)`` measures
+        organ and tumor together; pass ``2`` for tumor only.
+    params:
+        Path to a PyRadiomics parameter YAML, or a settings dict. Defaults to
+        :func:`default_params`.
+    drop_diagnostics:
+        Remove the ``diagnostics_*`` provenance entries from the result.
+
+    Returns
+    -------
+    dict
+        Feature name to value, plus ``series_id`` when the input carries one.
+    """
+    from radiomics import featureextractor
+
+    from .image import RadiologyImage
+    from .io import nifti_to_sitk
+
+    if isinstance(image, RadiologyImage):
+        radiology_image = image
+    else:
+        radiology_image = RadiologyImage(image, mask=mask)
+
+    if radiology_image.mask is None:
+        raise ValueError(
+            f"{radiology_image.series_id or 'image'}: radiomics needs a mask defining "
+            "the region of interest."
+        )
+
+    dimensionality = "2D" if radiology_image.ndim < 3 else "3D"
+    sitk_image = nifti_to_sitk(radiology_image.image)
+    sitk_mask, label = _merge_labels(radiology_image, labels)
+
+    extractor = _build_extractor(
+        featureextractor, params if params is not None else default_params(dimensionality)
+    )
+
+    with _quiet_radiomics():
+        features = extractor.execute(sitk_image, sitk_mask, label=label)
+
+    result = {
+        key: (float(value) if isinstance(value, (np.floating, np.integer)) else value)
+        for key, value in features.items()
+        if not (drop_diagnostics and key.startswith("diagnostics_"))
+    }
+    if radiology_image.series_id:
+        result = {"series_id": radiology_image.series_id, **result}
+    return result
+
+
+def _merge_labels(radiology_image: "RadiologyImage", labels: Labels):
+    """Collapse the requested labels into a single region valued 1."""
+    from .io import nifti_to_sitk
+
+    if isinstance(labels, (int, np.integer)):
+        wanted = [int(labels)]
+    else:
+        wanted = [int(value) for value in labels]
+
+    mask_data = np.rint(radiology_image.mask_array).astype(np.int32)
+    present = set(int(value) for value in np.unique(mask_data)) - {0}
+    missing = [value for value in wanted if value not in present]
+    if missing and len(missing) == len(wanted):
+        raise ValueError(
+            f"{radiology_image.series_id or 'image'}: none of the labels {wanted} are "
+            f"in the mask (it contains {sorted(present) or 'nothing'})."
+        )
+    if missing:
+        logger.debug(
+            "%s: labels %s absent from the mask; extracting from %s.",
+            radiology_image.series_id or "image", missing,
+            [value for value in wanted if value in present],
+        )
+
+    merged = np.isin(mask_data, wanted).astype(np.uint8)
+
+    import nibabel as nib
+
+    mask_image = nib.Nifti1Image(merged, radiology_image.mask.affine, radiology_image.mask.header)
+    return nifti_to_sitk(mask_image), 1
+
+
+def _build_extractor(featureextractor, params: Union[str, dict]):
+    if isinstance(params, str):
+        if not os.path.exists(params):
+            raise FileNotFoundError(f"PyRadiomics parameter file not found: {params}")
+        return featureextractor.RadiomicsFeatureExtractor(params)
+
+    import yaml
+
+    # PyRadiomics only reads a nested imageType/featureClass/setting structure
+    # from a file, so a dict is written to a short-lived temporary file.
+    with tempfile.TemporaryDirectory(prefix="ctkit_radiomics_") as tmp:
+        path = os.path.join(tmp, "params.yaml")
+        with open(path, "w") as handle:
+            yaml.safe_dump(params, handle, sort_keys=False, default_flow_style=False)
+        return featureextractor.RadiomicsFeatureExtractor(path)
+
+
+class _quiet_radiomics:
+    """Silence PyRadiomics' very chatty per-image logging."""
+
+    def __enter__(self):
+        import radiomics
+
+        self._level = radiomics.logger.level
+        radiomics.logger.setLevel(logging.ERROR)
+        return self
+
+    def __exit__(self, *exc_info) -> None:
+        import radiomics
+
+        radiomics.logger.setLevel(self._level)