logging.TrialLogger

logging.TrialLogger(event_logs=None, *, scenario=None, label=None)

A container and analysis utility for managing multiple event logs from repeated simulation runs or trials.

The TrialLogger aggregates logs produced by EventLogger instances, indexes them by run ID, and provides utilities for retrieving logs, summarizing trial statistics, and computing event-to-event durations.

Methods include add_log(event_log) Add a new EventLogger log to the trial collection. get_log_by_run(run, as_df=False) Retrieve the log for a specific run. Can return raw records or as a DataFrame. to_dataframe() Return the full trial data as a pandas DataFrame. summary() Return a simple summary of the number of runs in the trial. get_event_durations(first_event, second_event, match=“first”, kwargs) Compute per-entity durations between two event types across every run. get_event_duration_stat(first_event, second_event, what=“mean”, exclude_incomplete=True, dp=2, label=None, kwargs) Compute statistics on durations between two event types across runs. plot_duration_distribution(first_event, second_event, kind=“hist”, kwargs) Plot the distribution of durations between two events, across every run. generate_dfg(output_format=“graphviz-object”, run_number=None, across_runs=False, kwargs) Build a process map: the representative run, one chosen run, or one combined cross-run map. reshape_for_animations(run_number=None, kwargs) Reshape one run into the per-snapshot frame the animation uses. animate_activity_log(event_position_df, scenario=None, run_number=None, kwargs) Build an animated visualisation of one run in the trial.

Parameters

Name Type Description Default
event_logs list[EventLogger] A list of vidigi EventLogger instances to initialize the trial log with. None
scenario object or dict The parameters object that produced these runs - a class, an instance, or a plain {name: count} dict. Same shape accepted by the animation and resource-utilisation helpers; when set, get_resource_utilisation, plot_resource_utilisation and plot_resource_utilisation_over_time use it automatically if no scenario= is passed to them. If omitted, it is inherited from the EventLoggers (a disagreement between runs warns). None
label str A human-readable name for this trial. Inherited from the EventLoggers if omitted. Surfaced in summary(). None

Methods

Name Description
add_log Add a new event log to the trial collection.
animate_activity_log Build an animated visualisation of one run in this trial.
compare_event_duration_stat Compare a duration statistic between this trial and another scenario.
compare_resource_utilisation Compare a resource utilisation metric between this trial and another scenario.
generate_dfg Generate a Directly-Follows Graph (process map) from the trial.
get_entity_metric_by_arrival Per-entity duration joined with each entity’s arrival time.
get_event_duration_ci Confidence interval for a duration statistic, computed across replications.
get_event_duration_stat Compute statistics on durations between two event types across runs.
get_event_durations Compute per-entity durations between two event types across every run.
get_event_occurrence_rate Proportion of runs in which an event occurs at least once.
get_log_by_run Retrieve the log for a specific run.
get_outlier_runs Flag replications whose duration statistic is a statistical outlier.
get_replication_precision Running confidence-interval precision as replications accumulate.
get_resource_utilisation Summarise resource use into busy time, mean-in-use and utilisation, per run.
plot_duration_distribution Plot the distribution of durations between two events, across every run.
plot_event_duration_comparison Plot a bar chart comparing a duration statistic between this trial and another.
plot_metric Plot event duration statistics for a list of event pairs, as a bar, box or violin.
plot_metric_bar Plot a bar chart of event duration statistics for a list of event pairs.
plot_metric_vs_arrival_time Plot a duration/metric against the arrival time of the entity it belongs to.
plot_outlier_runs Plot a horizontal beeswarm of per-replication values, flagging outliers.
plot_queue_size Plot the size of one or more queues over time across simulation runs.
plot_replication_analysis Plot cumulative-mean precision against replication count.
plot_resource_utilisation Plot a bar chart of resource utilisation, one bar per group, across runs.
plot_resource_utilisation_comparison Plot a bar chart comparing a resource utilisation metric between two trials.
plot_resource_utilisation_over_time Plot how many units of each resource step were in use over time, across runs.
plot_warm_up_diagnostic Plot a Welch (or cumulative-mean) diagnostic for choosing warm_up=.
read_pickle Load a TrialLogger previously written with to_pickle.
reshape_for_animations Reshape one run’s event log into the per-snapshot frame the animation uses.
summary Summarize the trial logs.
to_dataframe Return the full trial data as a single concatenated DataFrame.
to_pickle Pickle this TrialLogger to a file path or writable binary buffer.

add_log

logging.TrialLogger.add_log(event_log)

Add a new event log to the trial collection.

Parameters

Name Type Description Default
event_log EventLogger An EventLogger instance containing a log of events for a single run. required

animate_activity_log

logging.TrialLogger.animate_activity_log(
    event_position_df,
    *,
    scenario=None,
    run_number=None,
    **kwargs,
)

Build an animated visualisation of one run in this trial.

Thin wrapper over vidigi.animation.animate_activity_log, called on this trial directly. See that function for the full parameter list.

Parameters

Name Type Description Default
event_position_df pandas.DataFrame The layout: an x/y position per event. Build it with vidigi.utils.create_event_position_df / EventPosition. required
scenario object or dict The parameters object (or {name: count} dict) that produced the run, used to draw one icon per available resource unit. Falls back to the trial’s own scenario if not given. None
run_number int or str Which replication to animate. Required if the trial holds more than one run - passing a multi-run trial without it raises ValueError. None
**kwargs Additional keyword arguments forwarded to vidigi.animation.animate_activity_log (e.g. every_x_time_units, limit_duration, plotly_height, the appearance arguments). {}

Returns

Name Type Description
plotly.graph_objects.Figure

See Also

vidigi.animation.animate_activity_log : The underlying implementation. reshape_for_animations : The first step, if you want to run the pipeline yourself.

compare_event_duration_stat

logging.TrialLogger.compare_event_duration_stat(
    other,
    first_event,
    second_event,
    *,
    what='mean',
    ci_level=0.95,
    match='first',
    warm_up=0,
    label_a=None,
    label_b=None,
    **kwargs,
)

Compare a duration statistic between this trial and another scenario.

Thin wrapper over vidigi.analysis.compare_replication_values, computing each trial’s per-replication values via get_event_durations + replication_means, then comparing them - a two-independent-sample confidence-interval-overlap check plus a Welch’s t-test, the “scenario comparison highlighter” for event-duration metrics.

Parameters

Name Type Description Default
other TrialLogger The trial to compare against. 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 side’s interval and the significance test. 0.95
match (first, last, occurrence) How repeated occurrences of the two events are paired. "first"
warm_up float Pairings whose first_time is before warm_up are excluded. 0
label_a str Names for each scenario. Default to this trial’s and other’s .label, falling back to "A"/"B" if neither has one. None
label_b str Names for each scenario. Default to this trial’s and other’s .label, falling back to "A"/"B" if neither has one. None
**kwargs dict Additional keyword arguments passed to the chosen statistic, e.g. q=0.9 for what="quantile". {}

Returns

Name Type Description
vidigi.analysis.ScenarioComparison

Raises

Name Type Description
TypeError If other is not a TrialLogger.
ValueError If no complete pairs are found in any run of either trial.
ImportError If scipy is not installed.

See Also

vidigi.analysis.compare_replication_values : The underlying implementation. plot_event_duration_comparison : Plots this comparison. compare_resource_utilisation : The resource-utilisation analogue.

compare_resource_utilisation

logging.TrialLogger.compare_resource_utilisation(
    other,
    *,
    metric='utilisation',
    ci_level=0.95,
    label_a=None,
    label_b=None,
    **kwargs,
)

Compare a resource utilisation metric between this trial and another scenario.

Thin wrapper over vidigi.analysis.compare_replication_values, computing each trial’s per-run metric via get_resource_utilisation(by="run"), then comparing them - the resource-utilisation analogue of compare_event_duration_stat. Always pools every step/resource together into one blended per-run figure (by="run", see vidigi.analysis.resource_utilisation); to compare one specific step or resource instead, call get_resource_utilisation(by=...) on each trial and pass the metric column straight into vidigi.analysis.compare_replication_values.

Parameters

Name Type Description Default
other TrialLogger The trial to compare against. required
metric (utilisation, busy_time, mean_in_use) Which vidigi.analysis.resource_utilisation column to compare. "utilisation"
ci_level float Confidence level for each side’s interval and the significance test. 0.95
label_a str Names for each scenario. Default to this trial’s and other’s .label, falling back to "A"/"B" if neither has one. None
label_b str Names for each scenario. Default to this trial’s and other’s .label, falling back to "A"/"B" if neither has one. None
**kwargs dict Additional keyword arguments forwarded to get_resource_utilisation on both trials (e.g. scenario=, warm_up=). {}

Returns

Name Type Description
vidigi.analysis.ScenarioComparison

Raises

Name Type Description
TypeError If other is not a TrialLogger.
ValueError If metric is not a resource-utilisation column.
ImportError If scipy is not installed.

See Also

vidigi.analysis.compare_replication_values : The underlying implementation. compare_event_duration_stat : The event-duration analogue.

generate_dfg

logging.TrialLogger.generate_dfg(
    output_format='graphviz-object',
    *,
    run_number=None,
    across_runs=False,
    input_time_format='minutes',
    warm_up=None,
    occupancy_metrics=False,
    occupancy_snapshot_interval=1,
    **kwargs,
)

Generate a Directly-Follows Graph (process map) from the trial.

Wraps :func:vidigi.process_mapping.discover_dfg and the DFG renderers, the same way :meth:EventLogger.generate_dfg does, with three ways to handle the several replications a trial holds:

===================== ================================================= Call What you get ===================== ================================================= (default) The representative run - the replication whose mean time in system is closest to the trial median. Real integer counts. run_number=N That one replication. across_runs=True One combined cross-run map: transitions grouped per (run, entity) so no cross-run edge is fabricated, node/edge counts shown as per-run means with the between-run range, transition times pooled over every run. ===================== =================================================

Parameters

Name Type Description Default
output_format DFGType As :meth:EventLogger.generate_dfg. "graphviz-object"
run_number int or str Render this one replication. Mutually exclusive with across_runs=True. None
across_runs bool Render one combined map across every replication (see above). False
input_time_format str Time unit for durations and timestamps. "minutes"
warm_up float Discard events at or before this simulation time. With across_runs=True a missing warm_up warns, because start-up transient then feeds a stakeholder-facing aggregate. None
occupancy_metrics bool Annotate queue/resource nodes with occupancy, via :func:vidigi.analysis.activity_occupancy_stats. With across_runs=True the figures are averaged over runs (across_runs="average") - note this averages over the runs in which a step occurred, whereas the node counts zero-fill, so the two conventions differ for a step absent from some runs. False
occupancy_snapshot_interval float Snapshot granularity for occupancy_metrics. 1
**kwargs Forwarded to the renderer. An auto title (graphviz) or caption (cytoscape) is set unless you pass your own. {}

Returns

Name Type Description
graphviz.Source or ipycytoscape widget or bytes

Raises

Name Type Description
ValueError If both run_number and across_runs=True are given, or run_number is not a run in this trial.

Notes

For across_runs=True:

  • Counts are per replication (pooled total / number of runs); the n=3.5 (1-7) annotation gives the between-run range. An edge seen fewer than min_frequency times per run on average is hidden by the cytoscape renderers’ min_frequency=1 default.
  • Transition probability is pooled (frequency-weighted across runs); with near-exchangeable replications the Simpson’s-paradox risk of pooling is negligible.
  • Entities still in the system at a run’s end have truncated paths, which under-weights long-pathway transitions and biases transition times downwards - the opposite of what a bottleneck analysis wants. Set warm_up and be wary of a heavily censored run.

See Also

EventLogger.generate_dfg : The single-run version. vidigi.process_mapping.discover_dfg : Edge discovery logic. get_event_duration_ci : A formal confidence interval on a transition time, rather than the between-run range shown here.

get_entity_metric_by_arrival

logging.TrialLogger.get_entity_metric_by_arrival(
    first_event,
    second_event,
    *,
    arrival_event='arrival',
    match='first',
    **kwargs,
)

Per-entity duration joined with each entity’s arrival time.

Thin wrapper over vidigi.analysis.entity_metric_by_arrival, called on this trial’s combined dataframe.

Parameters

Name Type Description Default
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
arrival_event str The event marking an entity’s arrival. "arrival"
match (first, last, occurrence) How repeated occurrences of the two events are paired. Does not affect the arrival-time lookup. "first"
**kwargs dict Additional keyword arguments forwarded to vidigi.analysis.entity_metric_by_arrival (e.g. run_col_name). {}

Returns

Name Type Description
pandas.DataFrame

See Also

vidigi.analysis.entity_metric_by_arrival : The underlying implementation. plot_metric_vs_arrival_time : The matching chart.

get_event_duration_ci

logging.TrialLogger.get_event_duration_ci(
    first_event,
    second_event,
    *,
    what='mean',
    ci_level=0.95,
    match='first',
    warm_up=0,
    **kwargs,
)

Confidence interval for a duration statistic, computed across replications.

The headline “what is this number, and how sure are we” summary for a trial: the chosen statistic is computed separately within each run (vidigi.analysis.replication_means), then a Student’s t confidence interval is taken over those per-replication values (vidigi.analysis.mean_confidence_interval). Replications are the independent unit - see that function’s Notes for why an interval must never be computed over pooled per-entity durations.

Unlike get_replication_precision, which reports how the interval tightens as replications accumulate, this returns the single interval from every replication in the trial.

Parameters

Name Type Description Default
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 the interval is about: one of "mean", "median", "max", "min", "quantile", "std", "var", "sum". Entity-counting aggregations ("count", "summary", …) are rejected - see vidigi.analysis.replication_means. "mean"
ci_level float Confidence level, e.g. 0.95 for a 95% interval. 0.95
match (first, last, occurrence) How repeated occurrences of the two events are paired. "first"
warm_up float Pairings whose first_time is before warm_up are excluded before the per-replication statistic is computed. See vidigi.analysis.event_durations’s same parameter. 0
**kwargs dict Additional keyword arguments passed to the chosen statistic, e.g. q=0.9 for what="quantile". {}

Returns

Name Type Description
vidigi.analysis.ConfidenceInterval Named tuple (mean, half_width, lower, upper, n, method). With fewer than two replications that have a complete pairing, half_width/lower/upper are NaN and a warning is raised.

Raises

Name Type Description
ValueError If no complete pairs are found in any run, or what is not a per-replication statistic.
ImportError If scipy is not installed - see vidigi.analysis.mean_confidence_interval.

See Also

get_event_duration_stat : The point estimate, with across="runs" for the same per-replication mean. get_replication_precision : How this interval tightens as replications accumulate. vidigi.analysis.mean_confidence_interval : The underlying implementation.

get_event_duration_stat

logging.TrialLogger.get_event_duration_stat(
    first_event,
    second_event,
    what='mean',
    exclude_incomplete=True,
    dp=2,
    label=None,
    match='first',
    warm_up=0,
    across='entities',
    **kwargs,
)

Compute statistics on durations between two event types across runs.

Parameters

Name Type Description Default
first_event str Name of the first event (start). required
second_event str Name of the second event (end). required
what str Statistic to compute. Options include: - Standard aggregations: {“mean”, “median”, “max”, “min”, “quantile”, “std”, “var”, “sum”} - Special aggregations: {“count”, “unserved_count”, “served_count”, “unserved_rate”, “served_rate”, “summary”} "mean"
exclude_incomplete bool If True, ignore cases where the second event is missing (NaN). True
dp int Number of decimal places to round numeric results to. 2
label str If provided, return the result as a dictionary with keys {“stat”: label, “value”: result}. None
match (first, last, occurrence) How repeated occurrences of the two events for the same entity are paired, for entities that revisit a step. See vidigi.analysis.event_durations for the full explanation. The default matches the behaviour of every prior release, where an entity visiting either event more than once was unsupported. "first"
warm_up float Pairings whose first_time is before warm_up are excluded before the statistic is computed. See vidigi.analysis.event_durations’s same parameter. n_runs (used by "unserved_rate"/"served_rate"/"summary") is unaffected - it always counts every run in the trial. 0
across (entities, runs) Whether the statistic is pooled over every entity’s duration with run boundaries ignored (the default, matching every prior release), or computed separately within each run and then averaged across runs - the mean of vidigi.analysis.replication_means’s per-run values. across="runs" weights every replication equally rather than by its entity count, and is the figure a confidence interval (get_event_duration_ci) is about; it accepts only a genuine per-replication what ("mean", "median", "max", "min", "quantile", "std", "var", "sum"), and requires exclude_incomplete=True. "entities"
**kwargs dict Additional arguments passed to the pandas Series method corresponding to what (e.g., quantile(q=0.9)). {}

Returns

Name Type Description
float or dict The computed statistic, rounded to dp if numeric. If what="summary", returns a dictionary with multiple statistics. If label is provided, wraps the result in a dict with the label.

Raises

Name Type Description
ValueError If what is not a supported aggregation function; if across is not "entities" or "runs"; if across="runs" is combined with exclude_incomplete=False, an entity-counting what, or a trial with no complete pairs in any run.

See Also

get_event_durations : The per-entity durations this method summarises. get_event_duration_ci : A confidence interval around the across="runs" mean. get_replication_precision : How that interval tightens as replications accumulate.

get_event_durations

logging.TrialLogger.get_event_durations(
    first_event,
    second_event,
    *,
    match='first',
    warm_up=0,
    **kwargs,
)

Compute per-entity durations between two event types across every run.

Thin wrapper over vidigi.analysis.event_durations, called on the trial’s combined dataframe. See that function for the full parameter list, the meaning of match, and how incomplete pairs are handled.

Parameters

Name Type Description Default
first_event str Name of the first event. required
second_event str Name of the second event. required
match (first, last, occurrence) How repeated occurrences of the two events for the same entity are paired. See vidigi.analysis.event_durations. "first"
warm_up float Pairings whose first_time is before warm_up are excluded. See vidigi.analysis.event_durations’s same parameter. 0
**kwargs dict Additional keyword arguments forwarded to vidigi.analysis.event_durations (e.g. entity_col_name, keep_incomplete). {}

Returns

Name Type Description
pandas.DataFrame One row per matched pair, with columns entity_id, run_number, pathway, occurrence, first_time, second_time, duration.

See Also

vidigi.analysis.event_durations : Full parameter list and pairing semantics.

get_event_occurrence_rate

logging.TrialLogger.get_event_occurrence_rate(
    event_name,
    *,
    ci_level=0.95,
    event_col_name='event',
)

Proportion of runs in which an event occurs at least once.

Thin wrapper over vidigi.analysis.event_occurrence_rate, called on this trial’s combined dataframe, with n_runs always set to the true number of runs in the trial (len(self._event_logs)) - not inferred from which runs happened to log the event, so a run where the event never occurred is still correctly counted in the denominator.

Parameters

Name Type Description Default
event_name str The event to check for. Occurring for any entity, one or more times, counts a run as an occurrence. required
ci_level float Confidence level for the interval. 0.95
event_col_name str Column holding the event name. "event"

Returns

Name Type Description
vidigi.analysis.ProportionEstimate Named tuple (proportion, lower, upper, n_runs, n_occurred, ci_level, method) - see vidigi.analysis.event_occurrence_rate.

Raises

Name Type Description
ValueError If event_name is not present in the trial’s log.
ImportError If scipy is not installed - see vidigi.analysis.mean_confidence_interval.

See Also

vidigi.analysis.event_occurrence_rate : The underlying implementation. get_event_duration_stat : Entity-level "unserved_rate"/"served_rate" within one event pair.

get_log_by_run

logging.TrialLogger.get_log_by_run(run, as_df=False)

Retrieve the log for a specific run.

Parameters

Name Type Description Default
run int or str The run identifier to fetch. required
as_df bool If True, return the log as a pandas DataFrame. Otherwise, return the raw event records (list of dicts). False

Returns

Name Type Description
list of dict or pandas.DataFrame The requested run log, either as raw records or a DataFrame.

get_outlier_runs

logging.TrialLogger.get_outlier_runs(
    first_event,
    second_event,
    *,
    what='mean',
    match='first',
    warm_up=0,
    iqr_multiplier=1.5,
    **kwargs,
)

Flag replications whose duration statistic is a statistical outlier.

Thin wrapper over vidigi.analysis.event_durations, replication_means and vidigi.analysis.flag_outlier_runs, called on this trial’s combined dataframe.

Parameters

Name Type Description Default
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"
match (first, last, occurrence) How repeated occurrences of the two events are paired. "first"
warm_up float Pairings whose first_time is before warm_up are excluded. See vidigi.analysis.event_durations’s same parameter. 0
iqr_multiplier float Fence width in IQRs. See vidigi.analysis.flag_outlier_runs. 1.5
**kwargs dict Additional keyword arguments passed to the chosen statistic, e.g. q=0.9 for what="quantile". {}

Returns

Name Type Description
pandas.DataFrame One row per run, with value, lower_fence, upper_fence and is_outlier columns - see vidigi.analysis.flag_outlier_runs.

Raises

Name Type Description
ValueError If no complete pairs are found in any run, or iqr_multiplier is negative.

See Also

vidigi.analysis.flag_outlier_runs : The underlying implementation. get_replication_precision : A different per-replication diagnostic (precision, not outliers).

get_replication_precision

logging.TrialLogger.get_replication_precision(
    first_event,
    second_event,
    *,
    what='mean',
    ci_level=0.95,
    deviation_threshold=0.05,
    match='first',
    **kwargs,
)

Running confidence-interval precision as replications accumulate.

Thin wrapper over vidigi.analysis.event_durations, replication_means and vidigi.analysis.replication_precision, called on this trial’s combined dataframe.

Parameters

Name Type Description Default
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 used for stays_below_threshold - see vidigi.analysis.replication_precision. 0.05
match (first, last, occurrence) How repeated occurrences of the two events are paired. "first"
**kwargs dict Additional keyword arguments forwarded to vidigi.analysis.event_durations (e.g. run_col_name). {}

Returns

Name Type Description
pandas.DataFrame One row per replication count k - see vidigi.analysis.replication_precision.

Raises

Name Type Description
ValueError If no complete pairs are found in any run.
ImportError If scipy is not installed - see vidigi.analysis.mean_confidence_interval.

See Also

vidigi.analysis.replication_precision : The underlying implementation. plot_replication_analysis : Plots this table.

get_resource_utilisation

logging.TrialLogger.get_resource_utilisation(
    by='step',
    scenario=None,
    resource_map=None,
    event_position_df=None,
    resource_capacities=None,
    capacity=None,
    warm_up=0,
    limit_duration=None,
    unclosed='censor',
    resource_col_name=None,
    **kwargs,
)

Summarise resource use into busy time, mean-in-use and utilisation, per run.

Thin wrapper over vidigi.analysis.resource_utilisation, called on the trial’s combined dataframe. See that function for the full parameter list, the four capacity-resolution routes, and how an unclosed resource use is handled.

Parameters

Name Type Description Default
by (step, resource, run) What each row summarises. See vidigi.analysis.resource_utilisation. "step"
scenario Capacity resolution - see vidigi.analysis._resolve_resource_capacities for the four routes. All optional; with none given, utilisation is NaN throughout and only busy_time/mean_in_use are meaningful. scenario defaults to the one attached to this TrialLogger (if any) when not passed here. None
resource_map Capacity resolution - see vidigi.analysis._resolve_resource_capacities for the four routes. All optional; with none given, utilisation is NaN throughout and only busy_time/mean_in_use are meaningful. scenario defaults to the one attached to this TrialLogger (if any) when not passed here. None
event_position_df Capacity resolution - see vidigi.analysis._resolve_resource_capacities for the four routes. All optional; with none given, utilisation is NaN throughout and only busy_time/mean_in_use are meaningful. scenario defaults to the one attached to this TrialLogger (if any) when not passed here. None
resource_capacities Capacity resolution - see vidigi.analysis._resolve_resource_capacities for the four routes. All optional; with none given, utilisation is NaN throughout and only busy_time/mean_in_use are meaningful. scenario defaults to the one attached to this TrialLogger (if any) when not passed here. None
capacity Capacity resolution - see vidigi.analysis._resolve_resource_capacities for the four routes. All optional; with none given, utilisation is NaN throughout and only busy_time/mean_in_use are meaningful. scenario defaults to the one attached to this TrialLogger (if any) when not passed here. None
warm_up float Start of the analysis window. 0
limit_duration float End of the analysis window. None (default) uses the latest time seen anywhere in the trial. None
unclosed (censor, drop) How an entity still holding a resource at the end of the window is handled. See vidigi.analysis.resource_use_intervals. "censor"
resource_col_name str Which column identifies the physical resource for by="resource". None (the default) uses "unique_resource_id" if that column is present on this trial’s log, else "resource_id" - so a model built with VidigiStore(..., label=...) and logging unique_resource_id alongside resource_id (see vidigi.resources.VidigiStore) gets a collision-proof breakdown with no extra argument here. Pass an explicit column name to override. None
**kwargs dict Additional keyword arguments forwarded to vidigi.analysis.resource_utilisation (e.g. entity_col_name, time_col_name, run_col_name). {}

Returns

Name Type Description
pandas.DataFrame One row per run per group - see vidigi.analysis.resource_utilisation.

See Also

vidigi.analysis.resource_utilisation : The underlying implementation. vidigi.analysis.resource_use_intervals : The underlying per-bout intervals.

plot_duration_distribution

logging.TrialLogger.plot_duration_distribution(
    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, across every run.

Thin wrapper over vidigi.plots.plot_duration_distribution, called on this trial’s combined dataframe. See that function for the full parameter list.

Parameters

Name Type Description Default
first_event str The two events to measure the duration between. required
second_event str The two events to measure the duration between. required
kind (hist, box, violin, ecdf, ridgeline, heatmap) Chart type. "ridgeline" and "heatmap" require split_by to be set - see vidigi.plots.plot_duration_distribution for the full explanation of each. "hist"
split_by (run, pathway) If given, one trace (or, for "heatmap", one row) per distinct value of that column. "run"
bins int, sequence, or None Passed to numpy.histogram when kind is "hist", "ridgeline" or "heatmap". None
match (first, last, occurrence) How repeated occurrences of the two events are paired. "first"
normalise bool For kind="hist" or kind="heatmap": heights/cells as a probability density rather than raw counts. "ridgeline" always uses density, regardless of this argument. False
highlight_bands list of dict Shaded threshold zones drawn behind the chart, valid only for kind="box" or kind="violin" - see vidigi.plots.plot_duration_distribution for the dict shape. None
title str Figure title. None
**kwargs dict Additional keyword arguments forwarded to vidigi.analysis.event_durations (e.g. warm_up, entity_col_name). {}

Returns

Name Type Description
plotly.graph_objects.Figure

See Also

vidigi.plots.plot_duration_distribution : The underlying implementation. vidigi.analysis.event_durations : The underlying per-entity durations.

plot_event_duration_comparison

logging.TrialLogger.plot_event_duration_comparison(
    other,
    first_event,
    second_event,
    **kwargs,
)

Plot a bar chart comparing a duration statistic between this trial and another.

Thin wrapper over vidigi.plots.plot_scenario_comparison, called on this trial’s and other’s combined dataframes. See that function for the full parameter list.

Parameters

Name Type Description Default
other TrialLogger The trial to compare against. 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
**kwargs dict Additional keyword arguments forwarded to vidigi.plots.plot_scenario_comparison (e.g. what=, ci_level=, label_a=, label_b=, highlight_bands=). {}

Returns

Name Type Description
plotly.graph_objects.Figure

Raises

Name Type Description
TypeError If other is not a TrialLogger.

See Also

vidigi.plots.plot_scenario_comparison : The underlying implementation. compare_event_duration_stat : The underlying numbers.

plot_metric

logging.TrialLogger.plot_metric(
    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,
    **kwargs,
)

Plot event duration statistics for a list of event pairs, as a bar, box or violin.

Thin wrapper over vidigi.plots.plot_metric, called on this trial’s combined dataframe. See that function for the full parameter list. The kind="bar" replacement for the deprecated plot_metric_bar.

Parameters

Name Type Description Default
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. "box"/"violin" draw the full per-replication distribution for each pair instead of a bar, and require across="runs". "bar"
what str The statistic to compute on event durations. See vidigi.analysis.event_durations’s module for the full set. When across="runs", only a genuine per-replication statistic is accepted - see vidigi.analysis.replication_means. "mean"
exclude_incomplete bool If True, incomplete event durations (where the second event is missing) are excluded from the calculation. Must be True when across="runs". True
across (entities, runs) Whether each bar/box/violin is a statistic pooled over every entity, or built from a per-replication statistic computed separately for each run. error_bars, show_runs and kind="box"/"violin" all require across="runs". "entities"
error_bars (ci, sd, se, range, iqr) The spread drawn as an error bar around each bar. Only valid with kind="bar". "ci" requires the optional scipy dependency (pip install vidigi[stats]). See vidigi.plots.plot_metric_bar for the full explanation of each. "ci"
ci_level float Confidence level used when error_bars="ci". 0.95
show_runs bool If True, overlays each replication’s individual value - a semi-transparent point for kind="bar", the trace’s own points (boxpoints="all"/points="all") for kind="box"/"violin". False
highlight_bands list of dict Shaded threshold zones drawn behind the chart - see vidigi.plots.plot_duration_distribution for the dict shape. 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
**kwargs dict Additional keyword arguments forwarded to vidigi.analysis.event_durations (e.g. entity_col_name, run_col_name). {}

Returns

Name Type Description
plotly.graph_objects.Figure

See Also

plot_metric_bar : Deprecated - the kind="bar"-only predecessor to this method. plot_duration_distribution : A box/violin of raw per-entity durations for a single pair. vidigi.plots.plot_metric : The underlying implementation.

Examples

>>> event_pairs = [
...     {"label": "Start to End", "first_event": "start", "second_event": "end"},
... ]
>>> fig = obj.plot_metric(event_pairs, kind="box", across="runs")
>>> fig.show()

plot_metric_bar

logging.TrialLogger.plot_metric_bar(
    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,
    interactive=True,
    **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(event_pair_list, kind="bar", ...) instead - see vidigi.plots.plot_metric for why.

Thin wrapper over vidigi.plots.plot_metric_bar, called on this trial’s combined dataframe. See that function for the full parameter list.

Parameters

Name Type Description Default
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 on event durations. See vidigi.analysis.event_durations’s module for the full set. When across="runs", only a genuine per-replication statistic is accepted - see vidigi.analysis.replication_means. "mean"
exclude_incomplete bool If True, incomplete event durations (where the second event is missing) are excluded from the calculation. Must be True when across="runs". 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". "entities"
error_bars (ci, sd, se, range, iqr) The spread drawn as an error bar around each bar. "ci" requires the optional scipy dependency (pip install vidigi[stats]). See vidigi.plots.plot_metric_bar for the full explanation of each. "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. 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
interactive bool If True, returns an interactive Plotly bar chart. If False, static plotting is not currently supported (a message will be printed). True
**kwargs dict Additional keyword arguments passed to plotly.express.bar (e.g. title=, width=). {}

Returns

Name Type Description
plotly.graph_objs._figure.Figure or None An interactive Plotly bar chart if interactive=True. Otherwise, prints a message and returns None.

See Also

plot_duration_distribution : The full distribution behind one of these bars. vidigi.plots.plot_metric_bar : The underlying implementation.

Examples

>>> event_pairs = [
...     {"label": "Start to End", "first_event": "start", "second_event": "end"},
...     {"label": "Check to Approve", "first_event": "check", "second_event": "approve"},
... ]
>>> fig = obj.plot_metric_bar(event_pairs, what="mean")
>>> fig.show()

plot_metric_vs_arrival_time

logging.TrialLogger.plot_metric_vs_arrival_time(
    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,
    **kwargs,
)

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

Thin wrapper over vidigi.plots.plot_metric_vs_arrival_time, called on this trial’s combined dataframe. See that function for the full parameter list.

Parameters

Name Type Description Default
first_event str The two events to measure the duration between. required
second_event str The two events to measure the duration between. required
arrival_event str The event marking an entity’s arrival - drawn on the x-axis. "arrival"
colour_by (run, pathway) If given, draws one trace per distinct value of the corresponding column instead of a single pooled trace. "run"
rolling_window int Half-width, in points, of a count-based moving average. Mutually exclusive with rolling_time. None
rolling_time float Half-width, in time units, of a time-window moving average. Mutually exclusive with rolling_window. None
warm_up float Points whose arrival_time is before warm_up are excluded. 0
match (first, last, occurrence) How repeated occurrences of the two events are paired. "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 vidigi.plots.plot_duration_distribution for the dict shape. None
title str Figure title. None
**kwargs dict Additional keyword arguments forwarded to vidigi.plots.plot_metric_vs_arrival_time (e.g. run_col_name). {}

Returns

Name Type Description
plotly.graph_objects.Figure

See Also

vidigi.plots.plot_metric_vs_arrival_time : The underlying implementation. get_entity_metric_by_arrival : The underlying per-entity table.

plot_outlier_runs

logging.TrialLogger.plot_outlier_runs(first_event, second_event, **kwargs)

Plot a horizontal beeswarm of per-replication values, flagging outliers.

Thin wrapper over vidigi.plots.plot_outlier_runs, called on this trial’s combined dataframe. See that function for the full parameter list.

Parameters

Name Type Description Default
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
**kwargs dict Additional keyword arguments forwarded to vidigi.plots.plot_outlier_runs (e.g. what=, iqr_multiplier=, marker_size=, spacing=). {}

Returns

Name Type Description
plotly.graph_objects.Figure

Raises

Name Type Description
ValueError If no complete pairs are found in any run, or iqr_multiplier is negative.

See Also

vidigi.plots.plot_outlier_runs : The underlying implementation. get_outlier_runs : The underlying per-run table.

plot_queue_size

logging.TrialLogger.plot_queue_size(
    event_list,
    limit_duration,
    every_x_time_units=1,
    interactive=True,
    show_all_runs=True,
    shared_y_axis=True,
    highlight_bands=None,
    warm_up=0,
    backend='express',
    **kwargs,
)

Plot the size of one or more queues over time across simulation runs.

Thin wrapper over vidigi.plots.plot_queue_size, called on this trial’s combined dataframe.

Parameters

Name Type Description Default
event_list list of str List of event types (e.g., "queue_enter", "queue_exit") to include in the plot. required
limit_duration int or float Maximum simulation duration (time units) to include in the plot. required
every_x_time_units int Time granularity for snapshots. Larger values aggregate queue size over coarser time intervals. 1
interactive bool If True, generates an interactive Plotly figure. Static plotting is not currently implemented. True
show_all_runs bool If True, plots all runs with semi-transparent lines and overlays the mean trajectory. If False, only the mean trajectory is plotted. True
highlight_bands list of dict Shaded threshold zones drawn behind the chart - see vidigi.plots.plot_duration_distribution for the dict shape. None
warm_up int Time at which the plotted window begins. Snapshots run from warm_up to limit_duration. See vidigi.prep.reshape_for_animations for why this - and not filtering the log by time - is the correct way to discard a warm-up period. The default of 0 is a no-op. 0
backend (express, go) Which plotly API builds the figure. See vidigi.plots.plot_queue_size for the full explanation - in short, "go" gives every trace a deterministic name and order instead of px’s automatic grouping, which some callers find easier to target when restyling the figure afterwards. **kwargs is ignored when backend="go". "express"
**kwargs Additional keyword arguments passed to plotly.express.line. Ignored (with a warning) when backend="go". {}

Returns

Name Type Description
fig plotly.graph_objects.Figure Interactive Plotly figure containing the queue size plot.

Notes

  • When multiple event types are specified, they are faceted in separate panels if show_all_runs=False.
  • Queue lengths are not capped at step_snapshot_max, unlike the animation functions, so long queues are plotted at their full length rather than flattening off. Reshaping without that cap uses more memory than an equivalent animation would.
  • Snapshots at which an event has nobody queuing are plotted as zero rather than omitted, so a queue that empties is drawn dropping to the axis and the mean is taken across every run. An event in event_list that occurs in no run is plotted as zero throughout, with a warning.
  • If interactive=False, no plot is returned and a message is printed instead.

See Also

vidigi.plots.plot_queue_size : The underlying implementation. vidigi.analysis.queue_size_over_time : The underlying per-run, per-snapshot counts.

Examples

>>> sim.plot_queue_size(
...     event_list=["queue_enter", "queue_exit"],
...     limit_duration=500,
...     every_x_time_units=5,
...     show_all_runs=True
... )
<plotly.graph_objs._figure.Figure>

plot_replication_analysis

logging.TrialLogger.plot_replication_analysis(
    first_event,
    second_event,
    *,
    what='mean',
    ci_level=0.95,
    deviation_threshold=0.05,
    show_deviation=True,
    match='first',
    **kwargs,
)

Plot cumulative-mean precision against replication count.

Thin wrapper over vidigi.plots.plot_replication_analysis, called on this trial’s combined dataframe. See that function for the full parameter list.

Parameters

Name Type Description Default
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. "mean"
ci_level float Confidence level for each cumulative interval. 0.95
deviation_threshold float Relative half-width threshold - drawn as a reference line and used for the recommended-replication-count annotation. 0.05
show_deviation bool If True, draws the relative half-width in a second panel below the mean+CI panel. True
match (first, last, occurrence) How repeated occurrences of the two events are paired. "first"
**kwargs dict Additional keyword arguments forwarded to vidigi.plots.plot_replication_analysis (e.g. run_col_name). {}

Returns

Name Type Description
plotly.graph_objects.Figure

See Also

vidigi.plots.plot_replication_analysis : The underlying implementation. get_replication_precision : The underlying per-k table.

plot_resource_utilisation

logging.TrialLogger.plot_resource_utilisation(
    by='step',
    metric='utilisation',
    kind='bar',
    error_bars='ci',
    ci_level=0.95,
    show_runs=True,
    highlight_bands=None,
    sort_by=None,
    scenario=None,
    resource_map=None,
    event_position_df=None,
    resource_capacities=None,
    capacity=None,
    warm_up=0,
    limit_duration=None,
    unclosed='censor',
    resource_col_name=None,
    **kwargs,
)

Plot a bar chart of resource utilisation, one bar per group, across runs.

Thin wrapper over vidigi.plots.plot_resource_utilisation, called on this trial’s combined dataframe. See that function for the full parameter list.

Parameters

Name Type Description Default
by (step, resource, run) What each bar summarises. See vidigi.analysis.resource_utilisation. "step"
metric (busy_time, mean_in_use, utilisation) Which quantity is the bar height. Falls back to "mean_in_use", with a warning, if no capacity was resolved for any group. "busy_time"
kind (bar, box, violin) Chart type. "box"/"violin" draw the full per-run distribution for each group instead of a bar - error_bars is not valid with either. "bar"
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". "ci" requires the optional scipy dependency (pip install vidigi[stats]). "ci"
ci_level float Confidence level used when error_bars="ci". 0.95
show_runs bool If True, overlays each run’s individual value - a semi-transparent point for kind="bar", the trace’s own points (boxpoints="all"/points="all") for kind="box"/"violin". True
highlight_bands list of dict Shaded threshold zones drawn behind the chart - see vidigi.plots.plot_duration_distribution for the dict shape. None
sort_by value If "value", bars are ordered by descending metric value. "value"
scenario Capacity resolution - see vidigi.analysis._resolve_resource_capacities for the four routes. Unused when by="resource". scenario defaults to the one attached to this TrialLogger (if any) when not passed here. None
resource_map Capacity resolution - see vidigi.analysis._resolve_resource_capacities for the four routes. Unused when by="resource". scenario defaults to the one attached to this TrialLogger (if any) when not passed here. None
event_position_df Capacity resolution - see vidigi.analysis._resolve_resource_capacities for the four routes. Unused when by="resource". scenario defaults to the one attached to this TrialLogger (if any) when not passed here. None
resource_capacities Capacity resolution - see vidigi.analysis._resolve_resource_capacities for the four routes. Unused when by="resource". scenario defaults to the one attached to this TrialLogger (if any) when not passed here. None
capacity Capacity resolution - see vidigi.analysis._resolve_resource_capacities for the four routes. Unused when by="resource". scenario defaults to the one attached to this TrialLogger (if any) when not passed here. None
warm_up float Start of the analysis window. 0
limit_duration float End of the analysis window. None (default) uses the latest time seen anywhere in the trial. None
unclosed (censor, drop) How an entity still holding a resource at the end of the window is handled. See vidigi.analysis.resource_use_intervals. "censor"
resource_col_name str Which column identifies the physical resource for by="resource". None (the default) uses "unique_resource_id" if that column is present on this trial’s log, else "resource_id" - so a model built with VidigiStore(..., label=...) and logging unique_resource_id alongside resource_id (see vidigi.resources.VidigiStore) gets a collision-proof breakdown with no extra argument here. Pass an explicit column name to override. None
**kwargs dict Additional keyword arguments forwarded to vidigi.plots.plot_resource_utilisation (e.g. entity_col_name, time_col_name, run_col_name). {}

Returns

Name Type Description
plotly.graph_objects.Figure

See Also

vidigi.plots.plot_resource_utilisation : The underlying implementation. get_resource_utilisation : The underlying per-run, per-group summary.

plot_resource_utilisation_comparison

logging.TrialLogger.plot_resource_utilisation_comparison(
    other,
    *,
    metric='utilisation',
    ci_level=0.95,
    label_a=None,
    label_b=None,
    scenario_a=None,
    scenario_b=None,
    highlight_bands=None,
    **kwargs,
)

Plot a bar chart comparing a resource utilisation metric between two trials.

Thin wrapper over vidigi.plots.plot_resource_utilisation_comparison, called on this trial’s and other’s combined dataframes - the plot counterpart to compare_resource_utilisation, as plot_event_duration_comparison is to compare_event_duration_stat.

Parameters

Name Type Description Default
other TrialLogger The trial to compare against. required
metric (utilisation, busy_time, mean_in_use) Which vidigi.analysis.resource_utilisation column to compare. "utilisation"
ci_level float Confidence level for each side’s interval and the significance test. 0.95
label_a str Names for each scenario. Default to this trial’s and other’s .label, falling back to "A"/"B" if neither has one. None
label_b str Names for each scenario. Default to this trial’s and other’s .label, falling back to "A"/"B" if neither has one. None
scenario_a object or dict Capacity-resolution scenario for each trial - see vidigi.analysis._resolve_resource_capacities. Default to this trial’s and other’s own attached .scenario, exactly as get_resource_utilisation defaults scenario=self.scenario. None
scenario_b object or dict Capacity-resolution scenario for each trial - see vidigi.analysis._resolve_resource_capacities. Default to this trial’s and other’s own attached .scenario, exactly as get_resource_utilisation defaults scenario=self.scenario. None
highlight_bands list of dict Shaded threshold zones drawn behind the chart - see vidigi.plots.plot_duration_distribution for the dict shape. None
**kwargs dict Additional keyword arguments forwarded to vidigi.plots.plot_resource_utilisation_comparison for both trials (e.g. resource_map=, warm_up=). {}

Returns

Name Type Description
plotly.graph_objects.Figure

Raises

Name Type Description
TypeError If other is not a TrialLogger.
ValueError If metric is not a resource-utilisation column, or either trial has no runs to compare.
ImportError If scipy is not installed.

See Also

vidigi.plots.plot_resource_utilisation_comparison : The underlying implementation. compare_resource_utilisation : The underlying numbers.

plot_resource_utilisation_over_time

logging.TrialLogger.plot_resource_utilisation_over_time(
    every_x_time_units=1,
    warm_up=0,
    limit_duration=None,
    as_proportion=False,
    show_all_runs=True,
    shared_y_axis=True,
    highlight_bands=None,
    scenario=None,
    resource_map=None,
    event_position_df=None,
    resource_capacities=None,
    capacity=None,
    resource_col_name=None,
    **kwargs,
)

Plot how many units of each resource step were in use over time, across runs.

Thin wrapper over vidigi.plots.plot_resource_utilisation_over_time, called on this trial’s combined dataframe. See that function for the full parameter list.

Parameters

Name Type Description Default
every_x_time_units float Time granularity for snapshots. 1
warm_up float Time at which the plotted window begins. 0
limit_duration float End of the plotted window. None (default) uses the latest time seen anywhere in the trial. None
as_proportion bool If True, each step’s count is divided by its resolved capacity, so the y-axis is a proportion in use rather than a raw count. Requires a capacity to be resolvable for every step plotted. False
show_all_runs bool If True, plots every run with semi-transparent lines and overlays the mean trajectory. True
shared_y_axis bool If True (and more than one step is plotted), every facet shares a y-axis range. True
highlight_bands list of dict Shaded threshold zones drawn behind the chart - see vidigi.plots.plot_duration_distribution for the dict shape. Spans every facet when more than one step is plotted. None
scenario Capacity resolution, used only when as_proportion=True. scenario defaults to the one attached to this TrialLogger (if any) when not passed here. None
resource_map Capacity resolution, used only when as_proportion=True. scenario defaults to the one attached to this TrialLogger (if any) when not passed here. None
event_position_df Capacity resolution, used only when as_proportion=True. scenario defaults to the one attached to this TrialLogger (if any) when not passed here. None
resource_capacities Capacity resolution, used only when as_proportion=True. scenario defaults to the one attached to this TrialLogger (if any) when not passed here. None
capacity Capacity resolution, used only when as_proportion=True. scenario defaults to the one attached to this TrialLogger (if any) when not passed here. None
resource_col_name str Which column identifies the physical resource, used to pair resource_use/resource_use_end bouts. None (the default) uses "unique_resource_id" if that column is present on this trial’s log, else "resource_id" - see get_resource_utilisation’s same parameter for why. Pass an explicit column name to override. None
**kwargs dict Additional keyword arguments forwarded to vidigi.plots.plot_resource_utilisation_over_time (e.g. entity_col_name, time_col_name, run_col_name). {}

Returns

Name Type Description
plotly.graph_objects.Figure

Notes

Traces use line_shape="hv" - occupancy is a step function, and linear interpolation between snapshots would draw fractional resource counts that never existed.

See Also

vidigi.plots.plot_resource_utilisation_over_time : The underlying implementation. vidigi.analysis.resource_occupancy_over_time : The underlying per-run, per-snapshot counts.

plot_warm_up_diagnostic

logging.TrialLogger.plot_warm_up_diagnostic(
    series='queue',
    event=None,
    first_event=None,
    second_event=None,
    method='welch',
    windows=(5, 10, 20),
    every_x_time_units=1,
    limit_duration=None,
    show_ensemble=True,
    show_runs=False,
    **kwargs,
)

Plot a Welch (or cumulative-mean) diagnostic for choosing warm_up=.

Thin wrapper over vidigi.plots.plot_warm_up_diagnostic, called on this trial’s combined dataframe. See that function for the full parameter list.

Parameters

Name Type Description Default
series (queue, occupancy, duration) What per-run series to diagnose. See vidigi.plots.plot_warm_up_diagnostic. "queue"
event str The queue’s or resource step’s event name. Required, and only used, for series="queue"/"occupancy". None
first_event str The two events to pair. Required, and only used, for series="duration". None
second_event str The two events to pair. Required, and only used, for series="duration". None
method (welch, cumulative, none) Smoothing procedure - see vidigi.analysis.welch_moving_average. "welch"
windows sequence of int Window half-widths to overlay when method="welch". (5, 10, 20)
every_x_time_units float Snapshot granularity. Only used for series="queue"/"occupancy". 1
limit_duration float End of the window snapshots are taken over. None (default) uses the latest time seen anywhere in the trial. None
show_ensemble bool If True, also draws the raw (unsmoothed) ensemble-average series. True
show_runs bool If True, also draws every individual replication’s own raw series, at opacity=0.2 under one shared legend entry. See vidigi.plots.plot_warm_up_diagnostic. False
**kwargs dict Additional keyword arguments forwarded to vidigi.plots.plot_warm_up_diagnostic (e.g. entity_col_name, time_col_name, run_col_name, match= for series="duration"). {}

Returns

Name Type Description
plotly.graph_objects.Figure

See Also

vidigi.plots.plot_warm_up_diagnostic : The underlying implementation. vidigi.analysis.welch_moving_average : The underlying smoothing procedure.

read_pickle

logging.TrialLogger.read_pickle(path_or_buffer)

Load a TrialLogger previously written with to_pickle.

reshape_for_animations

logging.TrialLogger.reshape_for_animations(run_number=None, **kwargs)

Reshape one run’s event log into the per-snapshot frame the animation uses.

Thin wrapper over vidigi.prep.reshape_for_animations, called on this trial directly. See that function for the full parameter list.

Parameters

Name Type Description Default
run_number int or str Which replication to reshape. Required if the trial holds more than one run - passing a multi-run trial without it raises ValueError. None
**kwargs Keyword arguments forwarded to vidigi.prep.reshape_for_animations (e.g. every_x_time_units, limit_duration, step_snapshot_max). {}

Returns

Name Type Description
pandas.DataFrame One row per (entity, snapshot time) - the input to generate_animation_df.

See Also

vidigi.prep.reshape_for_animations : The underlying implementation. animate_activity_log : Run all three animation steps in one call.

summary

logging.TrialLogger.summary()

Summarize the trial logs.

Returns

Name Type Description
dict Dictionary with summary information: - "number_of_runs" : int The number of runs currently stored. - "label" : str or None The trial’s human-readable name. - "scenario_attached" : bool Whether a scenario / parameters object is attached.

to_dataframe

logging.TrialLogger.to_dataframe()

Return the full trial data as a single concatenated DataFrame.

Returns

Name Type Description
pandas.DataFrame A dataframe containing all events from all runs.

to_pickle

logging.TrialLogger.to_pickle(path_or_buffer)

Pickle this TrialLogger to a file path or writable binary buffer.

Every constituent EventLogger and any attached scenario / label are pickled; each logger’s simulation env is not (see EventLogger.to_pickle). An attached scenario must itself be picklable.

Back to top