bids.analysis.analysis.Step

class Step(layout, level, index, name=None, transformations=None, model=None, contrasts=None, inputs=None, dummy_contrasts=False)[source]

Represents a single analysis step from a BIDS-Model specification.

Parameters
  • layout (bids.layout.BIDSLayout) – The BIDSLayout containing all project files.

  • level (str) – The BIDS keyword to use as the grouping variable; must be one of [‘run’, ‘session’, ‘subject’, or ‘dataset’].

  • index (int) – The numerical index of the current Step within the sequence of steps.

  • name (str) – Optional name to assign to the step. Must be specified in order to enable name-based indexing in the parent Analysis.

  • transformations (list) – List of BIDS-Model transformations to apply.

  • model (dict) – The ‘model’ part of the BIDS-StatsModels specification.

  • contrasts (list) – List of contrasts to apply to the parameter estimates generated when the model is fit.

  • inputs (list) – Optional list of BIDSVariableCollections to use as input to this Step (typically, the outputs from the preceding Step).

  • dummy_contrasts (dict) – Optional dictionary specifying which conditions to create indicator contrasts for. Dictionary must include a “type” key (‘t’ or ‘FEMA’), and optionally a subset of “conditions”. This parameter is over-written by the setting in setup() if the latter is passed.

Methods

add_collections(self[, drop_na])

Add BIDSVariableCollections (i.e., predictors) to the current Step.

get_collections(self, \*\*filters)

Returns BIDSVariableCollections at the current Step.

get_contrasts(self, collection[, names, …])

Return contrast information at this step for the passed collection.

get_model_spec(self, collection[, sampling_rate])

Get a ModelSpec instance for the passed collection.

setup(self[, inputs])

Set up the Step.

__init__(self, layout, level, index, name=None, transformations=None, model=None, contrasts=None, inputs=None, dummy_contrasts=False)[source]

Initialize self. See help(type(self)) for accurate signature.

Methods

__init__(self, layout, level, index[, name, …])

Initialize self.

add_collections(self[, drop_na])

Add BIDSVariableCollections (i.e., predictors) to the current Step.

get_collections(self, \*\*filters)

Returns BIDSVariableCollections at the current Step.

get_contrasts(self, collection[, names, …])

Return contrast information at this step for the passed collection.

get_model_spec(self, collection[, sampling_rate])

Get a ModelSpec instance for the passed collection.

setup(self[, inputs])

Set up the Step.

add_collections(self, drop_na=False, **kwargs)[source]

Add BIDSVariableCollections (i.e., predictors) to the current Step.

Parameters
  • drop_na (bool) – Boolean indicating whether or not to automatically drop events that have a n/a amplitude when reading in data from event files.

  • kwargs (dict) – Optional keyword arguments to pass onto load_variables.

Notes

No checking for redundancy is performed, so if load_collections() is invoked multiple times with overlapping selectors, redundant predictors are likely to be stored internally.

get_collections(self, **filters)[source]

Returns BIDSVariableCollections at the current Step.

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

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

Return type

list of BIDSVariableCollection instances

get_contrasts(self, collection, names=None, variables=None)[source]

Return contrast information at this step for the passed collection.

Parameters
  • collection (BIDSVariableCollection) – The collection to generate/validate contrasts for.

  • names (list) – Optional list of names of contrasts to return. If None (default), all contrasts are returned.

  • variables (bool) – Optional list of strings giving the names of design matrix columns to use when generating the matrix of weights.

Returns

A list of ContrastInfo namedtuples, one per contrast.

Return type

list

Notes

The ‘variables’ argument take precedence over the natural process of column selection. I.e., if a variable shows up in a contrast, but isn’t named in variables, it will not be included in the result.

get_model_spec(self, collection, sampling_rate='TR')[source]

Get a ModelSpec instance for the passed collection.

Parameters
  • collection (BIDSVariableCollection) – The BIDSVariableCollection to construct a model for.

  • sampling_rate ({'TR', 'highest'} or float) – For run-level models, the sampling rate at which to generate the design matrix. When ‘TR’, the repetition time is used, if available, to select the sampling rate (1/TR). When ‘highest’, all variables are resampled to the highest sampling rate of any variable in the collection. The sampling rate may also be specified explicitly in Hz. Has no effect on non-run-level collections.

Returns

Return type

A bids.analysis.model_spec.ModelSpec instance.

Notes

If the passed BIDSVariableCollection contains any sparse variables, they will be automatically converted to dense (using the specified sampling rate) before the ModelSpec is constructed. For non-run-level collections, timing is irrelevant, so the design matrix is constructed based on the “as-is” values found in each variable.

setup(self, inputs=None, **kwargs)[source]

Set up the Step.

Processes inputs from previous step, combines it with currently loaded data, and applies transformations to produce a design matrix-ready set of variable collections.

Parameters
  • inputs (list) – Optional list of BIDSVariableCollections produced as output by the preceding Step in the analysis. If None, uses inputs passed at initialization (if any).

  • kwargs (dict) – Optional keyword arguments constraining the collections to include.