niworkflows.interfaces.bids module#

Interfaces for handling BIDS-like neuroimaging structures.

class niworkflows.interfaces.bids.BIDSDataGrabber(*args, **kwargs)[source]#

Bases: nipype.interfaces.base.core.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

  • bold (a list of items which are any value) – Output functional 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.

  • 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)[source]#

Bases: nipype.interfaces.base.core.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

  • 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)[source]#

Bases: nipype.interfaces.base.core.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-1_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)

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 niworkflows.interfaces.bids._BIDSInfoOutputSpec

class niworkflows.interfaces.bids.DerivativesDataSink(allowed_entities=None, out_path_base=None, **inputs)[source]#

Bases: nipype.interfaces.base.core.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-1_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-1_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-1_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-1_space-MNI152NLin6Asym_res-01_desc-preproc_bold.json'

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

>>> lines[2]
'  "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-1_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 tomatch 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.ReadSidecarJSON(fields=None, undef_fields=False, **inputs)[source]#

Bases: nipype.interfaces.base.core.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)

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 niworkflows.interfaces.bids._ReadSidecarJSONOutputSpec