Merge pull request #22 from pythonhealthdatascience/hints

v0.2.2

CHANGES.md

@@ -7,7 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.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)
 
-## [v2.1.0]() - 2024-05-30
+## [v2.2.0]() UNRELEASED
+
+### Added
+
+* All model classes and functions now have python type hints
+* `treat_sim.datasets` module with `load_nelson_arrivals`, `load_alternative_arrivals` and `valid_arrival_profile` functions
+* `tests/test_datasets.py` contains functional and dirty tests for loading and using internal arrival profile datasets.
+
+### Changed
+
+* `Scenario` defaults to the time dependent arrival profile given in Nelson (2013), but also accepts `arrival_profile` a `pandas.DataFrame` parameter for scenario analysis. 
+* Default arrival profile is sourced from local package rather than GitHub URL.
+
+### Fixed
+
+* MODEL: thinning alg: `np.Inf` -> `np.inf` for compatibility with `numpy>=2`
+
+## [v2.1.0](https://github.com/pythonhealthdatascience/stars-treat-sim/releases/tag/v2.1.0) - 2024-05-30 - [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.11396022.svg)](https://doi.org/10.5281/zenodo.11396022)
 
 ### Changes
 

README.md

@@ -1,26 +1,25 @@
+
+# 💫 Towards Sharing Tools, and Artifacts, for Reusable Simulation (STARS): a minimal model example
+
 [![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](https://img.shields.io/pypi/pyversions/treat_sim)](https://pypi.org/project/treat_sim/)
 [![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/)
-
-
 [<img src="https://img.shields.io/static/v1?label=dockerhub&message=images&color=important?style=for-the-badge&logo=docker">](https://hub.docker.com/r/tommonks01/treat_sim)
 
-
-# Towards Sharing Tools, and Artifacts, for Reusable Simulation: a minimal model example
-
 ## 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**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.  
+The materials and methods in this repository support work towards developing the STARShealthcare 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 STARS 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`;
-* 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); 
+* Python dependencies are managed through `mamba`;
+* Documentation of the model is enhanced using a simple Jupyter notebook.
+* The python model itself can be viewed and executed in Jupyter notebooks via [Binder](https://mybinder.org); 
 * 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.
+* A full suite of automated tests are provided with the model. 
 
 ## Author ORCIDs
 
@@ -35,7 +34,7 @@ This code is part of independent research supported by the National Institute fo
 
 ### Install from PyPI
 
-If you do not wish to you the code or would like to use the model as part of your own work you can install the model as a python package.
+If you do not wish to view the code or would like to use the model as part of your own work you can install the model as a python package.
 
 ```bash
 pip install treat-sim
@@ -59,7 +58,7 @@ git clone https://github.com/pythonhealthdatascience/stars-treat-sim
 
 #### Installing dependencies
 
-[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/release/python-380/)
+[![Python](https://img.shields.io/pypi/pyversions/treat_sim)](https://pypi.org/project/treat_sim/)
 
 All dependencies can be found in [`binder/environment.yml`]() and are pulled from conda-forge.  To run the code locally, we recommend installing [miniforge](https://github.com/conda-forge/miniforge);
 
@@ -111,6 +110,23 @@ if __name__ == '__main__':
     print(results)
 
 ```
+
+The model can be run with different time dependent arrival profiles. By default the model runs with the arrival profile taken from Nelson (2013). The `datasets` module provides access to an alternative example dataset where arrivals are slightly skewed towards the end of the working day.  
+
+```python
+
+from treat_sim.model import Scenario, multiple_replications
+from treat_sim.datasets import load_alternative_arrivals
+
+if __name__ == '__main__':
+
+    # set the arrival profile to later in the day
+    scenario1 = Scenario(arrival_porfile=load_alternative_arrivals())
+
+    alternative_results = multiple_replications(scenario1).describe().round(2).T
+    print(alternative_results)
+```
+
 #### Testing the model
 
 > See our [online documentation](https://pythonhealthdatascience.github.io/stars-simpy-example-docs/content/02_model_code/05_testing.html) for an overview of testing
@@ -142,12 +158,15 @@ pytest --cov=treat_sim tests/
 ├── pyproject.toml
 ├── README.md
 ├── tests
+│   └── test_datasets.ipynb
 │   └── test_model.ipynb
 └── treat_sim
     ├── data
     │   └── ed_arrivals.csv
-    ├── distributions.py
+    │   └── ed_arrivals_scenario1.csv
     ├── __init__.py
+    ├── datasets.py
+    ├── distributions.py
     └── model.py
 ```
 
@@ -161,8 +180,9 @@ pytest --cov=treat_sim tests/
 * `tests/` - contains automated testing code
 * `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.
+    * `datasets.py` - functions to load example dataset for parameterising the model.
+    * `distributions.py` - distribution classes.
     * `model.py` - example SimPy model.
 
 
@@ -182,7 +202,7 @@ Monks, T., Harper, A., & Heather, A. (2024). Towards Sharing Tools, and Artifact
   month        = May,
   year         = 2024,
   publisher    = {Zenodo},
-  version      = {v2.0.0},
+  version      = {v2.2.0},
   doi          = {10.5281//zenodo.10026326.},
   url          = {https://doi.org/10.5281//zenodo.10026326}
 }