aslprep.utils.spaces module
Utilities for tracking and filtering spaces.
- FSAVERAGE_DENSITY = {'fsaverage': '164k', 'fsaverage3': '642', 'fsaverage4': '2562', 'fsaverage5': '10k', 'fsaverage6': '41k'}
A map of legacy fsaverageX names to surface densities.
- FSAVERAGE_LEGACY = {'10k': 'fsaverage5', '164k': 'fsaverage', '2562': 'fsaverage4', '41k': 'fsaverage6', '642': 'fsaverage3'}
A map of surface densities to legacy fsaverageX names.
- NONSTANDARD_REFERENCES = ['T1w', 'T2w', 'anat', 'fsnative', 'asl', 'run', 'sbref', 'session', 'individual', 'dwi']
List of supported nonstandard reference spaces.
- class OutputReferencesAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)[source]
Bases:
Action
Parse spatial references.
- class Reference(space: str | None = None, spec=_Nothing.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:
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 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'})]
- __init__(spaces=None, checkpoint=False)[source]
Maintain the bookkeeping of spaces and templates.
Internal spaces are normalizations required for pipeline execution which can vary based on user arguments. Output spaces are desired user outputs.
- property cached
Get cached spaces, raise error if not cached.
- 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_spaces(standard=True, nonstandard=True, dim=(2, 3))[source]
Return space names.
- Parameters:
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']
- 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', 'fsLR', 'fsaverage', 'onavg')
List of supported standard reference spaces.