bids.variables.SparseRunVariable

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 (pandas.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 (dict) – 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.

__init__(self, name, data, run_info, source, **kwargs)[source]

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

Methods

__init__(self, name, data, run_info, source, …)

Initialize self.

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.

Parameters
  • func (callable) – The function to apply to each group.

  • groupby (str or list) – Name(s) of column(s) defining the grouping.

  • kwargs (args,) – 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 (pandas.DataFrame or array_like) – 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

Return type

BIDSVariable or None if no rows are left after filtering.

get_duration(self)[source]

Return the total duration of the Variable’s run(s).

get_grouper(self, groupby='run')

Return a list suitable for use in groupby calls.

Parameters

groupby (str or list) – 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.

Return type

list

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 (dict) – Optional keyword arguments to pass onto the class-specific merge() call. See merge_variables docstring for details.

Returns

Return type

A single BIDSVariable of the same class as the input variables.

select_rows(self, rows)

Truncate internal arrays to keep only the specified rows.

Parameters

rows (array_like) – An integer or boolean array identifying the indices of rows to keep.

split(self, grouper)

Split the current SparseRunVariable into multiple columns.

Parameters

grouper (pandas.DataFrame) – Binary DF specifying the design matrix to use for splitting. Number of rows must match current SparseRunVariable; a new SparseRunVariable will be generated for each column in the grouper.

Returns

Return type

A list of SparseRunVariables, one per column in the grouper DF.

to_dense(self, sampling_rate)[source]

Convert the current sparse column to a dense representation.

Parameters

sampling_rate (int or str) – Sampling rate (in Hz) to use when constructing the DenseRunVariable.

Returns

Return type

DenseRunVariable

to_df(self, condition=True, entities=True, **kwargs)

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.