plots.plot_queue_size

plots.plot_queue_size(
    event_log,
    event_list,
    limit_duration,
    *,
    every_x_time_units=1,
    warm_up=0,
    show_all_runs=True,
    shared_y_axis=True,
    highlight_bands=None,
    backend='express',
    run_col_name='auto',
    entity_col_name='entity_id',
    time_col_name='time',
    event_type_col_name='event_type',
    event_col_name='event',
    pathway_col_name=None,
    **kwargs,
)

Plot the size of one or more queues over time, across every run.

Thin wrapper over vidigi.analysis.queue_size_over_time: this function only builds the figure from that data.

Parameters

Name Type Description Default
event_log pandas.DataFrame Long-format event log spanning one or more runs, e.g. the output of TrialLogger.to_dataframe(). required
event_list list of str Event names (matched against event_col_name) to plot a queue size for. required
limit_duration int or float Maximum time to include, in the same units as time_col_name. required
every_x_time_units int Time granularity for snapshots. Larger values aggregate queue size over coarser time intervals. 1
warm_up int Time at which the plotted window begins. Snapshots run from warm_up to limit_duration. See vidigi.prep.reshape_for_animations for why this - and not filtering the log by time - is the correct way to discard a warm-up period; the default of 0 is a no-op. 0
show_all_runs bool If True, plots every run with semi-transparent lines and overlays the mean trajectory. If False, only the mean trajectory is plotted. True
shared_y_axis bool If True (and more than one event is plotted), every facet shares a y-axis range. If False, each is scaled independently. True
highlight_bands list of dict Shaded threshold zones drawn behind the chart - see plot_duration_distribution’s parameter of the same name for the dict shape. Spans every facet when more than one event is plotted; applies with either backend. None
backend (express, go) Which plotly API builds the figure. "express" (several spellings accepted, see vidigi.animation.AnimationBackend for the equivalent on the animation functions) matches the pre-existing behaviour and accepts **kwargs forwarded to plotly.express.line for styling at creation time. "go" builds every trace explicitly with plotly.graph_objects instead: trace names, order and legend grouping are then deterministic rather than depending on px’s automatic grouping, which some callers find easier to target when restyling the figure afterwards. **kwargs is not used by the "go" backend - style the returned figure directly. "express"
run_col_name str or None Column identifying which run each row belongs to. See vidigi.analysis.queue_size_over_time. "auto"
entity_col_name str 'entity_id'
time_col_name str 'entity_id'
event_type_col_name str 'entity_id'
event_col_name str 'entity_id'
pathway_col_name str or None Column names forwarded to vidigi.analysis.queue_size_over_time. None
**kwargs dict Additional keyword arguments passed to plotly.express.line. Ignored (with a warning) when backend="go". {}

Returns

Name Type Description
plotly.graph_objects.Figure

Raises

Name Type Description
ValueError If a highlight_bands entry has neither lower nor upper set, or lower >= upper.

Notes

  • When multiple event types are specified, they are faceted in separate panels.
  • Queue lengths are not capped at the display limit used by the animation functions, so long queues are plotted at their full length.
  • A snapshot where an event has nobody queuing is plotted as zero rather than omitted, so a queue that empties is drawn dropping to the axis, and the mean is taken across every run rather than only those with someone waiting. An event in event_list that occurs in no run is plotted as zero throughout, with a warning.

See Also

vidigi.analysis.queue_size_over_time : The underlying per-run, per-snapshot counts.

Examples

>>> plot_queue_size(
...     trial.to_dataframe(),
...     event_list=["queue_enter", "queue_exit"],
...     limit_duration=500,
...     every_x_time_units=5,
... )
<plotly.graph_objs._figure.Figure>
Back to top