groupby_events

class xarray_events.EventsAccessor(ds: xarray.core.dataset.Dataset)

xarray accessor with extended events-handling functionality.

An xarray accessor that extends its functionality to handle events in a high-level way. This API makes it easy to load events into an existing Dataset from a DataFrame and perform selections on the events satisfying a set of specified constraints.

Attributes:

_ds: The Dataset to be accessed whose class-level functionality is to be extended.

property df

Manage the events DataFrame.

Note: Getting it when it doesn’t exist raises an exception. Setting it when it apparently already exists raises a warning.

property ds_df_mapping

Manage the mapping from Dataset to DataFrame.

Note: Getting it when it doesn’t exist raises an exception. Setting it when it apparently already exists raises a warning.

This is basically a dictionary where a key is a Dataset dimension or coordinate and a value is a tuple or a string referring to an events DataFrame column. The reason behind its existence is that it is a non-trivial task to automatically deduce such correspondances which are needed for some operations with events. This dictionary is provided as an argument to load().

property duration_mapping

Manage the events column pairs that represent a duration.

This property is automatically deduced from (and therefore depends on) ds_df_mapping.

groupby_events(array_to_group: Hashable, dimension_matching_col: Optional[Hashable] = None, fill_method: Optional[Hashable] = None) → xarray.core.groupby.DataArrayGroupBy

Group a data variable by the events in the DataFrame.

This method uses a DataArray generated by expand_to_match_ds() to group a DataVariable of the Dataset, resulting in a GroupBy object on which functions can be called.

Call this method strictly after having called load() with the ds_df_mapping argument.

Args:

array_to_group: Dataset data variable or coordinate

to group.

dimension_matching_col: Events DataFrame column whose

values form a subset of the values of some Dataset dimension or coordinate and will be expanded to match them. This argument uses a mapping from a column of the events DataFrame to a Dataset dimension or coordinate that must have already been specified upon calling load().

fill_method: Method to be used to fill the gaps that emerge

after expanding dimension_matching_col. The possible filling methods are:

• pad / ffill: Propagate values forward until next one.

• backfill / bfill: Use next value to fill gap.

• nearest: Use nearest values to fill gap.

Returns:

A DataArrayGroupBy object, which is internally just like GroupBy from pandas.

Raises:

KeyError: when dimension_matching_col is unrecognizable.

Example:

See Grouping a data variable by the events in the DataFrame.