prep.reshape_for_animations

prep.reshape_for_animations(
    event_log,
    every_x_time_units=10,
    limit_duration=10 * 60 * 24,
    step_snapshot_max=60,
    step_snapshot_max_overrides=None,
    time_col_name='time',
    entity_col_name='entity_id',
    event_type_col_name='event_type',
    event_col_name='event',
    pathway_col_name=None,
    debug_mode=False,
    save_intermediate_outputs=False,
    run_number=None,
    run_col_name='auto',
    warm_up=0,
    snapshot_alignment='warm_up',
)

Reshape event log data for animation purposes.

This function processes an event log to create a series of snapshots at regular time intervals, suitable for creating animations of patient flow through a system.

Parameters

Name Type Description Default
event_log pd.DataFrame, EventLogger, or TrialLogger The input event log containing entity events and timestamps in the form of a number of time units since the simulation began. A vidigi.logging.EventLogger or TrialLogger may be passed directly, in which case its .to_dataframe() is called for you. required
every_x_time_units int The time interval between snapshots in preferred time units (default is 10). 10
limit_duration int The time at which the animation stops, in preferred time units (default is 10 days). Together with warm_up this defines the animation window, which runs from warm_up to limit_duration. 10 * 60 * 24
step_snapshot_max int The maximum number of entities to include in each snapshot for each event (default is 60). Acts as the fallback for any event not named in step_snapshot_max_overrides. 60
step_snapshot_max_overrides dict A mapping of event name to a per-event step_snapshot_max, e.g. {"waiting_for_bed": 250}. Any event not listed uses the scalar step_snapshot_max. Default None (every event uses step_snapshot_max). A key that matches no event in the log raises a warning. None
time_col_name str Name of the column in event_log that contains the timestamp of each event. Timestamps should represent the number of time units since the simulation began. "time"
entity_col_name str Name of the column in event_log that contains the unique identifier for each entity (e.g., “entity_id”, “entity”, “patient”, “patient_id”, “customer”, “ID”). "entity_id"
event_type_col_name str Name of the column in event_log that specifies the category of the event. Supported event types include ‘arrival_departure’, ‘resource_use’, ‘resource_use_end’, and ‘queue’. "event_type"
event_col_name str Name of the column in event_log that specifies the actual event that occurred. "event"
pathway_col_name str Name of the column in event_log that identifies the specific pathway or process flow the entity is following. If None, it is assumed that pathway information is not present. None
debug_mode bool If True, print debug information during processing (default is False). False
save_intermediate_outputs bool | str | None For debugging purposes. If True or a string, output a series of csvs with intermediate transformed dataframes. If a string is passed, this will be interpreted as the path to prefix the dataframes with. Default is False. False
run_number int Selects a single replication from a TrialLogger passed as event_log. Only valid with a TrialLogger: passing it alongside a DataFrame or an EventLogger raises ValueError, as does passing a multi-run TrialLogger without it. None
run_col_name str or None Name of the column identifying which simulation run (replication) each row belongs to, used to reject event logs containing more than one replication. Default is “auto”, which looks for a column named (case-insensitively) one of ‘run’, ‘run_number’, ‘replication’, ‘rep’ or ‘run_id’. Pass an explicit column name to override the search, or None to disable the check. 'auto'
warm_up int The time at which the animation starts, in preferred time units (default is 0, the beginning of the run). Snapshots then run up to limit_duration, spaced every_x_time_units apart; snapshot_alignment controls exactly where that grid falls. This is how to discard a warm-up period. Pass the whole event log and set warm_up to the end of your warm-up; do not filter the log by time first. Filtering removes the ‘arrival’ rows of every entity that arrived during the warm-up, and since this function works out who is present from arrival and departure rows, those entities then vanish from every frame - including ones still queuing. warm_up trims the window while leaving that history intact. 0
snapshot_alignment (warm_up, run_start) Which point the snapshot grid counts from when warm_up is non-zero. Ignored when warm_up is 0, as the two are then identical. - “warm_up” (default): snapshots are taken at warm_up, warm_up + every_x_time_units, and so on, so the first frame lands exactly on the boundary and shows the state of the system as the warm-up ends. - “run_start”: snapshots stay on the grid that runs from time 0, and those before warm_up are simply dropped. Frame times are then the same ones you would get with no warm-up at all, which keeps them round numbers when warm_up is not a multiple of every_x_time_units. This matches the longstanding workaround of filtering the reshaped frame by snapshot_time, except that a snapshot falling exactly on warm_up is kept rather than dropped. The two produce identical grids whenever warm_up is a multiple of every_x_time_units. "warm_up"

Returns

Name Type Description
DataFrame A reshaped DataFrame containing snapshots of entity positions at regular time intervals, sorted by minute and event.

Notes

  • This function animates a single replication only. An event log containing more than one run is rejected with a ValueError, because the runs would otherwise be blended together into an animation representing no run of your model. Filter your log first, e.g. event_log[event_log["run"] == 1].
  • The function creates snapshots of entity positions at specified time intervals.
  • It handles entities who are present in the system at each snapshot time.
  • Entities are ranked within each event based on their arrival order.
  • A maximum number of patients per event can be set to limit the number of entities who will be displayed on screen within any one event type at a time. This is step_snapshot_max, optionally overridden per event by step_snapshot_max_overrides.
  • This function assumes entities only exist in one place/queue at a time. Simulations where this assumption does not hold may display unexpected behaviour.
  • An ‘exit’ event is added for each entity at the end of their journey.
  • The function uses memory management techniques (del and gc.collect()) to handle large datasets.
  • Includes a hidden_run_before column: for each row, the number of consecutive snapshots immediately before it where the entity was present but hidden by step_snapshot_max. 0 for a genuine new arrival and for ordinary continuous movement; positive only where an entity re-emerges as an individually-drawn icon after being capped out. Consumed by generate_animation_df’s step_snapshot_reveal_pop_in.
  • To skip a warm-up period, use warm_up rather than filtering the event log. Presence at each snapshot is derived from arrival and departure rows, so a log truncated with something like event_log[event_log["time"] >= warm_up] has lost the arrival row of everyone who was already in the system, and those entities are then absent from every frame. A warning is raised if the log looks truncated this way, but warm_up avoids the problem entirely.

TODO

  • Add behavior for when limit_duration is None.
  • Implement pathway order and precedence columns.
  • Fix the automatic exit at the end of the simulation run for all entities.
Back to top