bids.variables.kollekshuns¶
Classes and functions related to the management of sets of BIDSVariables.
Why ‘kollekshuns’? Because ‘collections’ would conflict with the standard lib module of the same name on Python 2. We could go with something sensible but verbose like ‘variable_collections’, but that would make far too much sense.
Functions
merge_collections (collections[, …]) |
Merge two or more collections at the same level of analysis. |
Classes
BIDSRunVariableCollection (variables[, …]) |
A container for one or more RunVariables–i.e., Variables that have a temporal dimension. |
BIDSVariableCollection (variables) |
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
()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
(pattern[, return_type])Return columns whose names match the provided regex pattern. matches_entities
(entities[, strict])Checks whether current Collection’s entities match the input. merge_variables
(variables, **kwargs)Concatenates Variables along row axis. resample
([sampling_rate, variables, …])Resample all dense variables (and optionally, sparse ones) to the specified sampling rate. to_df
([variables, format, sparse, …])Merge columns into a single pandas DataFrame. -
clone
()¶ 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 (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
(pattern, return_type='name')¶ 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
(entities, strict=False)¶ Checks whether current Collection’s entities match the input.
-
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.
-
resample
(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, float) – Target sampling rate (in Hz). If None, uses the instance sampling rate.
- variables (list) – Optional list 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.
-
to_df
(variables=None, format='wide', sparse=True, sampling_rate=None, include_sparse=True, include_dense=True, **kwargs)[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.
- sparse (bool) – If True, variables will be kept in a sparse format provided they are all internally represented as such. If False, a dense matrix (i.e., uniform sampling rate for all events) will be exported. Will be ignored if at least one variable is dense.
- sampling_rate (float) – If a dense matrix is written out, the sampling rate (in Hz) to use for downsampling. Defaults to the value currently set in the instance.
- kwargs – Optional keyword arguments to pass onto each Variable’s to_df() call (e.g., condition, entities, and timing).
- include_sparse (bool) – Whether or not to include sparse Variables.
- include_dense (bool) – Whether or not to include dense Variables.
Returns: A pandas DataFrame.
-
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
()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
(pattern[, return_type])Return columns whose names match the provided regex pattern. matches_entities
(entities[, strict])Checks whether current Collection’s entities match the input. merge_variables
(variables, **kwargs)Concatenates Variables along row axis. to_df
([variables, format, fillna])Merge variables into a single pandas DataFrame. -
clone
()[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
(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
(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
(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 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 – 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.
-
merge_collections
(collections, force_dense=False, sampling_rate='auto')[source]¶ Merge two or more collections at the same level of analysis.
Parameters: - collections (list) – List of Collections to merge.
- sampling_rate (int, str) – Sampling rate to use if it becomes necessary to resample DenseRunVariables. Either an integer or ‘auto’ (see merge_variables docstring for further explanation).
Returns: A BIDSVariableCollection or BIDSRunVariableCollection, depending on the type of the input collections.