nifreeze.analysis.similarity module

Similarity between a predicted and an actual volume, within a mask.

nifreeze.analysis.similarity.DEFAULT_MI_BINS = 32

Number of intensity bins of the mutual information histogram.

nifreeze.analysis.similarity.METRICS = {'cc': <function masked_cc>, 'mi': <function mutual_information>, 'nrmse': <function nrmse>}

Similarity metrics by name.

nifreeze.analysis.similarity.masked_cc(predicted: ndarray, reference: ndarray, mask: ndarray | None = None) → float

Pearson correlation between two volumes, within a mask.

Parameters:

• predicted (ndarray) – The predicted volume.

• reference (ndarray) – The actual volume.

• mask (ndarray, optional) – Boolean mask of the voxels compared (all if None).

Returns:

The correlation, or 0 if either volume is constant within the mask.

Return type:

float

Examples

>>> x = np.arange(10.0)
>>> round(masked_cc(3 * x + 2, x), 6)
1.0
>>> round(masked_cc(-x, x), 6)
-1.0

nifreeze.analysis.similarity.mutual_information(predicted: ndarray, reference: ndarray, mask: ndarray | None = None, bins: int = 32) → float

Mutual information between two volumes, within a mask.

The joint histogram has bins equal-width bins spanning each volume’s range within the mask.

Parameters:

• predicted (ndarray) – The predicted volume.

• reference (ndarray) – The actual volume.

• mask (ndarray, optional) – Boolean mask of the voxels compared (all if None).

• bins (int, optional) – Number of intensity bins per volume.

Returns:

The mutual information, in nats. A volume shares with itself its own (binned) entropy, the largest value any prediction can reach.

Return type:

float

Examples

>>> x = np.repeat(np.arange(4.0), 25)
>>> bool(np.isclose(mutual_information(x, x, bins=4), np.log(4)))
True
>>> rng = np.random.default_rng(0)
>>> mutual_information(rng.random(10000), rng.random(10000), bins=4) < 0.01
True

nifreeze.analysis.similarity.nrmse(predicted: ndarray, reference: ndarray, mask: ndarray | None = None, scale: float | None = None) → float

Root-mean-square error, normalized by the standard deviation of the reference.

Parameters:

• predicted (ndarray) – The predicted volume.

• reference (ndarray) – The actual volume.

• mask (ndarray, optional) – Boolean mask of the voxels compared (all if None).

• scale (float, optional) – Denominator replacing the reference’s standard deviation, so that errors measured against different references share one scale.

Returns:

The normalized error: 0 for a perfect prediction, 1 for predicting the reference’s mean everywhere.

Return type:

float

Examples

>>> x = np.arange(10.0)
>>> nrmse(x, x)
0.0
>>> round(nrmse(np.full(10, x.mean()), x), 6)
1.0
>>> float(nrmse(x + 1, x, scale=2.0))
0.5