def _filter_collections(self, collections, kwargs):
# Keeps only collections that match target entities, and also removes
# those keys from the kwargs dict.
valid_ents = {'task', 'subject', 'session', 'run'}
entities = {k: kwargs.pop(k) for k in dict(kwargs) if k in valid_ents}
collections = [c for c in collections if matches_entities(c, entities)]
return (collections, kwargs)
def matches_entities(self, entities, strict=False):
''' Determine whether current AnalysisNode matches passed entities.
Args:
entities (dict): Dictionary of entities to match. Keys are entity
names; values are single values or lists.
strict (bool): If True, _all_ entities in the current Node must
match in order to return True.
'''
return matches_entities(self, entities, strict)
def matches_entities(self, entities, strict=False):
''' Determine whether current AnalysisNode matches passed entities.
Args:
entities (dict): Dictionary of entities to match. Keys are entity
names; values are single values or lists.
strict (bool): If True, _all_ entities in the current Node must
match in order to return True.
'''
return matches_entities(self, entities, strict)
def matches_entities(self, entities, strict=False):
"""Determine whether current AnalysisNode matches passed entities.
Parameters
----------
entities : dict
Dictionary of entities to match. Keys are entity
names; values are single values or lists.
strict : bool
If True, _all_ entities in the current Node must
match in order to return True.
"""
return matches_entities(self, entities, strict)
def get_collections(self, **filters):
"""Returns BIDSVariableCollections at the current node.
Parameters
----------
filters : dict
Optional keyword filters used to constrain which of the available
collections get returned (e.g., passing subject=['01', '02'] will
return collections for only subjects '01' and '02').
Returns
-------
list of BIDSVariableCollection instances
One instance per unit of the current analysis level (e.g., if
level='run', each element in the list represents the collection
for a single run).
"""
# Keeps only collections that match target entities, and also removes
# those keys from the kwargs dict.
return [c for c in self._collections if matches_entities(c, filters)]
def matches_entities(self, entities, strict=False):
''' Checks whether current Collection's entities match the input. '''
return matches_entities(self, entities, strict)
def matches_entities(self, entities, strict=False):
"""Checks whether current Collection's entities match the input. """
return matches_entities(self, entities, strict)
def matches_entities(self, entities, strict=False):
"""Checks whether current Variable's entities match the input. """
return matches_entities(self, entities, strict)
def get_collections(self,
unit,
names=None,
merge=False,
sampling_rate=None,
**entities):
"""Retrieve variable data for a specified level in the Dataset.
Parameters
----------
unit : str
The unit of analysis to return variables for. Must be
one of 'run', 'session', 'subject', or 'dataset'.
names : list
Optional list of variables names to return. If
None, all available variables are returned.
merge : bool
If True, variables are merged across all observations
of the current unit. E.g., if unit='subject' and return_type=
'collection', variables from all subjects will be merged into a
single collection. If False, each observation is handled
separately, and the result is returned as a list.
sampling_rate : int or str
If unit='run', the sampling rate to
pass onto the returned BIDSRunVariableCollection.
entities : dict
Optional constraints used to limit what gets returned.
Returns
-------
A list of BIDSVariableCollections if merge=False; a single
BIDSVariableCollection if merge=True.
"""
nodes = self.get_nodes(unit, entities)
var_sets = []
for n in nodes:
var_set = list(n.variables.values())
var_set = [v for v in var_set if matches_entities(v, entities)]
if names is not None:
var_set = [v for v in var_set if v.name in names]
# Additional filtering on Variables past run level, because their
# contents are extracted from TSV files containing rows from
# multiple observations
if unit != 'run':
var_set = [v.filter(entities) for v in var_set]
var_sets.append(var_set)
if merge:
var_sets = [list(chain(*var_sets))]
results = []
for vs in var_sets:
if not vs:
continue
if unit == 'run':
vs = clc.BIDSRunVariableCollection(vs, sampling_rate)
else:
vs = clc.BIDSVariableCollection(vs)
results.append(vs)
if merge:
return results[0] if results else None
return results
def run(self,
inputs=None,
group_by=None,
force_dense=True,
sampling_rate='TR',
invalid_contrasts='drop',
**filters):
"""Execute node with provided inputs.
Parameters
----------
inputs: [[ContrastInfo]]
List of list of ContrastInfo tuples passed from the previous node.
Each element in the outer list maps to the output of a unit at the
previous level; each element in the inner list is a ContrastInfo
tuple. E.g., if contrast information is being passed from run-level
to subject-level, each outer element is a run.
group_by: [str]
Optional list of strings giving the names of entities that define
the grouping structure for all variables. The current node will be
executed separately for each unique combination of levels specified
in group_by. For example, if group_by=['contrast', 'subject'], and
there are 2 contrasts and 3 subjects, then there will be 6 separate
iterations, and the returned list will have 6 elements. If None is
passed, the value set at node initialization (if any) will be used.
force_dense: bool
If True, the returned design matrices contained in ModelSpec
instances will represent time in a dense (i.e., uniform temporal
sampling) format. If False, the returned format will be sparse if
all available variables are sparse, and dense otherwise. Ignored
if none of the variables at this node are run-level.
sampling_rate: str, float
The sampling rate to use for timeseries resampling when working
with run-level variables and returning dense output. Ignored if
there are no run-level variables, or if force_dense is False and
all available variables are sparse.
invalid_contrasts: str
Indicates how to handle invalid contrasts--i.e., ones where the
specification contains variables that aren't found at run-time.
Valid values:
* 'drop' (default): Drop invalid contrasts, retain the rest.
* 'ignore': Keep invalid contrasts despite the missing variables.
* 'error': Raise an error.
filters: dict
Optional keyword arguments used to constrain the subset of the data
that's processed. E.g., passing subject='01' will process and
return data only for files associated with subject '01'.
Returns
-------
A list of BIDSStatsModelsNodeOutput instances.
"""
inputs = inputs or []
collections = self._collections
group_by = listify(group_by or self.group_by)
# Filter inputs and collections if needed
if filters:
inputs = [i for i in inputs if matches_entities(i, filters)]
collections = [
c for c in collections if matches_entities(c, filters)
]
# group all collections and inputs
all_objects = inputs + collections
groups = self._build_groups(all_objects, group_by)
results = []
for grp_ents, grp_objs in list(groups.items()):
# split group's objects into inputs and collections
grp_inputs, grp_colls = [], []
for obj in grp_objs:
if isinstance(obj, BIDSVariableCollection):
grp_colls.append(obj)
else:
grp_inputs.append(obj)
node_output = BIDSStatsModelsNodeOutput(
node=self,
entities=dict(grp_ents),
collections=grp_colls,
inputs=grp_inputs,
force_dense=force_dense,
sampling_rate=sampling_rate,
invalid_contrasts=invalid_contrasts)
results.append(node_output)
return results
def matches_entities(self, entities, strict=False):
''' Checks whether current Variable's entities match the input. '''
return matches_entities(self, entities, strict)
