1.1.0

  • Add TrialLogger class, allowing storage of multiple EventLogger objects and access to new helper functions for trial summarisation and plotting
  • Fix plot_entity_timeline() method in EventLogger
  • Add from_csv() option for generating EventLogger object from existing dataframe, allowing access to EventLogger’s helper functions even when you have not used it for the initial logging
  • Improve default hover tooltip for entities
  • Add support for custom hover tooltips for entities
  • Add helper function for including ASCII gauges to better visualise large queues
  • Added option to swap out ‘+ x more’ text for an ASCII gauge in generate_animation and animate_activity_log
  • Improved how ‘+ x more’ and ASCII gauges are handled as entities, preventing them from flying in/out on most frame updates
  • Various improvements to type hinting and documentation of functions
  • Added various warnings for incorrect types in core functions
  • Added warning when step_snapshot_limit is not a multiple of wrap_queues_at (which can cause odd behaviour for placement of the ‘+ x more’ text or ASCII excess queue gauge)
  • Added and refined several documentation pages
  • Minor refactoring and efficiencies to reshape_for_animations function
  • Added some very basic tests for reshape_for_animations function

1.0.2

  • Bump minimum Python version to 3.10 to simplify support for install across both conda-forge and python. 3.9 is no longer going to be supported after October 2025.

1.0.1

  • Added ‘background_image_opacity’ argument to generate_animation and animate_activity_log. Default opacity is 0.5, which matches the previous hardcoded value.
  • Added ‘overflow_text_color’ argument to generate_animation and animate_activity_log. Default is ‘black’. Overflow text refers to the ‘+ x more’ text that appears when queue lengths exceed the snapshot size.
  • Added ‘stage_label_text_colour’ argument to generate_animation and animate_activity_log. Default is ‘black’. These are the optional labels showing the stages as defined in the event position dataframe, which you may be using instead of passing in a custom background with stage labels.
  • Add ability to log custom events with non-standard event_type using the .log_custom_event() method of the EventLogger class.
  • Fully empty columns are now automatically removed when
    • exporting event log as df or csv
    • using prep.reshape_for_animation
    • using prep.generate_animation_df
  • Experimental: Added a graph objects backend (alternative to plotly express). This is not recommended for active use - it primarily exists to help explore ways in which further customisations could be applied to the plot.

1.0.0

Migration guide below!

Changelog

BREAKING CHANGES

  • significant changes to VidigiPriorityStore
    • BREAKING: the original implementation of VidigiPriorityStore has been renamed to VidigiPriorityStoreLegacy
  • default entity column name for all prep and animation functions is now ‘entity_id’ rather than ‘patient’. This can be managed by passing in the argument entity_col_name="patient" to each of these functions.
  • various classes and functions have been moved into more appropriate files, rather than all existing in Utils.
    • VidigiStore, VidigiPriorityStore, VidigiPriorityStoreLegacy and other resources are now in vidigi.resources
    • EventLogger is now in vidigi.logging
  • parameter icon_and_text_size has been removed and replaced with separate parameters
    • resource_icon_size
    • entity_icon_size
    • text_size
  • parameter gap_between_rows has been removed and replaced with separate parameters for queues and resources
    • gap_between_queue_rows
    • gap_between_resource_rows
  • CustomResource is now called VidigiResource. This generally should not cause problems as you are likely to only be accessing it indirectly through use of VidigiStore or VidigiPriorityStore.
  • init_items argument for VidigiStore and VidigiPriorityStore has been replaced with num_resources. Defaulting to none, this functions identically to the populate_stores function, but instead allows you to initialise the resource on start.
  • the dataframe expected by generate_animation_df is now full_entity_df, not full_patient_df. Only the parameter name needs updating.
  • the dataframe expected by generate_animation is now full_entity_df_plus_pos, not full_patient_df_plus_pos. Only the parameter name needs updating.

NEW FEATURES:

Adds

  • an additional VidigiStore class to replace use of standard store
  • tests to ensure identical functioning of VidigiStore, VidigiPriorityStore and VidigiPriorityStoreLegacy to their core simpy counterparts

The benefit of these new classes is that they allow the common resource requesting patterns to be used

So

with self.nurse.request() as req:
    # Freeze the function until the request for a nurse can be met.
    # The patient is currently queuing.
    yield req

will work when using a VidigiStore or VidigiPriorityStore - mimicking the syntax of making a request from resources - while supporting the inclusion of a resource ID attribute (not possible with traditional simpy resources) that is necessary to grab for simpy.

To access the attribute, it does necessitate some small change -

with self.nurse.request() as req:
    # Freeze the function until the request for a nurse can be met.
    # The patient is currently queuing.
    nurse_resource = yield req ## NEED TO ASSIGN HERE

So req.id_attribute would not work

but

nurse_resource.id_attribute would

This is hopefully still a far less substantial change than was required previously, where models using resources had to switch to using .get() and .put().

Further testing still required for more complex request logic that incorporates aspects like reneging.

Additional new features:

  • allow flexible naming of all key input columns - so you’re no longer limited to ‘patient’, ‘event’, ‘event_type’, ‘resource_id’, ‘time’, ‘pathway’.
    • these are now controlled with the parameters entity_col_name, event_col_name, event_type_col_name, resource_col_name", "time_col_name", "pathway_col_name
  • add helper class for event logging (from vidigi.logging import EventLogger)
  • add helper class and function for generating an event positioning dataframe (from vidigi.utils import EventPosition, create_event_position_df)
  • add helper function for generating a repeating overlay to the final animation, e.g. to make it clear when something like night or a clinic closure is occurring (from vidigi.animation import add_repeating_overlay
  • add in a wide range of additional ways that the simulation time can be displayed (e.g. ‘Simulation Day 1’, am/pm rather than 24 hour, or even custom strftime string)

BUGFIXES

  • fix bugs preventing the generation of ‘resourceless’ animations
  • fix bugs relating to resource wrapping with multiple pools
  • prevent shifting of entities to the exit position on the final frame
  • fix bug leading to skipped frames when no entities present
  • fix bugs with ordering of ciw logs
  • fix bug with incorrect end type for resource use in ciw logs
  • ensure sim start and end time are respected in different situations
  • ensure sensible behaviour when start_time parameter is provided but start_date is not
  • ensure exit step always shown

OTHER

  • bump ciw example from 2.x to 3.x
  • add more complex ciw example
  • add resourceless queue examples
  • add multiple concurrent trace example

🚀 Migration Guide: vidigi 0.0.4 → 1.0.0

This guide will help you update your code and workflows to work with vidigi version 1.0.0, which includes breaking changes, new features, and important bug fixes.

⚠️ Breaking Changes

1. Default Entity Column Name

Was: 'patient' Now: 'entity_id'

Update your function calls OR change your entity ID column name to entity_id:

# Before
animate_activity_log(event_log,  event_position_df)

# After
animate_activity_log(event_log,  event_position_df, entity_col_name="patient")

2. Module Reorganization

Some classes and functions have moved:

Old Location New Location
vidigi.utils.VidigiPriorityStore vidigi.resources.VidigiPriorityStoreLegacy

Update your import statements accordingly.

3. Visual Parameter Changes

  • icon_and_text_size → replaced with:
    • resource_icon_size
    • entity_icon_size
    • text_size
  • gap_between_rows → replaced with:
    • gap_between_queue_rows
    • gap_between_resource_rows

4. Parameter names for main dataframes in step-by-step functions

  • the dataframe expected by generate_animation_df is now full_entity_df, not full_patient_df. Only the parameter name needs updating.
  • the dataframe expected by generate_animation is now full_entity_df_plus_pos, not full_patient_df_plus_pos. Only the parameter name needs updating.

5. CustomResource Renamed

CustomResource is now VidigiResource. This is typically used indirectly through VidigiStore or VidigiPriorityStore, so minimal changes may be needed unless you were using it directly.

6. Resource Initialization Parameter

init_items has been replaced with num_resources in VidigiStore and VidigiPriorityStore.

Example:

Before

resource_store = VidigiStore(simulation_env, init_items=[...])

OR

resource_store = simpy.Store(simulation_env)

populate_store(5, resource_store, simulation_env)

After

resource_store = VidigiStore(simulation_env, num_resources=3)

✨ New Features

✅ Flexible Column Names

You can now customize column names in the animation and animation prep functions, meaning you are no longer tied to using ‘patient’ for your entity IDs!

  • entity_col_name
  • event_col_name
  • event_type_col_name
  • resource_col_name
  • time_col_name
  • pathway_col_name

Defaults are

  • entity_id
  • event
  • event_type
  • resource_id
  • time
  • pathway

(note ‘pathway’ is an optional column you may choose not to populate)

✅ What You Should Do

If you run into issues or have questions, check out the documentation or open an issue on the repo. Thanks for upgrading!