timestamped collection

class TimestampedInstanceCollection(*, data=None, cfg=None, validate_on_init=True)

Bases: InstanceCollection

Represents a collection of timestamped instances.

This class provides direct access to timestamps and adds functionality specific to timestamped data, such as sorting by timestamp and slicing based on time windows. It ensures that a timestamp key is defined in the configuration.

Parameters:

  • data (Mapping[str, ndarray] | None, default: None) – The instance data for the collection.

  • cfg (Config | None, default: None) – The configuration object.

  • validate_on_init (bool, default: True) – Whether to validate the data during initialization.

Raises:

ValueError – If the timestamp key is not defined in the trajectory keys during initialization.

get_slice(start, stop)

Converts a time window to a slice object for accessing data within the window.

Parameters:

  • start (int | float) – The start time of the window (inclusive).

  • stop (int | float) – The end time of the window (inclusive).

Return type:

slice

Returns:

The slice object for accessing data within the window.

Raises:

  • ValueError – If the collection has zero length or is not sorted.

  • utils.OutOfInterval – If the start or stop time is outside the timestamp range.

property is_sorted: bool

Checks if the timestamps in the collection are sorted in ascending order.

property key_timestamp: str

Returns the key used to access the timestamp within each instance.

slice_window(start, stop)

Slices the collection based on a specified time window.

Parameters:

  • start (int | float) – The start time of the window (inclusive).

  • stop (int | float) – The end time of the window (inclusive).

Return type:

Self

Returns:

The sliced collection based on the specified time window.

sort(copy=True)

Sorts the collection by timestamp.

Parameters:

copy (bool, default: True) – Whether to return a copy of the sorted collection.

Return type:

Self

Returns:

The sorted collection.

Raises:

ValueError – If copy=False and the collection is a view or has existing views.

property timestamps: ndarray

Returns the timestamps of the instances in the collection.