bids.variables.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 columns whose names match the provided pattern.
merge_variables
(variables, \*\*kwargs)Concatenates Variables along row axis.
to_df
(self[, variables, format, fillna, …])Merge variables into a single pandas DataFrame.
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 columns whose names match the provided pattern.
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 (
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
-
match_variables
(self, pattern, return_type='name', match_type='unix')[source]¶ 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)[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.
- Return type
list
-
to_df
(self, variables=None, format='wide', fillna=nan, entities=True, timing=True)[source]¶ Merge variables into a single pandas DataFrame.
- Parameters
variables (list of str or BIDSVariable) – Optional list of variables or variable names to retain. If strings are passed, each one gives the name of a variable in the current collection. If BIDSVariables are passed, they will be used as-is. If None, all variables are returned. Strings and BIDSVariables cannot be mixed in the list.
format ({'wide', 'long'}) – 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 (value) – Replace missing values with the specified value.
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