DT_Lung

<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. 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^1,2,4, Sumin Kim MSc^1,2,4, Thomas Borrillo MHSc^1,2, Abby McCaig BSc¹⁻³, Haaniya Ahmed^1,2, Youxue Ren MSc^1,2, Olivia Hough PhD^1,2, Luca Orsini MD^1,2,8, Bonnie T. Chao PhD^1,2, Micheal McInnis MD⁹, Marcelo Cypel MD^1-3,10, Mingyao Liu MD^1-3,10, Jonathan C. Yeung MD^1-3,10, Lorenzo Del Sorbo MD^1,2,8, Shaf Keshavjee* MD^1-3,10, and Andrew T. Sage* PhD^1-3,10 </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^nd hour lung function using 1^st hour baseline data)
  • A1F50_A3F50 – Collection of GRU models for static digital lung forecasting (Forecast 3^rd hour lung function using 1^st hour baseline data)
  • A1F50A2F50_A3F50 – Collection of GRU models for dynamic digital lung forecasting (Forecast 3^rd hour lung function using 1^st and 2^nd 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.

1. 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^rd hour lung X-ray derived features using 1^st hour baseline data)
  • models_dynamic – XGBoost models to create dynamic digital lung image features (Forecast 3^rd hour lung X-ray derived features using 1^st and 2^nd hour observed data)

1. 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.

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.