nifreeze.utils.iterators module

Iterators to traverse the volumes in a 4D image.

nifreeze.utils.iterators.BVALS_KWARG = 'bvals'

b-vals keyword argument name.

nifreeze.utils.iterators.ITERATOR_SIZE_ERROR_MSG = "None of ('size', 'bvals', 'uptake') were provided to infer size: cannot build iterator without size."

Iterator size argument error message.

nifreeze.utils.iterators.KWARG_ERROR_MSG = 'Keyword argument {kwarg} is required.'

Iterator keyword argument error message.

nifreeze.utils.iterators.SIZE_KEYS = ('size', 'bvals', 'uptake')

Keys that may be used to infer the number of volumes in a dataset. When the size of the structure to iterate over is not given explicitly, these keys correspond to properties that distinguish one imaging modality from another, and are part of the 4th axis (e.g. diffusion gradients in DWI or update in PET).

nifreeze.utils.iterators.UPTAKE_KWARG = 'uptake'

Uptake keyword argument name.

nifreeze.utils.iterators.bvalue_iterator(*_, **kwargs) → Iterator[int][source]

Traverse the volumes in a DWI dataset by increasing b-value.

Parameters:

bvals (list) – List of b-values corresponding to all orientations of the dataset. Please note that bvals is a keyword argument and MUST be provided to generate the volume sequence.

Yields:

int – The next index.

Examples

>>> list(bvalue_iterator(bvals=[0.0, 0.0, 1000.0, 1000.0, 700.0, 700.0, 2000.0, 2000.0, 0.0]))
[0, 1, 8, 4, 5, 2, 3, 6, 7]
nifreeze.utils.iterators.centralsym_iterator(**kwargs) → Iterator[int][source]

Traverse the dataset starting from the center and alternatingly progressing to the sides.

Other Parameters:

  • size (obj:int, optional) – Size of the structure to iterate over.

  • bvals (list, optional) – List of b-values corresponding to all orientations of a DWI dataset.

  • uptake (list, optional) – List of uptake values corresponding to all volumes of the dataset.

Notes

Only one of the above keyword arguments may be provided at a time. If size is given, all other size-related keyword arguments will be ignored. If size is not provided, the function will attempt to infer the number of volumes from the length or value of the provided keyword argument. If more than one such keyword is provided, a ValueError will be raised.

Examples

>>> list(centralsym_iterator(size=10))
[5, 4, 6, 3, 7, 2, 8, 1, 9, 0]
>>> list(centralsym_iterator(size=11))
[5, 4, 6, 3, 7, 2, 8, 1, 9, 0, 10]
nifreeze.utils.iterators.linear_iterator(**kwargs) → Iterator[int][source]

Traverse the dataset volumes in ascending order.

Other Parameters:

  • size (obj:int, optional) – Size of the structure to iterate over.

  • bvals (list, optional) – List of b-values corresponding to all orientations of a DWI dataset.

  • uptake (list, optional) – List of uptake values corresponding to all volumes of the dataset.

Notes

Only one of the above keyword arguments may be provided at a time. If size is given, all other size-related keyword arguments will be ignored. If size is not provided, the function will attempt to infer the number of volumes from the length or value of the provided keyword argument. If more than one such keyword is provided, a ValueError will be raised.

Yields:

int – The next index.

Examples

>>> list(linear_iterator(size=10))
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
nifreeze.utils.iterators.random_iterator(**kwargs) → Iterator[int][source]

Traverse the dataset volumes randomly.

If the seed key is present in the keyword arguments, initializes the seed of Python’s random pseudo-random number generator library with the given value. Specifically, if False, None is used as the seed; if True, a default seed value is used.

Other Parameters:

seed (int, bool, str, or None) – If int or str or None, initializes the seed of Python’s random generator with the given value. If False, the random generator is passed None. If True, a default seed value is set.

sizeobj:int, optional

Size of the structure to iterate over.

bvalslist, optional

List of b-values corresponding to all orientations of a DWI dataset.

uptakelist, optional

List of uptake values corresponding to all volumes of the dataset.

Notes

Only one of the above keyword arguments may be provided at a time. If size is given, all other size-related keyword arguments will be ignored. If size is not provided, the function will attempt to infer the number of volumes from the length or value of the provided keyword argument. If more than one such keyword is provided, a ValueError will be raised.

Yields:

int – The next index.

Examples

>>> list(random_iterator(size=15, seed=0))  # seed is 0
[1, 10, 9, 5, 11, 2, 3, 7, 8, 4, 0, 14, 12, 6, 13]
>>>  # seed is True -> the default value 20210324 is set
>>> list(random_iterator(size=15, seed=True))
[1, 12, 14, 5, 0, 11, 10, 9, 7, 8, 3, 13, 2, 6, 4]
>>> list(random_iterator(size=15, seed=20210324))
[1, 12, 14, 5, 0, 11, 10, 9, 7, 8, 3, 13, 2, 6, 4]
>>> list(random_iterator(size=15, seed=42))  # seed is 42
[8, 13, 7, 6, 14, 12, 5, 2, 9, 3, 4, 11, 0, 1, 10]
nifreeze.utils.iterators.uptake_iterator(*_, **kwargs) → Iterator[int][source]

Traverse the volumes in a PET dataset by decreasing uptake value.

This function assumes that each uptake value corresponds to a single volume, and that this value summarizes the uptake of the volume in a meaningful way, e.g. a mean value across the entire volume.

Parameters:

uptake (list) – List of uptake values corresponding to all volumes of the dataset. Please note that uptake is a keyword argument and MUST be provided to generate the volume sequence.

Yields:

int – The next index.

Examples

>>> list(uptake_iterator(uptake=[-1.23, 1.06, 1.02, 1.38, -1.46, -1.12, -1.19, 1.24, 1.05]))
[3, 7, 1, 8, 2, 5, 6, 0, 4]