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 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
.
-
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 theDataset
.Given the column
dimension_matching_col
of the eventsDataFrame
whose values form a subset of the values of aDataset
dimension or coordinate, this method will create aDataArray
in such a way that its coordinates are the values of the aforementioned superset and the values are given by the columnfill_value_col
of the eventsDataFrame
, filling in the emerging gaps as perfill_method
.This subset-superset correspondance is a mapping (key-value pair) from a column of the events
DataFrame
(key) to aDataset
dimension or coordinate (value), and it must be previously specified in a dictionary upon callingload()
. It is handled by theds_df_mapping()
property.Call this method strictly after having called
load()
with theds_df_mapping
argument.- Args:
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: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
: EventsDataFrame
column whose valuesfill the output array.
- Returns:
A
DataArray
created as specified above.- Raises:
- KeyError: when either
dimension_matching_col
or fill_value_col
is unrecognizable.
- KeyError: when either
- Example:
See Expanding an events column to match the Dataset’s shape.