File size: 9,114 Bytes
bcc97ac 2f0c734 bcc97ac 2f0c734 bcc97ac 2f0c734 bcc97ac 2f0c734 bcc97ac 2f0c734 bcc97ac |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 |
---
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**. |