{"id":22731098,"url":"https://github.com/genentech/topological_prm_for_lunghrct","last_synced_at":"2026-03-10T11:04:10.061Z","repository":{"id":180795130,"uuid":"659920023","full_name":"Genentech/topological_PRM_for_lungHRCT","owner":"Genentech","description":"Lung image analysis pipeline for topological PRM maps ","archived":false,"fork":false,"pushed_at":"2025-05-18T18:37:00.000Z","size":191,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-10-24T16:54:35.857Z","etag":null,"topics":["copd","hrct","lung","minkowski-functionals","parametric-response-mapping","topological-data-analysis"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Genentech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"citation.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-06-28T21:21:43.000Z","updated_at":"2025-05-18T18:37:03.000Z","dependencies_parsed_at":"2024-12-10T19:21:18.794Z","dependency_job_id":"9c27a872-92f8-408e-9929-556920dd30b4","html_url":"https://github.com/Genentech/topological_PRM_for_lungHRCT","commit_stats":null,"previous_names":["genentech/topological_prm_for_lunghrct"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Genentech/topological_PRM_for_lungHRCT","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Genentech%2Ftopological_PRM_for_lungHRCT","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Genentech%2Ftopological_PRM_for_lungHRCT/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Genentech%2Ftopological_PRM_for_lungHRCT/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Genentech%2Ftopological_PRM_for_lungHRCT/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Genentech","download_url":"https://codeload.github.com/Genentech/topological_PRM_for_lungHRCT/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Genentech%2Ftopological_PRM_for_lungHRCT/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30331644,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T05:25:20.737Z","status":"ssl_error","status_checked_at":"2026-03-10T05:25:17.430Z","response_time":106,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["copd","hrct","lung","minkowski-functionals","parametric-response-mapping","topological-data-analysis"],"created_at":"2024-12-10T19:19:25.437Z","updated_at":"2026-03-10T11:04:10.035Z","avatar_url":"https://github.com/Genentech.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Topological Parametric Response Mapping for Lung HRCT\n\n## Description\nA 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)\u003csup\u003e1\u003c/sup\u003e.\n\nNOTE: this pipeline calculates topology metrics from Minkowski functionals computed with the QuantImPy Python package\u003csup\u003e2\u003c/sup\u003e, which may differ from Minkowski measures in Hoff et al. (2017)\u003csup\u003e1\u003c/sup\u003e.\n\n\n## Table of contents\n1. [Installation](#1-installation)\n2. [Usage](#2-usage)\n3. [Outputs](#3-outputs)\n4. [Authors and acknowledgement](#4-authors-and-acknowledgment)\n\n## 1. Installation\nThe 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.\n\n### 1.1 Conda installation\nWe 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.\n\n#### 1.1.1 Conda installation: Intel Mac and Linux systems\nThe 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/)\n\n#### 1.1.2 Conda installation: Apple Silicon Mac\nInstall Miniforge using step 2 of this [link](https://caffeinedev.medium.com/how-to-install-tensorflow-on-m1-mac-8e9b91d93706)\n\n### 1.2 Install Python packages in a virtual environment\n\n#### 1.2.1 Create a virual environment\nCreate a conda virtual environment using the following command in terminal, where `\u003cenvName\u003e` can be any environment name of your choosing.\n```bash\nconda create --name \u003cenvName\u003e python=3.9.1\n```\nConfirm that the environment is available:\n```bash\nconda env list\n```\nTo activate the environment:\n```bash\nconda activate \u003cenvName\u003e\n```\n\n#### 1.2.2 Install Python packages\nBefore 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.\n```bash\npip install -r setup/requirements.txt\n```\n\n## 2. Usage\nThe pipeline currently takes the following required inputs (supported file formats: .nii):\n- Registered inspiratory and expiratory HRCTs in hounsfield units (HU) AND segmentation mask with positive integers denoting regions of lung parenchyma.\n\u003cbr /\u003e OR \n- Existing PRM map with binned regions labeled as {1,2,3,4} AND segmentation mask with positive integers denoting regions of lung parenchyma.\n\u003cbr /\u003e OR\n- Existing PRM map with binned regions labeled as {1,2,3,4} and regions outside of lung parenchyma labeled as 0.\n\n### 2.1 Create subject configuration file(s)\nConfiguration (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.\n\u003cbr /\u003e \n\u003cbr /\u003e`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.\n \u003cbr /\u003e\n\u003cbr /\u003e`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.\n\u003cbr /\u003e\n\u003cbr /\u003eIf 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.\n\u003cbr /\u003e\n\u003cbr /\u003eIf no existing PRM map is provided, the required fields are: `subjID`, `inFileExp`, `inFileInspReg`, `inFileMask`, and `outDir`.\n\n### 2.2 Process a single subject\nTo process a single subject run, active your virtual environment, navigate to the main program directory, and run the following command.\n```bash\npython main.py --config \u003cpath-to-subject-config-file\u003e\n```\n\n### 2.3 Process a batch of subjects\nFirst 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.\n```bash\npython main.py --batch --config \u003cpath-to-config-file-directory\u003e\n```\n\n### 2.4 Compute only PRM maps and global topology metrics\nProcessing 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`\n```bash\npython main.py --glbl --config \u003cpath-to-subject-config-file\u003e\n```\nor\n```bash\npython main.py --glbl --batch --config \u003cpath-to-config-file-directory\u003e\n```\n\n## 3. Outputs\n- PRM\n    - Combined 3D PRM map of normal lung structure, emphysema, fSAD, and emptying emphysema (.nii). PRM classifications are assigned the following values -\u003e normal: 1, fSAD: 2, emphysema: 3, emptying emphysema: 4\n    - Colorcoded PRM image of a representative slice along the anterior-posterior dimension (.png)\n    - Percentage of lung parenchyma voxels in each PRM classification (.csv)\n- Topology\n    - Separate 3D maps of local topology density metrics for voxels characterized by normal lung structure, emphysema, fSAD, and emptying emphysema (.nii)\n    - Images of surface area density for a reprsentative slice along the anterior-posterior for all PRM maps (.png)\n    - Global and mean local topology metrics and whole-lung mean local topology metrics for each PRM classification (.csv)\n    - Note: output topology density metrics have the following units (pipeline assumes voxel dimensions in HRCT NIfTI header are in mm)\n        - Fractional volume (volume density): unitless\n        - Surface area density: m\u003csup\u003e-1\u003c/sup\u003e\n        - Integral mean curvature density: m\u003csup\u003e-2\u003c/sup\u003e\n        - Euler-Poincare characteristic density: unitless\n\n\n## 4. Authors and acknowledgment\nSources:\n\u003e1. 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\n\n\u003e2. 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\n\nRelated publications:\n\u003e1. 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. \n\nDevelopers: Aryil Bechtel, Ruiqi Geng\u003cbr /\u003e \nCredits: Laura Bell \u003cbr /\u003e \nCorrespondence: Laura Bell (bell.laura@gene.com), Aryil Bechtel (aryilbechtel@gmail.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgenentech%2Ftopological_prm_for_lunghrct","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgenentech%2Ftopological_prm_for_lunghrct","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgenentech%2Ftopological_prm_for_lunghrct/lists"}