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.