logging.TrialLogger

logging.TrialLogger(self, event_logs=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_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.

Parameters

Name	Type	Description	Default
event_logs	list[EventLogger]	A list of vidigi EventLogger instances to initialize the trial log with.	None

Methods

Name	Description
add_log	Add a new event log to the trial collection.
get_event_duration_stat	Compute statistics on durations between two event types across runs.
get_log_by_run	Retrieve the log for a specific run.
plot_metric_bar	Plot a bar chart of event duration statistics for a list of event pairs.
plot_queue_size	Plot the size of one or more queues over time across simulation runs.
summary	Summarize the trial logs.
to_dataframe	Return the full trial data as a single concatenated DataFrame.

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

get_event_duration_stat

logging.TrialLogger.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.

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
**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.

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.

plot_metric_bar

logging.TrialLogger.plot_metric_bar(
    event_pair_list,
    what='mean',
    exclude_incomplete=True,
    interactive=True,
    **kwargs,
)

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

This function computes a specified statistic (e.g., mean, median) of durations between pairs of events and plots the results as a bar chart. Interactive plotting is supported via Plotly.

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. Supported values depend on the implementation of get_event_duration_stat (e.g., “mean”, “median”).	"mean"
exclude_incomplete	bool	If True, incomplete event durations (where the second event is missing) are excluded from the calculation.	True
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.	{}

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_queue_size : Plot the size of queues for events over time.

Notes

This method relies on self.get_event_duration_stat to compute the chosen statistic for each event pair.

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_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,
    **kwargs,
)

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

This function processes logged simulation events, computes queue sizes for specified event types, and visualizes the results. If multiple runs are available, individual trajectories and/or their mean are shown. Currently, only interactive Plotly-based plotting is supported.

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
**kwargs		Additional keyword arguments passed to plotly.express.line.	{}

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.
• The function relies on reshape_for_animations to transform raw event logs into a time-indexed format suitable for plotting.
• If interactive=False, no plot is returned and a message is printed instead.

See Also

reshape_for_animations : Helper function for snapshotting simulation logs.

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>

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.

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.