diff --git a/CHANGES.md b/CHANGES.md index 8008f0f..a3762ec 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,15 +1,45 @@ -# CHANGELOG +# Changelog -## v1.1.1 +All notable changes to this project will be documented in this file. -* PATCH: Trauma patient treatment fixed to use correct distribution and parameters. +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Dates formatted as YYYY-MM-DD as per [ISO standard](https://www.iso.org/iso-8601-date-and-time-format.html). -## v1.1.0 +Consistent identifier (represents all versions, resolves to latest): [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10026326.svg)](https://doi.org/10.5281/zenodo.10026326) -### Updates and new features +## [v1.2.0]() - 2024-05-08 -* Upgraded internal implementation of generating non-overlapping random number streams. This is now implemented to use `np.random.SeedSequence`. See https://numpy.org/doc/stable/reference/random/parallel.html +### Changed -### Patches +* `CHANGES.md` uses Keep a Changelog formatting, and includes release links, DOIs, and first release. +* `CITATION.cff` includes references, new author, and spelling/grammar fixes. +* `README.md` updated repo overview and spelling/grammar fixes +* Full author list in `__init__` -* `setup.py` now links to correct Github URL \ No newline at end of file +### Fixed + +* Model uses data from this repository (rather than external) + +### Removed + +* Duplicate `ed_arrivals.csv` + +## [v1.1.1](https://github.com/pythonhealthdatascience/stars-treat-sim/releases/tag/v1.1.1) - 2024-05-01 - [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.11098944.svg)](https://doi.org/10.5281/zenodo.11098944) + +### Fixed + +* Trauma patient treatment fixed to use correct distribution and parameters. + +## [v1.1.0](https://github.com/pythonhealthdatascience/stars-treat-sim/releases/tag/v1.1.0) - 2024-04-06 - [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10936052.svg)](https://doi.org/10.5281/zenodo.10936052) + +### Changed + +* Upgraded internal implementation of generating non-overlapping random number streams. This is now implemented to use `np.random.SeedSequence`. See [https://numpy.org/doc/stable/reference/random/parallel.html](https://numpy.org/doc/stable/reference/random/parallel.html). + +### Fixed + +* `setup.py` now links to correct Github URL + +## [v1.0.0](https://github.com/pythonhealthdatascience/stars-treat-sim/releases/tag/v1.0.0) - 2023-10-20 - [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10026327.svg)](https://doi.org/10.5281/zenodo.10026327) + +:seedling: First release. \ No newline at end of file diff --git a/CITATION.cff b/CITATION.cff index 6074ac4..5771772 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -4,7 +4,7 @@ cff-version: 1.2.0 title: >- Towards Sharing Tools, and Artifacts, for Reusable - Simulation: a minimal model examplar + Simulation: a minimal model example message: >- If you use this software, please cite it using the metadata from this file. @@ -18,20 +18,54 @@ authors: family-names: Harper affiliation: University of Exeter orcid: 'https://orcid.org/0000-0001-5274-5037' + - given-names: Amy + family-names: Heather + affiliation: University of Exeter + orcid: 'https://orcid.org/0000-0002-6596-3479' repository-code: 'https://github.com/pythonhealthdatascience/stars-treat-sim' +identifiers: + - description: Consistent identifier for archived snapshots of repository (represents all versions, resolves to latest) + type: doi + value: '10.5281/zenodo.10026326' abstract: > The materials and methods in this repository support work towards developing the S.T.A.R.S healthcare framework - (Sharing Tools and Artifacts for Reuable Simulations in + (Sharing Tools and Artifacts for Reusable Simulations in healthcare). The code and written materials re demonstrate the application of S.T.A.R.S' version 1 to - sharing a `simpy` discrete-event simulation model and + sharing a `SimPy` discrete-event simulation model and associated research artifacts. keywords: - Free and Open Source Software - Model Reuse - Discrete-event simulation - Open Science - - Simpy + - SimPy license: MIT +references: + - type: article + title: 'Towards sharing tools and artefacts for reusable simulations in healthcare' + authors: + - given-names: Thomas + family-names: Monks + - given-names: Alison + family-names: Harper + - given-names: Navonil + family-names: Mustafee + doi: 10.1080/17477778.2024.2347882 + journal: 'Journal of Simulation' + publisher: + name: 'Taylor & Francis' + month: 5 + year: 2024 + - type: book + title: 'Foundations and Methods of Stochastic Simulation' + authors: + - given-names: Barry L. + family-names: Nelson + publisher: + name: 'Springer New York' + year: 2013 + doi: 10.1007/978-1-4614-6160-9 + edition: '1st edition' \ No newline at end of file diff --git a/README.md b/README.md index b1b5de6..891693a 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/pythonhealthdatascience/stars-treat-sim/HEAD) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/release/python-360+/) -[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10026327.svg)](https://doi.org/10.5281/zenodo.10026327) +[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/release/python-380+/) +[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10026326.svg)](https://doi.org/10.5281/zenodo.10026326) [![PyPI version fury.io](https://badge.fury.io/py/treat-sim.svg)](https://pypi.org/project/treat-sim/) [](https://hub.docker.com/r/tommonks01/treat_sim) @@ -11,14 +11,14 @@ ## Overview -The materials and methods in this repository support work towards developing the S.T.A.R.S healthcare framework (**S**haring **T**ools and **A**rtifacts for **R**euable **S**imulations in healthcare). The code and written materials here demonstrate the application of S.T.A.R.S' version 1 to sharing a `simpy` discrete-event simuilation model and associated research artifacts. +The materials and methods in this repository support work towards developing the S.T.A.R.S healthcare framework (**S**haring **T**ools and **A**rtifacts for **R**eusable **S**imulations in healthcare). The code and written materials here demonstrate the application of S.T.A.R.S' version 1 to sharing a `SimPy` discrete-event simulation model and associated research artifacts. * All artifacts in this repository are linked to study researchers via ORCIDs; * Model code is made available under an MIT license; -* Python dependencies are managed through `conda`;` +* Python dependencies are managed through `conda`; * Documentation of the model is enhanced using a Jupyter notebook. * The python code itself can be viewed and executed in Jupyter notebooks via [Binder](https://mybinder.org); -* The materials are deposited and made citatable using Zenodo; +* The materials are deposited and made citable using Zenodo; * The model is sharable with other researchers and the NHS without the need to install software. ## Author ORCIDs @@ -36,7 +36,7 @@ This code is part of independent research supported by the National Institute fo The python code for the model has been setup to run online in Jupyter notebooks via binder [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/pythonhealthdatascience/stars-treat-sim/HEAD) -> mybinder.org is a free tier service. If it has not been used in a while Binder will need to re-containerise the code repository, and push to binderhub. This will take several minutes. After that the online environment will be quick to load. +> mybinder.org is a free tier service. If it has not been used in a while Binder will need to re-containerise the code repository, and push to BinderHub. This will take several minutes. After that the online environment will be quick to load. ### To download code and run locally @@ -50,7 +50,7 @@ git clone https://github.com/pythonhealthdatascience/stars-treat-sim #### Installing dependencies -[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/release/python-390/) +[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/release/python-380/) All dependencies can be found in [`binder/environment.yml`]() and are pulled from conda-forge. To run the code locally, we recommend install [mini-conda](https://docs.conda.io/en/latest/miniconda.html); navigating your terminal (or cmd prompt) to the directory containing the repo and issuing the following command: @@ -58,7 +58,7 @@ All dependencies can be found in [`binder/environment.yml`]() and are pulled fro conda env create -f binder/environment.yml ``` -Activate the conda environment using the following command +Activate the conda environment using the following command: ``` conda activate stars_treat_sim @@ -66,8 +66,7 @@ conda activate stars_treat_sim #### Running the model -To run 50 multiple replications of across a number of example experiments use the following code - +To run 50 multiple replications across a number of example experiments, use the following code: ```python from treat_sim.model import (get_scenarios, run_scenario_analysis, @@ -85,7 +84,7 @@ if __name__ == '__main__': ``` -Alternative you can design and execute individual experiments by creating a `Scenario` object +Alternative you can design and execute individual experiments by creating a `Scenario` object: ```python from treat_sim.model import Scenario, multiple_replications @@ -100,13 +99,14 @@ if __name__ == '__main__': ``` - ## Repo overview ``` . ├── binder │   └── environment.yml +├── CHANGES.md +├── CITATION.cff ├── LICENSE ├── MANIFEST.in ├── notebooks @@ -122,30 +122,39 @@ if __name__ == '__main__': └── model.py ``` -* `binder` - contains the environment.yml file (sim) and all dependencies managed via conda -* `data` - directory containing data files used by analysis notebooks. +* `binder/` - contains the environment.yml file (sim) and all dependencies managed via conda, used to set-up the notebooks on Binder. +* `CHANGES.md` - changelog with record of notable changes to project between versions. +* `CITATION.cff` - citation information for the package. * `LICENSE` - details of the MIT permissive license of this work. -* `notebooks` - contains a notebook to run the model and provides basic enhanced model documentation. -* `main.py` - an example simpy model to use to test the virtual environment -* `README` - what you are reading now! -* `treat_sim` - contains a packaged version of the model. - +* `MANIFEST.in` - files to include in the package. +* `notebooks/` - contains a notebook to run the model and provides basic enhanced model documentation. +* `README.md` - what you are reading now! +* `requirements.txt` - list of packages and minimum versions required. +* `setup.py` - used to build and distribute package. +* `treat_sim/` - contains packaged version of the model. + * `data/` - directory containing data file used by package. + * `distributions.py` - distribution classes. + * `__init__.py` - required as part of package - contains author and version. + * `model.py` - example SimPy model. ## Citation If you use the materials within this repository we would appreciate a citation. +``` +Monks, T., Harper, A., & Heather, A. (2024). Towards Sharing Tools, and Artifacts, for Reusable Simulation: a minimal model example (v1.2.0). Zenodo. https://doi.org/10.5281//zenodo.10026326 +``` + ```bibtex -@software{monks_2023_10026327, - author = {Monks, Thomas and - Harper, Alison}, +@software{stars_treat_sim, + author = {Thomas Monks, Alison Harper and Amy Heather}, title = {{Towards Sharing Tools, and Artifacts, for Reusable - Simulation: a minimal model examplar}}, - month = oct, - year = 2023, + Simulation: a minimal model example}}, + month = May, + year = 2024, publisher = {Zenodo}, - version = {v1.0.0}, - url = {https://zenodo.org/records/10026327} + version = {v1.2.0}, + doi = {10.5281//zenodo.10026326.}, + url = {https://doi.org/10.5281//zenodo.10026326} } ``` - diff --git a/data/ed_arrivals.csv b/data/ed_arrivals.csv deleted file mode 100644 index a0c4e5d..0000000 --- a/data/ed_arrivals.csv +++ /dev/null @@ -1,19 +0,0 @@ -period,arrival_rate -6AM-7AM,2.36666666666667 -7AM-8AM,2.8 -8AM-9AM,8.83333333333333 -9AM-10AM,10.4333333333333 -10AM-11AM,14.8 -11AM-12PM,26.2666666666667 -12PM-1PM,31.4 -1PM-2PM,18.0666666666667 -2PM-3PM,16.4666666666667 -3PM-4PM,12.0333333333333 -4PM-5PM,11.6 -5PM-6PM,28.8666666666667 -6PM-7PM,18.0333333333333 -7PM-8PM,11.5 -8PM-9PM,5.3 -9PM-10PM,4.06666666666667 -10PM-11PM,2.2 -11PM-12AM,2.1 diff --git a/treat_sim/__init__.py b/treat_sim/__init__.py index cd9c0ee..d703e6b 100644 --- a/treat_sim/__init__.py +++ b/treat_sim/__init__.py @@ -1,2 +1,2 @@ -__author__ = 'T.Monks' -__version__ = '1.1.1' +__author__ = 'Thomas Monks, Alison Harper and Amy Heather' +__version__ = '1.2.0' diff --git a/treat_sim/model.py b/treat_sim/model.py index 42a3c4c..164e106 100644 --- a/treat_sim/model.py +++ b/treat_sim/model.py @@ -15,14 +15,14 @@ The health clinic expects two types of patient arrivals: **Trauma arrivals:** -patients with severe illness and trauma that must first be stablised in a +patients with severe illness and trauma that must first be stabilised in a trauma room. These patients then undergo treatment in a cubicle before being discharged. **Non-trauma arrivals** patients with minor illness and no trauma go through registration and examination activities. A proportion of non-trauma patients require treatment -in a cubicle before being dicharged. +in a cubicle before being discharged. In this model treatment of trauma and non-trauma patients is modelled seperately ''' @@ -32,7 +32,8 @@ import itertools import simpy -from treat_sim.distributions import (Exponential, Normal, Uniform, Bernoulli, Lognormal) +from treat_sim.distributions import ( + Exponential, Normal, Uniform, Bernoulli, Lognormal) # Constants and defaults for modelling **as-is** @@ -71,8 +72,8 @@ # The data for arrival rates varies between clinic opening at 6am and closure at # 12am. -NSPP_PATH = 'https://raw.githubusercontent.com/TomMonks/' \ - + 'open-science-for-sim/main/src/notebooks/01_foss_sim/data/ed_arrivals.csv' +NSPP_PATH = 'https://raw.githubusercontent.com/pythonhealthdatascience/' \ + + 'stars-treat-sim/main/treat_sim/data/ed_arrivals.csv' # Resource counts @@ -203,7 +204,7 @@ def __init__(self, random_number_set=DEFAULT_RNG_SET, The number of examination rooms n_trauma: int - The number of trauma bays for stablisation + The number of trauma bays for stabilisation n_cubicles_1: int The number of non-trauma treatment cubicles @@ -276,7 +277,7 @@ def set_random_no_set(self, random_number_set): Parameters: ---------- random_number_set: int - Used to control the set of psuedo random numbers + Used to control the set of pseudo random numbers used by the distributions in the simulation. ''' self.random_number_set = random_number_set @@ -514,7 +515,7 @@ def __init__(self, identifier, env, args): identifier: int a numeric identifier for the patient. - env: simpy.Environment + env: SimPy.Environment the simulation environment args: Scenario @@ -649,7 +650,7 @@ class TreatmentCentreModel: The main class that a user interacts with to run the model is `TreatmentCentreModel`. This implements a `.run()` method, contains a simple - algorithm for the non-stationary poission process for patients arrivals and + algorithm for the non-stationary Poisson process for patients arrivals and inits instances of `TraumaPathway` or `NonTraumaPathway` depending on the arrival type. @@ -729,7 +730,7 @@ def run(self, results_collection_period=DEFAULT_RESULTS_COLLECTION_PERIOD): # setup the arrival generator process self.env.process(self.arrivals_generator()) - # store rc perio + # store rc period self.rc_period = results_collection_period # run @@ -752,7 +753,7 @@ def arrivals_generator(self): t = int(self.env.now // 60) % self.args.arrivals.shape[0] lambda_t = self.args.arrivals['arrival_rate'].iloc[t] - #set to a large number so that at least 1 sample taken! + # set to a large number so that at least 1 sample taken! u = np.Inf interarrival_time = 0.0 @@ -856,7 +857,7 @@ def process_run_results(self): self.args.n_trauma, self.model.trauma_patients) - # mean waiting time for treatment (rauma) + # mean waiting time for treatment (trauma) mean_treat_wait2 = self.get_mean_metric('wait_treat', self.model.trauma_patients) @@ -979,7 +980,7 @@ def single_run(scenario, rc_period=DEFAULT_RESULTS_COLLECTION_PERIOD, ----------- scenario: Scenario object - The scenario/paramaters to run + The scenario/parameters to run rc_period: int The length of the simulation run that collects results @@ -1019,7 +1020,7 @@ def multiple_replications(scenario, rc_period=DEFAULT_RESULTS_COLLECTION_PERIOD, Params: ------ scenario: Scenario - Parameters/arguments to configurethe model + Parameters/arguments to configure the model rc_period: float, optional (default=DEFAULT_RESULTS_COLLECTION_PERIOD) results collection period.