bids.variables.collections¶
Classes and functions related to the management of sets of BIDSVariables.
Functions
|
Merge two or more collections at the same level of analysis. |
Classes
|
A container for one or more RunVariables–i.e., Variables that have a temporal dimension. |
|
A container for one or more variables extracted from variable files at a single level of analysis. |
-
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
-
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
-
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().
-
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.
-
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
-
merge_collections
(collections, sampling_rate='highest', output_level=None)[source]¶ Merge two or more collections at the same level of analysis.
- Parameters
collections (list) – List of Collections to merge.
sampling_rate (int or str) – Sampling rate to use if it becomes necessary to resample DenseRunVariables. Either an integer or ‘highest’ (see merge_variables docstring for further explanation).
output_level (str, optional) – Assign a new level (e.g., ‘run’, ‘subject’, etc.) to the merged collection. If None, the current level is retained.
- Returns
Result type depends on the type of the input collections.
- Return type