nifreeze.utils.iterators module - nifreeze 26.0.0.dev99 documentation

nifreeze.utils.iterators.BVALS_KWARG = 'bvals'¶

b-vals keyword argument name.

nifreeze.utils.iterators.DEFAULT_ROUND_DECIMALS = 2¶

Round decimals to use when comparing values to be sorted for iteration purposes.

nifreeze.utils.iterators.ITERATOR_MULTIPLICITY_ERROR_MSG = 'f"Multiple {SIZE_KEYS} were provided; provide exactly one or provide a value for\n{SIZE_KWARG} to build the iterator.'¶

Iterator size multiplicity error message.

nifreeze.utils.iterators.ITERATOR_SIZE_ERROR_MSG = 'None of {features} were provided or had no valid values to infer size: cannot build iterator without size.'¶

Iterator size argument error message.

nifreeze.utils.iterators.MODALITY_SPECIFIC_SIZE_KEYS = ('bvals', 'uptake')¶

Modality-specific keys to infer the number of volumes in a dataset.

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 uptake in PET).

nifreeze.utils.iterators.SIZE_KWARG = 'size'¶

Size keyword argument name.

nifreeze.utils.iterators.START_INDEX_DATA_LENGTH_ERROR_MSG = "'start_index' must be less than the length of {feature}."¶

Start index data length error message.

nifreeze.utils.iterators.START_INDEX_KWARG = 'start_index'¶

Start index keyword argument name.

nifreeze.utils.iterators.START_INDEX_POSITIVITY_ERROR_MSG = "'start_index' must be positive."¶

Start index positivity error message.

nifreeze.utils.iterators.STOP_INDEX_DATA_LENGTH_ERROR_MSG = "'stop_index' must be less or equal to the length of {feature}."¶

Stop index data length error message.

nifreeze.utils.iterators.STOP_INDEX_KWARG = 'stop_index'¶

Stop index keyword argument name.

nifreeze.utils.iterators.STOP_INDEX_ORDERING_ERROR_MSG = "'stop_index' must be larger than 'start_index'."¶

Stop index value ordering error message.

nifreeze.utils.iterators.UPTAKE_KWARG = 'uptake'¶

Uptake keyword argument name.

nifreeze.utils.iterators.centralsym_iterator(**kwargs: Any) → Iterator[int][source]¶

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

Other Parameters:

size (int, optional) – Number of indices to generate.
bvals (list, optional) – List of b-values corresponding to all orientations of a DWI dataset. If provided and stop_index is not set, then stop_index is inferred as len(bvals). If stop_index is set, then stop_index must be <= len(bvals).
uptake (list, optional) – List of uptake values corresponding to all volumes of the dataset. If provided and stop_index is not set, then stop_index is inferred as len(uptake). If stop_index is set, then stop_index must be <= len(uptake)

start_indexint, optional: Starting index (inclusive) for the iteration. If provided, only indices >= start_index will be yielded.
stop_indexint, optional: Stopping index (exclusive) for the iteration. If provided, only indices < stop_index will be yielded; if not provided and no domain-defining sequence (('bvals', 'uptake')) is provided, then stop_index is inferred as start_index + size.

Notes

Iterators operate over an absolute index domain and yield absolute indices. The domain is always the half-open interval [start_index, stop_index) (end exclusive). One of the size-defining inputs must be provided: size, bvals, or uptake.If bvals or uptake is given, it takes precedence over size; size is only used when no modality-specific parameter is provided. When a sequence (bvals/uptake) is used, it defines the maximum valid index (i.e., the domain length) and stop_index defaults to len(sequence).

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]
>>> list(centralsym_iterator(size=7, start_index=3))
[5, 4, 6, 3]
>>> list(centralsym_iterator(size=7, start_index=3, stop_index=6))
[4, 3, 5]

nifreeze.utils.iterators.linear_iterator(**kwargs: Any) → Iterator[int][source]¶

Traverse the dataset volumes in ascending order.

Other Parameters:

size (int, optional) – Number of indices to generate.
bvals (list, optional) – List of b-values corresponding to all orientations of a DWI dataset. If provided and stop_index is not set, then stop_index is inferred as len(bvals). If stop_index is set, then stop_index must be <= len(bvals).
uptake (list, optional) – List of uptake values corresponding to all volumes of the dataset. If provided and stop_index is not set, then stop_index is inferred as len(uptake). If stop_index is set, then stop_index must be <= len(uptake)

start_indexint, optional: Starting index (inclusive) for the iteration. If provided, only indices >= start_index will be yielded.
stop_indexint, optional: Stopping index (exclusive) for the iteration. If provided, only indices < stop_index will be yielded; if not provided and no domain-defining sequence (('bvals', 'uptake')) is provided, then stop_index is inferred as start_index + size.

Notes

Iterators operate over an absolute index domain and yield absolute indices. The domain is always the half-open interval [start_index, stop_index) (end exclusive). One of the size-defining inputs must be provided: size, bvals, or uptake.If bvals or uptake is given, it takes precedence over size; size is only used when no modality-specific parameter is provided. When a sequence (bvals/uptake) is used, it defines the maximum valid index (i.e., the domain length) and stop_index defaults to len(sequence).

Yields:: int – The next index.

Examples

>>> list(linear_iterator(size=10))
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
>>> list(linear_iterator(size=7, start_index=3))
[3, 4, 5, 6]
>>> list(linear_iterator(size=4, start_index=3))
[3]
>>> list(linear_iterator(bvals=[0, 0, 700, 1000, 1000, 200], start_index=3))
[3, 4, 5]
>>> list(linear_iterator(bvals=[0, 0, 700, 1000, 1000, 200], start_index=3, stop_index=5))
[3, 4]

nifreeze.utils.iterators.monotonic_value_iterator(*_, **kwargs: Any) → Iterator[int][source]¶

Traverse the volumes by increasing b-value in a DWI dataset or by decreasing uptake value in a PET dataset.

This function requires bvals or uptake be a keyword argument to generate the volume sequence. The b-values are assumed to all orientations in a DWI dataset, and uptake uptake values correspond to all volumes in a PET dataset.

It is assumed 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.

Other Parameters:

size (int, optional) – Number of indices to generate.
bvals (list, optional) – List of b-values corresponding to all orientations of a DWI dataset. If provided and stop_index is not set, then stop_index is inferred as len(bvals). If stop_index is set, then stop_index must be <= len(bvals).
uptake (list, optional) – List of uptake values corresponding to all volumes of the dataset. If provided and stop_index is not set, then stop_index is inferred as len(uptake). If stop_index is set, then stop_index must be <= len(uptake)

start_indexint, optional: Starting index (inclusive) for the iteration. If provided, only indices >= start_index will be yielded.
stop_indexint, optional: Stopping index (exclusive) for the iteration. If provided, only indices < stop_index will be yielded; if not provided and no domain-defining sequence (('bvals', 'uptake')) is provided, then stop_index is inferred as start_index + size.

Notes

Iterators operate over an absolute index domain and yield absolute indices. The domain is always the half-open interval [start_index, stop_index) (end exclusive). One of the size-defining inputs must be provided: size, bvals, or uptake.If bvals or uptake is given, it takes precedence over size; size is only used when no modality-specific parameter is provided. When a sequence (bvals/uptake) is used, it defines the maximum valid index (i.e., the domain length) and stop_index defaults to len(sequence).

Yields:: int – The next index.

Examples

>>> list(monotonic_value_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]
>>> list(monotonic_value_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]
>>> list(monotonic_value_iterator(bvals=[0.0, 0.0, 1000.0, 1000.0, 700.0, 700.0, 2000.0, 2000.0, 0.0], start_index=4))
[8, 4, 5, 6, 7]
>>> list(monotonic_value_iterator(uptake=[-1.23, 1.06, 1.02, 1.38, -1.46, -1.12, -1.19, 1.24, 1.05], start_index=2))
[3, 7, 8, 2, 5, 6, 4]
>>> list(monotonic_value_iterator(bvals=[0.0, 0.0, 1000.0, 1000.0, 700.0, 700.0, 2000.0, 2000.0, 0.0], start_index=4, stop_index=7))
[4, 5, 6]
>>> list(monotonic_value_iterator(uptake=[-1.23, 1.06, 1.02, 1.38, -1.46, -1.12, -1.19, 1.24, 1.05], start_index=2, stop_index=7))
[3, 2, 5, 6, 4]

nifreeze.utils.iterators.random_iterator(**kwargs: Any) → 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.

sizeint, optional: Number of indices to generate.
bvalslist, optional: List of b-values corresponding to all orientations of a DWI dataset. If provided and stop_index is not set, then stop_index is inferred as len(bvals). If stop_index is set, then stop_index must be <= len(bvals).
uptakelist, optional: List of uptake values corresponding to all volumes of the dataset. If provided and stop_index is not set, then stop_index is inferred as len(uptake). If stop_index is set, then stop_index must be <= len(uptake)
start_indexint, optional: Starting index (inclusive) for the iteration. If provided, only indices >= start_index will be yielded.
stop_indexint, optional: Stopping index (exclusive) for the iteration. If provided, only indices < stop_index will be yielded; if not provided and no domain-defining sequence (('bvals', 'uptake')) is provided, then stop_index is inferred as start_index + size.

Notes

Iterators operate over an absolute index domain and yield absolute indices. The domain is always the half-open interval [start_index, stop_index) (end exclusive). One of the size-defining inputs must be provided: size, bvals, or uptake.If bvals or uptake is given, it takes precedence over size; size is only used when no modality-specific parameter is provided. When a sequence (bvals/uptake) is used, it defines the maximum valid index (i.e., the domain length) and stop_index defaults to len(sequence).

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]
>>> list(random_iterator(size=4, start_index=3, seed=0))
[3]
>>> list(random_iterator(size=7, start_index=3, stop_index=6, seed=0))
[3, 5, 4]

nifreeze.utils.iterators module¶