README.md

---
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](https://creativecommons.org/licenses/by-nc-nd/4.0/).