plots.plot_replication_analysis

plots.plot_replication_analysis(
    event_log,
    first_event,
    second_event,
    *,
    what='mean',
    ci_level=0.95,
    deviation_threshold=0.05,
    show_deviation=True,
    match='first',
    marker_size=6,
    line_width=3,
    **col_kwargs,
)

Plot cumulative-mean precision against replication count.

Ensemble-averages vidigi.analysis.replication_precision’s running confidence interval into a chart: the cumulative mean and its CI band as replications accumulate, plus (optionally) the relative half-width (deviation) underneath - the diagnostic a modeller reads to decide “how many replications is enough” for one event-pair metric, the counterpart to plot_warm_up_diagnostic for “how much warm-up to discard.”

Parameters

Name Type Description Default
event_log pandas.DataFrame Long-format event log spanning one or more runs. required
first_event str The two events to pair - see vidigi.analysis.event_durations. required
second_event str The two events to pair - see vidigi.analysis.event_durations. required
what str The per-replication statistic to compute - see vidigi.analysis.replication_means. "mean"
ci_level float Confidence level for each cumulative interval. 0.95
deviation_threshold float Relative half-width threshold drawn as a dashed reference line on the deviation panel, and used to compute the recommended replication count annotated there - see vidigi.analysis.replication_precision’s stays_below_threshold. 0.05
show_deviation bool If True, draws the relative half-width (deviation) in a second panel stacked below the mean+CI panel, sharing the same x-axis. If False, only the mean+CI panel is drawn. True
match (first, last, occurrence) How repeated occurrences of the two events are paired. See vidigi.analysis.event_durations. "first"
marker_size float Marker size for the cumulative-mean and deviation traces. The default suits a handful of replications; at a few hundred, markers this size can overlap heavily enough to read as a solid, thickened line - pass a smaller value (e.g. 3) to keep individual points distinguishable. 6
line_width float Line width for the same two traces. 3
**col_kwargs dict Column-name keyword arguments forwarded to vidigi.analysis.event_durations, e.g. run_col_name=. {}

Returns

Name Type Description
plotly.graph_objects.Figure

Raises

Name Type Description
ValueError If no complete pairs are found in any run, or fewer than 2 replications have a complete pair.
ImportError If scipy is not installed - see vidigi.analysis.mean_confidence_interval.

Notes

Replications are read in run_number order - the same deterministic ordering vidigi.analysis.replication_precision requires - since a cumulative diagnostic only means “as replications accumulate” walked through in the order they were actually generated.

See Also

vidigi.analysis.replication_precision : The underlying per-k table. plot_warm_up_diagnostic : The companion diagnostic for choosing warm_up=.

Examples

>>> plot_replication_analysis(trial.to_dataframe(), "start", "end")
<plotly.graph_objs._figure.Figure>
Back to top