README.md

---
license: cc-by-nc-nd-4.0
language:
- en
tags: [digital-twin, ex vivo lung, time-series, forecasting, regression]

---

<h1 align="center">
  <span style="font-size:32px">
  Digital Twins of Ex Vivo Human Lungs
  </span>
</h1>

<p align="center">
  
  <a href="https://sage-lab-ai.github.io/DT_Lung/">
    <img alt="Project Page"
         src="https://img.shields.io/badge/Project-Page-green" />
  </a>
  <a href="https://github.com/Sage-Lab-ai/DT_Lung">
    <img alt="GitHub Code"
         src="https://img.shields.io/badge/GitHub-Code-black?logo=github" />
  </a>
  <a href="https://huggingface.co/SageLabUHN/DT_Lung">
    <img alt="Hugging Face Model"
         src="https://img.shields.io/badge/HuggingFace-Model-yellow?logo=huggingface" />
  </a>
  <a href="https://huggingface.co/datasets/SageLabUHN/DT_Lung_Demo_Data">
    <img alt="Hugging Face Dataset"
         src="https://img.shields.io/badge/HuggingFace-Dataset-yellow?logo=huggingface" />
  </a>

</p>

<p align="center">
  <a href="https://colab.research.google.com/drive/1IrzccQ09mP5amxQTZy07n4LgLSC2r1uj?usp=sharing">
    <img alt="Colab: DT Lung Demo"
         src="https://img.shields.io/badge/Colab-DT%20Lung%20Demo-orange?logo=google-colab" />
  </a>
  
  <a href="https://dt-lung.streamlit.app/">
    <img alt="Streamlit Web App"
         src="https://img.shields.io/badge/Streamlit-Web%20App-red?logo=streamlit" />
  </a>
  
  <a href="https://hub.docker.com/u/sagelabuhn">
  <img alt="Docker Hub"
       src="https://img.shields.io/badge/Docker-Hub-blue?logo=docker&logoColor=white" />
  </a>
</p>

## Purpose

This is the official model repository that accompanies [Digital Twin of Ex Vivo Human Lungs Project](https://github.com/Sage-Lab-ai/DT_Lung). This repository contains *a full collection of multi-modal models for creating digital twins of ex vivo human lungs*.  

**Authors**  
<div align="center">
<span style="font-size:16px">
Xuanzi Zhou MHSc¹⁻³, Bo Wang PhD⁴⁻⁷, Yiyang Wei BCS¹⁻³, Serena Hacker MScAC<sup>1,2,4</sup>, Sumin Kim MSc<sup>1,2,4</sup>,  
Thomas Borrillo MHSc<sup>1,2</sup>, Abby McCaig BSc¹⁻³, Haaniya Ahmed<sup>1,2</sup>, Youxue Ren MSc<sup>1,2</sup>,  
Olivia Hough PhD<sup>1,2</sup>, Luca Orsini MD<sup>1,2,8</sup>, Bonnie T. Chao PhD<sup>1,2</sup>, Micheal McInnis MD⁹,  
Marcelo Cypel MD<sup>1-3,10</sup>, Mingyao Liu MD<sup>1-3,10</sup>, Jonathan C. Yeung MD<sup>1-3,10</sup>,  
Lorenzo Del Sorbo MD<sup>1,2,8</sup>, Shaf Keshavjee* MD<sup>1-3,10</sup>, and Andrew T. Sage* PhD<sup>1-3,10</sup>  
</span>
</div>

<div align="center">
<span style="font-size:14px">
1. Latner Thoracic Research Laboratories, Toronto General Hospital Research Institute, University Health Network, Toronto, ON, Canada <br> 
2. Toronto Lung Transplant Program, Ajmera Transplant Centre, University Health Network, Toronto, ON, Canada  <br>
3. Institute of Medical Science, University of Toronto, Toronto, ON, Canada  <br>
4. Department of Computer Science, University of Toronto, Toronto, ON, Canada  <br>
5. Peter Munk Cardiac Centre, University Health Network, Toronto, ON, Canada <br> 
6. Department of Laboratory Medicine and Pathobiology, University of Toronto, Toronto, ON, Canada  <br>
7. Vector Institute, Toronto, ON, Canada  <br>
8. Interdepartmental Division of Critical Care Medicine, Medical and Surgical Intensive Care Unit, University Health Network, Toronto, ON, Canada  <br>
9. Department of Medical Imaging, Temerty Faculty of Medicine, University of Toronto, University Health Network, Toronto, ON, Canada  <br>
10. Department of Surgery, Temerty Faculty of Medicine, University of Toronto, Toronto, ON, Canada <br> 
</span>
</div>

<div align="center">
<small>*Co-Senior authors</small>
</div>


---

## Highlights
- ✅ Trained on the world's largest ex vivo lung function dataset  
- ⚡ Fast inference: Creating a digital lung within minutes
- 📊 Predicts over 75 multi-modal lung functional parameters including lung physiology, biochemistry, images, protein and transcriptomic markers.
- 🔄 Supports both static (single‑timepoint) and dynamic (continuous recalibration) forecasting  

---

## Available Models
The DT model is built using two machine learning model architectures: gated recurrent unit (GRU) and XGBoost (XGB).

1. **GRU‑based Time‑Series Models**

  - `DT_Lung/GRU`
    - `A1F50_A2F50` – Collection of GRU models for static digital lung forecasting (Forecast 2<sup>nd</sup> hour lung function using 1<sup>st</sup> hour baseline data)
    - `A1F50_A3F50` – Collection of GRU models for static digital lung forecasting (Forecast 3<sup>rd</sup> hour lung function using 1<sup>st</sup> hour baseline data)
    - `A1F50A2F50_A3F50` – Collection of GRU models for dynamic digital lung forecasting (Forecast 3<sup>rd</sup> hour lung function using 1<sup>st</sup> and 2<sup>nd</sup> hour observed data)

     Legend: `A = assessment period`, `F = first breaths`, `numbers = the number of breaths included` <br>
     *Note: everything before _ is included as input to the model, and everything after _ is forecasted by the model.* <br>
     Each folder contains the best-performing GRU models resulting from our hyperparameter tuning for the specified digital lung setup.

2. **XGBoost Tabular Regressors** 

   Each folder below contains the best-performing XGBoost models resulting from our hyperparameter tuning for the specified lung function parameters for each digital lung setup.

  - `DT_Lung/XGB` – Collection of XGBoost models for multiple data modalities
    - `Hourly` – XGBoost models for predicting hourly lung functional parameters (e.g., oxygenation level, compliance, pH, etc.)
      - `H1_to_H2`: Models for static digital lung forecasting (Forecast 2nd hour lung function using 1st hour baseline data)
      - `H1_to_H3`: Models for static digital lung forecasting (Forecast 3rd hour lung function using 1st hour baseline data)
      - `H1_H2_to_H3`: Models for dynamic digital lung forecasting (Forecast 3rd hour lung function using 1st and 2nd hour observed data)
    - `Protein` – XGBoost models for predicting protein markers (e.g., interleukin-8, interleukin-6, etc.)
      - `H1_to_H2`: Models for static digital lung forecasting (Forecast 2nd hour lung function using 1st hour baseline data)
      - `H1_to_H3`: Models for static digital lung forecasting (Forecast 3rd hour lung function using 1st hour baseline data)
      - `H1_predH2_to_H3`: Models for static digital lung forecasting (Forecast 3rd hour lung function using 1st hour baseline data and predicted 2nd hour data)
      - `H1_H2_to_H3`: Models for dynamic digital lung forecasting (Forecast 3rd hour lung function using 1st and 2nd hour obsereved data)
    - `Transcriptomics` – XGBoost models for predicting transcriptomic pathways (e.g., TGF-β, apoptosis, etc.)
      - `static_forecasting`: Models for static digital lung forecasting of gene enrichment scores (Forecast post-perfusion gene enrichment scores using baseline data)
      - `dynamic_forecasting`: Models for dynamic digital lung forecasting of gene enrichment scores (Forecast post-perfusion gene enrichment scores using hourly observed data)
      

  - `DT_Lung/XGB_PC` – Collection of XGBoost models for lung x-ray images
    - `models_static` – XGBoost models to create static digital lung image features (Forecast 3<sup>rd</sup> hour lung X-ray derived features using 1<sup>st</sup> hour baseline data)
    - `models_dynamic` – XGBoost models to create dynamic digital lung image features (Forecast 3<sup>rd</sup> hour lung X-ray derived features using 1<sup>st</sup> and 2<sup>nd</sup> hour observed data)

3. Folders with the `.tar.gz` extension are provided to make model download and distribution easier. Their contents are identical to those in the corresponding folders without the `.tar.gz` extension. 

---

## Downloading Models

### Option 1: Download individual models

```
from huggingface_hub import hf_hub_download

gru_model_dir = hf_hub_download(
    repo_id="SageLabUHN/DT_Lung",
    filename="GRU/A1F50_A2F50/Dy_comp.pt", # example path, please modify accordingly
    local_dir="DT_Lung/models"  # example path, specify your local directory
)

print(f"Model downloaded to: {gru_model_dir}")
```

### Option 2: Download all models to a specific folder

```
from huggingface_hub import snapshot_download

model_dir = snapshot_download(
    repo_id="SageLabUHN/DT_Lung",
    local_dir="DT_Lung/Model", # make sure the Model folder is in the project root dir
)

print(f"Models downloaded to: {model_dir}")
```

Alternatively, you can manually download the models from the [Hugging Face repository page](https://huggingface.co/SageLabUHN/DT_Lung/tree/main).

## Intended Use

**Intended for**  
- Research and education use 

**Not for**  
- Clinical decisions without further validation  
- Commercial deployment (non‑commercial only) 

---

## License

This repository and all model weights are released under the **Creative Commons Attribution‑NonCommercial‑ShareAlike 4.0 International (CC BY‑NC‑SA 4.0)** license.  
Commercial use is **prohibited**.