sdcflows.fieldmaps module

Utilities for fieldmap estimation.

class sdcflows.fieldmaps.EstimatorType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Represents different types of fieldmap estimation approach.

class sdcflows.fieldmaps.FieldmapEstimation(sources=None, *, bids_id: str = None)

Bases: object

Represent fieldmap estimation strategies.

This class provides a consistent interface to all types of fieldmap estimation strategies. The actual type of method for estimation is inferred from the sources input, and collects all the available metadata.

bids_id

The unique B0FieldIdentifier field of this fieldmap.

get_workflow(set_inputs=True, **kwargs)

Build the estimation workflow corresponding to this instance.

method

Flag indicating the estimator type inferred from the input sources.

paths()

Return a tuple of paths that are sorted.

sanitized_id

Sanitized version of the bids_id with special characters replaced by underscores.

sources

File path or list of paths indicating the source data to estimate a fieldmap.

class sdcflows.fieldmaps.FieldmapFile(path, *, metadata=NOTHING, find_meta: bool = True)

Bases: object

Represent a file that can be used in some fieldmap estimation method.

The class will read metadata from a sidecar JSON with filename matching that of the file. This class may receive metadata as a keyword argument at initialization.

Examples

>>> f = FieldmapFile(dsA_dir / "sub-01" / "anat" / "sub-01_T1w.nii.gz")
>>> f.suffix
'T1w'

By default, the immediate JSON sidecar file is consulted for metadata.

>>> f = FieldmapFile(
...     dsA_dir / "sub-01" / "fmap" / "sub-01_dir-LR_epi.nii.gz",
... )
>>> f.metadata['TotalReadoutTime']
0.005

>>> f = FieldmapFile(
...     dsA_dir / "sub-01" / "fmap" / "sub-01_phasediff.nii.gz"
... )
>>> f.metadata['EchoTime2']
0.00746

>>> f = FieldmapFile(
...     dsA_dir / "sub-01" / "fmap" / "sub-01_phase2.nii.gz"
... )
>>> f.metadata['EchoTime']
0.00746

>>> f = FieldmapFile(
...     dsA_dir / "sub-01" / "fmap" / "sub-01_fieldmap.nii.gz"
... )
>>> f.metadata['Units']
'rad/s'

However, it is possible to provide alternative metadata. It is recommended to load the metadata with an external tool that fully implements the BIDS inheritance rules to ensure correctness.

>>> f = FieldmapFile(
...     dsA_dir / "sub-01" / "fmap" / "sub-01_dir-LR_epi.nii.gz",
...     metadata={'TotalReadoutTime': 0.006}
... )
>>> f.metadata['TotalReadoutTime']
0.006

If metadata is present, warnings or errors may be presented.

>>> FieldmapFile(
...     dsA_dir / "sub-01" / "fmap" / "sub-01_dir-LR_epi.nii.gz",
...     find_meta=False
... )  
Traceback (most recent call last):
MetadataError: Missing 'PhaseEncodingDirection' ...

>>> FieldmapFile(
...     dsA_dir / "sub-01" / "fmap" / "sub-01_phasediff.nii.gz",
...     find_meta=False
... )  
Traceback (most recent call last):
MetadataError:

>>> FieldmapFile(
...     dsA_dir / "sub-01" / "fmap" / "sub-01_phase2.nii.gz",
...     find_meta=False
... )  
Traceback (most recent call last):
MetadataError:

>>> FieldmapFile(
...     dsA_dir / "sub-01" / "fmap" / "sub-01_fieldmap.nii.gz",
...     find_meta=False
... )  
Traceback (most recent call last):
MetadataError:

Readout timing information is required to estimate PEPOLAR fieldmaps, but it is possible to provide a fallback values. Therefore, warnings are logged if the metadata are missing.

>>> with caplog.at_level(logging.WARNING, "sdcflows.fieldmaps"):
...     f = FieldmapFile(
...         dsA_dir / "sub-01" / "fmap" / "sub-01_dir-LR_epi.nii.gz",
...         metadata={"TotalReadoutTime": None},
...     )  
>>> print(caplog.text)
WARNING ... Missing readout timing information ... Explicit fallback must be provided.

>>> with caplog.at_level(logging.WARNING, "sdcflows.fieldmaps"):
...     f = FieldmapFile(
...         dsA_dir / "sub-01" / "fmap" / "sub-01_dir-LR_epi.nii.gz",
...         metadata={"PhaseEncodingDirection": "i", "EstimatedTotalReadoutTime": 0.05},
...         find_meta=False,
...     )  
>>> print(caplog.text)
WARNING ... Missing readout timing information ... Estimated timing is available.

bids_root

Path of the BIDS root.

check_path(attribute, value)

Validate a fieldmap path.

entities

BIDS entities extracted from filepath.

find_meta

Enable/disable automated search for corresponding metadata.

metadata

Metadata associated to this file. When provided as keyword argument in initialization, will overwrite metadata read from sidecar JSON.

path

Path to a fieldmap file.

suffix

Extracted suffix from input file.

exception sdcflows.fieldmaps.MetadataError

Bases: ValueError

A better name for a specific value error.

sdcflows.fieldmaps.clear_registry()

Empty registries.

sdcflows.fieldmaps.get_identifier(filename, by='IntendedFor')

Return the fieldmap identifier for a given filename.

Parameters:

• filename (str) – The file we want to search in indexes.

• by (str (IntendedFor or sources)) – Index table in which the search should be performed.