nema_merge

Tools for merging and comparing NEMA analysis results across experiments.

Overview

nema_merge aggregates CSV outputs from multiple experiments defined in an XML configuration. It generates merged plots and statistical summaries for QA and longitudinal monitoring.

Main Features

XML-Driven Merging: Define experiments and data sources in one file
Comparative Plots: Contrast and background variability across datasets
Dose-Response Analysis: Optional dose plots when dose values are provided
Lung & Advanced Metrics: Optional lung insert and advanced metric summaries
Statistical Summaries: t-tests and corrected significance heatmaps

Module Contents

Quick Start

Command Line Usage

Basic merge:

chameleoniq_merge experiments.xml \
  --config config.yaml \
  --output results/merged

Inputs

XML configuration

The CLI reads an XML file that defines experiments and their data sources. Each experiment element requires name and path attributes. Optional attributes include plot_status, dose, lung_path, and advanced_path.

<experiments>
  <experiment
    name="Scanner_A_Jan"
    path="results/scanner_a_metrics.csv"
    plot_status="enhanced"
    dose="10.0"
    lung_path="results/scanner_a_lung.csv"
    advanced_path="results/scanner_a_advanced.csv" />
  <experiment
    name="Scanner_B_Jan"
    path="results/scanner_b_metrics.csv"
    plot_status="default"
    dose="12.5" />
</experiments>

Metrics CSV format

Each metrics CSV should include these columns:

diameter_mm (or diameter, diam, d)
percentaje_constrast_QH
background_variability_N

Optional lung CSV

If lung_path is provided, the CSV must include a data column containing lung insert accuracy values.

Optional advanced metrics CSV

If advanced_path is provided, the CSV should include one row per experiment with columns such as Dice, Jaccard, VS, MI, Recall, and ASSD.

Configuration

The CLI requires a YAML config file (--config). This controls plot styling and shared defaults. See Configuration Guide for details.

Command Line Arguments

Required

xml_config (positional): Path to XML configuration file
–output: Output directory for merged plots (required)
–config, -c: YAML configuration file (required)

Optional

–log-level: Logging verbosity (10=DEBUG, 20=INFO, 30=WARNING, 40=ERROR)

Outputs

The command produces:

Merged contrast/background plots in the output directory
Dose-response plots when dose is provided in the XML
Lung insert violin plots when lung_path is provided
Advanced metrics boxplots and heatmaps when advanced_path is provided

Tips

Use plot_status="enhanced" to highlight specific experiments.
Provide numeric dose values to enable dose-response plots.
Keep experiment CSV schemas consistent across runs.

Troubleshooting

No experiments loaded:: Verify the XML file contains experiment elements with name and path attributes.
Missing columns:: Ensure metrics CSVs include diameter_mm, percentaje_constrast_QH, and background_variability_N (or accepted alternatives for diameter).