Overview

This repository contains the code required to complete analysis using WALES & all related data.

The repository is divided into two main parts:

1. Analysis.zip: Contains the datasets, processed images, and results from various experiments.
2. WALES_GUI_code.zip: Contains the Python scripts, notebooks, and required files to run the WALES analysis GUI.

Repository Structure

The repository is organized as follows:

• Analysis/
  • Contains sub-folders for different experimental analyses (Homogenous, Inflation, Main_Analysis, TRI_vs_H&E). Each sub-folder generally includes Original_Images, Masked, Thresholded, and analysis results (heatmaps, .csv, .txt files).
• WALES_GUI_code/
  • Contains the source code and necessary files for the WALES image analysis tools.

Analysis Folder Structure

Within the Analysis/ directory, experiments are separated:

• Analysis/Main_Analysis/
  • The primary analysis folder, including reproducibility tests and thresholding comparisons.
• Analysis/Inflation/
  • Analysis comparing optimally-, over-, and under-inflated lung samples.
• Analysis/TRI_vs_H&E/
  • Analysis directly comparing Trichrome vs. H&E staining.
• Homogenous/
  • Analysis including both constant and variable width on a homogenous lung sample.

Common Sub-folders within Analysis Experiments:

• Original_Images/: Raw .tif image files.
• Masked/: Images with artifact/background mask applied.
• Thresholded/: Final binary images for quantification. For greater clarity, the masked regions are shown as green. These areas are not included in further steps.
• .../heatmaps/ or .../analysis/: Generated data and visualizations (heatmaps, average widths, percentage analyses).
  • whole_heatmap/: Heatmap .png images for the entire sample.
  • av_widths/: Images and av_widths.txt files for average alveolar width.
  • heatmaps_U.../: Heatmaps for specific cutoffs (e.g. "U12_50" for 12.5% cutoff).

File structures

• homogenous_analysis_constant_width.csv
  This file contains analysis of a homogenous tissue with a constant Gaussian kernel size applied with respect to a control group.
  The columns are as follows:

  • column 1: Filename
  • column 2: Group
  • column 3: Percentage of tissue under 50% cutoff

• homogenous_analysis_varying_width.csv
  This file contains analysis of a homogenous tissue with a varying Gaussian kernel size applied (varying alveolar width calculation) with respect to a control group.
  The columns are as follows:

  • column 1: Filename
  • column 2: Group
  • column 3: Percentage of tissue under 50% cutoff

• av_widths.txt
  These files indicate the calculated average alveolar width. These values are applied in later analysis steps for heatmap creation. These files indicate the size of the Gaussian kernel to be applied to each lung image.
  The file setup is as follows:

  • (filename, average alveolar width in pixels)

• percentage_analysis.txt
  These files indicate the calculated percentage of tissue under the specified cutoff. The directory in which they reside indicates the specific cutoff applied. These files are created by the analysis program.
  The file setup is as follows:

  • column 1: Filename
  • column 2: Percentage of tissue under specified cutoff

• inflation_analysis.csv
  This file contains the analysis performed for the inflation dependency study. Here, lungs of different levels of inflation (over, under, and optimally inflated) are compared.
  The file setup is as follows:

  • column 1: Filename
  • column 2: Group
  • column 3: Percentage of tissue under 12.5% cutoff

• tech_1_analysis.csv
  This file contains the analysis performed by technician 1 for the reproducibility study between technician 1 and 2.
  The file setup is as follows:

  • column 1: Filename
  • column 2: Percentage airspace in binarized lung image
  • column 3: Percentage tissue in binarized lung image
  • column 4: Threshold value used to binarize image in pixels
  • column 5: Percentage of tissue under 12.5% cutoff

• tech_2_analysis.csv
  This file contains the analysis performed by technician 2 for the reproducibility study between technician 1 and 2.
  The file setup is as follows:

  • column 1: Filename
  • column 2: Percentage airspace in binarized lung image
  • column 3: Percentage tissue in binarized lung image
  • column 4: Threshold value used to binarize image in pixels
  • column 5: Percentage of tissue under 12.5% cutoff

WALES GUI Code Structure (WALES_GUI_code/)

This directory contains the Python code for image processing and analysis:

• WALES_mask_thresholding.py: A Python script designed to mask and threshold single or multiple images.
• heatmap_GUI.py: A Python script to perform heatmap analysis. Here, you may define a constant width if necessary.
• WALES_mask_thresholding.ipynb: A Jupyter Notebook version of the mask and thresholding step.
• requirements_CPU.txt: A list of Python packages required to run the code using CPU processing.
• requirements_CUDA.txt: A list of Python packages required to run the code using GPU (CUDA) acceleration.
• lungsICO.ico: Icon file used for the GUI application.

Requirements & Usage

For Running WALES Code (WALES_GUI_code/)

• Python 3.10: The code is written in Python.

• Meta SAM Model Checkpoint (vit_h recommended): You will need the sam_vit_h.pth model checkpoint file from Meta's Segment Anything Model (SAM) [1]. You typically need to download this separately. Ensure it is placed in the same directory. Find the model on Github/facebookresearch/Segment Anything Model

• Required Packages: Install the necessary packages using pip:

  • For CPU: pip install -r requirements_CPU.txt
  • For GPU (NVIDIA CUDA): pip install -r requirements_CUDA.txt (Ensure CUDA toolkit and cuDNN are correctly installed and compatible with the specified package versions, especially PyTorch. CUDA Tooklit version 12.6 is compatible).

• Running the GUI: Navigate to the /WALES_GUI_code/ directory and run first:

  python WALES_mask_thresholding.py
  

  Here, you may edit the model hyperparameters in settings.

  Secondly, after storing the masked and thresholded images in separate folders, run:

  python heatmap_GUI.py
  

For Analysis Notebooks (Analysis/Main_Analysis/)

Example analysis notebooks can be found Reproducibility/reproducibility.ipynb & Thresholding_comparison/thresholding_comparison.ipynb.

• Python 3.10
• Jupyter Notebook or JupyterLab
• Install packages as listed in files

References

[1] Kirillov A, Mintun E, Ravi N, Mao H, Rolland C, Gustafson L, et al., editors. Segment Anything. 2023 IEEE/CVF International Conference on Computer Vision (ICCV); 2023 1-6 Oct. 2023.