Bergam0t/vidigi: v1.0.0
Fuente:
Zenodo
Gespeichert in:
| Hauptverfasser: | , |
|---|---|
| Format: | Recurso digital |
| Veröffentlicht: |
Zenodo
2025
|
| Online-Zugang: | |
| Tags: |
Tag hinzufügen
Keine Tags, Fügen Sie den ersten Tag hinzu!
|
| _version_ | 1866902164976173056 |
|---|---|
| author | Sammi Rosser Helena Robinson |
| author_facet | Sammi Rosser Helena Robinson |
| contents | <h2>What's Changed</h2> <ul> <li>Import relevant code as expander in examples by @Bergam0t in https://github.com/Bergam0t/vidigi/pull/54</li> <li>Add demo and comparison with bupar by @Bergam0t in https://github.com/Bergam0t/vidigi/pull/55</li> <li>Store wrappers by @Bergam0t in https://github.com/Bergam0t/vidigi/pull/56</li> <li>Bugfix 51 time setting by @Bergam0t in https://github.com/Bergam0t/vidigi/pull/59</li> <li>Huge v1.0 feature and fix branch by @Bergam0t in https://github.com/Bergam0t/vidigi/pull/73</li> <li>v1.0.0 by @Bergam0t in https://github.com/Bergam0t/vidigi/pull/81</li> </ul> <p><strong>Full Changelog</strong>: https://github.com/Bergam0t/vidigi/compare/0.0.4...1.0.0</p> <h1>1.0.0</h1> <p>Migration guide below!</p> <h2>Changelog</h2> <h3>BREAKING CHANGES</h3> <ul> <li>significant changes to <code>VidigiPriorityStore</code><ul> <li>BREAKING: the original implementation of <code>VidigiPriorityStore</code> has been renamed to <code>VidigiPriorityStoreLegacy</code></li> </ul> </li> <li>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 <code>entity_col_name="patient"</code> to each of these functions.</li> <li>various classes and functions have been moved into more appropriate files, rather than all existing in <code>Utils</code>.<ul> <li>VidigiStore, VidigiPriorityStore, VidigiPriorityStoreLegacy and other resources are now in <code>vidigi.resources</code></li> <li>EventLogger is now in <code>vidigi.logging</code></li> </ul> </li> <li>parameter <code>icon_and_text_size</code> has been removed and replaced with separate parameters<ul> <li><code>resource_icon_size</code></li> <li><code>entity_icon_size</code></li> <li><code>text_size</code></li> </ul> </li> <li>parameter <code>gap_between_rows</code> has been removed and replaced with separate parameters for queues and resources<ul> <li><code>gap_between_queue_rows</code></li> <li><code>gap_between_resource_rows</code></li> </ul> </li> <li>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.</li> <li><code>init_items</code> argument for VidigiStore and VidigiPriorityStore has been replaced with <code>num_resources</code>. Defaulting to none, this functions identically to the <code>populate_stores</code> function, but instead allows you to initialise the resource on start.</li> </ul> <p>NEW FEATURES:</p> <p>Adds</p> <ul> <li>an additional <code>VidigiStore</code> class to replace use of standard store</li> <li>tests to ensure identical functioning of VidigiStore, VidigiPriorityStore and VidigiPriorityStoreLegacy to their core simpy counterparts</li> </ul> <p>The benefit of these new classes is that they allow the common resource requesting patterns to be used</p> <p>So</p> <pre><code>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 </code></pre> <p>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.</p> <p>To access the attribute, it does necessitate some small change -</p> <pre><code>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 </code></pre> <p>So <code>req.id_attribute</code> would not work</p> <p>but</p> <p><code>nurse_resource.id_attribute</code> would</p> <p>This is hopefully still a far less substantial change than was required previously, where models using resources had to switch to using <code>.get()</code> and <code>.put()</code>.</p> <p>Further testing still required for more complex request logic that incorporates aspects like reneging.</p> <p>Additional new features:</p> <ul> <li>allow flexible naming of all key input columns - so you're no longer limited to 'patient', 'event', 'event_type', 'resource_id', 'time', 'pathway'.<ul> <li>these are now controlled with the parameters <code>entity_col_name</code>, <code>event_col_name</code>, <code>event_type_col_name</code>, <code>resource_col_name", "time_col_name", "pathway_col_name</code></li> </ul> </li> <li>add helper class for event logging (<code>from vidigi.logging import EventLogger</code>)</li> <li>add helper class and function for generating an event positioning dataframe (<code>from vidigi.utils import EventPosition, create_event_position_df</code>)</li> <li>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 (<code>from vidigi.animation import add_repeating_overlay</code></li> <li>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)</li> </ul> <h3>BUGFIXES</h3> <ul> <li>fix bugs preventing the generation of 'resourceless' animations</li> <li>fix bugs relating to resource wrapping with multiple pools</li> <li>prevent shifting of entities to the exit position on the final frame</li> <li>fix bug leading to skipped frames when no entities present</li> <li>fix bugs with ordering of ciw logs</li> <li>fix bug with incorrect end type for resource use in ciw logs</li> <li>ensure sim start and end time are respected in different situations</li> <li>ensure sensible behaviour when start_time parameter is provided but start_date is not</li> <li>ensure exit step always shown</li> </ul> <h3>OTHER</h3> <ul> <li>bump ciw example from 2.x to 3.x</li> <li>add more complex ciw example</li> <li>add resourceless queue examples</li> <li>add multiple concurrent trace example</li> </ul> <h2> Migration Guide: <code>vidigi</code> 0.0.4 → 1.0.0</h2> <p>This guide will help you update your code and workflows to work with <code>vidigi</code> version <strong>1.0.0</strong>, which includes <strong>breaking changes</strong>, <strong>new features</strong>, and <strong>important bug fixes</strong>.</p> <h3>⚠️ Breaking Changes</h3> <h4>1. Default Entity Column Name</h4> <p><strong>Was:</strong> <code>'patient'</code> <strong>Now:</strong> <code>'entity_id'</code></p> <p>Update your function calls OR change your entity ID column name to entity_id:</p> <pre><code># Before animate_activity_log(event_log, event_position_df) # After animate_activity_log(event_log, event_position_df, entity_col_name="patient")</code></pre> <h4>2. Module Reorganization</h4> <p>Some classes and functions have moved:</p> <p>Old Location | New Location -------------|-------------- <code>vidigi.utils.VidigiPriorityStore</code> | <code>vidigi.resources.VidigiPriorityStoreLegacy</code></p> <p>Update your import statements accordingly.</p> <h4>3. Visual Parameter Changes</h4> <ul> <li><p><code>icon_and_text_size</code> → replaced with:</p> <ul> <li><code>resource_icon_size</code></li> <li><code>entity_icon_size</code></li> <li><code>text_size</code></li> </ul> </li> <li><p><code>gap_between_rows</code> → replaced with:</p> <ul> <li><code>gap_between_queue_rows</code></li> <li><code>gap_between_resource_rows</code></li> </ul> </li> </ul> <h4>4. <code>CustomResource</code> Renamed</h4> <p><code>CustomResource</code> is now <code>VidigiResource</code>. This is typically used indirectly through <code>VidigiStore</code> or <code>VidigiPriorityStore</code>, so minimal changes may be needed unless you were using it directly.</p> <h4>5. Resource Initialization Parameter</h4> <p><code>init_items</code> has been <strong>replaced</strong> with <code>num_resources</code> in <code>VidigiStore</code> and <code>VidigiPriorityStore</code>.</p> <p>Example:</p> <h5>Before</h5> <p><code>resource_store = VidigiStore(simulation_env, init_items=[...])</code></p> <p>OR</p> <p><code>resource_store = simpy.Store(simulation_env)</code></p> <p><code>populate_store(5, resource_store, simulation_env)</code></p> <h5>After</h5> <p><code>resource_store = VidigiStore(simulation_env, num_resources=3)</code></p> <h3>✨ New Features</h3> <h4>✅ Flexible Column Names</h4> <p>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!</p> <ul> <li><code>entity_col_name</code></li> <li><code>event_col_name</code></li> <li><code>event_type_col_name</code></li> <li><code>resource_col_name</code></li> <li><code>time_col_name</code></li> <li><code>pathway_col_name</code></li> </ul> <p>Defaults are</p> <ul> <li>entity_id</li> <li>event</li> <li>event_type</li> <li>resource_id</li> <li>time</li> <li>pathway</li> </ul> <p>(note 'pathway' is an optional column you may choose not to populate)</p> <h3>✅ What You Should Do</h3> <ul> <li>[ ] Update your column name to 'entity_id' instead of 'patient' or pass overrides in the form of 'entity_col_name="patient"`</li> <li>[ ] Update import paths</li> <li>[ ] Switch from VidigiPriorityStore to VidigiPriorityStoreLegacy if you don't want to have to make any changes to how you request resources</li> <li>[ ] Replace removed sizing and spacing parameters with new ones</li> <li>[ ] Explore new features and examples - the new resource types, event logging helpers and event positioning helpers may make your life easier!</li> </ul> <p>If you run into issues or have questions, check out the documentation or open an issue on the repo. Thanks for upgrading!</p> |
| format | Recurso digital |
| id | zenodo_https___doi_org_10_5281_zenodo_15641428 |
| institution | Zenodo |
| language | |
| publishDate | 2025 |
| publisher | Zenodo |
| record_format | zenodo |
| spellingShingle | Bergam0t/vidigi: v1.0.0 Sammi Rosser Helena Robinson <h2>What's Changed</h2> <ul> <li>Import relevant code as expander in examples by @Bergam0t in https://github.com/Bergam0t/vidigi/pull/54</li> <li>Add demo and comparison with bupar by @Bergam0t in https://github.com/Bergam0t/vidigi/pull/55</li> <li>Store wrappers by @Bergam0t in https://github.com/Bergam0t/vidigi/pull/56</li> <li>Bugfix 51 time setting by @Bergam0t in https://github.com/Bergam0t/vidigi/pull/59</li> <li>Huge v1.0 feature and fix branch by @Bergam0t in https://github.com/Bergam0t/vidigi/pull/73</li> <li>v1.0.0 by @Bergam0t in https://github.com/Bergam0t/vidigi/pull/81</li> </ul> <p><strong>Full Changelog</strong>: https://github.com/Bergam0t/vidigi/compare/0.0.4...1.0.0</p> <h1>1.0.0</h1> <p>Migration guide below!</p> <h2>Changelog</h2> <h3>BREAKING CHANGES</h3> <ul> <li>significant changes to <code>VidigiPriorityStore</code><ul> <li>BREAKING: the original implementation of <code>VidigiPriorityStore</code> has been renamed to <code>VidigiPriorityStoreLegacy</code></li> </ul> </li> <li>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 <code>entity_col_name="patient"</code> to each of these functions.</li> <li>various classes and functions have been moved into more appropriate files, rather than all existing in <code>Utils</code>.<ul> <li>VidigiStore, VidigiPriorityStore, VidigiPriorityStoreLegacy and other resources are now in <code>vidigi.resources</code></li> <li>EventLogger is now in <code>vidigi.logging</code></li> </ul> </li> <li>parameter <code>icon_and_text_size</code> has been removed and replaced with separate parameters<ul> <li><code>resource_icon_size</code></li> <li><code>entity_icon_size</code></li> <li><code>text_size</code></li> </ul> </li> <li>parameter <code>gap_between_rows</code> has been removed and replaced with separate parameters for queues and resources<ul> <li><code>gap_between_queue_rows</code></li> <li><code>gap_between_resource_rows</code></li> </ul> </li> <li>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.</li> <li><code>init_items</code> argument for VidigiStore and VidigiPriorityStore has been replaced with <code>num_resources</code>. Defaulting to none, this functions identically to the <code>populate_stores</code> function, but instead allows you to initialise the resource on start.</li> </ul> <p>NEW FEATURES:</p> <p>Adds</p> <ul> <li>an additional <code>VidigiStore</code> class to replace use of standard store</li> <li>tests to ensure identical functioning of VidigiStore, VidigiPriorityStore and VidigiPriorityStoreLegacy to their core simpy counterparts</li> </ul> <p>The benefit of these new classes is that they allow the common resource requesting patterns to be used</p> <p>So</p> <pre><code>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 </code></pre> <p>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.</p> <p>To access the attribute, it does necessitate some small change -</p> <pre><code>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 </code></pre> <p>So <code>req.id_attribute</code> would not work</p> <p>but</p> <p><code>nurse_resource.id_attribute</code> would</p> <p>This is hopefully still a far less substantial change than was required previously, where models using resources had to switch to using <code>.get()</code> and <code>.put()</code>.</p> <p>Further testing still required for more complex request logic that incorporates aspects like reneging.</p> <p>Additional new features:</p> <ul> <li>allow flexible naming of all key input columns - so you're no longer limited to 'patient', 'event', 'event_type', 'resource_id', 'time', 'pathway'.<ul> <li>these are now controlled with the parameters <code>entity_col_name</code>, <code>event_col_name</code>, <code>event_type_col_name</code>, <code>resource_col_name", "time_col_name", "pathway_col_name</code></li> </ul> </li> <li>add helper class for event logging (<code>from vidigi.logging import EventLogger</code>)</li> <li>add helper class and function for generating an event positioning dataframe (<code>from vidigi.utils import EventPosition, create_event_position_df</code>)</li> <li>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 (<code>from vidigi.animation import add_repeating_overlay</code></li> <li>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)</li> </ul> <h3>BUGFIXES</h3> <ul> <li>fix bugs preventing the generation of 'resourceless' animations</li> <li>fix bugs relating to resource wrapping with multiple pools</li> <li>prevent shifting of entities to the exit position on the final frame</li> <li>fix bug leading to skipped frames when no entities present</li> <li>fix bugs with ordering of ciw logs</li> <li>fix bug with incorrect end type for resource use in ciw logs</li> <li>ensure sim start and end time are respected in different situations</li> <li>ensure sensible behaviour when start_time parameter is provided but start_date is not</li> <li>ensure exit step always shown</li> </ul> <h3>OTHER</h3> <ul> <li>bump ciw example from 2.x to 3.x</li> <li>add more complex ciw example</li> <li>add resourceless queue examples</li> <li>add multiple concurrent trace example</li> </ul> <h2> Migration Guide: <code>vidigi</code> 0.0.4 → 1.0.0</h2> <p>This guide will help you update your code and workflows to work with <code>vidigi</code> version <strong>1.0.0</strong>, which includes <strong>breaking changes</strong>, <strong>new features</strong>, and <strong>important bug fixes</strong>.</p> <h3>⚠️ Breaking Changes</h3> <h4>1. Default Entity Column Name</h4> <p><strong>Was:</strong> <code>'patient'</code> <strong>Now:</strong> <code>'entity_id'</code></p> <p>Update your function calls OR change your entity ID column name to entity_id:</p> <pre><code># Before animate_activity_log(event_log, event_position_df) # After animate_activity_log(event_log, event_position_df, entity_col_name="patient")</code></pre> <h4>2. Module Reorganization</h4> <p>Some classes and functions have moved:</p> <p>Old Location | New Location -------------|-------------- <code>vidigi.utils.VidigiPriorityStore</code> | <code>vidigi.resources.VidigiPriorityStoreLegacy</code></p> <p>Update your import statements accordingly.</p> <h4>3. Visual Parameter Changes</h4> <ul> <li><p><code>icon_and_text_size</code> → replaced with:</p> <ul> <li><code>resource_icon_size</code></li> <li><code>entity_icon_size</code></li> <li><code>text_size</code></li> </ul> </li> <li><p><code>gap_between_rows</code> → replaced with:</p> <ul> <li><code>gap_between_queue_rows</code></li> <li><code>gap_between_resource_rows</code></li> </ul> </li> </ul> <h4>4. <code>CustomResource</code> Renamed</h4> <p><code>CustomResource</code> is now <code>VidigiResource</code>. This is typically used indirectly through <code>VidigiStore</code> or <code>VidigiPriorityStore</code>, so minimal changes may be needed unless you were using it directly.</p> <h4>5. Resource Initialization Parameter</h4> <p><code>init_items</code> has been <strong>replaced</strong> with <code>num_resources</code> in <code>VidigiStore</code> and <code>VidigiPriorityStore</code>.</p> <p>Example:</p> <h5>Before</h5> <p><code>resource_store = VidigiStore(simulation_env, init_items=[...])</code></p> <p>OR</p> <p><code>resource_store = simpy.Store(simulation_env)</code></p> <p><code>populate_store(5, resource_store, simulation_env)</code></p> <h5>After</h5> <p><code>resource_store = VidigiStore(simulation_env, num_resources=3)</code></p> <h3>✨ New Features</h3> <h4>✅ Flexible Column Names</h4> <p>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!</p> <ul> <li><code>entity_col_name</code></li> <li><code>event_col_name</code></li> <li><code>event_type_col_name</code></li> <li><code>resource_col_name</code></li> <li><code>time_col_name</code></li> <li><code>pathway_col_name</code></li> </ul> <p>Defaults are</p> <ul> <li>entity_id</li> <li>event</li> <li>event_type</li> <li>resource_id</li> <li>time</li> <li>pathway</li> </ul> <p>(note 'pathway' is an optional column you may choose not to populate)</p> <h3>✅ What You Should Do</h3> <ul> <li>[ ] Update your column name to 'entity_id' instead of 'patient' or pass overrides in the form of 'entity_col_name="patient"`</li> <li>[ ] Update import paths</li> <li>[ ] Switch from VidigiPriorityStore to VidigiPriorityStoreLegacy if you don't want to have to make any changes to how you request resources</li> <li>[ ] Replace removed sizing and spacing parameters with new ones</li> <li>[ ] Explore new features and examples - the new resource types, event logging helpers and event positioning helpers may make your life easier!</li> </ul> <p>If you run into issues or have questions, check out the documentation or open an issue on the repo. Thanks for upgrading!</p> |
| title | Bergam0t/vidigi: v1.0.0 |
| url | https://doi.org/10.5281/zenodo.15641428 |