larvaworld.lib.plot.traj ======================== .. py:module:: larvaworld.lib.plot.traj .. autoapi-nested-parse:: Agent 2D trajectory-related plotting Functions --------- .. autoapisummary:: larvaworld.lib.plot.traj.traj_1group larvaworld.lib.plot.traj.traj_grouped larvaworld.lib.plot.traj.track_annotated larvaworld.lib.plot.traj.annotated_strideplot larvaworld.lib.plot.traj.annotated_turnplot larvaworld.lib.plot.traj.track_annotated_data larvaworld.lib.plot.traj.annotated_strideplot_data larvaworld.lib.plot.traj.annotated_turnplot_data larvaworld.lib.plot.traj.plot_marked_strides larvaworld.lib.plot.traj.plot_sample_tracks Module Contents --------------- .. py:function:: traj_1group(d: Any, unit: str = 'mm', mode: str = 'default', title: Optional[str] = None, single_color: bool = False, time_range: Optional[Tuple[int, int]] = 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) .. py:function:: traj_grouped(unit: str = 'mm', name: Optional[str] = None, subfolder: str = 'trajectories', range: Optional[Tuple[int, int]] = 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)) .. py:function:: track_annotated(epoch: str = 'stride', a: Any = None, dt: float = 0.1, a2plot: Any = None, ylab: Optional[str] = None, ylim: Optional[Sequence[float]] = None, xlim: Optional[Sequence[float]] = None, slice: Optional[Tuple[int, int]] = None, agent_idx: int = 0, agent_id: Optional[str] = None, subfolder: str = 'tracks', moving_average_interval: Optional[float] = None, epoch_boundaries: bool = True, show_extrema: bool = True, min_amp: Optional[float] = 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) .. py:function:: 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) .. py:function:: 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) .. py:function:: track_annotated_data(name: Optional[str] = None, subfolder: str = 'tracks', epoch: str = 'stride', a2plot_k: Optional[str] = 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]) .. py:function:: 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]) .. py:function:: 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]) .. py:function:: plot_marked_strides(agent_idx: int = 0, agent_id: Optional[str] = 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]) .. py:function:: plot_sample_tracks(mode: Sequence[str] = ['strides', 'turns'], agent_idx: int = 4, agent_id: Optional[str] = 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])