niworkflows.interfaces.bids module

Interfaces for handling BIDS-like neuroimaging structures.

class niworkflows.interfaces.bids.BIDSDataGrabber(*args, **kwargs)

Bases: SimpleInterface

Collect files from a BIDS directory structure.

>>> bids_src = BIDSDataGrabber(anat_only=False)
>>> bids_src.inputs.subject_data = bids_collect_data(
...     str(datadir / 'ds114'), '01', bids_validate=False)[0]
>>> bids_src.inputs.subject_id = '01'
>>> res = bids_src.run()
>>> res.outputs.t1w  
['.../ds114/sub-01/ses-retest/anat/sub-01_ses-retest_T1w.nii.gz',
 '.../ds114/sub-01/ses-test/anat/sub-01_ses-test_T1w.nii.gz']

Optional Inputs:

• subject_data (a dictionary with keys which are a string and with values which are any value)

• subject_id (a string)

Outputs:

• asl (a list of items which are any value) – Output ASL images.

• bold (a list of items which are any value) – Output functional images.

• dwi (a list of items which are any value) – Output DWI images.

• flair (a list of items which are any value) – Output FLAIR images.

• fmap (a list of items which are any value) – Output fieldmaps.

• out_dict (a dictionary with keys which are any value and with values which are any value) – Output data structure.

• pet (a list of items which are any value) – Output PET images.

• roi (a list of items which are any value) – Output ROI images.

• sbref (a list of items which are any value) – Output sbrefs.

• t1w (a list of items which are any value) – Output T1w images.

• t2w (a list of items which are any value) – Output T2w images.

class niworkflows.interfaces.bids.BIDSFreeSurferDir(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Prepare a FreeSurfer subjects directory for use in a BIDS context.

Constructs a subjects directory path, creating if necessary, and copies fsaverage subjects (if necessary or forced via overwrite_fsaverage) into from the local FreeSurfer distribution.

If subjects_dir is an absolute path, then it is returned as the output subjects_dir. If it is a relative path, it will be resolved relative to the `derivatives directory.`

Regardless of the path, if fsaverage spaces are provided, they will be verified to exist, or copied from $FREESURFER_HOME/subjects, if missing.

The output subjects_dir is intended to be passed to ReconAll and other FreeSurfer interfaces.

Mandatory Inputs:

• derivatives (a pathlike object or string representing an existing directory) – BIDS derivatives directory.

• freesurfer_home (a pathlike object or string representing an existing directory) – FreeSurfer installation directory.

Optional Inputs:

• minimum_fs_version (‘7.0.0’) – Minimum FreeSurfer version for compatibility.

• overwrite_fsaverage (a boolean) – Overwrite fsaverage directories, if present. (Nipype default value: False)

• spaces (a list of items which are a string) – Set of output spaces to prepare.

• subjects_dir (a string or a pathlike object or string representing a directory) – Name of FreeSurfer subjects directory. (Nipype default value: freesurfer)

Outputs:

subjects_dir (a string or os.PathLike object referring to an existing directory) – FreeSurfer subjects directory.

class niworkflows.interfaces.bids.BIDSInfo(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Extract BIDS entities from a BIDS-conforming path.

This interface uses only the basename, not the path, to determine the subject, session, task, run, acquisition or reconstruction.

>>> bids_info = BIDSInfo(bids_dir=str(datadir / 'ds054'), bids_validate=False)
>>> bids_info.inputs.in_file = '''sub-01/func/ses-retest/sub-01_ses-retest_task-covertverbgeneration_bold.nii.gz'''
>>> res = bids_info.run()
>>> res.outputs

acquisition = <undefined>
reconstruction = <undefined>
run = <undefined>
session = retest
subject = 01
suffix = bold
task = covertverbgeneration

>>> bids_info = BIDSInfo(bids_dir=str(datadir / 'ds054'), bids_validate=False)
>>> bids_info.inputs.in_file = '''sub-01/func/ses-retest/sub-01_ses-retest_task-covertverbgeneration_rec-MB_acq-AP_run-01_bold.nii.gz'''
>>> res = bids_info.run()
>>> res.outputs

acquisition = AP
reconstruction = MB
run = 1
session = retest
subject = 01
suffix = bold
task = covertverbgeneration

>>> bids_info = BIDSInfo(bids_dir=str(datadir / 'ds054'), bids_validate=False)
>>> bids_info.inputs.in_file = '''sub-01/func/ses-retest/sub-01_ses-retest_task-covertverbgeneration_acq-AP_run-01_bold.nii.gz'''
>>> res = bids_info.run()
>>> res.outputs

acquisition = AP
reconstruction = <undefined>
run = 1
session = retest
subject = 01
suffix = bold
task = covertverbgeneration

>>> bids_info = BIDSInfo(bids_validate=False)
>>> bids_info.inputs.in_file = str(
...     datadir / 'ds114' / 'sub-01' / 'ses-retest' /
...     'func' / 'sub-01_ses-retest_task-covertverbgeneration_bold.nii.gz')
>>> res = bids_info.run()
>>> res.outputs

acquisition = <undefined>
reconstruction = <undefined>
run = <undefined>
session = retest
subject = 01
suffix = bold
task = covertverbgeneration

>>> bids_info = BIDSInfo(bids_validate=False)
>>> bids_info.inputs.in_file = '''sub-01/func/ses-retest/sub-01_ses-retest_task-covertverbgeneration_bold.nii.gz'''
>>> res = bids_info.run()
>>> res.outputs

acquisition = <undefined>
reconstruction = <undefined>
run = <undefined>
session = retest
subject = 01
suffix = bold
task = covertverbgeneration

Mandatory Inputs:

in_file (a pathlike object or string representing a file) – Input file, part of a BIDS tree.

Optional Inputs:

• bids_dir (a pathlike object or string representing an existing directory or None) – Optional bids directory. (Nipype default value: None)

• bids_validate (a boolean) – Enable BIDS validator. (Nipype default value: True)

• index_db (a pathlike object or string representing an existing directory) – A PyBIDS layout cache directory.

Outputs:

• acquisition (a string)

• reconstruction (a string)

• run (an integer)

• session (a string)

• subject (a string)

• suffix (a string)

• task (a string)

output_spec

alias of _BIDSInfoOutputSpec

class niworkflows.interfaces.bids.DerivativesDataSink(allowed_entities=None, out_path_base=None, **inputs)

Bases: SimpleInterface

Store derivative files.

Saves the in_file into a BIDS-Derivatives folder provided by base_directory, given the input reference source_file.

>>> import tempfile
>>> tmpdir = Path(tempfile.mkdtemp())
>>> tmpfile = tmpdir / 'a_temp_file.nii.gz'
>>> tmpfile.open('w').close()  # "touch" the file
>>> t1w_source = bids_collect_data(
...     str(datadir / 'ds114'), '01', bids_validate=False)[0]['t1w'][0]
>>> dsink = DerivativesDataSink(base_directory=str(tmpdir), check_hdr=False)
>>> dsink.inputs.in_file = str(tmpfile)
>>> dsink.inputs.source_file = t1w_source
>>> dsink.inputs.desc = 'denoised'
>>> dsink.inputs.compress = False
>>> res = dsink.run()
>>> res.outputs.out_file  
'.../niworkflows/sub-01/ses-retest/anat/sub-01_ses-retest_desc-denoised_T1w.nii'

>>> tmpfile = tmpdir / 'a_temp_file.nii'
>>> tmpfile.open('w').close()  # "touch" the file
>>> dsink = DerivativesDataSink(base_directory=str(tmpdir), check_hdr=False,
...                             allowed_entities=("custom",))
>>> dsink.inputs.in_file = str(tmpfile)
>>> dsink.inputs.source_file = t1w_source
>>> dsink.inputs.custom = 'noise'
>>> res = dsink.run()
>>> res.outputs.out_file  
'.../niworkflows/sub-01/ses-retest/anat/sub-01_ses-retest_custom-noise_T1w.nii'

>>> dsink = DerivativesDataSink(base_directory=str(tmpdir), check_hdr=False,
...                             allowed_entities=("custom",))
>>> dsink.inputs.in_file = [str(tmpfile), str(tmpfile)]
>>> dsink.inputs.source_file = t1w_source
>>> dsink.inputs.custom = [1, 2]
>>> dsink.inputs.compress = True
>>> res = dsink.run()
>>> res.outputs.out_file  
['.../niworkflows/sub-01/ses-retest/anat/sub-01_ses-retest_custom-1_T1w.nii.gz',
 '.../niworkflows/sub-01/ses-retest/anat/sub-01_ses-retest_custom-2_T1w.nii.gz']

>>> dsink = DerivativesDataSink(base_directory=str(tmpdir), check_hdr=False,
...                             allowed_entities=("custom1", "custom2"))
>>> dsink.inputs.in_file = [str(tmpfile)] * 2
>>> dsink.inputs.source_file = t1w_source
>>> dsink.inputs.custom1 = [1, 2]
>>> dsink.inputs.custom2 = "b"
>>> res = dsink.run()
>>> res.outputs.out_file  
['.../niworkflows/sub-01/ses-retest/anat/sub-01_ses-retest_custom1-1_custom2-b_T1w.nii',
 '.../niworkflows/sub-01/ses-retest/anat/sub-01_ses-retest_custom1-2_custom2-b_T1w.nii']

When multiple source files are passed, only common entities are passed down. For example, if two T1w images from different sessions are used to generate a single image, the session entity is removed automatically.

>>> bids_dir = tmpdir / 'bidsroot'
>>> multi_source = [
...     bids_dir / 'sub-02/ses-A/anat/sub-02_ses-A_T1w.nii.gz',
...     bids_dir / 'sub-02/ses-B/anat/sub-02_ses-B_T1w.nii.gz']
>>> for source_file in multi_source:
...     source_file.parent.mkdir(parents=True, exist_ok=True)
...     _ = source_file.write_text("")
>>> dsink = DerivativesDataSink(base_directory=str(tmpdir), check_hdr=False)
>>> dsink.inputs.in_file = str(tmpfile)
>>> dsink.inputs.source_file = list(map(str, multi_source))
>>> dsink.inputs.desc = 'preproc'
>>> res = dsink.run()
>>> res.outputs.out_file  
'.../niworkflows/sub-02/anat/sub-02_desc-preproc_T1w.nii'

If, on the other hand, only one is used, the session is preserved:

>>> dsink.inputs.source_file = str(multi_source[0])
>>> res = dsink.run()
>>> res.outputs.out_file  
'.../niworkflows/sub-02/ses-A/anat/sub-02_ses-A_desc-preproc_T1w.nii'

>>> bids_dir = tmpdir / 'bidsroot' / 'sub-02' / 'ses-noanat' / 'func'
>>> bids_dir.mkdir(parents=True, exist_ok=True)
>>> tricky_source = bids_dir / 'sub-02_ses-noanat_task-rest_run-01_bold.nii.gz'
>>> tricky_source.open('w').close()
>>> dsink = DerivativesDataSink(base_directory=str(tmpdir), check_hdr=False)
>>> dsink.inputs.in_file = str(tmpfile)
>>> dsink.inputs.source_file = str(tricky_source)
>>> dsink.inputs.desc = 'preproc'
>>> res = dsink.run()
>>> res.outputs.out_file  
'.../niworkflows/sub-02/ses-noanat/func/sub-02_ses-noanat_task-rest_run-01_desc-preproc_bold.nii'

>>> bids_dir = tmpdir / 'bidsroot' / 'sub-02' / 'ses-noanat' / 'func'
>>> bids_dir.mkdir(parents=True, exist_ok=True)
>>> tricky_source = bids_dir / 'sub-02_ses-noanat_task-rest_run-01_bold.nii.gz'
>>> tricky_source.open('w').close()
>>> dsink = DerivativesDataSink(base_directory=str(tmpdir), check_hdr=False)
>>> dsink.inputs.in_file = str(tmpfile)
>>> dsink.inputs.source_file = str(tricky_source)
>>> dsink.inputs.desc = 'preproc'
>>> dsink.inputs.RepetitionTime = 0.75
>>> res = dsink.run()
>>> res.outputs.out_meta  
'.../niworkflows/sub-02/ses-noanat/func/sub-02_ses-noanat_task-rest_run-01_desc-preproc_bold.json'

>>> Path(res.outputs.out_meta).read_text().splitlines()[1]
'  "RepetitionTime": 0.75'

>>> bids_dir = tmpdir / 'bidsroot' / 'sub-02' / 'ses-noanat' / 'func'
>>> bids_dir.mkdir(parents=True, exist_ok=True)
>>> tricky_source = bids_dir / 'sub-02_ses-noanat_task-rest_run-01_bold.nii.gz'
>>> tricky_source.open('w').close()
>>> dsink = DerivativesDataSink(base_directory=str(tmpdir), check_hdr=False,
...                             SkullStripped=True)
>>> dsink.inputs.in_file = str(tmpfile)
>>> dsink.inputs.source_file = str(tricky_source)
>>> dsink.inputs.desc = 'preproc'
>>> dsink.inputs.space = 'MNI152NLin6Asym'
>>> dsink.inputs.resolution = '01'
>>> dsink.inputs.RepetitionTime = 0.75
>>> res = dsink.run()
>>> res.outputs.out_meta  
'.../niworkflows/sub-02/ses-noanat/func/sub-02_ses-noanat_task-rest_run-01_space-MNI152NLin6Asym_res-01_desc-preproc_bold.json'

>>> lines = Path(res.outputs.out_meta).read_text().splitlines()
>>> lines[1]
'  "RepetitionTime": 0.75,'

>>> lines[2]  
'  "Resolution": "Template MNI152NLin6Asym (1.0x1.0x1.0 mm^3)...'

>>> lines[3]
'  "SkullStripped": true'

>>> bids_dir = tmpdir / 'bidsroot' / 'sub-02' / 'ses-noanat' / 'func'
>>> bids_dir.mkdir(parents=True, exist_ok=True)
>>> tricky_source = bids_dir / 'sub-02_ses-noanat_task-rest_run-01_bold.nii.gz'
>>> tricky_source.open('w').close()
>>> dsink = DerivativesDataSink(base_directory=str(tmpdir), check_hdr=False,
...                             SkullStripped=True)
>>> dsink.inputs.in_file = str(tmpfile)
>>> dsink.inputs.source_file = str(tricky_source)
>>> dsink.inputs.desc = 'preproc'
>>> dsink.inputs.resolution = 'native'
>>> dsink.inputs.space = 'MNI152NLin6Asym'
>>> dsink.inputs.RepetitionTime = 0.75
>>> dsink.inputs.meta_dict = {'RepetitionTime': 1.75, 'SkullStripped': False, 'Z': 'val'}
>>> res = dsink.run()
>>> res.outputs.out_meta  
'.../niworkflows/sub-02/ses-noanat/func/sub-02_ses-noanat_task-rest_run-01_space-MNI152NLin6Asym_desc-preproc_bold.json'

>>> lines = Path(res.outputs.out_meta).read_text().splitlines()
>>> lines[1]
'  "RepetitionTime": 0.75,'

>>> lines[2]
'  "SkullStripped": true,'

>>> lines[3]
'  "Z": "val"'

Mandatory Inputs:

• in_file (a list of items which are a pathlike object or string representing an existing file) – The object to be saved.

• source_file (a list of items which are a pathlike object or string representing a file) – The source file(s) to extract entities from.

Optional Inputs:

• base_directory (a string or os.PathLike object) – Path to the base directory for storing data.

• check_hdr (a boolean) – Fix headers of NIfTI outputs. (Nipype default value: True)

• compress (a list of items which are a boolean or None) – Whether in_file should be compressed (True), uncompressed (False) or left unmodified (None, default). (Nipype default value: [])

• data_dtype (a string) – NumPy datatype to coerce NIfTI data to, or source to match the input file dtype.

• dismiss_entities (a list of items which are a string or None) – A list entities that will not be propagated from the source file. (Nipype default value: [])

• meta_dict (a dictionary with keys which are a value of class ‘str’ and with values which are any value) – An input dictionary containing metadata.

Outputs:

• compression (a list of items which are a boolean or None) – Whether in_file should be compressed (True), uncompressed (False) or left unmodified (None).

• fixed_hdr (a list of items which are a boolean) – Whether derivative header was fixed.

• out_file (a list of items which are a pathlike object or string representing an existing file)

• out_meta (a list of items which are a pathlike object or string representing an existing file)

out_path_base = 'niworkflows'

class niworkflows.interfaces.bids.PrepareDerivative(allowed_entities=None, **inputs)

Bases: SimpleInterface

Prepare derivative files and metadata.

Collects entities from source files and inputs, filters them for allowed entities, and constructs a relative path within a BIDS dataset.

For each file, the interface will determine if any changes to the file contents are needed, including:

• Compression (or decompression) of the file

• Coercion of the data type

• Fixing the NIfTI header - Align qform and sform affines and codes - Set zooms and units

If the input file needs to be modified, the interface will write a new file and return the path to it. If no changes are needed, the interface will return the path to the input file.

>>> import tempfile
>>> tmpdir = Path(tempfile.mkdtemp())
>>> tmpfile = tmpdir / 'a_temp_file.nii.gz'
>>> tmpfile.open('w').close()  # "touch" the file
>>> t1w_source = bids_collect_data(
...     str(datadir / 'ds114'), '01', bids_validate=False)[0]['t1w'][0]
>>> prep = PrepareDerivative(check_hdr=False)
>>> prep.inputs.in_file = str(tmpfile)
>>> prep.inputs.source_file = t1w_source
>>> prep.inputs.desc = 'denoised'
>>> prep.inputs.compress = False
>>> res = prep.run()
>>> res.outputs.out_file  
'.../a_temp_file.nii.gz'
>>> res.outputs.out_path  
'sub-01/ses-retest/anat/sub-01_ses-retest_desc-denoised_T1w.nii'

>>> tmpfile = tmpdir / 'a_temp_file.nii'
>>> tmpfile.open('w').close()  # "touch" the file
>>> prep = PrepareDerivative(check_hdr=False, allowed_entities=("custom",))
>>> prep.inputs.in_file = str(tmpfile)
>>> prep.inputs.source_file = t1w_source
>>> prep.inputs.custom = 'noise'
>>> res = prep.run()
>>> res.outputs.out_file  
'.../a_temp_file.nii'
>>> res.outputs.out_path  
'sub-01/ses-retest/anat/sub-01_ses-retest_custom-noise_T1w.nii'

>>> prep = PrepareDerivative(check_hdr=False, allowed_entities=("custom",))
>>> prep.inputs.in_file = [str(tmpfile), str(tmpfile)]
>>> prep.inputs.source_file = t1w_source
>>> prep.inputs.custom = [1, 2]
>>> prep.inputs.compress = True
>>> res = prep.run()
>>> res.outputs.out_file  
['.../a_temp_file.nii', '.../a_temp_file.nii']
>>> res.outputs.out_path  
['sub-01/ses-retest/anat/sub-01_ses-retest_custom-1_T1w.nii.gz',
 'sub-01/ses-retest/anat/sub-01_ses-retest_custom-2_T1w.nii.gz']

>>> prep = PrepareDerivative(check_hdr=False, allowed_entities=("custom1", "custom2"))
>>> prep.inputs.in_file = [str(tmpfile)] * 2
>>> prep.inputs.source_file = t1w_source
>>> prep.inputs.custom1 = [1, 2]
>>> prep.inputs.custom2 = "b"
>>> res = prep.run()
>>> res.outputs.out_file  
['.../a_temp_file.nii', '.../a_temp_file.nii']
>>> res.outputs.out_path  
['sub-01/ses-retest/anat/sub-01_ses-retest_custom1-1_custom2-b_T1w.nii',
 'sub-01/ses-retest/anat/sub-01_ses-retest_custom1-2_custom2-b_T1w.nii']

When multiple source files are passed, only common entities are passed down. For example, if two T1w images from different sessions are used to generate a single image, the session entity is removed automatically.

>>> bids_dir = tmpdir / 'bidsroot'
>>> multi_source = [
...     bids_dir / 'sub-02/ses-A/anat/sub-02_ses-A_T1w.nii.gz',
...     bids_dir / 'sub-02/ses-B/anat/sub-02_ses-B_T1w.nii.gz']
>>> for source_file in multi_source:
...     source_file.parent.mkdir(parents=True, exist_ok=True)
...     _ = source_file.write_text("")
>>> prep = PrepareDerivative(check_hdr=False)
>>> prep.inputs.in_file = str(tmpfile)
>>> prep.inputs.source_file = list(map(str, multi_source))
>>> prep.inputs.desc = 'preproc'
>>> res = prep.run()
>>> res.outputs.out_path  
'sub-02/anat/sub-02_desc-preproc_T1w.nii'

If, on the other hand, only one is used, the session is preserved:

>>> prep.inputs.source_file = str(multi_source[0])
>>> res = prep.run()
>>> res.outputs.out_path  
'sub-02/ses-A/anat/sub-02_ses-A_desc-preproc_T1w.nii'

>>> bids_dir = tmpdir / 'bidsroot' / 'sub-02' / 'ses-noanat' / 'func'
>>> bids_dir.mkdir(parents=True, exist_ok=True)
>>> tricky_source = bids_dir / 'sub-02_ses-noanat_task-rest_run-01_bold.nii.gz'
>>> tricky_source.open('w').close()
>>> prep = PrepareDerivative(check_hdr=False)
>>> prep.inputs.in_file = str(tmpfile)
>>> prep.inputs.source_file = str(tricky_source)
>>> prep.inputs.desc = 'preproc'
>>> res = prep.run()
>>> res.outputs.out_path  
'sub-02/ses-noanat/func/sub-02_ses-noanat_task-rest_run-01_desc-preproc_bold.nii'

>>> bids_dir = tmpdir / 'bidsroot' / 'sub-02' / 'ses-noanat' / 'func'
>>> bids_dir.mkdir(parents=True, exist_ok=True)
>>> tricky_source = bids_dir / 'sub-02_ses-noanat_task-rest_run-01_bold.nii.gz'
>>> tricky_source.open('w').close()
>>> prep = PrepareDerivative(check_hdr=False)
>>> prep.inputs.in_file = str(tmpfile)
>>> prep.inputs.source_file = str(tricky_source)
>>> prep.inputs.desc = 'preproc'
>>> prep.inputs.RepetitionTime = 0.75
>>> res = prep.run()
>>> res.outputs.out_meta  
{'RepetitionTime': 0.75}

>>> bids_dir = tmpdir / 'bidsroot' / 'sub-02' / 'ses-noanat' / 'func'
>>> bids_dir.mkdir(parents=True, exist_ok=True)
>>> tricky_source = bids_dir / 'sub-02_ses-noanat_task-rest_run-01_bold.nii.gz'
>>> tricky_source.open('w').close()
>>> prep = PrepareDerivative(check_hdr=False, SkullStripped=True)
>>> prep.inputs.in_file = str(tmpfile)
>>> prep.inputs.source_file = str(tricky_source)
>>> prep.inputs.desc = 'preproc'
>>> prep.inputs.space = 'MNI152NLin6Asym'
>>> prep.inputs.resolution = '01'
>>> prep.inputs.RepetitionTime = 0.75
>>> res = prep.run()
>>> res.outputs.out_meta  
{'SkullStripped': True,
 'RepetitionTime': 0.75,
 'Resolution': 'Template MNI152NLin6Asym (1.0x1.0x1.0 mm^3)...'}

>>> bids_dir = tmpdir / 'bidsroot' / 'sub-02' / 'ses-noanat' / 'func'
>>> bids_dir.mkdir(parents=True, exist_ok=True)
>>> tricky_source = bids_dir / 'sub-02_ses-noanat_task-rest_run-01_bold.nii.gz'
>>> tricky_source.open('w').close()
>>> prep = PrepareDerivative(check_hdr=False, SkullStripped=True)
>>> prep.inputs.in_file = str(tmpfile)
>>> prep.inputs.source_file = str(tricky_source)
>>> prep.inputs.desc = 'preproc'
>>> prep.inputs.resolution = 'native'
>>> prep.inputs.space = 'MNI152NLin6Asym'
>>> prep.inputs.RepetitionTime = 0.75
>>> prep.inputs.meta_dict = {'RepetitionTime': 1.75, 'SkullStripped': False, 'Z': 'val'}
>>> res = prep.run()
>>> res.outputs.out_meta  
{'RepetitionTime': 0.75, 'SkullStripped': True, 'Z': 'val'}

Mandatory Inputs:

• in_file (a list of items which are a pathlike object or string representing an existing file) – The object to be saved.

• source_file (a list of items which are a pathlike object or string representing a file) – The source file(s) to extract entities from.

Optional Inputs:

• check_hdr (a boolean) – Fix headers of NIfTI outputs. (Nipype default value: True)

• compress (a list of items which are a boolean or None) – Whether in_file should be compressed (True), uncompressed (False) or left unmodified (None, default). (Nipype default value: [])

• data_dtype (a string) – NumPy datatype to coerce NIfTI data to, or source to match the input file dtype.

• dismiss_entities (a list of items which are a string or None) – A list entities that will not be propagated from the source file. (Nipype default value: [])

• meta_dict (a dictionary with keys which are a value of class ‘str’ and with values which are any value) – An input dictionary containing metadata.

Outputs:

• fixed_hdr (a list of items which are a boolean) – Whether derivative header was fixed.

• out_file (a list of items which are a pathlike object or string representing an existing file) – Derivative file path.

• out_meta (a dictionary with keys which are a value of class ‘str’ and with values which are any value) – Derivative metadata.

• out_path (a list of items which are a string) – Relative path in target directory.

class niworkflows.interfaces.bids.ReadSidecarJSON(fields=None, undef_fields=False, **inputs)

Bases: SimpleInterface

Read JSON sidecar files of a BIDS tree.

>>> fmap = str(datadir / 'ds054' / 'sub-100185' / 'fmap' /
...            'sub-100185_phasediff.nii.gz')

>>> meta = ReadSidecarJSON(in_file=fmap, bids_dir=str(datadir / 'ds054'),
...                        bids_validate=False).run()
>>> meta.outputs.subject
'100185'
>>> meta.outputs.suffix
'phasediff'
>>> meta.outputs.out_dict['Manufacturer']
'SIEMENS'
>>> meta = ReadSidecarJSON(in_file=fmap, fields=['Manufacturer'],
...                        bids_dir=str(datadir / 'ds054'),
...                        bids_validate=False).run()
>>> meta.outputs.out_dict['Manufacturer']
'SIEMENS'
>>> meta.outputs.Manufacturer
'SIEMENS'
>>> meta.outputs.OtherField  
Traceback (most recent call last):
AttributeError:
>>> meta = ReadSidecarJSON(
...     in_file=fmap, fields=['MadeUpField'],
...     bids_dir=str(datadir / 'ds054'),
...     bids_validate=False).run()  
Traceback (most recent call last):
KeyError:
>>> meta = ReadSidecarJSON(in_file=fmap, fields=['MadeUpField'],
...                        undef_fields=True,
...                        bids_dir=str(datadir / 'ds054'),
...                        bids_validate=False).run()
>>> meta.outputs.MadeUpField
<undefined>

Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – The input nifti file.

Optional Inputs:

• bids_dir (a pathlike object or string representing an existing directory or None) – Optional bids directory. (Nipype default value: None)

• bids_validate (a boolean) – Enable BIDS validator. (Nipype default value: True)

• index_db (a pathlike object or string representing an existing directory) – A PyBIDS layout cache directory.

Outputs:

• acquisition (a string)

• out_dict (a dictionary with keys which are any value and with values which are any value)

• reconstruction (a string)

• run (an integer)

• session (a string)

• subject (a string)

• suffix (a string)

• task (a string)

layout = None

output_spec

alias of _ReadSidecarJSONOutputSpec

class niworkflows.interfaces.bids.SaveDerivative(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Save a prepared derivative file.

This interface is intended to be used after the PrepareDerivative interface. Its main purpose is to copy data to the output directory if an identical copy is not already present.

This ensures that changes to the output directory metadata (e.g., mtime) do not trigger unnecessary recomputations in the workflow.

Mandatory Inputs:

• base_directory (a pathlike object or string representing an existing directory) – Path to the base directory for storing data.

• in_file (a list of items which are a pathlike object or string representing an existing file) – The object to be saved.

Optional Inputs:

• metadata (a dictionary with keys which are a value of class ‘str’ and with values which are any value) – Metadata to be saved alongside the file.

• relative_path (a list of items which are a string) – Path to the file relative to the base directory.

Outputs:

• out_file (a list of items which are a pathlike object or string representing a file) – Written file path.

• out_meta (a list of items which are a pathlike object or string representing a file) – Written JSON sidecar path.