trajectory

class Trajectory(*, data=None, cfg=None, timestep=None, validate_on_init=True)

Bases: TimestampedInstanceCollection

Represents a trajectory, a collection of timestamped instances from a single animal.

This class adds functionality specific to trajectories, such as interpolation and sampling at specific timestamps. It also manages a timestep attribute.

Parameters:

  • data (Mapping[str, ndarray] | None, default: None) – A dictionary containing the trajectory data.

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

  • timestep (int | float | None, default: None) – The timestep of the trajectory.

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

get_interpolated_length(timestep=None)

Calculates the interpolated length of the trajectory based on a given timestep.

Parameters:

timestep (int | float | None, default: None) – The time step to use for interpolation; defaults to the trajectory’s timestep if not provided.

Return type:

int

Returns:

The interpolated length of the trajectory.

Raises:

ValueError – If the timestep does not result in an integer trajectory length.

init_other(*, data, copy_config=False, validate_on_init=False)

Initializes a new trajectory, optionally copying the configuration.

Parameters:

  • data (dict[str, ndarray] | None) – The data to initialize the trajectory with.

  • copy_config (bool, default: False) – Whether to copy or use the same configuration.

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

Return type:

Self

Returns:

A new trajectory instance.

interpolate(timestep=None, *, copy=True)

Linearly interpolates the trajectory to a new timestep, effectively resampling the trajectory at a different rate.

See also Trajectory.sample().

Parameters:

  • timestep (int | float | None, default: None) – The desired timestep for the interpolated trajectory. If None, the original timestep is used.

  • copy (bool, default: True) – Whether to create a copy of the trajectory data.

Return type:

Self

Returns:

The interpolated trajectory.

property is_complete: bool

Checks if the trajectory is complete based on its length, timestamps, and timestep.

sample(timestamps, *, keep_dtype=False, copy=True)

Samples the trajectory at the given timestamps, linearly interpolating values where necessary.

Parameters:

  • timestamps (ndarray) – The timestamps at which to sample the trajectory.

  • keep_dtype (bool, default: False) – Whether to preserve the original data type of the timestamps.

  • copy (bool, default: True) – Whether to return a new Trajectory object or modify the existing one.

Return type:

Self

Returns:

The sampled trajectory.

Raises:

AssertionError – If the trajectory is not sorted or if it contains more than one unique identity.

slice_window(start, stop, *, copy=True, interpolate=True, interpolation_timestep=None)

Slices a time window of the trajectory, optionally interpolating to a fixed timestep.

Parameters:

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

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

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

  • interpolate (bool, default: True) – Whether to interpolate the window to a fixed timestep.

  • interpolation_timestep (int | float | None, default: None) – The timestep to use for interpolation.

Return type:

Self

Returns:

The sliced trajectory.

Raises:

ValueError – If interpolate=True and copy=False.

property timestep: int | float

Returns or sets the timestep of the trajectory.

If the timestep is not set, it is inferred as the greatest common denominator of the time steps between consecutive timestamps.

validate_data(data, *, allow_duplicated_timestamps=False, allow_missing_keys=False, try_broadcasting=True, require_array_like=False)

Validates the input data against the specified requirements.

See validate_data() for more details.

Parameters:

  • data (Mapping[str, ndarray | int | float | str | integer | floating]) – The data to validate.

  • allow_duplicated_timestamps (bool, default: False) – Ignored, exists for consistency with InstanceCollection.

  • allow_missing_keys (bool, default: False) – Whether to allow missing keys.

  • try_broadcasting (bool, default: True) – Whether to try broadcasting.

  • require_array_like (bool, default: False) – Whether to require array-like data.

Return type:

bool

Returns:

If the data passed validation.