bids.variables.BIDSRunVariableCollection

class BIDSRunVariableCollection(variables, sampling_rate=None)[source]

A container for one or more RunVariables–i.e., Variables that have a temporal dimension.

Parameters
  • variables (list) – A list of SparseRunVariable and/or DenseRunVariable.

  • sampling_rate (float) – Sampling rate (in Hz) to use when working with dense representations of variables. If None, defaults to 10.

Notes

Variables in the list must all be at the ‘run’ level. For other levels (session, subject, or dataset), use the BIDSVariableCollection.

Methods

clone(self)

Returns a shallow copy of the current instance, except that all variables are deep-cloned.

from_df(data[, entities, source])

Create a Collection from a pandas DataFrame.

get_dense_variables(self[, variables])

Returns a list of all stored DenseRunVariables.

get_sparse_variables(self[, variables])

Returns a list of all stored SparseRunVariables.

match_variables(self, pattern[, …])

Return columns whose names match the provided pattern.

merge_variables(variables, \*\*kwargs)

Concatenates Variables along row axis.

resample(self[, sampling_rate, variables, …])

Resample all dense variables (and optionally, sparse ones) to the specified sampling rate.

to_dense(self[, sampling_rate, variables, …])

Convert all contained SparseRunVariables to DenseRunVariables.

to_df(self[, variables, format, fillna, …])

Merge columns into a single pandas DataFrame.

all_dense

all_sparse

__init__(self, variables, sampling_rate=None)[source]

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

Methods

__init__(self, variables[, sampling_rate])

Initialize self.

all_dense(self)

all_sparse(self)

clone(self)

Returns a shallow copy of the current instance, except that all variables are deep-cloned.

from_df(data[, entities, source])

Create a Collection from a pandas DataFrame.

get_dense_variables(self[, variables])

Returns a list of all stored DenseRunVariables.

get_sparse_variables(self[, variables])

Returns a list of all stored SparseRunVariables.

match_variables(self, pattern[, …])

Return columns whose names match the provided pattern.

merge_variables(variables, \*\*kwargs)

Concatenates Variables along row axis.

resample(self[, sampling_rate, variables, …])

Resample all dense variables (and optionally, sparse ones) to the specified sampling rate.

to_dense(self[, sampling_rate, variables, …])

Convert all contained SparseRunVariables to DenseRunVariables.

to_df(self[, variables, format, fillna, …])

Merge columns into a single pandas DataFrame.

clone(self)

Returns a shallow copy of the current instance, except that all variables are deep-cloned.

classmethod from_df(data, entities=None, source='contrast')

Create a Collection from a pandas DataFrame.

Parameters
  • df (pandas.DataFrame) – The DataFrame to convert to a Collection. Each column will be converted to a SimpleVariable.

  • entities (pandas.DataFrame) – An optional second DataFrame containing entity information.

  • source (str) – The value to set as the source for all Variables.

Returns

Return type

BIDSVariableCollection

get_dense_variables(self, variables=None)[source]

Returns a list of all stored DenseRunVariables.

get_sparse_variables(self, variables=None)[source]

Returns a list of all stored SparseRunVariables.

match_variables(self, pattern, return_type='name', match_type='unix')

Return columns whose names match the provided pattern.

Parameters
  • pattern (str, list) – One or more regex patterns to match all variable names against.

  • return_type ({'name', 'variable'}) – What to return. Must be one of: ‘name’: Returns a list of names of matching variables. ‘variable’: Returns a list of Variable objects whose names match.

  • match_type (str) –

    Matching approach to use. Either ‘regex’ (full-blown regular

    expression matching) or ‘unix’ (unix-style pattern matching via the fnmatch module).

Returns

Return type

A list of all matching variables or variable names

static merge_variables(variables, **kwargs)

Concatenates Variables along row axis.

Parameters

variables (list) – List of Variables to merge. Variables can have different names (and all Variables that share a name will be concatenated together).

Returns

A list of Variables.

Return type

list

resample(self, sampling_rate=None, variables=None, force_dense=False, in_place=False, kind='linear')[source]

Resample all dense variables (and optionally, sparse ones) to the specified sampling rate.

Parameters
  • sampling_rate (int or float) – Target sampling rate (in Hz). If None, uses the instance value.

  • variables (list) – Optional list of names of Variables to resample. If None, all variables are resampled.

  • force_dense (bool) – if True, all sparse variables will be forced to dense.

  • in_place (bool) – When True, all variables are overwritten in-place. When False, returns resampled versions of all variables.

  • kind (str) – Argument to pass to scipy’s interp1d; indicates the kind of interpolation approach to use. See interp1d docs for valid values.

Returns

Return type

A BIDSVariableCollection (if in_place is False)

to_dense(self, sampling_rate=None, variables=None, in_place=False, kind='linear')[source]

Convert all contained SparseRunVariables to DenseRunVariables.

Parameters
  • sampling_rate (None, {'TR', 'highest'}, float) – Sampling rate to use when densifying sparse variables. If None, uses the currently stored instance value. If ‘TR’, the repetition time is used, if available, to select the sampling rate (1/TR). If ‘highest’, all variables are resampled to the highest sampling rate of any of the existing dense variables. The sampling rate may also be specified explicitly in Hz as a float.

  • variables (list) – Optional list of names of Variables to resample. If None, all variables are resampled.

  • in_place (bool) – When True, all variables are overwritten in-place. When False, returns resampled versions of all variables.

  • kind (str) – Argument to pass to scipy’s interp1d; indicates the kind of interpolation approach to use. See interp1d docs for valid values.

Returns

Return type

A BIDSVariableCollection (if in_place is False)

Notes

Categorical variables are ignored.

to_df(self, variables=None, format='wide', fillna=nan, sampling_rate='highest', include_sparse=True, include_dense=True, entities=True, timing=True)[source]

Merge columns into a single pandas DataFrame.

Parameters
  • variables (list) – Optional list of variable names to retain; if None, all variables are written out.

  • format (str) – Whether to return a DataFrame in ‘wide’ or ‘long’ format. In ‘wide’ format, each row is defined by a unique onset/duration, and each variable is in a separate column. In ‘long’ format, each row is a unique combination of onset, duration, and variable name, and a single ‘amplitude’ column provides the value.

  • fillna (value) – Replace missing values with the specified value.

  • sampling_rate (float) – Specifies the sampling rate to use for all variables in the event that resampling needs to be performed (i.e., if some variables are sparse, or if dense variables have different sampling rates). Must be one of ‘TR’, ‘highest’, None, or a float (specifying the rate in Hz). If None, uses the instance sampling rate (10 Hz by default).

  • include_sparse (bool) – Whether or not to include sparse variables in the output.

  • include_dense (bool) – Whether or not to include dense variables in the output.

  • entities (bool) – Whether or not to include a column for each entity.

  • timing (bool) – Whether or not to include onset and duration columns.

Returns

A pandas DataFrame.

Return type

pandas.DataFrame

Notes

The precise format of the resulting DataFrame depends on the variables contained in the current instance. If all variables are sparse, the output will also be sparse–i.e., the events in the DataFrame may have non-uniform timing. If at least one dense variable is present, and the user has not explicitly excluded dense variables (by setting include_dense=False), all selected variables will be implicitly converted to dense using the specified sampling_rate (if provided). To avoid unexpected behavior, we recommend converting mixed collections to all-dense form explicitly via the to_dense() or resample() methods before calling to_df().