bids.variables.variables¶
Functions
|
Merge/concatenate a list of variables along the row axis. |
Classes
|
Base representation of a column in a BIDS project. |
|
A dense representation of a single column. |
|
Represents a simple design matrix column that has no timing information. |
|
A sparse representation of a single column of events. |
-
class
BIDSVariable
(name, values, source)[source]¶ Base representation of a column in a BIDS project.
Methods
apply
(self, func[, groupby])Applies the passed function to the groups defined by the groupby argument.
clone
(self[, data])Clone (deep copy) the current column, optionally replacing its data and/or any other attributes.
filter
(self[, filters, query, strict, inplace])Returns a copy of the current Variable with only rows that match the filters retained.
get_grouper
(self[, groupby])Return a list suitable for use in groupby calls.
matches_entities
(self, entities[, strict])Checks whether current Variable’s entities match the input.
merge
(variables[, name])Merge/concatenate a list of variables along the row axis.
to_df
(self[, condition, entities])Convert to a DataFrame, with columns for name and entities.
-
apply
(self, func, groupby='run', *args, **kwargs)[source]¶ Applies the passed function to the groups defined by the groupby argument. Works identically to the standard pandas df.groupby() call. :param func: The function to apply to each group. :type func: callable :param groupby: Name(s) of column(s) defining the grouping. :type groupby: str, list :param args, kwargs: Optional positional and keyword arguments to pass
onto the function call.
-
clone
(self, data=None, **kwargs)[source]¶ Clone (deep copy) the current column, optionally replacing its data and/or any other attributes.
- Parameters
data (DataFrame, ndarray) – Optional new data to substitute into the cloned column. Must have same dimensionality as the original.
kwargs (dict) – Optional keyword arguments containing new attribute values to set in the copy. E.g., passing name=’my_name’ would set the .name attribute on the cloned instance to the passed value.
-
filter
(self, filters=None, query=None, strict=False, inplace=False)[source]¶ Returns a copy of the current Variable with only rows that match the filters retained.
- Parameters
filters (dict) – Dictionary of filters to apply. Keys can be either ‘amplitude’ or any named entity. Values must be single values or lists.
query (str) – Optional query string to pass to df.query(). Will not be validated in any way, so must have valid column names. Takes precedence over filters in the event that both are passed.
strict (bool) – By default, keys in ‘filters’ that cannot be found in the Variable will be silently ignored. If strict=True, None will be returned in such cases.
inplace (bool) – If True, filtering is performed in place. If False, a filtered copy of the Variable is returned.
- Returns
A BIDSVariable, or None if no rows are left after filtering.
-
get_grouper
(self, groupby='run')[source]¶ Return a list suitable for use in groupby calls. :param groupby: Name(s) of column(s) defining the grouper
object. Anything that would be valid inside a .groupby() call on a pandas structure.
- Returns
A list defining the groups.
-
matches_entities
(self, entities, strict=False)[source]¶ Checks whether current Variable’s entities match the input.
-
classmethod
merge
(variables, name=None, **kwargs)[source]¶ Merge/concatenate a list of variables along the row axis.
- Parameters
variables (list) – A list of Variables to merge.
name (str) – Optional name to assign to the output Variable. By default, uses the same name as the input variables.
kwargs – Optional keyword arguments to pass onto the class-specific merge() call. See merge_variables docstring for details.
- Returns
A single BIDSVariable of the same class as the input variables.
Notes: see merge_variables docstring for additional details.
-
to_df
(self, condition=True, entities=True, **kwargs)[source]¶ Convert to a DataFrame, with columns for name and entities. :param condition: If True, adds a column for condition name, and
names the amplitude column ‘amplitude’. If False, returns just onset, duration, and amplitude, and gives the amplitude column the current column name.
- Parameters
entities (bool) – If True, adds extra columns for all entities.
-
-
class
DenseRunVariable
(name, values, run_info, source, sampling_rate)[source]¶ A dense representation of a single column.
- Parameters
name (
str
) – The name of the column.values (
numpy.ndarray
) – The values/amplitudes to store.run_info (
list
) – A list of RunInfo objects carrying information about all runs represented in the Variable.source ({'events', 'physio', 'stim', 'regressors', 'scans', 'sessions', 'participants', 'beh'}) – The type of BIDS variable file the data were extracted from.
sampling_rate (
float
) – Optional sampling rate (in Hz) to use. Must match the sampling rate used to generate the values. If None, the collection’s sampling rate will be used.
Methods
apply
(self, func[, groupby])Applies the passed function to the groups defined by the groupby argument.
clone
(self[, data])Clone (deep copy) the current column, optionally replacing its data and/or any other attributes.
filter
(self[, filters, query, strict, inplace])Returns a copy of the current Variable with only rows that match the filters retained.
get_grouper
(self[, groupby])Return a list suitable for use in groupby calls.
matches_entities
(self, entities[, strict])Checks whether current Variable’s entities match the input.
merge
(variables[, name])Merge/concatenate a list of variables along the row axis.
resample
(self, sampling_rate[, inplace, kind])Resample the Variable to the specified sampling rate.
split
(self, grouper)Split the current DenseRunVariable into multiple columns.
to_df
(self[, condition, entities, timing, …])Convert to a DataFrame, with columns for name and entities.
-
apply
(self, func, groupby='run', *args, **kwargs)¶ Applies the passed function to the groups defined by the groupby argument. Works identically to the standard pandas df.groupby() call. :param func: The function to apply to each group. :type func: callable :param groupby: Name(s) of column(s) defining the grouping. :type groupby: str, list :param args, kwargs: Optional positional and keyword arguments to pass
onto the function call.
-
clone
(self, data=None, **kwargs)¶ Clone (deep copy) the current column, optionally replacing its data and/or any other attributes.
- Parameters
data (DataFrame, ndarray) – Optional new data to substitute into the cloned column. Must have same dimensionality as the original.
kwargs (dict) – Optional keyword arguments containing new attribute values to set in the copy. E.g., passing name=’my_name’ would set the .name attribute on the cloned instance to the passed value.
-
filter
(self, filters=None, query=None, strict=False, inplace=False)¶ Returns a copy of the current Variable with only rows that match the filters retained.
- Parameters
filters (dict) – Dictionary of filters to apply. Keys can be either ‘amplitude’ or any named entity. Values must be single values or lists.
query (str) – Optional query string to pass to df.query(). Will not be validated in any way, so must have valid column names. Takes precedence over filters in the event that both are passed.
strict (bool) – By default, keys in ‘filters’ that cannot be found in the Variable will be silently ignored. If strict=True, None will be returned in such cases.
inplace (bool) – If True, filtering is performed in place. If False, a filtered copy of the Variable is returned.
- Returns
A BIDSVariable, or None if no rows are left after filtering.
-
get_grouper
(self, groupby='run')¶ Return a list suitable for use in groupby calls. :param groupby: Name(s) of column(s) defining the grouper
object. Anything that would be valid inside a .groupby() call on a pandas structure.
- Returns
A list defining the groups.
-
matches_entities
(self, entities, strict=False)¶ Checks whether current Variable’s entities match the input.
-
classmethod
merge
(variables, name=None, **kwargs)¶ Merge/concatenate a list of variables along the row axis.
- Parameters
variables (list) – A list of Variables to merge.
name (str) – Optional name to assign to the output Variable. By default, uses the same name as the input variables.
kwargs – Optional keyword arguments to pass onto the class-specific merge() call. See merge_variables docstring for details.
- Returns
A single BIDSVariable of the same class as the input variables.
Notes: see merge_variables docstring for additional details.
-
resample
(self, sampling_rate, inplace=False, kind='linear')[source]¶ Resample the Variable to the specified sampling rate.
- Parameters
sampling_rate (
int
,float
) – Target sampling rate (in Hz).inplace (
bool
, optional) – If True, performs resampling in-place. If False, returns a resampled copy of the current Variable. Default is False.kind ({'linear', 'nearest', 'zero', 'slinear', 'quadratic', 'cubic'}) – Argument to pass to
scipy.interpolate.interp1d
; indicates the kind of interpolation approach to use. See interp1d docs for valid values. Default is ‘linear’.
-
split
(self, grouper)[source]¶ Split the current DenseRunVariable into multiple columns.
- Parameters
grouper (
pandas.DataFrame
) – Binary DF specifying the design matrix to use for splitting. Number of rows must match currentDenseRunVariable
; a newDenseRunVariable
will be generated for each column in the grouper.- Returns
- Return type
A list of DenseRunVariables, one per unique value in the grouper.
-
to_df
(self, condition=True, entities=True, timing=True, sampling_rate=None)[source]¶ Convert to a DataFrame, with columns for name and entities.
- Parameters
condition (
bool
) – If True, adds a column for condition name, and names the amplitude column ‘amplitude’. If False, returns just onset, duration, and amplitude, and gives the amplitude column the current column name.entities (
bool
) – If True, adds extra columns for all entities.timing (
bool
) – If True, includes onset and duration columns (even though events are sampled uniformly). If False, omits them.
-
class
SimpleVariable
(name, data, source, **kwargs)[source]¶ Represents a simple design matrix column that has no timing information.
- Parameters
name (str) – Name of the column.
data (DataFrame) – A pandas DataFrame minimally containing a column named ‘amplitude’ as well as any identifying entities.
source (str) – The type of BIDS variable file the data were extracted from. Must be one of: ‘events’, ‘physio’, ‘stim’, ‘regressors’, ‘scans’, ‘sessions’, ‘participants’, or ‘beh’.
kwargs – Optional keyword arguments passed onto superclass.
Methods
apply
(self, func[, groupby])Applies the passed function to the groups defined by the groupby argument.
clone
(self[, data])Clone (deep copy) the current column, optionally replacing its data and/or any other attributes.
filter
(self[, filters, query, strict, inplace])Returns a copy of the current Variable with only rows that match the filters retained.
get_grouper
(self[, groupby])Return a list suitable for use in groupby calls.
matches_entities
(self, entities[, strict])Checks whether current Variable’s entities match the input.
merge
(variables[, name])Merge/concatenate a list of variables along the row axis.
select_rows
(self, rows)Truncate internal arrays to keep only the specified rows.
split
(self, grouper)Split the current SparseRunVariable into multiple columns.
to_df
(self[, condition, entities])Convert to a DataFrame, with columns for name and entities.
-
apply
(self, func, groupby='run', *args, **kwargs)¶ Applies the passed function to the groups defined by the groupby argument. Works identically to the standard pandas df.groupby() call. :param func: The function to apply to each group. :type func: callable :param groupby: Name(s) of column(s) defining the grouping. :type groupby: str, list :param args, kwargs: Optional positional and keyword arguments to pass
onto the function call.
-
clone
(self, data=None, **kwargs)¶ Clone (deep copy) the current column, optionally replacing its data and/or any other attributes.
- Parameters
data (DataFrame, ndarray) – Optional new data to substitute into the cloned column. Must have same dimensionality as the original.
kwargs (dict) – Optional keyword arguments containing new attribute values to set in the copy. E.g., passing name=’my_name’ would set the .name attribute on the cloned instance to the passed value.
-
filter
(self, filters=None, query=None, strict=False, inplace=False)¶ Returns a copy of the current Variable with only rows that match the filters retained.
- Parameters
filters (dict) – Dictionary of filters to apply. Keys can be either ‘amplitude’ or any named entity. Values must be single values or lists.
query (str) – Optional query string to pass to df.query(). Will not be validated in any way, so must have valid column names. Takes precedence over filters in the event that both are passed.
strict (bool) – By default, keys in ‘filters’ that cannot be found in the Variable will be silently ignored. If strict=True, None will be returned in such cases.
inplace (bool) – If True, filtering is performed in place. If False, a filtered copy of the Variable is returned.
- Returns
A BIDSVariable, or None if no rows are left after filtering.
-
get_grouper
(self, groupby='run')¶ Return a list suitable for use in groupby calls. :param groupby: Name(s) of column(s) defining the grouper
object. Anything that would be valid inside a .groupby() call on a pandas structure.
- Returns
A list defining the groups.
-
matches_entities
(self, entities, strict=False)¶ Checks whether current Variable’s entities match the input.
-
classmethod
merge
(variables, name=None, **kwargs)¶ Merge/concatenate a list of variables along the row axis.
- Parameters
variables (list) – A list of Variables to merge.
name (str) – Optional name to assign to the output Variable. By default, uses the same name as the input variables.
kwargs – Optional keyword arguments to pass onto the class-specific merge() call. See merge_variables docstring for details.
- Returns
A single BIDSVariable of the same class as the input variables.
Notes: see merge_variables docstring for additional details.
-
select_rows
(self, rows)[source]¶ Truncate internal arrays to keep only the specified rows.
- Parameters
rows (array) – An integer or boolean array identifying the indices of rows to keep.
-
split
(self, grouper)[source]¶ Split the current SparseRunVariable into multiple columns.
- Parameters
grouper (iterable) – list to groupby, where each unique value will be taken as the name of the resulting column.
- Returns
A list of SparseRunVariables, one per unique value in the grouper.
-
to_df
(self, condition=True, entities=True, **kwargs)¶ Convert to a DataFrame, with columns for name and entities. :param condition: If True, adds a column for condition name, and
names the amplitude column ‘amplitude’. If False, returns just onset, duration, and amplitude, and gives the amplitude column the current column name.
- Parameters
entities (bool) – If True, adds extra columns for all entities.
-
class
SparseRunVariable
(name, data, run_info, source, **kwargs)[source]¶ A sparse representation of a single column of events.
- Parameters
name (str) – Name of the column.
data (DataFrame) – A pandas DataFrame minimally containing the columns ‘onset’, ‘duration’, and ‘amplitude’.
run_info (list) – A list of RunInfo objects carrying information about all runs represented in the Variable.
source (str) – The type of BIDS variable file the data were extracted from. Must be one of: ‘events’, ‘physio’, ‘stim’, ‘regressors’, ‘scans’, ‘sessions’, ‘participants’, or ‘beh’.
kwargs – Optional keyword arguments passed onto superclass.
Methods
apply
(self, func[, groupby])Applies the passed function to the groups defined by the groupby argument.
clone
(self[, data])Clone (deep copy) the current column, optionally replacing its data and/or any other attributes.
filter
(self[, filters, query, strict, inplace])Returns a copy of the current Variable with only rows that match the filters retained.
get_duration
(self)Return the total duration of the Variable’s run(s).
get_grouper
(self[, groupby])Return a list suitable for use in groupby calls.
matches_entities
(self, entities[, strict])Checks whether current Variable’s entities match the input.
merge
(variables[, name])Merge/concatenate a list of variables along the row axis.
select_rows
(self, rows)Truncate internal arrays to keep only the specified rows.
split
(self, grouper)Split the current SparseRunVariable into multiple columns.
to_dense
(self, sampling_rate)Convert the current sparse column to a dense representation.
to_df
(self[, condition, entities])Convert to a DataFrame, with columns for name and entities.
-
apply
(self, func, groupby='run', *args, **kwargs)¶ Applies the passed function to the groups defined by the groupby argument. Works identically to the standard pandas df.groupby() call. :param func: The function to apply to each group. :type func: callable :param groupby: Name(s) of column(s) defining the grouping. :type groupby: str, list :param args, kwargs: Optional positional and keyword arguments to pass
onto the function call.
-
clone
(self, data=None, **kwargs)¶ Clone (deep copy) the current column, optionally replacing its data and/or any other attributes.
- Parameters
data (DataFrame, ndarray) – Optional new data to substitute into the cloned column. Must have same dimensionality as the original.
kwargs (dict) – Optional keyword arguments containing new attribute values to set in the copy. E.g., passing name=’my_name’ would set the .name attribute on the cloned instance to the passed value.
-
filter
(self, filters=None, query=None, strict=False, inplace=False)¶ Returns a copy of the current Variable with only rows that match the filters retained.
- Parameters
filters (dict) – Dictionary of filters to apply. Keys can be either ‘amplitude’ or any named entity. Values must be single values or lists.
query (str) – Optional query string to pass to df.query(). Will not be validated in any way, so must have valid column names. Takes precedence over filters in the event that both are passed.
strict (bool) – By default, keys in ‘filters’ that cannot be found in the Variable will be silently ignored. If strict=True, None will be returned in such cases.
inplace (bool) – If True, filtering is performed in place. If False, a filtered copy of the Variable is returned.
- Returns
A BIDSVariable, or None if no rows are left after filtering.
-
get_grouper
(self, groupby='run')¶ Return a list suitable for use in groupby calls. :param groupby: Name(s) of column(s) defining the grouper
object. Anything that would be valid inside a .groupby() call on a pandas structure.
- Returns
A list defining the groups.
-
matches_entities
(self, entities, strict=False)¶ Checks whether current Variable’s entities match the input.
-
classmethod
merge
(variables, name=None, **kwargs)¶ Merge/concatenate a list of variables along the row axis.
- Parameters
variables (list) – A list of Variables to merge.
name (str) – Optional name to assign to the output Variable. By default, uses the same name as the input variables.
kwargs – Optional keyword arguments to pass onto the class-specific merge() call. See merge_variables docstring for details.
- Returns
A single BIDSVariable of the same class as the input variables.
Notes: see merge_variables docstring for additional details.
-
select_rows
(self, rows)¶ Truncate internal arrays to keep only the specified rows.
- Parameters
rows (array) – An integer or boolean array identifying the indices of rows to keep.
-
split
(self, grouper)¶ Split the current SparseRunVariable into multiple columns.
- Parameters
grouper (iterable) – list to groupby, where each unique value will be taken as the name of the resulting column.
- Returns
A list of SparseRunVariables, one per unique value in the grouper.
-
to_dense
(self, sampling_rate)[source]¶ Convert the current sparse column to a dense representation. Returns: A DenseRunVariable.
- Parameters
sampling_rate (int, str) – Sampling rate (in Hz) to use when constructing the DenseRunVariable.
- Returns
A DenseRunVariable.
-
to_df
(self, condition=True, entities=True, **kwargs)¶ Convert to a DataFrame, with columns for name and entities. :param condition: If True, adds a column for condition name, and
names the amplitude column ‘amplitude’. If False, returns just onset, duration, and amplitude, and gives the amplitude column the current column name.
- Parameters
entities (bool) – If True, adds extra columns for all entities.
-
merge_variables
(variables, name=None, **kwargs)[source]¶ Merge/concatenate a list of variables along the row axis.
- Parameters
variables (
list
) – A list of Variables to merge.name (
str
) – Optional name to assign to the output Variable. By default, uses the same name as the input variables.kwargs –
Optional keyword arguments to pass onto the class-specific merge() call. Possible args:
sampling_rate (int, str): The sampling rate to use if resampling of DenseRunVariables is necessary for harmonization. If ‘auto’, the highest sampling rate found will be used. This argument is only used when passing DenseRunVariables in the variables list.
- Returns
- Return type
A single BIDSVariable of the same class as the input variables.
Notes
Currently, this function only support homogenously-typed lists. In future, it may be extended to support implicit conversion.
Variables in the list must all share the same name (i.e., it is not possible to merge two different variables into a single variable.)