DOI: 10.5061/dryad.dv41ns2b8
title: Data and code from: Wide-Angle Lung Experiment Segmentation (WALES): A novel methodology for quantitative assessment of lung pathology in model systems

description: For pre-clinical studies, the standard practice for evaluating lung injury
 usually involves an assessment of pulmonary histopathology by a certified
 pathologist. This is typically accomplished by light microscopy using a
 semi-quantitative 4-point scale. In contrast, automated image analysis
 software allows a more quantitative assessment, though inherent
 limitations with such automated programs can produce misleading
 conclusions. For example, specific imaging features may be incorrectly
 scored or classified within the specimen because of the complex
 architecture and heterogenous structures present in the lung.
 Additionally, tissue processing and handling may further introduce
 artifacts and inconsistencies that affect automated analysis. To address
 these limitations, we developed a novel lung image analysis program, Wide
 Angle Lung Experiment Segmentation (WALES), which employs Meta’s Segment
 Anything Model to provide semi-automated masking and relative density
 analysis to efficiently quantify lung injury. Density analysis using WALES
 effectively delineated varying severities of lung injury, not achieved
 using more standard methods. WALES is widely applicable for many
 preclinical lung injury models.
description: # WALES GUI and Analysis ## 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](https://github.com/facebookresearch/segment-anything) * **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: ```bash 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: ```bash 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.