animation.generate_animation

animation.generate_animation(
    full_entity_df_plus_pos,
    event_position_df,
    scenario=None,
    time_col_name='time',
    entity_col_name='entity_id',
    event_col_name='event',
    event_type_col_name='event_type',
    resource_col_name='resource_id',
    simulation_time_unit='minutes',
    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,
    hover_text_entity='default',
    custom_hover_data=None,
    resource_icon_size=24,
    override_x_max=None,
    override_y_max=None,
    time_display_units=None,
    start_date=None,
    start_time=None,
    resource_opacity=0.8,
    custom_resource_icon=None,
    wrap_resources_at=20,
    gap_between_resources=10,
    gap_between_resource_rows=30,
    setup_mode=False,
    frame_duration=400,
    frame_transition_duration=600,
    debug_mode=False,
    background_image_opacity=0.5,
    overflow_text_color='black',
    stage_label_text_colour='black',
    backend='express',
)

Generate an animated visualization of patient flow through a system.

This function creates an interactive Plotly animation based on patient data and event positions.

Parameters

Name Type Description Default
full_entity_df_plus_pos pd.DataFrame DataFrame containing entity data with position information. This will be the output of passing an event log through the reshape_for_animations() and generate_animation_df() functions. required
event_position_df pd.DataFrame DataFrame specifying the positions of different events. required
scenario object Object containing attributes for resource counts at different steps (default is None). None
time_col_name str Name of the column in event_log that contains the timestamp of each event (default is “time”). 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”) (default is “entity_id”). 'entity_id'
event_col_name str Name of the column in event_log that specifies the actual event that occurred (default is “event”). 'event'
event_type_col_name str Name of the column in event_log that specifies the category of the event (default is “event_type”). Supported event types include ‘arrival_departure’, ‘resource_use’, ‘resource_use_end’, and ‘queue’. 'event_type'
resource_col_name str Name of the column for the resource identifier (default is “resource_id”). 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'
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). 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
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 “%{customdata[0]} some text” etc. See https://plotly.com/python/hover-text-and-formatting/#customizing-hover-text-with-a-hovertemplate for full details. It is recommended you pair this with custom_hover_data to have control over the order of column names present in the customdata list. '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
resource_icon_size int Size of resource icons in the animation (default is 24). 24
override_x_max int Override the maximum x-coordinate (default is None). None
override_y_max int Override the maximum y-coordinate (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
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
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
wrap_resources_at int Number of resources to show before wrapping to a new row (default is 20). If this has been set elsewhere, it is also important to set it in this function to ensure the visual indicators of the resources wrap in the same way the entities using those resources do. 20
gap_between_resources int Spacing between resources in pixels (default is 10). 10
gap_between_resource_rows int Vertical spacing between rows in pixels (default is 30). 30
setup_mode bool Whether to run in setup mode, showing grid and tick marks (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 Whether to run in debug mode with additional output (default is False). 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'

Returns

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

Notes

  • The function uses Plotly Express to create an animated scatter plot.
  • Time can be displayed as actual dates or as model time units.
  • The animation supports customization of icon sizes, resource representation, and animation speed.
  • A background image can be added to provide context for the patient flow.
  • If time_display_units is specified, the simulation time is converted into real-world datetimes using the simulation_time_unit and optionally start_date and start_time.
  • If start_date and/or start_time are not provided, a default offset from today’s date is used.
  • The snapshot_time column is transformed to datetime strings, and a snapshot_time_display column is created for visual display.
Back to top