logging.EventLogger

logging.EventLogger(
    event_model=BaseEvent,
    env=None,
    run_number=None,
    *,
    scenario=None,
    label=None,
)

Records simulation events for later reshaping into animations and statistics.

Parameters

Name	Type	Description	Default
env	optional	A simulation environment with a .now attribute or method (e.g. a simpy or salabim Environment). When given, every log_* call below may omit time - it is read from env.now at call time. Without an env, time becomes a required argument on every log_* call, and omitting it raises ValueError.	None
run_number	int	Run/replication number to stamp on every event by default. When given, every log_* call below may omit run_number - it is filled in from this value. Without it, run_number is left off events unless supplied per-call.	None

Methods

Name	Description
animate_activity_log	Build an animated visualisation of the entities in this event log.
generate_dfg	Generate a Directly-Follows Graph (DFG) from the simulation data.
get_events_by_entity	Return all events associated with a specific entity_id.
get_events_by_event_name	Return all events of a specific event_type.
get_events_by_event_type	Return all events of a specific event_type.
get_events_by_run	Return all events associated with a specific entity_id.
log_arrival	Helper to log an arrival event with the correct event_type and event fields.
log_custom_event	Log a custom event. The ‘event’ here can be any string describing the queue event.
log_departure	Helper to log a departure event with the correct event_type and event fields.
log_queue	Log a queue event. The ‘event’ here can be any string describing the queue event.
log_resource_use_end	Log the end of resource use. Requires resource_id.
log_resource_use_start	Log the start of resource use. Requires resource_id.
plot_entity_timeline	Plot a timeline of events for a given entity.
read_pickle	Load an EventLogger previously written with to_pickle.
reshape_for_animations	Reshape this event log into the per-snapshot frame the animation uses.
to_csv	Write the log to a CSV file.
to_dataframe	Convert the event log to a pandas DataFrame.
to_json	Write the event log to a JSON file or file-like buffer.
to_json_string	Return the event log as a pretty JSON string.
to_pickle	Pickle this EventLogger to a file path or writable binary buffer.

animate_activity_log

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

Build an animated visualisation of the entities in this event log.

Thin wrapper over vidigi.animation.animate_activity_log, called on this logger directly (no .to_dataframe() step needed). 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.	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.

generate_dfg

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

Generate a Directly-Follows Graph (DFG) from the simulation data.

This method converts the object to a dataframe, appends simulation timestamps, discovers transitions between activities, and renders the result using the specified visualization backend.

Parameters

Name	Type	Description	Default
output_format	DFGType	The format of the returned graph. Supported values are: - “graphviz-object”: Returns a Graphviz object for rendering. - “graphviz-image”: Returns a static image of the graph. - “cytoscape-jupyter”: Returns an interactive Cytoscape widget for Jupyter notebooks. - “cytoscape-streamlit”: Returns a Cytoscape component compatible with Streamlit. By default “graphviz-object”.	'graphviz-object'
input_time_format	str	The time unit used to calculate durations and timestamps, by default “minutes”.	'minutes'
warm_up	float	Discard a warm-up period before the graph is built, by dropping events at or before this simulation time. Default is None, which keeps every event. See :func:vidigi.process_mapping.add_sim_timestamp for what this does and does not affect.	None
occupancy_metrics	bool	If True, annotate each queue and resource node with the mean, minimum and maximum number of entities present at that step, via :func:vidigi.analysis.activity_occupancy_stats. Off by default because the queue calculation runs reshape_for_animations once per run, which is slow on a long log. warm_up is applied to this the same way.	False
occupancy_snapshot_interval	float	Snapshot granularity for occupancy_metrics, in input_time_format units. A larger value is faster and coarser.	1
**kwargs		Arbitrary keyword arguments passed to the underlying rendering functions (dfg_to_graphviz, dfg_to_cytoscape, etc.).	{}

Returns

Name	Type	Description
	graphviz.Source or ipycytoscape.CytoscapeWidget or bytes	The rendered graph object in the format specified by output_format.

Raises

Name	Type	Description
	ValueError	If the provided output_format is not a valid DFGType.

Notes

This function is a wrapper. For detailed information on how nodes and edges are calculated, or for specific rendering parameters available in **kwargs, please refer to the documentation for:

• :func:discover_dfg: For edge discovery logic.
• :func:dfg_to_graphviz: For Graphviz-specific styling kwargs.
• :func:dfg_to_cytoscape: For jupyter cytoscape styling kwargs.
• :func:dfg_to_cytoscape_streamlit: For streamlit cytoscape styling kwargs.

get_events_by_entity

logging.EventLogger.get_events_by_entity(entity_id, as_dataframe=True)

Return all events associated with a specific entity_id.

get_events_by_event_name

logging.EventLogger.get_events_by_event_name(event_name, as_dataframe=True)

Return all events of a specific event_type.

get_events_by_event_type

logging.EventLogger.get_events_by_event_type(event_type, as_dataframe=True)

Return all events of a specific event_type.

get_events_by_run

logging.EventLogger.get_events_by_run(run_number, as_dataframe=True)

Return all events associated with a specific entity_id.

log_arrival

logging.EventLogger.log_arrival(
    entity_id,
    time=None,
    pathway=None,
    run_number=None,
    **extra_fields,
)

Helper to log an arrival event with the correct event_type and event fields.

entity_id must be unique per arrival/departure within a run - logging a second arrival under the same entity_id raises a ValueError when the log is reshaped for animation.

Parameters

Name	Type	Description	Default
time	float	Simulation time of the event. Defaults to env.now if env was passed to EventLogger(...); required otherwise.	None
run_number	int	Run/replication number. Defaults to the run_number passed to EventLogger(...), if any.	None

log_custom_event

logging.EventLogger.log_custom_event(
    entity_id,
    event_type,
    event,
    time=None,
    pathway=None,
    run_number=None,
    **extra_fields,
)

Log a custom event. The ‘event’ here can be any string describing the queue event. An ‘event_type’ must also be passed, but can be any string of the user’s choosing.

Parameters

Name	Type	Description	Default
time	float	Simulation time of the event. Defaults to env.now if env was passed to EventLogger(...); required otherwise.	None
run_number	int	Run/replication number. Defaults to the run_number passed to EventLogger(...), if any.	None

log_departure

logging.EventLogger.log_departure(
    entity_id,
    time=None,
    pathway=None,
    run_number=None,
    **extra_fields,
)

Helper to log a departure event with the correct event_type and event fields.

entity_id must be unique per arrival/departure within a run - logging a second departure under the same entity_id raises a ValueError when the log is reshaped for animation.

Parameters

Name	Type	Description	Default
time	float	Simulation time of the event. Defaults to env.now if env was passed to EventLogger(...); required otherwise.	None
run_number	int	Run/replication number. Defaults to the run_number passed to EventLogger(...), if any.	None

log_queue

logging.EventLogger.log_queue(
    entity_id,
    event,
    time=None,
    pathway=None,
    run_number=None,
    **extra_fields,
)

Log a queue event. The ‘event’ here can be any string describing the queue event.

Parameters

Name	Type	Description	Default
time	float	Simulation time of the event. Defaults to env.now if env was passed to EventLogger(...); required otherwise.	None
run_number	int	Run/replication number. Defaults to the run_number passed to EventLogger(...), if any.	None

log_resource_use_end

logging.EventLogger.log_resource_use_end(
    entity_id,
    resource_id,
    event='end',
    time=None,
    pathway=None,
    run_number=None,
    **extra_fields,
)

Log the end of resource use. Requires resource_id.

Parameters

Name	Type	Description	Default
event	str	Name of the specific step, e.g. "treatment_ends". Only used as a label by vidigi.analysis.resource_use_intervals - grouping uses the matching log_resource_use_start call’s event instead - but still worth naming distinctly for readability.	"end"
time	float	Simulation time of the event. Defaults to env.now if env was passed to EventLogger(...); required otherwise.	None
run_number	int	Run/replication number. Defaults to the run_number passed to EventLogger(...), if any.	None
**extra_fields		Any further keyword arguments are recorded on the event as extra columns in the log, e.g. an outcome=... known only once the resource is released, or unique_resource_id=resource.unique_id. When resource use is auto-logged via VidigiStore(logger=...), the same passthrough is available on VidigiStore.put()/return_item().	{}

Notes

This was already possible by passing event=... as an extra keyword argument - it silently overrode the literal "end" above, since **extra_fields is applied last. event is now an explicit, documented parameter instead; behaviour for existing callers is unchanged either way.

log_resource_use_start

logging.EventLogger.log_resource_use_start(
    entity_id,
    resource_id,
    event='start',
    time=None,
    pathway=None,
    run_number=None,
    **extra_fields,
)

Log the start of resource use. Requires resource_id.

Parameters

Name	Type	Description	Default
event	str	Name of the specific step, e.g. "treatment_begins". The default of "start" is fine for a model with only one resource-use step; with more than one, a distinct name per step is what lets vidigi.analysis.resource_use_intervals/resource_utilisation report them separately rather than pooling every resource together under one name.	"start"
time	float	Simulation time of the event. Defaults to env.now if env was passed to EventLogger(...); required otherwise.	None
run_number	int	Run/replication number. Defaults to the run_number passed to EventLogger(...), if any.	None
**extra_fields		Any further keyword arguments are recorded on the event as extra columns in the log, e.g. acuity=3, arrival_mode="ambulance", unique_resource_id=resource.unique_id. Useful for attaching entity-level attributes for later analysis. When resource use is auto-logged via VidigiStore(logger=...), the same passthrough is available on VidigiStore.request()/get_direct().	{}

Notes

This was already possible by passing event=... as an extra keyword argument - it silently overrode the literal "start" above, since **extra_fields is applied last. event is now an explicit, documented parameter instead; behaviour for existing callers is unchanged either way.

plot_entity_timeline

logging.EventLogger.plot_entity_timeline(
    entity_id,
    split_by_entity_type=False,
    show_labels=False,
    return_fig=False,
)

Plot a timeline of events for a given entity.

This method visualizes the sequence of events for a specified entity from the event log as a scatter plot. The timeline is plotted using Plotly, with events displayed along the time axis. Events can be split vertically by their type or shown by event labels. Optionally, labels can be displayed directly on the plot.

Parameters

Name	Type	Description	Default
entity_id	any	Identifier of the entity whose events should be plotted.	required
split_by_entity_type	bool	If True, the y-axis shows event types to separate events vertically. If False, the y-axis shows the event labels.	False
show_labels	bool	If True, the event labels are displayed as text on the plot. If False, no labels are shown.	False
return_fig	bool	If True, return the Plotly figure instead of calling fig.show(). Use this to customise the figure further or export it (e.g. fig.write_image(...)). Defaults to False for backwards compatibility; this default will flip to True in vidigi 3.0, at which point the method will stop calling fig.show() itself.	False

Returns

Name	Type	Description
	plotly.graph_objects.Figure or None	The figure if return_fig=True, otherwise None (the figure is displayed via fig.show() and not returned).

Raises

Name	Type	Description
	ValueError	If the event log is empty.
	ValueError	If no events are found for the given entity_id.

See Also

to_dataframe : Convert the event log into a DataFrame for analysis.

Notes

• The plot is built using plotly.express.scatter.
• The y-axis is treated as categorical to improve readability.
• Marker styling includes a fixed size and outline color for clarity.

read_pickle

logging.EventLogger.read_pickle(path_or_buffer)

Load an EventLogger previously written with to_pickle.

reshape_for_animations

logging.EventLogger.reshape_for_animations(**kwargs)

Reshape this event log into the per-snapshot frame the animation uses.

Thin wrapper over vidigi.prep.reshape_for_animations, called on this logger directly (no .to_dataframe() step needed). See that function for the full parameter list.

This is the first of the three steps animate_activity_log runs for you. Call it yourself only when you want to inspect or tweak the intermediate frame before continuing:

full_entity_df = logger.reshape_for_animations(every_x_time_units=5)
full_entity_df_plus_pos = generate_animation_df(
    full_entity_df, event_position_df
)
fig = generate_animation(full_entity_df_plus_pos, event_position_df)

generate_animation_df and generate_animation stay as functions in vidigi.prep / vidigi.animation - they act on the intermediate DataFrame, not on the logger.

Parameters

Name	Type	Description	Default
**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 steps in one call.

to_csv

logging.EventLogger.to_csv(path_or_buffer)

Write the log to a CSV file.

to_dataframe

logging.EventLogger.to_dataframe()

Convert the event log to a pandas DataFrame.

to_json

logging.EventLogger.to_json(path_or_buffer, indent=2)

Write the event log to a JSON file or file-like buffer.

to_json_string

logging.EventLogger.to_json_string(indent=2)

Return the event log as a pretty JSON string.

to_pickle

logging.EventLogger.to_pickle(path_or_buffer)

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

The event log and any attached scenario / label are pickled; the simulation env is not (it holds live generators), so a restored logger has env=None and cannot log new events - it is a finished record. An attached scenario must itself be picklable.