nifreeze.analysis.phantoms module

The synthetic phantoms of tools/phantoms/phantom.py, for the sensitivity analysis.

A phantom dataset holds, for each acquisition protocol, a noise-free reference and only the changed volumes of each perturbed copy of it, with their ground truth in the sidecars (see docs/phantoms.rst). load_phantom() reads one protocol as sensitivity() takes it: the reference, and each copy with its Perturbation.

nifreeze.analysis.phantoms.Cell

The ground truth of a perturbed copy, and a function that loads the copy.

alias of tuple[Perturbation, Callable[[], DWI]]

nifreeze.analysis.phantoms.Part

A file of changed volumes, the reference’s volumes that some of them replace, and the first of those in the file (they follow one another).

alias of tuple[Path, list[int], int]

nifreeze.analysis.phantoms.SUBJECT = '60501'

TRXScan’s adult (NIBS sub-60501).

Type:

The phantom’s subject

nifreeze.analysis.phantoms.load_phantom(root: Path | str, protocol: str, noise: int | None = None, counts: Iterable[int] | None = None, alone: Iterable[int] | None = None) → tuple[DWI, list[tuple[Perturbation, Callable[[], DWI]]]][source]

Read a protocol’s reference and its perturbed copies.

A copy is assembled from the reference: its eddy-current volumes replace their counterparts, then its first K moved volumes replace theirs (or one of them, see alone). The copies load one at a time, when sensitivity() needs them, since each is as large as the reference.

Parameters:

  • root (os.pathlike) – Root of the phantom dataset.

  • protocol (str) – Name of the protocol (acq-<protocol>).

  • noise (int, optional) – Seed of the noise added to every volume on load (add_noise(), at the protocol’s signal-to-noise ratio); noise-free if None. The noise is keyed on the volume, so a copy has the reference’s noise wherever it is unchanged.

  • counts (Iterable, optional) – Numbers of moved volumes: each copy with motions gives one copy per count, moving the first K of its volumes. All of them if None.

  • alone (Iterable, optional) – Volumes (numbered as the reference’s) that each copy with motions also moves alone, with the motion it gives them: one copy per volume, to rank the volumes by their influence. None if None.

Returns:

The reference, as a DWI (b=0 volumes are averaged into its bzero, and the diffusion-weighted ones are numbered from 0), and the copies, each with its ground truth.

Return type:

tuple