https://github.com/genentech/topological_prm_for_lunghrct
Lung image analysis pipeline for topological PRM maps
https://github.com/genentech/topological_prm_for_lunghrct
copd hrct lung minkowski-functionals parametric-response-mapping topological-data-analysis
Last synced: 3 days ago
JSON representation
Lung image analysis pipeline for topological PRM maps
- Host: GitHub
- URL: https://github.com/genentech/topological_prm_for_lunghrct
- Owner: Genentech
- License: apache-2.0
- Created: 2023-06-28T21:21:43.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-02-27T18:02:17.000Z (8 months ago)
- Last Synced: 2025-03-30T01:32:01.586Z (7 months ago)
- Topics: copd, hrct, lung, minkowski-functionals, parametric-response-mapping, topological-data-analysis
- Language: Python
- Homepage:
- Size: 182 KB
- Stars: 2
- Watchers: 4
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Topological Parametric Response Mapping for Lung HRCT
## Description
A pipeline for analyzing inspiratory and expiratory HRCT lung images through quantitative metrics and 3D maps. Currently, this pipeline provides 3D parametric response maps (PRM), global topology metrics, and 3D maps of local topology metrics for regions characterized by normal lung structure, emphysema, functional small airways disease (fSAD), and emptying emphysema. Pipeline can also process global and local topology for an existing PRM map. Analysis methods are adapted from methodology described in Hoff et al. (2017)1.
NOTE: this pipeline calculates topology metrics from Minkowski functionals computed with the QuantImPy Python package2, which may differ from Minkowski measures in Hoff et al. (2017)1.
## Table of contents
1. [Installation](#1-installation)
2. [Usage](#2-usage)
3. [Outputs](#3-outputs)
4. [Authors and acknowledgement](#4-authors-and-acknowledgment)
## 1. Installation
The following instructions are intended for Mac and Linux systems. Prior to installation, download or clone this git repository. This pipeline is written for use with Python 3.9.1.
### 1.1 Conda installation
We recommend creating a virtual environment to insall the necessary Python libraries required to run this pipeline. A conda distribution is required to create a virtual environment. If conda is already installed on your system, skip this section.
#### 1.1.1 Conda installation: Intel Mac and Linux systems
The Anaconda or Miniconda distirbution can be installed. To install the Anaconda distribution, follow the instructions in this [link](https://docs.conda.io/projects/continuumio-conda/en/latest/user-guide/install/index.html). To install the Miniconda distribution, follow the instructions in this [link](https://docs.anaconda.com/free/anaconda/install/)
#### 1.1.2 Conda installation: Apple Silicon Mac
Install Miniforge using step 2 of this [link](https://caffeinedev.medium.com/how-to-install-tensorflow-on-m1-mac-8e9b91d93706)
### 1.2 Install Python packages in a virtual environment
#### 1.2.1 Create a virual environment
Create a conda virtual environment using the following command in terminal, where `` can be any environment name of your choosing.
```bash
conda create --name python=3.9.1
```
Confirm that the environment is available:
```bash
conda env list
```
To activate the environment:
```bash
conda activate
```
#### 1.2.2 Install Python packages
Before installing packages, activate the virtual environment. The list of required packages can be found in `setup/requirements.txt`. To install the pacakges, navigate to the main program directory in terminal and execute the following command.
```bash
pip install -r setup/requirements.txt
```
## 2. Usage
The pipeline currently takes the following required inputs (supported file formats: .nii):
- Registered inspiratory and expiratory HRCTs in hounsfield units (HU) AND segmentation mask with positive integers denoting regions of lung parenchyma.
OR
- Existing PRM map with binned regions labeled as {1,2,3,4} AND segmentation mask with positive integers denoting regions of lung parenchyma.
OR
- Existing PRM map with binned regions labeled as {1,2,3,4} and regions outside of lung parenchyma labeled as 0.
### 2.1 Create subject configuration file(s)
Configuration (config) files (.ini) specify subject ID, inspiratory HRCT file path, expiratory file path, input PRM map (if available), and the path to save output files to. If the path to an existing PRM map is specified in the config file, the pipeline will skip generation of PRM map from HRCTs.
`config/config_demo.ini` shows config file structure and fields. If an existing PRM map is provided, the required fields are: subjID, inFilePrm, and outDir.
`scripts/write_config.py` can be used to create a config file for a single subject and can be adapted to create config files for a batch of subjects.
If an existing PRM map is provided, the required fields are: `subjID`, `inFilePrm`, and `outDir`. If `inFileMask` is provided, the input mask will be used. If not, a mask will be generated from binned voxels of the input PRM map.
If no existing PRM map is provided, the required fields are: `subjID`, `inFileExp`, `inFileInspReg`, `inFileMask`, and `outDir`.
### 2.2 Process a single subject
To process a single subject run, active your virtual environment, navigate to the main program directory, and run the following command.
```bash
python main.py --config
```
### 2.3 Process a batch of subjects
First create a config file for each subejct and place them all in one directory. To process the batch of subjects, activate your virtual environment, navigate to the main program directory in terminal, and run the following command in terminal.
```bash
python main.py --batch --config
```
### 2.4 Compute only PRM maps and global topology metrics
Processing only PRM maps and global topology metrics significantly cuts down computation time. This is useful if local topology maps are not needed. To do this, add the following flag in the command line when processing a single subject or a batch: `--glbl`
```bash
python main.py --glbl --config
```
or
```bash
python main.py --glbl --batch --config
```
## 3. Outputs
- PRM
- Combined 3D PRM map of normal lung structure, emphysema, fSAD, and emptying emphysema (.nii). PRM classifications are assigned the following values -> normal: 1, fSAD: 2, emphysema: 3, emptying emphysema: 4
- Colorcoded PRM image of a representative slice along the anterior-posterior dimension (.png)
- Percentage of lung parenchyma voxels in each PRM classification (.csv)
- Topology
- Separate 3D maps of local topology density metrics for voxels characterized by normal lung structure, emphysema, fSAD, and emptying emphysema (.nii)
- Images of surface area density for a reprsentative slice along the anterior-posterior for all PRM maps (.png)
- Global and mean local topology metrics and whole-lung mean local topology metrics for each PRM classification (.csv)
- Note: output topology density metrics have the following units (pipeline assumes voxel dimensions in HRCT NIfTI header are in mm)
- Fractional volume (volume density): unitless
- Surface area density: m-1
- Integral mean curvature density: m-2
- Euler-Poincare characteristic density: unitless
## 4. Authors and acknowledgment
Sources:
>1. Hoff, B.A., Pompe, E., Galbán, S. et al. CT-Based Local Distribution Metric Improves Characterization of COPD. Sci Rep 7, 2999 (2017). https://doi.org/10.1038/s41598-017-02871-1
>2. Arnout M.P. Boelens, and Hamdi A. Tchelepi, QuantImPy: Minkowski functionals and functions with Python. SoftwareX, Volume 16 100823, ISSN 2352-7110 (2021). https://doi.org/10.1016/j.softx.2021.100823
Related publications:
>1. Geng, R., Grimbaldeston, M.A., Coimbra, A., Bell, L.C. et al. PRM and Topological Imaging Features From HRCT Can Identify PRISm Patients Who Progress to COPD. Annual ATS meeting, Washington D.C., May 19-24, 2023. Oral Presentation.
Developers: Aryil Bechtel, Ruiqi Geng
Credits: Laura Bell
Correspondence: Laura Bell (bell.laura@gene.com), Aryil Bechtel (aryilbechtel@gmail.com)