comparison

comparison

Validation comparison against Digital Reference Objects.

This module provides functions for comparing osipy computed parameter maps against OSIPI Digital Reference Objects (DROs) or other reference datasets with known ground truth values.

References

OSIPI Task Force 4.1: DCE-MRI Technical Validation OSIPI Task Force 4.2: DSC-MRI Technical Validation QIBA DCE Profile v2.0

DROData dataclass

DROData(name, parameters, mask=None, metadata=None)

Container for Digital Reference Object data.

ATTRIBUTE	DESCRIPTION
name	DRO identifier name. TYPE: str
parameters	Ground truth parameter values. TYPE: dict[str, NDArray[floating]]
mask	Mask of valid comparison voxels. TYPE: NDArray[bool_] | None
metadata	Additional DRO metadata. TYPE: dict[str, Any]

__post_init__

__post_init__()

Initialize mutable defaults.

load_dro

load_dro(dro_path, dro_type='osipi')

Load Digital Reference Object data.

PARAMETER	DESCRIPTION
dro_path	Path to DRO directory or file. TYPE: str | Path
dro_type	DRO format type: "osipi", "qiba", or "custom". TYPE: str DEFAULT: 'osipi'

RETURNS	DESCRIPTION
DROData	Loaded reference data.

Examples:

>>> dro = load_dro("tests/fixtures/osipi_dro/dce_dro_v10")

validate_against_dro

validate_against_dro(
    computed,
    reference,
    tolerances=None,
    mask=None,
    reference_name="unknown",
)

Compare computed parameters against DRO reference values.

PARAMETER	DESCRIPTION
computed	Computed parameter maps from osipy. TYPE: dict[str, ParameterMap] | dict[str, NDArray]
reference	Reference (ground truth) parameter values. TYPE: DROData | dict[str, NDArray]
tolerances	Tolerance thresholds per parameter. Uses OSIPI/QIBA defaults if not specified. TYPE: dict[str, dict[str, float]] | None DEFAULT: None
mask	Mask of voxels to compare. Overrides DRO mask if provided. TYPE: NDArray[bool_] | None DEFAULT: None
reference_name	Name for the reference dataset. TYPE: str DEFAULT: 'unknown'

RETURNS	DESCRIPTION
ValidationReport	Detailed comparison results.

Examples:

>>> import numpy as np
>>> from osipy.common.validation.comparison import validate_against_dro
>>> computed = {"Ktrans": np.random.rand(10, 10, 5) * 0.1}
>>> reference = {"Ktrans": np.random.rand(10, 10, 5) * 0.1}
>>> report = validate_against_dro(computed, reference)
>>> print(report.summary())

create_synthetic_dro

create_synthetic_dro(
    shape=(16, 16, 8), modality="dce", noise_level=0.01
)

Create synthetic DRO for testing.

PARAMETER	DESCRIPTION
shape	Shape of parameter maps. TYPE: tuple[int, ...] DEFAULT: (16, 16, 8)
modality	Modality type: "dce", "dsc", "asl", or "ivim". TYPE: str DEFAULT: 'dce'
noise_level	Noise level to add to ground truth. TYPE: float DEFAULT: 0.01

RETURNS	DESCRIPTION
DROData	Synthetic reference data.

Examples:

>>> dro = create_synthetic_dro(shape=(8, 8, 4), modality="dce")