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', 'individual', 'dwi', 'asl']

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)

Bases: Action

Parse spatial references.

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

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)

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)

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)

Add one more space, without erroring if it exists.

append(value)

Concatenate one more space.

property cached

Get cached spaces, raise error if not cached.

static check_space(space)

Build a Reference object.

checkpoint(force=False)

Cache and freeze current spaces to separate attribute.

get_fs_spaces()

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))

Return nonstandard spaces.

get_spaces(standard=True, nonstandard=True, dim=(2, 3))

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))

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)

Concatenate one more space.

is_cached()

property references

Get all specified references.

standard_spaces = ('Fischer344', 'MNI152Lin', 'MNI152NLin2009aAsym', 'MNI152NLin2009aSym', 'MNI152NLin2009bAsym', 'MNI152NLin2009bSym', 'MNI152NLin2009cAsym', 'MNI152NLin2009cSym', 'MNI152NLin6Asym', 'MNI152NLin6Sym', 'MNI305', 'MNIColin27', 'MNIInfant', 'MNIPediatricAsym', 'MouseIn', 'NKI', 'NMT31Sym', 'OASIS30ANTs', 'PNC', 'RESILIENT', 'UNCInfant', 'VALiDATe29', 'WHS', 'dhcpAsym', 'dhcpSym', 'dhcpVol', 'fsLR', 'fsaverage', 'onavg')

List of supported standard reference spaces.

niworkflows.utils.spaces.format_reference(in_tuple)

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)

Check whether any of the keys are in a dict.

niworkflows.utils.spaces.reference2dict(in_tuple)

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