metadata
license: cc-by-nc-nd-4.0
language:
- en
tags:
- ensemble
- medical-imaging
- ipf
- survival-prediction
- ct-scan
ORACLE-IPF: CT-based IPF Survival Prediction
This repository hosts an ensemble of 5 models trained for idiopathic pulmonary fibrosis (IPF) survival analysis using chest CT scans.
Repository Structure
ORACLE-IPF/
├── README.md # Model card (this file)
├── inference/ # Inference pipeline
│ ├── README.md # Inference documentation
│ ├── checkpoints/ # Pre-trained model weights
│ │ ├── weight1.ckpt # Ensemble model 1
│ │ ├── weight2.ckpt # Ensemble model 2
│ │ ├── weight3.ckpt # Ensemble model 3
│ │ ├── weight4.ckpt # Ensemble model 4
│ │ └── weight5.ckpt # Ensemble model 5
│ ├── config/
│ │ ├── checkpoints.yaml # Checkpoint configuration
│ │ └── patients.yaml # Sample patient configuration
│ ├── requirements.txt # Python dependencies
│ ├── run_inference.sh # Shell script to run inference
│ ├── src/
│ │ ├── __init__.py
│ │ ├── ensemble.py # Ensemble prediction logic
│ │ └── inference.py # Main inference script
│ └── tests/
│ ├── __init__.py
│ └── test_results.py # Result validation tests
│
└── training/ # Training pipeline
├── README.md # Training documentation
├── .gitignore # Git ignore rules
├── .huggingfaceignore # HuggingFace ignore rules
├── config/
│ └── train_config.yaml # Training hyperparameters
├── scripts/
│ ├── prepare_data.sh # Data preparation script
│ └── train.sh # Training launch script
├── training_data_sample/ # Sample training data (de-identified)
│ └── ct{1,2,3}/ # Sample CT cases
│ ├── ct.npy # CT volume (D, H, W)
│ ├── meta.json # DICOM metadata
│ ├── LungTexture.Obj.Honeycomb.npy # Honeycomb pattern mask
│ ├── LungTexture.Obj.Reticular.npy # Reticular pattern mask
│ └── LungTexture.Obj.Normal.npy # Normal lung mask
└── src/
├── __init__.py
├── config.py # Model configuration (ModelArgs)
├── dataset.py # PyTorch dataset for IPF data
├── prepare_masks.py # IPF mask preparation script
├── train.py # Main training script
└── models/
├── __init__.py
├── oracle.py # ORACLE model architecture
├── cumulative_probability_layer.py # Survival probability layer
├── pooling_layer.py # Feature pooling layer
└── regressor.py # Regression head
Model Architecture
- Architecture: ORACLE / ORACLEDoubleDensity
- Backbone: R3D-18 (pretrained on Kinetics-400)
- Input: CT volume (B, 3, 200, 256, 256) with clinical features (sex, age)
- Output: The model outputs cumulative survival probabilities at annual horizons from 1 to 5 years, plus one additional probability for the subsequent time interval beyond 5 years (B, 6)
Data Format
Input Data
- CT volume: 3D numpy array (D, H, W) in Hounsfield Units
- Lung texture masks (for training only): Binary masks for Honeycomb, Reticular, and Normal patterns (obtained from AVIEW, Coreline, Seoul, Korea)
- Metadata: Patient demographics (sex, age at CT scan)
Processed Data
- IPF mask (i.e., fibrosis mask): Union of Honeycomb and Reticular patterns
- Fibrosis density: Ratio computed from Fibrosis (Honeycomb or Reticular) and Normal masks
Access and Usage Conditions
The distribution of these model weights is subject to the following conditions. By requesting and receiving access, you agree that:
- The weights are provided solely for non-commercial research and educational purposes.
- Any attempt to use the model for commercial applications, product development, or deployment beyond academic research requires separate written permission from the authors.
- Users must respect privacy standards and must not attempt to identify or re-identify any individual from the model outputs.
- Any use of the model in academic work must include a formal citation of the associated publication:
[TBU: DOI]
- The model has been developed for academic and research purposes and has not undergone regulatory validation for clinical deployment.
- The authors and affiliated institution retain all intellectual property rights and disclaim any responsibility for misuse.
License
This work is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License.