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 aDataFrame
and perform selections on the events satisfying a set of specified constraints.- Attributes:
_ds
: TheDataset
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
toDataFrame
.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 eventsDataFrame
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 toload()
.
-
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 byexpand_to_match_ds()
to group aDataVariable
of theDataset
, resulting in aGroupBy
object on which functions can be called.Call this method strictly after having called
load()
with theds_df_mapping
argument.- Args:
array_to_group
:Dataset
data variable or coordinateto group.
dimension_matching_col
: EventsDataFrame
column whosevalues 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 eventsDataFrame
to aDataset
dimension or coordinate that must have already been specified upon callingload()
.fill_method
: Method to be used to fill the gaps that emergeafter 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 likeGroupBy
frompandas
.- Raises:
KeyError: when
dimension_matching_col
is unrecognizable.- Example:
See Grouping a data variable by the events in the DataFrame.