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']

input_spec¶: alias of niworkflows.interfaces.bids._BIDSDataGrabberInputSpec

output_spec¶: alias of niworkflows.interfaces.bids._BIDSDataGrabberOutputSpec

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.

input_spec¶: alias of niworkflows.interfaces.bids._BIDSFreeSurferDirInputSpec

output_spec¶: alias of niworkflows.interfaces.bids._BIDSFreeSurferDirOutputSpec

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

input_spec¶: alias of niworkflows.interfaces.bids._BIDSInfoInputSpec

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"'

input_spec¶: alias of niworkflows.interfaces.bids._DerivativesDataSinkInputSpec

out_path_base = 'niworkflows'¶

output_spec¶: alias of niworkflows.interfaces.bids._DerivativesDataSinkOutputSpec

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>

input_spec¶: alias of niworkflows.interfaces.bids._ReadSidecarJSONInputSpec

layout = None¶

output_spec¶: alias of niworkflows.interfaces.bids._ReadSidecarJSONOutputSpec