bids.variables.kollekshuns.BIDSVariableCollection

class BIDSVariableCollection(variables)[source]

A container for one or more variables extracted from variable files at a single level of analysis.

Parameters

variables (list) – A list of BIDSVariables or SimpleVariables.

Notes

  • Variables in the list must all share the same analysis level, which must be one of ‘session’, ‘subject’, or ‘dataset’ level. For run-level Variables, use the BIDSRunVariableCollection.

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.

match_variables(self, pattern[, return_type])

Return columns whose names match the provided regex pattern.

matches_entities(self, entities[, strict])

Checks whether current Collection’s entities match the input.

merge_variables(variables, \*\*kwargs)

Concatenates Variables along row axis.

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

Merge variables into a single pandas DataFrame.

__init__(self, variables)[source]

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

Methods

__init__(self, variables)

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

match_variables(self, pattern[, return_type])

Return columns whose names match the provided regex pattern.

matches_entities(self, entities[, strict])

Checks whether current Collection’s entities match the input.

merge_variables(variables, \*\*kwargs)

Concatenates Variables along row axis.

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

Merge variables into a single pandas DataFrame.

clone(self)[source]

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

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

Create a Collection from a pandas DataFrame.

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

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

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

Returns

A BIDSVariableCollection.

match_variables(self, pattern, return_type='name')[source]

Return columns whose names match the provided regex pattern.

Parameters
  • pattern (str) – A regex pattern to match all variable names against.

  • return_type (str) – 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.

matches_entities(self, entities, strict=False)[source]

Checks whether current Collection’s entities match the input.

static merge_variables(variables, **kwargs)[source]

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.

to_df(self, variables=None, format='wide', fillna=nan, **kwargs)[source]

Merge variables into a single pandas DataFrame.

Parameters
  • variables (list) – Optional list of column names to retain; if None, all variables are returned.

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

  • fillna – Replace missing values with the specified value.

  • kwargs – Optional keyword arguments to pass onto each Variable’s to_df() call (e.g., condition, entities, and timing).

Returns: A pandas DataFrame.