Warning: This document is for an old version of niworkflows. The main version is master.

niworkflows.utils.spaces module

Utilities for tracking and filtering spaces.

niworkflows.utils.spaces.FSAVERAGE_DENSITY = {'fsaverage': '164k', 'fsaverage3': '642', 'fsaverage4': '2562', 'fsaverage5': '10k', 'fsaverage6': '41k'}

A map of legacy fsaverageX names to surface densities.

niworkflows.utils.spaces.FSAVERAGE_LEGACY = {'10k': 'fsaverage5', '164k': 'fsaverage', '2562': 'fsaverage4', '41k': 'fsaverage6', '642': 'fsaverage3'}

A map of surface densities to legacy fsaverageX names.

niworkflows.utils.spaces.NONSTANDARD_REFERENCES = ['T1w', 'T2w', 'anat', 'fsnative', 'func', 'run', 'sbref', 'session']

List of supported nonstandard reference spaces.

class niworkflows.utils.spaces.OutputReferencesAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)[source]

Bases: argparse.Action

Parse spatial references.

class niworkflows.utils.spaces.Reference(space: str = None, spec=NOTHING, standard: bool = False, dim: int = 3)[source]

Bases: object

Represent a (non)standard space specification.

Examples

>>> Reference('MNI152NLin2009cAsym')
Reference(space='MNI152NLin2009cAsym', spec={})
>>> Reference('MNI152NLin2009cAsym', {})
Reference(space='MNI152NLin2009cAsym', spec={})
>>> Reference('MNI152NLin2009cAsym', None)
Reference(space='MNI152NLin2009cAsym', spec={})
>>> Reference('MNI152NLin2009cAsym', {'res': 1})
Reference(space='MNI152NLin2009cAsym', spec={'res': 1})
>>> Reference('MNIPediatricAsym', {'cohort': '1'})
Reference(space='MNIPediatricAsym', spec={'cohort': '1'})
>>> Reference('func')
Reference(space='func', spec={})
>>> # Checks spaces with cohorts:
>>> Reference('MNIPediatricAsym')
Traceback (most recent call last):
  ...
ValueError: standard space "MNIPediatricAsym" is not fully defined.
...
>>> Reference(space='MNI152Lin', spec={'cohort': 1})
Traceback (most recent call last):
  ...
ValueError: standard space "MNI152Lin" does not accept ...
>>> Reference('MNIPediatricAsym', {'cohort': '100'})
Traceback (most recent call last):
  ...
ValueError: standard space "MNIPediatricAsym" does not contain ...
...
>>> Reference('MNIPediatricAsym', 'blah')
Traceback (most recent call last):
  ...
TypeError: ...
>>> Reference('shouldraise')
Traceback (most recent call last):
  ...
ValueError: space identifier "shouldraise" is invalid.
...
>>> # Check standard property
>>> Reference('func').standard
False
>>> Reference('MNI152Lin').standard
True
>>> Reference('MNIPediatricAsym', {'cohort': 1}).standard
True
>>> # Equality/inequality checks
>>> Reference('func') == Reference('func')
True
>>> Reference('func') != Reference('MNI152Lin')
True
>>> Reference('MNI152Lin', {'res': 1}) == Reference('MNI152Lin', {'res': 1})
True
>>> Reference('MNI152Lin', {'res': 1}) == Reference('MNI152Lin', {'res': 2})
False
>>> sp1 = Reference('MNIPediatricAsym', {'cohort': 1})
>>> sp2 = Reference('MNIPediatricAsym', {'cohort': 2})
>>> sp1 == sp2
False
>>> sp1 = Reference('MNIPediatricAsym', {'res': 1, 'cohort': 1})
>>> sp2 = Reference('MNIPediatricAsym', {'cohort': 1, 'res': 1})
>>> sp1 == sp2
True
dim

Dimensionality of the sampling manifold.

classmethod from_string(value)[source]

Parse a string to generate the corresponding list of References.

Parameters

value (str) – A string containing a space specification following fMRIPrep’s language for --output-spaces (e.g., MNIPediatricAsym:cohort-1:cohort-2:res-1:res-2).

Returns

spaces – A list of corresponding spaces given the input string.

Return type

list of Reference

Examples

>>> Reference.from_string("MNI152NLin2009cAsym")
[Reference(space='MNI152NLin2009cAsym', spec={})]
>>> # Bad space name
>>> Reference.from_string("shouldraise")
Traceback (most recent call last):
  ...
ValueError: space identifier "shouldraise" is invalid.
...
>>> # Missing cohort
>>> Reference.from_string("MNIPediatricAsym")
Traceback (most recent call last):
  ...
ValueError: standard space "MNIPediatricAsym" is not fully defined.
...
>>> Reference.from_string("MNIPediatricAsym:cohort-1")
[Reference(space='MNIPediatricAsym', spec={'cohort': '1'})]
>>> Reference.from_string("MNIPediatricAsym:cohort-1:cohort-2")
[Reference(space='MNIPediatricAsym', spec={'cohort': '1'}),
 Reference(space='MNIPediatricAsym', spec={'cohort': '2'})]
>>> Reference.from_string("fsaverage:den-10k:den-164k")
[Reference(space='fsaverage', spec={'den': '10k'}),
 Reference(space='fsaverage', spec={'den': '164k'})]
>>> Reference.from_string("MNIPediatricAsym:cohort-5:cohort-6:res-2")
[Reference(space='MNIPediatricAsym', spec={'cohort': '5', 'res': '2'}),
 Reference(space='MNIPediatricAsym', spec={'cohort': '6', 'res': '2'})]
>>> Reference.from_string("MNIPediatricAsym:cohort-5:cohort-6:res-2:res-iso1.6mm")
[Reference(space='MNIPediatricAsym', spec={'cohort': '5', 'res': '2'}),
 Reference(space='MNIPediatricAsym', spec={'cohort': '5', 'res': 'iso1.6mm'}),
 Reference(space='MNIPediatricAsym', spec={'cohort': '6', 'res': '2'}),
 Reference(space='MNIPediatricAsym', spec={'cohort': '6', 'res': 'iso1.6mm'})]
property fullname

Generate a full-name combining cohort.

Examples

>>> Reference('MNI152Lin').fullname
'MNI152Lin'
>>> Reference('MNIPediatricAsym', {'cohort': 1}).fullname
'MNIPediatricAsym:cohort-1'
property legacyname

Generate a legacy name for fsaverageX spaces.

Examples

>>> Reference(space='fsaverage')
Reference(space='fsaverage', spec={'den': '164k'})
>>> Reference(space='fsaverage').legacyname
'fsaverage'
>>> Reference(space='fsaverage6')
Reference(space='fsaverage', spec={'den': '41k'})
>>> Reference(space='fsaverage6').legacyname
'fsaverage6'
>>> # Overwrites density of legacy "fsaverage" specifications
>>> Reference(space='fsaverage6', spec={'den': '10k'})
Reference(space='fsaverage', spec={'den': '41k'})
>>> Reference(space='fsaverage6', spec={'den': '10k'}).legacyname
'fsaverage6'
>>> # Return None if no legacy space
>>> Reference(space='fsaverage', spec={'den': '30k'}).legacyname is None
True
space

Name designating this space.

spec

The dictionary of specs.

standard

Whether this space is standard or not.

class niworkflows.utils.spaces.SpatialReferences(spaces=None, checkpoint=False)[source]

Bases: object

Manage specifications of spatial references.

Examples

>>> sp = SpatialReferences([
...     'func',
...     'fsnative',
...     'MNI152NLin2009cAsym',
...     'anat',
...     'fsaverage5',
...     'fsaverage6',
...     ('MNIPediatricAsym', {'cohort': '2'}),
...     ('MNI152NLin2009cAsym', {'res': 2}),
...     ('MNI152NLin2009cAsym', {'res': 1}),
... ])
>>> sp.get_spaces(standard=False)
['func', 'fsnative', 'anat']
>>> sp.get_spaces(standard=False, dim=(3,))
['func', 'anat']
>>> sp.get_spaces(nonstandard=False)
['MNI152NLin2009cAsym', 'fsaverage', 'MNIPediatricAsym:cohort-2']
>>> sp.get_spaces(nonstandard=False, dim=(3,))
['MNI152NLin2009cAsym', 'MNIPediatricAsym:cohort-2']
>>> sp.get_fs_spaces()
['fsnative', 'fsaverage5', 'fsaverage6']
>>> sp.get_standard(full_spec=True)
[Reference(space='fsaverage', spec={'den': '10k'}),
 Reference(space='fsaverage', spec={'den': '41k'}),
 Reference(space='MNI152NLin2009cAsym', spec={'res': 2}),
 Reference(space='MNI152NLin2009cAsym', spec={'res': 1})]
>>> sp.is_cached()
False
>>> sp.cached
Traceback (most recent call last):
 ...
ValueError: References have not ...
>>> sp.checkpoint()
>>> sp.is_cached()
True
>>> sp.cached.references
[Reference(space='func', spec={}),
 Reference(space='fsnative', spec={}),
 Reference(space='MNI152NLin2009cAsym', spec={}),
 Reference(space='anat', spec={}),
 Reference(space='fsaverage', spec={'den': '10k'}),
 Reference(space='fsaverage', spec={'den': '41k'}),
 Reference(space='MNIPediatricAsym', spec={'cohort': '2'}),
 Reference(space='MNI152NLin2009cAsym', spec={'res': 2}),
 Reference(space='MNI152NLin2009cAsym', spec={'res': 1})]
>>> sp.cached.get_fs_spaces()
['fsnative', 'fsaverage5', 'fsaverage6']
>>> sp.add(('MNIPediatricAsym', {'cohort': '2'}))
>>> sp.get_spaces(nonstandard=False, dim=(3,))
['MNI152NLin2009cAsym', 'MNIPediatricAsym:cohort-2']
>>> sp += [('MNIPediatricAsym', {'cohort': '2'})]
Traceback (most recent call last):
  ...
ValueError: space ...
>>> sp += [('MNIPediatricAsym', {'cohort': '1'})]
>>> sp.get_spaces(nonstandard=False, dim=(3,))
['MNI152NLin2009cAsym', 'MNIPediatricAsym:cohort-2', 'MNIPediatricAsym:cohort-1']
>>> sp.insert(0, ('MNIPediatricAsym', {'cohort': '3'}))
>>> sp.get_spaces(nonstandard=False, dim=(3,))
['MNIPediatricAsym:cohort-3',
 'MNI152NLin2009cAsym',
 'MNIPediatricAsym:cohort-2',
 'MNIPediatricAsym:cohort-1']
>>> sp.insert(0, ('MNIPediatricAsym', {'cohort': '3'}))
Traceback (most recent call last):
  ...
ValueError: space ...
>>> sp.checkpoint()
Traceback (most recent call last):
 ...
ValueError: References have already ...
>>> sp.checkpoint(force=True)
>>> sp.cached.references
[Reference(space='MNIPediatricAsym', spec={'cohort': '3'}),
 Reference(space='func', spec={}),
 Reference(space='fsnative', spec={}),
 Reference(space='MNI152NLin2009cAsym', spec={}),
 Reference(space='anat', spec={}),
 Reference(space='fsaverage', spec={'den': '10k'}),
 Reference(space='fsaverage', spec={'den': '41k'}),
 Reference(space='MNIPediatricAsym', spec={'cohort': '2'}),
 Reference(space='MNI152NLin2009cAsym', spec={'res': 2}),
 Reference(space='MNI152NLin2009cAsym', spec={'res': 1}),
 Reference(space='MNIPediatricAsym', spec={'cohort': '1'})]
add(value)[source]

Add one more space, without erroring if it exists.

append(value)[source]

Concatenate one more space.

property cached

Get cached spaces, raise error if not cached.

static check_space(space)[source]

Build a Reference object.

checkpoint(force=False)[source]

Cache and freeze current spaces to separate attribute.

get_fs_spaces()[source]

Return FreeSurfer spaces.

Discards nonlegacy fsaverage values (i.e., with nonstandard density value).

Examples

>>> SpatialReferences([
...     'fsnative',
...     'fsaverage6',
...     'fsaverage5',
...     'MNI152NLin6Asym',
... ]).get_fs_spaces()
['fsnative', 'fsaverage6', 'fsaverage5']
>>> SpatialReferences([
...     'fsnative',
...     'fsaverage6',
...     Reference(space='fsaverage', spec={'den': '30k'})
... ]).get_fs_spaces()
['fsnative', 'fsaverage6']
get_nonstandard(full_spec=False, dim=(2, 3))[source]

Return nonstandard spaces.

get_spaces(standard=True, nonstandard=True, dim=(2, 3))[source]

Return space names.

Parameters
  • standard (bool, optional) – Return standard spaces.

  • nonstandard (bool, optional) – Return nonstandard spaces.

  • dim (tuple, optional) – Desired dimensions of the standard spaces (default is (2, 3))

Examples

>>> spaces = SpatialReferences(['MNI152NLin6Asym', ("fsaverage", {"den": "10k"})])
>>> spaces.get_spaces()
['MNI152NLin6Asym', 'fsaverage']
>>> spaces.get_spaces(standard=False)
[]
>>> spaces.get_spaces(dim=(3,))
['MNI152NLin6Asym']
>>> spaces.add(('MNI152NLin6Asym', {'res': '2'}))
>>> spaces.get_spaces()
['MNI152NLin6Asym', 'fsaverage']
>>> spaces.add(('func', {}))
>>> spaces.get_spaces()
['MNI152NLin6Asym', 'fsaverage', 'func']
>>> spaces.get_spaces(nonstandard=False)
['MNI152NLin6Asym', 'fsaverage']
>>> spaces.get_spaces(standard=False)
['func']
get_standard(full_spec=False, dim=(2, 3))[source]

Return output spaces.

Parameters
  • full_spec (bool) – Return only fully-specified standard references (i.e., they must either have density or resolution set).

  • dim (tuple, optional) – Desired dimensions of the standard spaces (default is (2, 3))

insert(index, value, error=True)[source]

Concatenate one more space.

is_cached()[source]
property references

Get all specified references.

standard_spaces = ('MNI152Lin', 'MNI152NLin2009cAsym', 'MNI152NLin2009cSym', 'MNI152NLin6Asym', 'MNI152NLin6Sym', 'MNIInfant', 'MNIPediatricAsym', 'NKI', 'OASIS30ANTs', 'PNC', 'WHS', 'fsLR', 'fsaverage')

List of supported standard reference spaces.

niworkflows.utils.spaces.format_reference(in_tuple)[source]

Format a spatial reference given as a tuple.

Examples

>>> format_reference(('MNI152Lin', {'res': 1}))
'MNI152Lin_res-1'
>>> format_reference(('MNIPediatricAsym:cohort-2', {'res': 2}))
'MNIPediatricAsym_cohort-2_res-2'
niworkflows.utils.spaces.hasspec(value, specs)[source]

Check whether any of the keys are in a dict.

niworkflows.utils.spaces.reference2dict(in_tuple)[source]

Split a spatial reference given as a tuple into a dictionary.

Examples

>>> reference2dict(('MNIPediatricAsym:cohort-2', {'res': 2}))
{'space': 'MNIPediatricAsym', 'cohort': '2', 'resolution': '2'}
>>> reference2dict(('MNIPediatricAsym:cohort-2', {'res': 2, 'resolution': 1}))
{'space': 'MNIPediatricAsym', 'cohort': '2', 'resolution': '1'}
>>> reference2dict(('MNIPediatricAsym:cohort-2', {'res': 2, 'den': '91k'}))
{'space': 'MNIPediatricAsym', 'cohort': '2', 'resolution': '2', 'density': '91k'}