plots.plot_metric_bar

plots.plot_metric_bar(
    event_log,
    event_pair_list,
    *,
    what='mean',
    exclude_incomplete=True,
    across='entities',
    error_bars=None,
    ci_level=0.95,
    show_runs=False,
    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',
    **kwargs,
)

Plot a bar chart of event duration statistics for a list of event pairs.

.. deprecated:: 2.0.0 plot_metric_bar() will be removed in vidigi 3.0. Use plot_metric(kind="bar", ...) instead - the same computation, built on plotly.graph_objects rather than plotly.express, plus kind="box"/ "violin" for a per-replication distribution and highlight_bands for threshold shading. **kwargs on this function is plotly-passthrough (title=, width=, …); plot_metric has no such passthrough - style the returned figure directly with fig.update_layout(...).

Thin wrapper over vidigi.analysis.event_durations, replication_means and mean_confidence_interval: this function only aggregates their output into one bar per pair and builds the figure.

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
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 every prior release), or the mean of a per-replication statistic computed separately for each run. error_bars and show_runs both 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. "ci" is a confidence interval at ci_level (see vidigi.analysis.mean_confidence_interval - requires the optional scipy dependency, pip install vidigi[stats]); "sd" is the sample standard deviation; "se" the standard error of the mean; "range" and "iqr" are asymmetric, spanning min-to-max and the 25th-to-75th percentile respectively. Requires across="runs". "ci"
ci_level float Confidence level used when error_bars="ci". 0.95
show_runs bool If True, overlays each replication’s individual value as a semi-transparent point on top of its bar. Requires across="runs". False
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. 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'
**kwargs dict Additional keyword arguments passed to plotly.express.bar - e.g. title=, width=. This is the one function in vidigi.plots where **kwargs is plotly passthrough rather than column-name passthrough, preserved unchanged from every prior release. {}

Returns

Name Type Description
plotly.graph_objects.Figure

Raises

Name Type Description
ValueError If across or error_bars is not one of the supported values; if error_bars or show_runs=True is requested without across="runs"; if exclude_incomplete=False is combined with across="runs"; 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.

See Also

plot_metric : The replacement for this function - same computation, go-based, plus kind="box"/"violin" and highlight_bands. plot_duration_distribution : The full distribution behind one of these bars. 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_bar(
...     trial.to_dataframe(), event_pairs, across="runs", error_bars="ci"
... )
<plotly.graph_objs._figure.Figure>
Back to top