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 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.

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 the Dataset.

This is the first method that should be called on a Dataset when using this API. The internal attribute it creates in the Dataset is _events.

Optionally, ds_df_mapping can be specified. This dictionary consists of key-value pairs that establish a correspondance between an events DataFrame column and a Dataset dimension or coordinate, which is needed for some operations on events.

To facilitate the task of referencing _events, we provide the property df(). Assuming you have a Dataset called ds, you may use it via ds.events.df.

Args:

source: A DataFrame specifying where the events are

to be loaded from.

ds_df_mapping: An optional dictionary where the keys are

columns from the events DataFrame and the values are dimensions or coordinates from the Dataset 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.