animation.add_synchronised_trace_from_dataframe

animation.add_synchronised_trace_from_dataframe(
    fig,
    data,
    make_trace,
    *,
    frame_time_col,
    match='index',
    accumulate=False,
    static_traces=None,
    redraw=None,
)

Add a synchronised trace built from a long-form DataFrame.

A convenience wrapper over :func:add_synchronised_trace for the usual shape: a DataFrame with a time column, from which one (or more) trace is built per animation frame.

Parameters

Name Type Description Default
fig plotly.graph_objects.Figure An animated figure from :func:generate_animation / :func:animate_activity_log. Modified in place. required
data pandas.DataFrame Long-form data. The distinct values of frame_time_col, sorted ascending, are the time steps. required
make_trace callable make_trace(rows) -> trace \| list[trace], where rows is the slice of data for the current frame (see accumulate). Must return the same number of traces every call - return an empty trace (e.g. go.Bar(x=[], y=[])) for a frame with no rows. required
frame_time_col str Column of data identifying the time step of each row. required
match (index, value) How data times line up with animation frames. "index" pairs the i-th distinct time with fig.frames[i] regardless of how the frame is labelled - robust to time_display_units - and raises ValueError if the counts differ. "value" matches str(time) == str(frame.name) instead, for when only some frames have data. "index"
accumulate bool False passes make_trace only the current time step’s rows (a snapshot - e.g. a bar chart of the current state). True passes every row up to and including the current time (a cumulative view - e.g. a line that grows as the animation plays). False
static_traces _TraceInput Passed through to :func:add_synchronised_trace. None
redraw _TraceInput Passed through to :func:add_synchronised_trace. None

Returns

Name Type Description
plotly.graph_objects.Figure The same figure, with the extra trace(s) added and every frame updated.
Back to top