plots.plot_metric
plots.plot_metric(
event_log,
event_pair_list,
*,
kind='bar',
what='mean',
exclude_incomplete=True,
across='entities',
error_bars=None,
ci_level=0.95,
show_runs=False,
highlight_bands=None,
match='first',
warm_up=0,
entity_col_name='entity_id',
time_col_name='time',
event_col_name='event',
run_col_name='auto',
pathway_col_name='pathway',
)Plot event duration statistics for a list of event pairs, as a bar, box or violin.
Thin wrapper over vidigi.analysis.event_durations, replication_means and mean_confidence_interval: this function only aggregates their output into one bar/box/violin per pair and builds the figure. The kind="bar" replacement for the deprecated plot_metric_bar.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| event_log | pandas.DataFrame | Long-format event log, e.g. the output of TrialLogger.to_dataframe(). |
required |
| event_pair_list | list of dict | A list of dictionaries, each containing: - "label" (str): A label for the event pair. - "first_event" (str): The name of the first event. - "second_event" (str): The name of the second event. |
required |
| kind | (bar, box, violin) | Chart type. "bar" draws one bar per pair, exactly as plot_metric_bar does. "box"/"violin" draw the full distribution of per-replication values instead of collapsing it to a mean - one trace per pair - and require across="runs" (there is only ever one value per pair to show when across="entities", nothing to draw a distribution from). For a box/violin of raw per-entity durations instead, use plot_duration_distribution. |
"bar" |
| what | str | The statistic to compute. See vidigi.analysis.event_durations’s module for the full set. When across="runs", only a genuine per-replication statistic is accepted - "mean", "median", "max", "min", "quantile", "std", "var", "sum" - see vidigi.analysis.replication_means. |
"mean" |
| exclude_incomplete | bool | If True, incomplete pairings (where the second event is missing) are excluded from the calculation. Must be True when across="runs" - a missing duration cannot contribute to a per-replication statistic. |
True |
| across | (entities, runs) | Whether each bar is a statistic pooled over every entity (matching plot_metric_bar’s default), or the mean of a per-replication statistic computed separately for each run. error_bars, show_runs and kind="box"/"violin" all require across="runs" - see Notes. |
"entities" |
| error_bars | (ci, sd, se, range, iqr) | The spread drawn as an error bar around each bar, computed over the per-run values. Only valid with kind="bar" - a box/violin already shows the full spread. See plot_metric_bar for the meaning of each option. |
"ci" |
| ci_level | float | Confidence level used when error_bars="ci". |
0.95 |
| show_runs | bool | If True, overlays each replication’s individual value. For kind="bar", a semi-transparent point on top of the bar; for kind="box"/"violin", the trace’s own points (boxpoints="all"/ points="all") alongside the box/violin shape. Requires across="runs". |
False |
| 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. Valid with any kind. |
None |
| match | (first, last, occurrence) | How repeated occurrences of the two events are paired. See vidigi.analysis.event_durations. |
"first" |
| warm_up | float | Pairings whose first_time is before warm_up are excluded from every bar/box/violin. See vidigi.analysis.event_durations’s same parameter. |
0 |
| entity_col_name | str | 'entity_id' |
|
| time_col_name | str | 'entity_id' |
|
| event_col_name | str | 'entity_id' |
|
| run_col_name | str | 'entity_id' |
|
| pathway_col_name | str or None | Column names forwarded to vidigi.analysis.event_durations. |
'pathway' |
Returns
| Name | Type | Description |
|---|---|---|
| plotly.graph_objects.Figure |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If kind, across or error_bars is not one of the supported values; if kind is "box"/"violin" and across != "runs"; if error_bars is set with kind != "bar"; if error_bars or show_runs=True is requested without across="runs"; if exclude_incomplete=False is combined with across="runs"; if a highlight_bands entry has neither lower nor upper set, or lower >= upper; or if what is not a valid per-replication statistic when across="runs". |
Notes
error_bars requires across="runs" by design: an interval computed over replication means attached to a bar height pooled over entities would be internally inconsistent, since entities within a run are correlated and runs are the independent unit - see vidigi.analysis.mean_confidence_interval’s Notes.
Unlike plot_metric_bar, there is no general plotly-kwargs passthrough on this function - style the returned figure directly with fig.update_layout(...).
See Also
plot_metric_bar : Deprecated - the kind="bar"-only predecessor to this function. plot_duration_distribution : A box/violin of raw per-entity durations for a single pair. vidigi.analysis.event_durations : The underlying per-entity durations. vidigi.analysis.replication_means : The underlying per-run statistics used by across="runs".
Examples
>>> event_pairs = [
... {"label": "Start to End", "first_event": "start", "second_event": "end"},
... ]
>>> plot_metric(
... trial.to_dataframe(), event_pairs, kind="box", across="runs"
... )
<plotly.graph_objs._figure.Figure>