ctkit 0.1.0__tar.gz

ctkit-0.1.0/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, Pachter Lab
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ctkit-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: ctkit
+Version: 0.1.0
+Summary: A toolkit for reproducible CT image processing for AI and radiomics.
+Author-email: Joseph Rich <josephrich98@gmail.com>
+Maintainer-email: Joseph Rich <josephrich98@gmail.com>
+License: BSD 2-Clause License
+        
+        Copyright (c) 2026, Pachter Lab
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this
+           list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice,
+           this list of conditions and the following disclaimer in the documentation
+           and/or other materials provided with the distribution.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+        
+Project-URL: Homepage, https://github.com/pachterlab/ctkit
+Project-URL: Source, https://github.com/pachterlab/ctkit
+Project-URL: Issues, https://github.com/pachterlab/ctkit/issues
+Keywords: AI,bioinformatics,deep learning,medicine,radiology,radiomics,CT,DICOM,NIfTI,TCIA,medical imaging
+Classifier: Environment :: Console
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: matplotlib
+Requires-Dist: tqdm
+Requires-Dist: requests
+Requires-Dist: pydicom
+Requires-Dist: highdicom
+Requires-Dist: nibabel
+Requires-Dist: scipy
+Requires-Dist: simpleitk
+Requires-Dist: pyyaml
+Requires-Dist: openpyxl
+Requires-Dist: pydantic>=2
+Provides-Extra: segmentation
+Requires-Dist: TotalSegmentator; extra == "segmentation"
+Provides-Extra: radiomics
+Requires-Dist: pyradiomics; extra == "radiomics"
+Provides-Extra: notebook
+Requires-Dist: ipython; extra == "notebook"
+Requires-Dist: ipykernel; extra == "notebook"
+Requires-Dist: ipywidgets; extra == "notebook"
+Provides-Extra: dicom
+Requires-Dist: dcm2niix; extra == "dicom"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: all
+Requires-Dist: TotalSegmentator; extra == "all"
+Requires-Dist: pyradiomics; extra == "all"
+Requires-Dist: ipython; extra == "all"
+Requires-Dist: ipykernel; extra == "all"
+Requires-Dist: ipywidgets; extra == "all"
+Requires-Dist: dcm2niix; extra == "all"
+Dynamic: license-file
+
+# ctkit
+
+CT image processing for AI and radiomics. Makes CT processing simple and reproducible.
+
+![pipeline](https://github.com/pachterlab/ctkit/blob/main/figures/Fig1.png?raw=true)
+
+## Installation
+
+```sh
+pip install ctkit
+```
+
+To install pyradiomics and TotalSegmentator:
+
+```sh
+pip install 'ctkit[all]'
+```
+
+## Quick start
+
+```python
+import ctkit
+
+ctkit.download("tcga-kirc", "data/tcga_kirc_raw", limit=20)
+
+data = ctkit.Dataset("data/tcga_kirc_raw")
+data.filter(min_slices=25).process("tcga-kirc", out_dir="data/processed")
+# the tcga-kirc protocol segments the kidneys, so this one needs ctkit[all]
+```
+
+## The pipeline
+
+| Step | What it does | Why it matters |
+| --- | --- | --- |
+| `filter` | Drop series that fail quality control, keeping a pass/fail table | Localizers, reformats and 4D series are not the acquisition you meant to analyze, and finding that out after processing wastes the expensive part |
+| `check` | Run the same quality control without dropping anything: a result for one series, the whole table for a cohort | The measurements behind every pass and fail, which is what an exclusion criterion has to cite |
+| `orient` | Reorient to canonical RAS | Archives disagree on storage order, so two scans of the same anatomy can arrive mirrored or transposed |
+| `segment` | TotalSegmentator organ masks, merged with any tumor mask | Gives a region of interest when the collection ships without one |
+| `clip` | Clamp to an intensity window (e.g. −200/300 HU) | Spends the dynamic range on the tissue you care about; caps metal artifacts |
+| `resample` | Resample to a fixed voxel size in mm | Until scans share a voxel grid, a millimeter of anatomy is a different number of voxels in each one |
+| `select_slice` | Keep one axial slice: the one with the most mask, or the one you name (2D mode) | How a 3D series becomes a 2D training example |
+| `apply_mask` | Blank outside the ROI, crop to its bounding box | Removes irrelevant anatomy and makes volumes small enough to hold a cohort in memory |
+| `crop_to_content` | Crop to the voxels above a threshold — air, once intensities are clipped | Trims the air around the body when there is no mask to crop to |
+| `standardize_size` | Center-crop/pad to a common array shape | Fixed-size tensors, without rescaling the anatomy |
+| `normalize` | Z-score, per volume or per dataset | Stops a model keying on per-scan intensity offsets |
+| `save` | Write the processed series to disk | Makes the processed dataset available for training and sharing |
+| `process` | Run the whole pipeline, with a saved configuration | Reproducibility and collaboration |
+| `radiomics` | Extract radiomics features | For radiomic analysis. Does not require many steps above. |
+
+## Reproducibility
+
+Every run that writes a cohort to disk writes `processing_config.yaml` next to
+it. To reproduce a dataset, or to hand one to a collaborator:
+
+```python
+ctkit.Dataset("data/raw").process(
+    "data/processed/processing_config.yaml", out_dir="rerun"
+)
+```
+
+`process` takes a protocol as a `ProcessingConfig`, a path to a saved one, or
+the name of a collection whose curated protocol to use.
+
+## Notebooks
+
+[`notebooks/quickstart.ipynb`](notebooks/quickstart.ipynb) walks through the
+package end to end: pick a collection, download it, filter it, process it, and
+extract features.
+
+## Relationship to tcia-radiology-processing
+
+This package grew out of the protocol in
+[pachterlab/tcia-radiology-processing](https://github.com/pachterlab/tcia-radiology-processing),
+which documents the same pipeline as a step-by-step notebook. That repository
+remains the written protocol; `ctkit` is the library implementation of it.
+
+## License
+
+BSD 2-Clause. See [LICENSE](LICENSE).
+
+---
+
+Issues and pull requests welcome.

ctkit-0.1.0/README.md

@@ -0,0 +1,83 @@
+# ctkit
+
+CT image processing for AI and radiomics. Makes CT processing simple and reproducible.
+
+![pipeline](https://github.com/pachterlab/ctkit/blob/main/figures/Fig1.png?raw=true)
+
+## Installation
+
+```sh
+pip install ctkit
+```
+
+To install pyradiomics and TotalSegmentator:
+
+```sh
+pip install 'ctkit[all]'
+```
+
+## Quick start
+
+```python
+import ctkit
+
+ctkit.download("tcga-kirc", "data/tcga_kirc_raw", limit=20)
+
+data = ctkit.Dataset("data/tcga_kirc_raw")
+data.filter(min_slices=25).process("tcga-kirc", out_dir="data/processed")
+# the tcga-kirc protocol segments the kidneys, so this one needs ctkit[all]
+```
+
+## The pipeline
+
+| Step | What it does | Why it matters |
+| --- | --- | --- |
+| `filter` | Drop series that fail quality control, keeping a pass/fail table | Localizers, reformats and 4D series are not the acquisition you meant to analyze, and finding that out after processing wastes the expensive part |
+| `check` | Run the same quality control without dropping anything: a result for one series, the whole table for a cohort | The measurements behind every pass and fail, which is what an exclusion criterion has to cite |
+| `orient` | Reorient to canonical RAS | Archives disagree on storage order, so two scans of the same anatomy can arrive mirrored or transposed |
+| `segment` | TotalSegmentator organ masks, merged with any tumor mask | Gives a region of interest when the collection ships without one |
+| `clip` | Clamp to an intensity window (e.g. −200/300 HU) | Spends the dynamic range on the tissue you care about; caps metal artifacts |
+| `resample` | Resample to a fixed voxel size in mm | Until scans share a voxel grid, a millimeter of anatomy is a different number of voxels in each one |
+| `select_slice` | Keep one axial slice: the one with the most mask, or the one you name (2D mode) | How a 3D series becomes a 2D training example |
+| `apply_mask` | Blank outside the ROI, crop to its bounding box | Removes irrelevant anatomy and makes volumes small enough to hold a cohort in memory |
+| `crop_to_content` | Crop to the voxels above a threshold — air, once intensities are clipped | Trims the air around the body when there is no mask to crop to |
+| `standardize_size` | Center-crop/pad to a common array shape | Fixed-size tensors, without rescaling the anatomy |
+| `normalize` | Z-score, per volume or per dataset | Stops a model keying on per-scan intensity offsets |
+| `save` | Write the processed series to disk | Makes the processed dataset available for training and sharing |
+| `process` | Run the whole pipeline, with a saved configuration | Reproducibility and collaboration |
+| `radiomics` | Extract radiomics features | For radiomic analysis. Does not require many steps above. |
+
+## Reproducibility
+
+Every run that writes a cohort to disk writes `processing_config.yaml` next to
+it. To reproduce a dataset, or to hand one to a collaborator:
+
+```python
+ctkit.Dataset("data/raw").process(
+    "data/processed/processing_config.yaml", out_dir="rerun"
+)
+```
+
+`process` takes a protocol as a `ProcessingConfig`, a path to a saved one, or
+the name of a collection whose curated protocol to use.
+
+## Notebooks
+
+[`notebooks/quickstart.ipynb`](notebooks/quickstart.ipynb) walks through the
+package end to end: pick a collection, download it, filter it, process it, and
+extract features.
+
+## Relationship to tcia-radiology-processing
+
+This package grew out of the protocol in
+[pachterlab/tcia-radiology-processing](https://github.com/pachterlab/tcia-radiology-processing),
+which documents the same pipeline as a step-by-step notebook. That repository
+remains the written protocol; `ctkit` is the library implementation of it.
+
+## License
+
+BSD 2-Clause. See [LICENSE](LICENSE).
+
+---
+
+Issues and pull requests welcome.

ctkit-0.1.0/ctkit/__init__.py

@@ -0,0 +1,144 @@
+"""ctkit: reproducible CT image processing for AI and radiomics.
+
+The package exists so that "how was this image processed?" has an exact,
+runnable answer. A protocol is a :class:`ProcessingConfig`; applying it to one
+scan is :class:`RadiologyImage`, and to a cohort is :class:`Dataset`.
+
+Quick start — construct a cohort or a scan, then call the steps on it::
+
+    import ctkit
+
+    ctkit.download("tcga-kirc", "data/raw", limit=20)
+
+    data = ctkit.Dataset("data/raw")
+    data.filter(min_slices=25).process("tcga-kirc", out_dir="data/processed")
+
+The same steps chain on one scan, modifying it in place::
+
+    scan = ctkit.RadiologyImage("case/imaging.nii.gz", mask="case/segmentation.nii.gz")
+    scan.orient().clip(-200, 300).resample((0.8, 0.8, 3.0)).save("processed/case.nii.gz")
+
+Each step is also a function taking whatever you have — a path, an array, a
+scan, or a cohort::
+
+    ctkit.clip("case/imaging.nii.gz", -200, 300)
+
+and a field of a :class:`ProcessingConfig`, which is what makes a protocol
+something you can print, save to YAML, and publish alongside a paper.
+
+Nothing is written to disk until ``save()``; intermediate volumes only ever
+exist in memory.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import TYPE_CHECKING
+
+__version__ = "0.1.0"
+
+from .api import (
+    apply_mask,
+    check,
+    clip,
+    crop_to_content,
+    filter,
+    normalize,
+    orient,
+    process,
+    radiomics,
+    resample,
+    save,
+    segment,
+    select_slice,
+    standardize_size,
+)
+from .config import ProcessingConfig
+from .constants import tcia_dataset_to_info
+from .dataset import Dataset
+from .datasets import EXTRA_CT_COLLECTIONS, get_dataset_info, list_datasets
+from .image import RadiologyImage
+from .io import dicom_to_nifti, load_image, save_image
+from .metadata import annotate, categorize_phase, categorize_region, summarize
+from .qc import QCCriteria, QCResult, check_series_metadata, check_volume
+
+if TYPE_CHECKING:  # pragma: no cover
+    from . import features, segmentation
+    from .tcia import download, list_collections
+
+__all__ = [
+    "__version__",
+    # pipeline steps, in the order they run
+    "filter",
+    "orient",
+    "segment",
+    "clip",
+    "resample",
+    "select_slice",
+    "apply_mask",
+    "crop_to_content",
+    "standardize_size",
+    "normalize",
+    # whole protocols and output
+    "process",
+    "save",
+    "radiomics",
+    # core
+    "RadiologyImage",
+    "Dataset",
+    "ProcessingConfig",
+    # quality control
+    "QCCriteria",
+    "QCResult",
+    "check",
+    "check_volume",
+    "check_series_metadata",
+    # data access
+    "download",
+    "download_supplementary",
+    "list_collections",
+    "list_datasets",
+    "get_dataset_info",
+    "EXTRA_CT_COLLECTIONS",
+    "tcia_dataset_to_info",
+    # io
+    "load_image",
+    "save_image",
+    "dicom_to_nifti",
+    # metadata
+    "categorize_region",
+    "categorize_phase",
+    "annotate",
+    "summarize",
+    # submodules
+    "features",
+    "segmentation",
+    "tcia",
+    "metadata",
+]
+
+#: Attributes served on first use, so that importing the package does not pull
+#: in `requests`, `pyradiomics` or `matplotlib`.
+_LAZY = {
+    "download": ("tcia", "download"),
+    "download_supplementary": ("tcia", "download_supplementary"),
+    "list_collections": ("tcia", "list_collections"),
+    "download_with_nbia_retriever": ("tcia", "download_with_nbia_retriever"),
+    "get_series": ("tcia", "get_series"),
+    "extract_features": ("features", "extract_features"),
+    "segment_organs": ("segmentation", "segment_organs"),
+}
+_LAZY_MODULES = {"features", "segmentation", "tcia", "io", "qc", "datasets", "metadata"}
+
+
+def __getattr__(name: str):
+    if name in _LAZY:
+        module_name, attribute = _LAZY[name]
+        return getattr(import_module(f".{module_name}", __name__), attribute)
+    if name in _LAZY_MODULES:
+        return import_module(f".{name}", __name__)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list:
+    return sorted(set(__all__) | set(globals()))