animation.add_subplot_panels

animation.add_subplot_panels(
    fig,
    *,
    row_heights,
    vertical_spacing=0.05,
    subplot_titles=None,
    hide_new_panel_axes=True,
)

Re-home a vidigi animation into the top row of a stacked subplot grid.

A vidigi animation is a plain single-axis Plotly figure. To show an extra chart beneath it (a running total, a per-frame bar panel, a growing line) the figure first needs a subplot grid it can share. This does the plotly.subplots.make_subplots scaffolding - including copying the private _grid_ref attribute, without which later fig.add_trace(..., row=2, col=1) calls cannot resolve the panel - so callers don’t have to.

Call this before :func:add_synchronised_trace / :func:add_synchronised_trace_from_dataframe: the target axes must exist before traces are placed on them.

Parameters

Name	Type	Description	Default
fig	plotly.graph_objects.Figure	The figure from :func:generate_animation or :func:animate_activity_log. Modified in place.	required
row_heights	sequence of float	One entry per row, top to bottom. row_heights[0] is the animation panel; there must be at least one row beneath it. Passed straight to make_subplots.	required
vertical_spacing	float	Gap between rows, as a fraction of figure height.	0.05
subplot_titles	sequence of str	One title per row (use "" for rows with no title).	None
hide_new_panel_axes	bool	Blank the grid lines, zero line, axis line and tick labels on the new panels (rows 2 onward). They are usually annotation strips rather than full charts; set False and restyle by hand if you want axes.	True

Returns

Name	Type	Description
	plotly.graph_objects.Figure	The same figure, now backed by a subplot grid, with the animation in row 1 and empty panels below it.