analysis.queue_size_over_time

analysis.queue_size_over_time(
    event_log,
    event_list,
    limit_duration,
    *,
    every_x_time_units=1,
    warm_up=0,
    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,
)

Compute the size of one or more queues at regular snapshots, across every run.

Extracted from TrialLogger.plot_queue_size, which is now a thin wrapper over vidigi.plots.plot_queue_size, itself a thin wrapper over this function.

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 report 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. 1
warm_up int Time at which the reported window begins. Snapshots run from warm_up to limit_duration. Passed straight through to reshape_for_animations; see that function’s docstring for why this - and not filtering the log by time - is the correct way to discard a warm-up period. 0
run_col_name str or None Column identifying which run each row belongs to. "auto" looks for a column named (case-insensitively) one of run, run_number, replication, rep or run_id. Pass an explicit column name to override, or None if the log holds a single run. "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 reshape_for_animations. See that function’s docstring for their meaning. None

Returns

Name Type Description
pandas.DataFrame Columns run_number, event, snapshot_time, count. One row per event in event_list per snapshot per run, including snapshots where the queue was empty - a queue with nobody in it is a real zero, not a missing row.

Notes

  • Queue lengths are not capped at the step_snapshot_max used internally by reshape_for_animations for keeping an animation drawable; a queue is reported at its true length, however long it got.
  • An event in event_list that occurs in no run at all is reported as zero throughout, with a warning - otherwise a misspelt event name is indistinguishable from a queue that genuinely never formed.
Back to top