sel

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.

sel(indexers: Optional[Mapping[str, Any]] = None, method: Optional[str] = None, tolerance: Optional[numbers.Number] = None, drop: bool = False, **indexers_kwargs: Any) → xarray.core.dataset.Dataset

Perform a selection on _ds given specified constraints.

This is a wrapper around xr.Dataset.sel() that extends its functionality to support events handling.

The arguments that match events DataFrame attributes are used to filter the events. Everything else is passed directly to xr.Dataset.sel().

Call this method by specifying constraints for both the Dataset dimensions and the events DataFrame attributes in a single dictionary.

The values for the constraints may be of different types, and the behavior varies accordingly. Here’s how it works:

  • If the value is a single value, filter by it directly.

  • If the value is an instance of Collection (like a list), filter the events by them.

  • If the value is a boolean mask, filter the DataFrame by it. In case the value is an instance of Callable (like a lambda function), apply the function to the events DataFrame to obtain a mask first.

Tip: If intended to be chained, call after having called load() to ensure that the events are properly loaded.

The arguments, return values and raised exceptions are the same as for xr.Dataset.sel, in order to stay true to the wrapper nature of this method. See the official xarray documentation for details.

Example:

See Selecting.