expand_to_match_ds

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.

expand_to_match_ds(dimension_matching_col: Hashable, fill_method: Optional[Hashable] = None, fill_value_col: Hashable = 'event_index') → xarray.core.dataarray.DataArray

Expand a DataFrame column to match the shape of the Dataset.

Given the column dimension_matching_col of the events DataFrame whose values form a subset of the values of a Dataset dimension or coordinate, this method will create a DataArray in such a way that its coordinates are the values of the aforementioned superset and the values are given by the column fill_value_col of the events DataFrame, filling in the emerging gaps as per fill_method.

This subset-superset correspondance is a mapping (key-value pair) from a column of the events DataFrame (key) to a Dataset dimension or coordinate (value), and it must be previously specified in a dictionary upon calling load(). It is handled by the ds_df_mapping() property.

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

Args:
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:

  • None (default): don’t fill gaps.

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

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

  • nearest: Use nearest values to fill gap.

fill_value_col: Events DataFrame column whose values

fill the output array.

Returns:

A DataArray created as specified above.

Raises:
KeyError: when either dimension_matching_col or

fill_value_col is unrecognizable.

Example:

See Expanding an events column to match the Dataset’s shape.