load¶
-
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
.
-
load
(source: pandas.core.frame.DataFrame, ds_df_mapping: Optional[Mapping[Hashable, Union[Tuple[Hashable, Hashable], Hashable]]] = None) → xarray.core.dataset.Dataset Set the events
DataFrame
as an attribute of theDataset
.This is the first method that should be called on a
Dataset
when using this API. The internal attribute it creates in theDataset
is_events
.Optionally,
ds_df_mapping
can be specified. This dictionary consists of key-value pairs that establish a correspondance between an eventsDataFrame
column and aDataset
dimension or coordinate, which is needed for some operations on events.To facilitate the task of referencing
_events
, we provide the propertydf()
. Assuming you have aDataset
calledds
, you may use it viads.events.df
.- Args:
source
: ADataFrame
specifying where the events areto be loaded from.
ds_df_mapping
: An optional dictionary where the keys arecolumns from the events
DataFrame
and the values are dimensions or coordinates from theDataset
thereby specifying a mapping between them.
- Returns:
The modified
Dataset
now including events as an attribute.- Raises:
ValueError: on an invalid mapping.
- Example:
See Loading.