plots.plot_metric_vs_arrival_time

plots.plot_metric_vs_arrival_time(
    event_log,
    first_event,
    second_event,
    *,
    arrival_event='arrival',
    colour_by=None,
    rolling_window=None,
    rolling_time=None,
    warm_up=0,
    match='first',
    marker_size=6,
    line_width=3,
    highlight_bands=None,
    title=None,
    **col_kwargs,
)

Plot a duration/metric against the arrival time of the entity it belongs to.

Thin wrapper over vidigi.analysis.entity_metric_by_arrival: a scatter of duration against arrival time, for spotting whether the metric drifts depending on when the entity arrived - a non-stationary arrival process or a time-of-day/load effect, for example. The counterpart to plot_replication_analysis (precision across replications) and plot_warm_up_diagnostic (the startup transient) - this is the diagnostic for drift within a run’s steady operation, ordered by arrival rather than by replication count.

Parameters

Name Type Description Default
event_log pandas.DataFrame Long-format event log, e.g. the output of TrialLogger.to_dataframe(). required
first_event str The two events to measure the duration between. See vidigi.analysis.event_durations. required
second_event str The two events to measure the duration between. See vidigi.analysis.event_durations. required
arrival_event str The event marking an entity’s arrival - drawn on the x-axis. See vidigi.analysis.entity_metric_by_arrival. "arrival"
colour_by (run, pathway) If given, draws one trace per distinct value of the corresponding column (run_number or pathway) instead of a single trace over every point pooled together - matches plot_duration_distribution’s split_by. "run"
rolling_window int Half-width, in points, of a symmetric moving average drawn over the scatter (in arrival-time order) - a count-based smoothing window. Mutually exclusive with rolling_time. None (default) draws no trend line. None
rolling_time float Half-width, in the event log’s time units, of a symmetric moving average drawn over the scatter - every point within rolling_time on either side of a given arrival time is averaged, so unlike rolling_window the number of points contributing can vary with local arrival density. Mutually exclusive with rolling_window. None (default) draws no trend line. None
warm_up float Points whose arrival_time is before warm_up are excluded, applied before any rolling average so excluded points cannot leak into the smoothing near the boundary. Filtered by arrival_time - this chart’s x-axis - not first_time; the default of 0 is a verified no-op. 0
match (first, last, occurrence) How repeated occurrences of first_event/second_event are paired. See vidigi.analysis.event_durations. Does not affect the arrival-time lookup - see vidigi.analysis.entity_metric_by_arrival. "first"
marker_size float Marker size for the scatter points. 6
line_width float Line width for the rolling-mean trend line, when drawn. 3
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. None
title str Figure title. None
**col_kwargs dict Column-name keyword arguments forwarded to vidigi.analysis.entity_metric_by_arrival, e.g. run_col_name=. {}

Returns

Name Type Description
plotly.graph_objects.Figure

Raises

Name Type Description
ValueError If colour_by is not one of the supported values; if both rolling_window and rolling_time are given; if either is given but not a positive number; if warm_up is negative; if colour_by is set but the corresponding column is entirely missing; if no points remain to plot after excluding incomplete pairs, missing arrival times, and warm_up; or if a highlight_bands entry has neither lower nor upper set, or lower >= upper.

See Also

vidigi.analysis.entity_metric_by_arrival : The underlying per-entity data. plot_warm_up_diagnostic : The companion diagnostic for the startup transient.

Notes

When colour_by groups the scatter, the rolling-mean trend line (if requested) is still computed once, pooled over every group - matching the “faint per-group traces + one bold pooled mean” visual language already used by plot_resource_utilisation_over_time/plot_queue_size, rather than drawing a separate trend per group.

Examples

>>> plot_metric_vs_arrival_time(trial.to_dataframe(), "wait_begins", "treatment_begins")
<plotly.graph_objs._figure.Figure>
Back to top