soffiafdz/hvr_cnn repository overview

⁠Documentation for HVR_CNN

⁠Overview

This Docker image provides an environment for running a CNN-based processing pipeline for the automatic calculation of the Hippocampal-to-Ventricle ratio. The main entry point is main.py, which processes neuroimaging data, generates segmentations, and computes various metrics. The image is built using Micromamba for efficient environment management and supports both CPU and GPU execution.

⁠Features

• Python environment managed via Micromamba.
• CNN-based segmentation pipeline.
• Supports input from CSV files or direct image paths.
• Generates outputs such as segmentations, QC images, and CSVs.
• Configurable output and working directories.

⁠Installation

Pull the Docker image from DockerHub:

docker pull soffiafdz/hvr_cnn:latest

⁠Running the Container

⁠Basic Usage

docker run --rm \

-v $(pwd)/data:/app/data \

-v $(pwd)/output:/app/output \

soffiafdz/hvr_cnn:latest \

-f /app/data/input.csv -o /app/output

⁠Mounting Volumes

Ensure the following:

• Input files (e.g., images, CSVs) are located in a mounted directory.
• Output directories are mounted to /app/output to persist results after the container stops.

Example:

• Input: $(pwd)/data
• Output: $(pwd)/output

⁠GPU Support (Optional)

To utilize GPU acceleration, ensure:

1. NVIDIA drivers and the NVIDIA Container Toolkit are installed on the host machine.

2. Run the container with GPU access:

docker run --rm \

--gpus all \

-v $(pwd)/data:/app/data \

-v $(pwd)/output:/app/output \

soffiafdz/hvr_cnn:latest \

-f /app/data/input.csv -o /app/output

⁠Input Options

⁠CSV Input

Specify a CSV file with the -f or --csv_file flag. The CSV file should contain columns for subject information, including:

• subject_id (optional)

• session_id (optional)

• input_img_path (mandatory)

• group (optional)

Example:

subject_id,session_id,input_img_path,group

subj_001,sess_001,/app/data/img1.mnc,control

subj_002,sess_002,/app/data/img2.mnc,patient

Command:

docker run --rm \

-v $(pwd)/data:/app/data \

-v $(pwd)/output:/app/output \

soffiafdz/hvr_cnn:latest \

-f /app/data/input.csv -o /app/output

⁠Direct Image Path

Provide an image path with -i or --input_img_path:

docker run --rm \

-v $(pwd)/data:/app/data \

-v $(pwd)/output:/app/output \

soffiafdz/hvr_cnn:latest \

-i /app/data/img1.mnc -o /app/output

⁠Output Options

⁠Default Output Directory

If -o or --output_dir is not specified, results are saved to /app/output inside the container. Mount a volume to persist these files:

-v $(pwd)/output:/app/output

⁠Segmentation Outputs

• Directory: /app/output/segmentations

• Format: .mnc

⁠QC Images (Optional)

• Enable with --qc or --qc_images

• Directory: /app/output/qc

• Format: .jpg

⁠CSV Outputs (Optional)

Generate volume-related outputs:

• --hc_vols: Hippocampal volumes CSV.

• --vc_vols: Ventricular volumes CSV.

• --hvr_csv: Hippocampal-to-Ventricular Ratio (HVR) CSV.

⁠Configuration Options

⁠Command-Line Arguments

• -f, --csv_file: Path to input CSV file.

• -i, --input_img_path: Path(s) to input image(s).

• -s, --subject_id: Subject ID(s).

• -v, --session_id: Session ID(s).

• -o, --output_dir: Directory for output files.

• --qc: Include QC images in the output.

• --hc_vols, --vc_vols, --hvr_csv: Save specific metrics to CSV.

⁠Environment Variables

• PYTHONPATH: Set to /app to enable module imports.

⁠Examples

⁠Process Multiple Subjects

docker run --rm \

-v $(pwd)/data:/app/data \

-v $(pwd)/output:/app/output \

soffiafdz/hvr_cnn:latest \

-f /app/data/input.csv -o /app/output --qc --hc_vols

⁠Process a Single Image

docker run --rm \

-v $(pwd)/data:/app/data \

-v $(pwd)/output:/app/output \

soffiafdz/hvr_cnn:latest \

-i /app/data/img1.mnc -o /app/output --qc

⁠License

This Docker image and associated code are licensed under GNU General Public License v3.0.

⁠Contact

For questions or issues, contact [email protected]⁠.