Configuration Guide

Overview

ChameleonIQ is configuration-driven so it can adapt to different scanners, phantoms, and activity protocols. Most calculations and reports depend on the YAML values you provide.

Why Configuration Matters

Ensures correct activity ratio for percent contrast
Converts millimeters to voxels with the right spacing
Aligns ROI positions with your phantom setup
Controls plot styling for consistent reports

Configuration Sections

ACQUISITION

Emission imaging parameters:

ACQUISITION:
  EMMISION_IMAGE_TIME_MINUTES: 10

EMMISION_IMAGE_TIME_MINUTES (int): Duration of acquisition in minutes

ACTIVITY

Activity concentration measurements:

ACTIVITY:
  HOT: 0.79
  BACKGROUND: 0.079
  RATIO: 9.91
  UNITS: "mCi"
  ACTIVITY_TOTAL: "29.24 MBq"

HOT (float): Activity in hot sphere regions
BACKGROUND (float): Activity in background regions
RATIO (float): Hot-to-background ratio used in the formula
UNITS (str): Activity units (mCi, MBq, etc.)
ACTIVITY_TOTAL (str): Total phantom activity

PHANTHOM

Phantom geometry and ROI definitions:

PHANTHOM:
  ROI_DEFINITIONS_MM:
    - center_yx: [211, 171]
      diameter_mm: 37
      color: "red"
      alpha: 0.18
      name: "hot_sphere_37mm"

ROIS

Region of Interest specifications:

ROIS:
  CENTRAL_SLICE: 172
  BACKGROUND_OFFSET_YX: [[-16, -28], ...]
  ORIENTATION_YX: [1, 1]
  SPACING: 2.0644

FILE

File naming and patterns:

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

STYLE

Visualization parameters:

STYLE:
  COLORS: ["#023743FF", ...]
  PLT_STYLE: "seaborn-v0_8-talk"
  RCPARAMS:
    - ["font.size", 24]
    - ["axes.titlesize", 24]

Real-World Examples

High-resolution scanner (1mm voxels): SPACING: 1.0
Standard clinical scanner: SPACING: 2.0644
High-contrast protocol: increase ACTIVITY.RATIO

Full Example YAML

ACQUISITION:
  EMMISION_IMAGE_TIME_MINUTES: 34

ACTIVITY:
  HOT: 31.22
  BACKGROUND: 3.76
  UNITS: "kBq/mL"
  RATIO: 8.30
  ACTIVITY_TOTAL: "37.42 MBq"

PHANTHOM:
  ROI_DEFINITIONS_MM:
    - center_yx: [213, 225]
      diameter_mm: 37
      color: "red"
      alpha: 0.18
      name: "hot_sphere_37mm"

ROIS:
  SPACING: 2.0644
  CENTRAL_SLICE: 165
  ORIENTATION_YX: [1, -1]

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

Using Configuration

From Python

from config.defaults import get_cfg_defaults

# Get default config
cfg = get_cfg_defaults()

# Modify settings
cfg.ACQUISITION.EMMISION_IMAGE_TIME_MINUTES = 20
cfg.ACTIVITY.UNITS = "MBq/mL"

# Use in analysis
metrics = analysis.calculate_image_quality_metrics(phantom, cfg=cfg)

From Command Line

nema_quant --input image.nii.gz --config custom.yaml --output results/

Custom YAML File

Create custom_config.yaml:

ACQUISITION:
  EMMISION_IMAGE_TIME_MINUTES: 15

ACTIVITY:
  HOT: 0.85
  BACKGROUND: 0.085
  RATIO: 10.0
  UNITS: "MBq/mL"

FILE:
  CASE: "My_Study"

For detailed configuration options, see config.