larvaworld.lib.plot.traj

Agent 2D trajectory-related plotting

Functions

traj_1group(→ Any)	Plot trajectories for a single dataset.
traj_grouped(→ Any)	Plot trajectories grouped by dataset.
track_annotated(→ Any)	Create annotated track with behavioral epochs highlighted.
annotated_strideplot(→ Any)	Create stride-annotated track plot.
annotated_turnplot(→ Any)	Create turn-annotated track plot.
track_annotated_data(→ Any)	Create annotated tracks for multiple individuals from datasets.
annotated_strideplot_data(→ Any)	Create stride-annotated tracks for multiple individuals.
annotated_turnplot_data(→ Any)	Create turn-annotated tracks for multiple individuals.
plot_marked_strides(→ Any)	Plot velocity track with marked stride epochs.
plot_sample_tracks(→ Any)	Plot sample tracks with stride and/or turn annotations.

Module Contents

larvaworld.lib.plot.traj.traj_1group(d: Any, unit: str = 'mm', mode: str = 'default', title: str | None = None, single_color: bool = False, time_range: Tuple[int, int] | None = None, **kwargs: Any) → Any

Plot trajectories for a single dataset.

Creates 2D trajectory plot showing movement paths of all individuals within arena boundaries with food sources marked.

Args:

d: Dataset containing trajectory data unit: Distance unit (‘mm’ or ‘m’). Defaults to ‘mm’ mode: Trajectory mode. Defaults to ‘default’ title: Plot title. Defaults to None single_color: Use single color for all tracks. Defaults to False time_range: Time range (start, end) to slice. Defaults to None **kwargs: Additional arguments passed to AutoBasePlot

Returns:

Plot output (figure object or None based on return_fig setting)

Example:

>>> fig = traj_1group(dataset, unit='mm', single_color=True)

larvaworld.lib.plot.traj.traj_grouped(unit: str = 'mm', name: str | None = None, subfolder: str = 'trajectories', range: Tuple[int, int] | None = None, mode: str = 'default', single_color: bool = False, **kwargs: Any) → Any

Plot trajectories grouped by dataset.

Creates multi-panel trajectory plots with one panel per dataset, showing all individual tracks within each dataset.

Args:

unit: Distance unit (‘mm’ or ‘m’). Defaults to ‘mm’ name: Plot name for saving. Auto-generated if None subfolder: Subfolder for saving. Defaults to ‘trajectories’ range: Time range (start, end) to slice. Defaults to None mode: Trajectory mode. Defaults to ‘default’ single_color: Use single color per dataset. Defaults to False **kwargs: Additional arguments passed to AutoPlot

Returns:

Plot output (figure object or None based on return_fig setting)

Example:

>>> fig = traj_grouped(datasets=[d1, d2], unit='mm', range=(0, 60))

larvaworld.lib.plot.traj.track_annotated(epoch: str = 'stride', a: Any = None, dt: float = 0.1, a2plot: Any = None, ylab: str | None = None, ylim: Sequence[float] | None = None, xlim: Sequence[float] | None = None, slice: Tuple[int, int] | None = None, agent_idx: int = 0, agent_id: str | None = None, subfolder: str = 'tracks', moving_average_interval: float | None = None, epoch_boundaries: bool = True, show_extrema: bool = True, min_amp: float | None = None, **kwargs: Any) → Any

Create annotated track with behavioral epochs highlighted.

Generates time series plot with stride/turn epochs shown as colored background regions and extrema marked.

Args:

epoch: Epoch type (‘stride’ or ‘turn’). Defaults to ‘stride’ a: Parameter array to plot. Defaults to None dt: Time step in seconds. Defaults to 0.1 a2plot: Alternative parameter to overlay. Defaults to None ylab: Y-axis label. Auto-generated if None ylim: Y-axis limits. Defaults to None xlim: X-axis limits. Defaults to None slice: Time slice (start, end). Defaults to None agent_idx: Agent index. Defaults to 0 agent_id: Specific agent ID. Uses agent_idx if None subfolder: Subfolder for saving. Defaults to ‘tracks’ moving_average_interval: Smoothing window. Defaults to None epoch_boundaries: Show epoch boundaries. Defaults to True show_extrema: Mark velocity extrema. Defaults to True min_amp: Minimum amplitude for turns. Defaults to None **kwargs: Additional arguments passed to AutoPlot

Returns:

Plot output (figure object or None based on return_fig setting)

Example:

>>> fig = track_annotated(datasets=[d1], epoch='stride', agent_idx=0)

larvaworld.lib.plot.traj.annotated_strideplot(**kwargs: Any) → Any

Create stride-annotated track plot.

Wrapper function that creates track with stride epochs highlighted.

Args:

**kwargs: Arguments passed to track_annotated

Returns:

Plot output (figure object or None based on return_fig setting)

Example:

>>> fig = annotated_strideplot(datasets=[d1], agent_idx=0)

larvaworld.lib.plot.traj.annotated_turnplot(**kwargs: Any) → Any

Create turn-annotated track plot.

Wrapper function that creates track with turn epochs highlighted.

Args:

**kwargs: Arguments passed to track_annotated

Returns:

Plot output (figure object or None based on return_fig setting)

Example:

>>> fig = annotated_turnplot(datasets=[d1], agent_idx=0)

larvaworld.lib.plot.traj.track_annotated_data(name: str | None = None, subfolder: str = 'tracks', epoch: str = 'stride', a2plot_k: str | None = None, agent_idx: Sequence[int] = [3, 4, 5, 6], dur: float = 1, **kwargs: Any) → Any

Create annotated tracks for multiple individuals from datasets.

Generates multi-panel figure with annotated tracks for multiple agents, showing behavioral epochs and trajectory metrics.

Args:

name: Plot name for saving. Auto-generated if None subfolder: Subfolder for saving. Defaults to ‘tracks’ epoch: Epoch type (‘stride’ or ‘turn’). Defaults to ‘stride’ a2plot_k: Additional parameter key to overlay. Defaults to None agent_idx: List of agent indices to plot. Defaults to [3, 4, 5, 6] dur: Duration in minutes. Defaults to 1 **kwargs: Additional arguments passed to AutoPlot

Returns:

Plot output (figure object or None based on return_fig setting)

Example:

>>> fig = track_annotated_data(datasets=[d1, d2], epoch='stride', agent_idx=[0, 1, 2])

larvaworld.lib.plot.traj.annotated_strideplot_data(**kwargs: Any) → Any

Create stride-annotated tracks for multiple individuals.

Wrapper that generates annotated tracks with stride epochs for multiple agents from datasets.

Args:

**kwargs: Arguments passed to track_annotated_data

Returns:

Plot output (figure object or None based on return_fig setting)

Example:

>>> fig = annotated_strideplot_data(datasets=[d1, d2], agent_idx=[0, 1])

larvaworld.lib.plot.traj.annotated_turnplot_data(**kwargs: Any) → Any

Create turn-annotated tracks for multiple individuals.

Wrapper that generates annotated tracks with turn epochs for multiple agents from datasets.

Args:

**kwargs: Arguments passed to track_annotated_data

Returns:

Plot output (figure object or None based on return_fig setting)

Example:

>>> fig = annotated_turnplot_data(datasets=[d1, d2], agent_idx=[0, 1])

larvaworld.lib.plot.traj.plot_marked_strides(agent_idx: int = 0, agent_id: str | None = None, slice: Sequence[int] = [20, 40], subfolder: str = 'individuals', **kwargs: Any) → Any

Plot velocity track with marked stride epochs.

Creates time series showing velocity with stride and pause epochs highlighted and extrema marked for individual analysis.

Args:

agent_idx: Agent index. Defaults to 0 agent_id: Specific agent ID. Uses agent_idx if None slice: Time slice [start, end] in seconds. Defaults to [20, 40] subfolder: Subfolder for saving. Defaults to ‘individuals’ **kwargs: Additional arguments passed to AutoPlot

Returns:

Plot output (figure object or None based on return_fig setting)

Example:

>>> fig = plot_marked_strides(datasets=[d1, d2], agent_idx=0, slice=[0, 60])

larvaworld.lib.plot.traj.plot_sample_tracks(mode: Sequence[str] = ['strides', 'turns'], agent_idx: int = 4, agent_id: str | None = None, slice: Sequence[int] = [0, 160], subfolder: str = 'individuals', **kwargs: Any) → Any

Plot sample tracks with stride and/or turn annotations.

Creates multi-panel figure showing strides and/or turns for sample individuals across datasets with detailed epoch marking.

Args:

mode: Plot modes (‘strides’, ‘turns’, or both). Defaults to both agent_idx: Agent index. Defaults to 4 agent_id: Specific agent ID. Uses agent_idx if None slice: Time slice [start, end] in seconds. Defaults to [0, 160] subfolder: Subfolder for saving. Defaults to ‘individuals’ **kwargs: Additional arguments passed to AutoPlot

Returns:

Plot output (figure object or None based on return_fig setting)

Example:

>>> fig = plot_sample_tracks(datasets=[d1, d2], mode=['strides'], slice=[0, 120])