plots.plot_duration_distribution

plots.plot_duration_distribution(
    event_log,
    first_event,
    second_event,
    *,
    kind='hist',
    split_by=None,
    bins=None,
    match='first',
    normalise=False,
    highlight_bands=None,
    title=None,
    **kwargs,
)

Plot the distribution of durations between two events.

Thin wrapper over vidigi.analysis.event_durations: this function only bins (for kind="hist") or reshapes the resulting durations for the chosen chart type - no statistic is computed that isn’t already in that DataFrame.

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
kind (hist, box, violin, ecdf, ridgeline, heatmap) Chart type. - "hist": a histogram, binned with numpy.histogram and drawn as bars - never plotly.graph_objects.Histogram, which bins in the browser and so has no inspectable y values. - "box" / "violin": the raw durations, one trace per group (or a single trace when split_by is None). - "ecdf": the empirical cumulative distribution function, drawn as a step line - linear interpolation between the sorted points would draw probabilities that never occurred. - "ridgeline": one histogram-derived density curve per group, stacked with a vertical offset and slight overlap (“joy plot” style). Always compares shape (each curve is its own density, area 1) rather than raw counts, so groups with different numbers of observations remain comparable; normalise is ignored. Requires split_by - a ridgeline needs more than one group to stack. - "heatmap": one row per group, duration binned along the x-axis, colour showing count or density per cell. Scales to far more groups than "ridgeline" can stay readable at, since it costs no vertical space per row. Requires split_by. "hist"
split_by (run, pathway) If given, produces one trace (or, for "heatmap", one row) per distinct value of the corresponding column (run_number or pathway) instead of a single trace over every duration pooled together. Required for kind="ridgeline" or kind="heatmap". "run"
bins int, sequence, or None Passed to numpy.histogram when kind is "hist", "ridgeline" or "heatmap". None uses 10 bins, matching numpy.histogram’s own default. The same bin edges are used for every group when split_by is set, so bars/rows stay comparable across groups. Ignored for other kinds. None
match (first, last, occurrence) How repeated occurrences of the two events are paired. See vidigi.analysis.event_durations. "first"
normalise bool For kind="hist" or kind="heatmap": if True, heights/cell values are a probability density (each group’s area sums to 1) rather than raw counts. Ignored for other kinds - "ridgeline" always uses density (see above), and the y-axis of "box"/"violin"/"ecdf" is either the raw durations or already a proportion. False
highlight_bands list of dict Shaded threshold zones drawn behind the chart, valid only for kind="box" or kind="violin". Each dict: lower/upper (float or None - a missing bound extends to the plotted data’s range; at least one must be given), colour (default "red"), label (default None - adds a legend entry when given) and opacity (default 0.12). E.g. a green “target” zone plus a red “breach” zone: [{"upper": 30, "colour": "green", "label": "target"}, {"lower": 60, "colour": "red", "label": "breach"}]. None
title str Figure title. There is no general plotly-kwargs passthrough on this function - style the returned figure directly. None
**kwargs dict Additional keyword arguments forwarded to vidigi.analysis.event_durations (e.g. entity_col_name, run_col_name, warm_up). {}

Returns

Name Type Description
plotly.graph_objects.Figure

Raises

Name Type Description
ValueError If kind or split_by is not one of the supported values; if kind is "ridgeline" or "heatmap" and split_by is not set; if no complete pairs are found to plot; if split_by is set but the corresponding column is entirely missing from the durations; if highlight_bands is set for a kind other than "box"/"violin", or a band has neither lower nor upper set, or lower >= upper; or if warm_up is negative.

See Also

vidigi.analysis.event_durations : The underlying per-entity durations. plot_metric : A box/violin of per-replication summary values, not raw per-entity durations.

Notes

Rows with an incomplete pairing (duration is NaN - an entity that never reached second_event, or vice versa) cannot be plotted on a distribution and are dropped before drawing. Call vidigi.analysis.event_durations directly if you need to know how many were excluded.

Back to top