animation.add_synchronised_trace

animation.add_synchronised_trace(
    fig,
    frame_traces,
    *,
    static_traces=None,
    initial_traces=None,
    redraw=None,
)

Add extra traces to an animation, kept in step with its frames.

A vidigi animation figure holds more traces in fig.data than in each fig.frames[i].data - the per-entity traces are animated, while the stage-label and resource-icon traces are static and simply left untouched as the animation plays. Adding your own animated trace by hand means reproducing that arrangement exactly, and getting it slightly wrong makes traces flicker, vanish after the first frame, or blank out the stage labels.

This helper does it for you:

  • static_traces are added once and never re-sent per frame, so - like vidigi’s own label/resource traces - they stay put for the whole animation.
  • frame_traces is called once per frame to build the animated trace(s) for that frame. It must return the same number of traces every time (return an empty trace such as go.Scatter(x=[], y=[]) for frames with nothing to show); a mismatch raises ValueError naming the frame.
  • The existing frames’ trace mapping is preserved, so the stage labels and resource icons keep rendering throughout.

Parameters

Name Type Description Default
fig plotly.graph_objects.Figure An animated figure from :func:generate_animation / :func:animate_activity_log. Modified in place. If it has no frames a UserWarning is issued and it is returned unchanged. required
frame_traces callable frame_traces(frame_name, frame_index) -> trace \| list[trace]. Called for every frame, in order. frame_name is fig.frames[i].name (the formatted time shown on the slider); frame_index is i. Prefer frame_index for lookups - frame_name is reformatted by time_display_units and may not match your data. required
static_traces trace or list of traces Trace(s) shown identically on every frame - a target line, a fixed annotation, a reference band. Added to fig.data only. None
initial_traces trace or list of traces What to seed fig.data with for the animated slots (the state shown before Play is pressed). Defaults to frame_traces(frames[0].name, 0). Must have the same length as frame_traces returns. None
redraw bool Whether to force redraw=True on the play button and slider. None (default) decides automatically: needed for non-scatter traces (bars) or traces on a secondary axis, not otherwise. Pass a bool to override. None

Returns

Name Type Description
plotly.graph_objects.Figure The same figure, with the extra traces added and every frame updated.

See Also

add_synchronised_trace_from_dataframe : convenience wrapper for the common case of a long-form DataFrame with one row per entity per time step. add_subplot_panels : make room for an extra chart panel first.

Back to top