nema_quant_iter

Iterative NEMA image quality analysis across reconstruction iterations.

Overview

nema_quant_iter analyzes a folder of reconstruction iterations and produces iteration-wise NEMA IQ metrics, plots, and reports. Iteration numbers are extracted from filenames using the regex pattern in FILE.USER_PATTERN.

Main Features

Batch Iteration Analysis: Process a directory of iteration images
Weighted CBR/FOM Tracking: Identify peak weighted CBR and FOM
Publication Plots: Contrast and background variability vs sphere diameter
Reports & CSV Export: Text, PDF, PNG, and CSV outputs

Module Contents

Quick Start

Command Line Usage

Basic analysis:

chameleoniq_quant_iter /path/to/iterations \
  --config config.yaml \
  --output results/iter_analysis.txt

With visualizations and explicit spacing:

chameleoniq_quant_iter /path/to/iterations \
  --config config.yaml \
  --output results/iter_analysis.txt \
  --save-visualizations \
  --visualizations-dir results/roi_masks \
  --spacing 2.0 2.0 2.0

Inputs

Iteration folder

The input path must be a folder containing .nii files. Iteration numbers are parsed from filenames using FILE.USER_PATTERN in the YAML configuration. For example, if your files are frame01.nii, frame02.nii, use:

FILE:
  USER_PATTERN: "frame(\\d+)"

If no files match the pattern, the analysis stops with an error.

Configuration

The CLI requires a YAML config file (--config). See Configuration Guide for full defaults and parameter reference. The most important config value for iterative analysis is:

FILE.USER_PATTERN: regex with a capture group for the iteration number

Command Line Arguments

Required

input_path (positional)

Folder containing iteration .nii files

–output, -o

Output text report path (required)

–config, -c

YAML configuration file (required)

–standard

NEMA standard to follow for analysis (required).

Options: NU_2_2018 (default), NU_4_2008

Optional

–spacing: Voxel spacing in millimeters as three floats: x y z
–save-visualizations: Save ROI mask and analysis images
–visualizations-dir: Directory to save visualization images (default: visualizations)
–log_level: Logging verbosity (10=DEBUG, 20=INFO, 30=WARNING, 40=ERROR, 50=CRITICAL)
–verbose, -v: Enable verbose error output

Outputs

The command produces:

Text report at the path provided by --output
PDF report with the same base name as --output
Plots in <output_dir>/png (contrast, background, convergence, lung plots)
CSV data in <output_dir>/csv
Log files in <output_dir>/logs

Tips

Use consistent iteration naming so the regex captures the correct number.
Provide --spacing if spacing is missing from the NIfTI header.
Start with a subset of iterations to validate the pipeline, then run full sets.

Troubleshooting

No iteration files found:: Ensure the input folder has .nii files and the regex in FILE.USER_PATTERN matches the filenames.
Spacing warning:: Provide --spacing x y z when voxel spacing is not stored in the header.