bids.analysis.analysis.Step

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

Represents a single analysis block 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 block. 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-Model block specification.

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

  • input_nodes (list) – Optional list of AnalysisNodes to use as input to this Step (typically, the output 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

get_contrasts(self[, names, variables])

Return contrast information for the current block.

get_design_matrix(self[, names, format, …])

Get design matrix and associated information.

setup(self[, input_nodes, drop_na])

Set up the Step and construct the design matrix.

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

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

Methods

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

Initialize self.

get_contrasts(self[, names, variables])

Return contrast information for the current block.

get_design_matrix(self[, names, format, …])

Get design matrix and associated information.

setup(self[, input_nodes, drop_na])

Set up the Step and construct the design matrix.

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

Return contrast information for the current block.

Parameters
  • 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.

  • kwargs (dict) – Optional keyword arguments used to constrain which of the available nodes get returned (e.g., passing subject=[‘01’, ‘02’] will return contrast information only for subjects ‘01’ and ‘02’).

Returns

A list with one element per unit of the current analysis level (e.g., if level=’run’, each element in the list representing the contrast information for a single run). Each element is a list of ContrastInfo namedtuples (one per contrast).

Return type

list

get_design_matrix(self, names=None, format='long', mode='both', force=False, sampling_rate='TR', **kwargs)[source]

Get design matrix and associated information.

Parameters
  • names (list) – Optional list of names of variables to include in the returned design matrix. If None, all variables are included.

  • format (str) – Whether to return the design matrix in ‘long’ or ‘wide’ format. Note that dense design matrices are always returned in ‘wide’ format.

  • mode (str) – Specifies whether to return variables in a sparse representation (‘sparse’), dense representation (‘dense’), or both (‘both’).

  • force (bool) – Indicates how to handle columns not of the type indicated by the mode argument. When False, variables of the non-selected type will be silently ignored. When True, variables will be forced to the desired representation. For example, if mode=’dense’ and force=True, sparse variables will be converted to dense variables and included in the returned design matrix in the .dense attribute. The force argument is ignored entirely if mode=’both’.

  • sampling_rate ({'TR', 'highest'} or float) – Sampling rate at which to generate the dense 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. The sampling rate may also be specified explicitly in Hz. Has no effect on sparse design matrices.

  • kwargs (dict) – Optional keyword arguments. Includes (1) selectors used to constrain which of the available nodes get returned (e.g., passing subject=[‘01’, ‘02’] will return design information only for subjects ‘01’ and ‘02’), and (2) arguments passed on to each Variable’s to_df() call (e.g., sampling_rate, entities, timing, etc.).

Returns

one tuple per unit of the current analysis level (e.g., if level=’run’, each element in the list represents the design matrix for a single run).

Return type

list of DesignMatrixInfo namedtuples

setup(self, input_nodes=None, drop_na=False, **kwargs)[source]

Set up the Step and construct the design matrix.

Parameters
  • input_nodes (list) – Optional list of Node objects produced by the preceding Step in the analysis. If None, uses any inputs passed in at Step initialization.

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