animation.animate_activity_log

animation.animate_activity_log(
    event_log,
    event_position_df,
    scenario=None,
    time_col_name='time',
    entity_col_name='entity_id',
    event_type_col_name='event_type',
    event_col_name='event',
    pathway_col_name=None,
    resource_col_name='resource_id',
    simulation_time_unit='minutes',
    every_x_time_units=10,
    wrap_queues_at=20,
    wrap_resources_at=20,
    step_snapshot_max=50,
    limit_duration=10 * 60 * 24,
    plotly_height=900,
    plotly_width=None,
    include_play_button=True,
    add_background_image=None,
    display_stage_labels=True,
    entity_icon_size=24,
    text_size=24,
    resource_icon_size=24,
    hover_text_entity='default',
    custom_hover_data=None,
    gap_between_entities=10,
    gap_between_queue_rows=30,
    gap_between_resource_rows=30,
    gap_between_resources=10,
    resource_opacity=0.8,
    custom_resource_icon=None,
    override_x_max=None,
    override_y_max=None,
    start_date=None,
    start_time=None,
    time_display_units=None,
    setup_mode=False,
    frame_duration=400,
    frame_transition_duration=600,
    debug_mode=False,
    custom_entity_icon_list=None,
    debug_write_intermediate_objects=False,
    background_image_opacity=0.5,
    overflow_text_color='black',
    stage_label_text_colour='black',
    backend='express',
    step_snapshot_limit_gauges=False,
    gauge_segments=10,
    gauge_max_override=None,
)

Generate an animated visualization of patient flow through a system.

This function processes event log data, adds positional information, and creates an interactive Plotly animation representing patient movement through various stages.

Parameters

Name Type Description Default
event_log pd.DataFrame The log of events to be animated, containing patient activities. required
event_position_df pd.DataFrame DataFrame specifying the positions of different events, with columns ‘event’, ‘x’, and ‘y’. required
scenario object An object containing attributes for resource counts at different steps. 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
resource_col_name str Name of the column for the resource identifier. Used for ‘resource_use’ events. "resource_id"
simulation_time_unit str Time unit used within the simulation (default is minutes). Possible values are ‘seconds’, ‘minutes’, ‘hours’, ‘days’, ‘weeks’, ‘years’ 'minutes'
every_x_time_units int Time interval between animation frames in minutes (default is 10). 10
wrap_queues_at int Maximum number of entities to display in a queue before wrapping to a new row (default is 20). 20
wrap_resources_at int Number of resources to show before wrapping to a new row (default is 20). 20
step_snapshot_max int Maximum number of patients to show in each snapshot per event (default is 50). 50
limit_duration int Maximum duration to animate in minutes (default is 10 days or 14400 minutes). 10 * 60 * 24
plotly_height int Height of the Plotly figure in pixels (default is 900). 900
plotly_width int Width of the Plotly figure in pixels (default is None, which auto-adjusts). None
include_play_button bool Whether to include a play button in the animation (default is True). True
add_background_image str Path to a background image file to add to the animation (default is None). None
display_stage_labels bool Whether to display labels for each stage (default is True). True
entity_icon_size int Size of entity icons in the animation (default is 24). 24
text_size int Size of text labels in the animation (default is 24). 24
resource_icon_size int Size of resource icons in the animation (default is 24). 24
hover_text_entity Optional[str] String to define the hover text. If None, hover on entity icons will be disabled. Default will display the entity ID, their current time in the system, etc. Must be provided in the format “%{some_column_name} some text” etc. See https://plotly.com/python/hover-text-and-formatting/#customizing-hover-text-with-a-hovertemplate for full details. All columns present in the initial dataframe are available to access by referencing their name in the format “%{some_column_name}” 'default'
custom_hover_data Optional[list[str]] A list of column names, which must be defined as strings. If provided, becomes a list of additional columns that can be accessed as part of the string defined within hover_text_entity. customdata[0] is the first column specified, customdata[1] is the second, etc. So e.g. if you pass in [“widgets_created_cumulative”] as your custom_hover_data, your hover_text_entity may be “Widgets created so far: %{customdata[0]}”. None
gap_between_entities int Horizontal spacing between entities in pixels (default is 10). 10
gap_between_queue_rows int Vertical spacing between rows in pixels (default is 30). 30
gap_between_resource_rows int Vertical spacing between rows in pixels (default is 30). 30
gap_between_resources int Horizontal spacing between resources in pixels (default is 10). 10
resource_opacity float Opacity of resource icons (default is 0.8). 0.8
custom_resource_icon str Custom icon to use for resources (default is None). None
override_x_max int Override the maximum x-coordinate of the plot (default is None). None
override_y_max int Override the maximum y-coordinate of the plot (default is None). None
start_date str Start date for the animation in ‘YYYY-MM-DD’ format. Only used when time_display_units is ‘d’ or ‘dhm’ (default is None). None
start_time str Start time for the animation in ‘HH:MM:SS’ format. Only used when time_display_units is ‘d’ or ‘dhm’ (default is None). None
time_display_units str Format for displaying time on the animation timeline. This affects how simulation time is converted into human-readable dates or clock formats. If None (default), the raw simulation time is used. Predefined options: - ‘dhms’ : Day Month Year + HH:MM:SS (e.g., “06 June 2025 14:23:45”) - ‘dhms_ampm’ : Same as ‘dhms’, but in 12-hour format with AM/PM (e.g., “06 June 2025 02:23:45 PM”) - ‘dhm’ : Day Month Year + HH:MM (e.g., “06 June 2025 14:23”) - ‘dhm_ampm’ : 12-hour format with AM/PM - (e.g., “06 June 2025 02:23 PM”) - ‘dh’ : Day Month Year + HH (e.g., “06 June 2025 14”) - ‘dh_ampm’ : 12-hour format with AM/PM (e.g., “06 June 2025 02 PM”) - ‘d’ : Full weekday and date (e.g., “Friday 06 June 2025”) - ‘m’ : Month and year (e.g., “June 2025”) - ‘y’ : Year only (e.g., “2025”) - ‘day_clock’ or ‘simulation_day_clock’ : Show simulation-relative day and time (e.g., “Simulation Day 3 14:15”) - ‘day_clock_ampm’ or ‘simulation_day_clock_ampm’ : Same as above, but time is shown in 12-hour clock with AM/PM (e.g., “Simulation Day 3 02:15 PM”) Alternatively, you can supply a custom strftime (https://strftime.org/) format string (e.g., ‘%Y-%m-%d %H’) to control the display manually. None
setup_mode bool If True, display grid and tick marks for initial setup (default is False). False
frame_duration int Duration of each frame in milliseconds (default is 400). 400
frame_transition_duration int Duration of transition between frames in milliseconds (default is 600). 600
debug_mode bool If True, print debug information during processing (default is False). False
custom_entity_icon_list Optional[list[str]] If given, overrides the default list of emojis used to represent entities None
debug_write_intermediate_objects bool If True, writes intermediate data objects (for example, the reshaped event log and positional dataframe) to CSV files in the current working directory. False
background_image_opacity float Opacity (0 is transparent, to 1, completely opaque) of the provided background image 0.5
overflow_text_color str Color of the text displayed on top of entity icons in the animation (default is black). 'black'
stage_label_text_colour str Color of the stage label text added next to each event position when display_stage_labels is True (default is black). 'black'
backend str EXPERIMENTAL. Whether to use the plotly express backend for the initial plot (default), or the experimental plotly go backend. The go approach is currently unstable and much slower. Use at your own risk. 'express'
step_snapshot_limit_gauges bool If True, replaces the text ‘+ x more’ with a gauge. The upper limit of the gauge is set by the maximum queue length observed across the simulation. False
gauge_segments int Number of discrete segments used when rendering queue length gauges in the animation. Higher values give a finer-grained visual indication of queue length, while lower values produce chunkier segments. 10
gauge_max_override int | float Manually specified maximum value for queue length gauges. If None, the upper limit is determined from the maximum queue length observed in the simulation when step_snapshot_limit_gauges is True. None

Returns

Name Type Description
plotly.graph_objs._figure.Figure An animated Plotly figure object representing the patient flow.

Notes

  • This function uses helper functions: reshape_for_animations, generate_animation_df, and generate_animation.
  • The animation supports customization of icon sizes, resource representation, and animation speed.
  • Time can be displayed as actual dates or as model time units.
  • A background image can be added to provide context for the patient flow.
  • The function handles both queuing and resource use events.
Back to top