STARS

Essential Components

Requirement Requirement Information (Source: https://des.hsma.co.uk/stars.html) Details
Open licence Before sharing code, it’s important to choose an appropriate open-source licence. A licence tells others how they can use, modify or share your work. Without a licence, you retain exclusive copyright, and others would not be able to legally reuse the model.

The code is licenced under the GNU General Plublic License V3.0.

This copyleft licence confers permissions including but not limited to commercial use, modification and distribution.

The licence file is available in the repository here: https://github.com/RichardPilbery/DAA_DES/blob/main/LICENSE
Dependency management

To make sure your code runs correctly for others (or for yourself in the future), you need to list the required software and versions. Without this, users may face errors due to missing dependencies.

In Python, common tools for managing this are:

  • Pip virtual environments with a requirements.txt file.

  • Conda environments with a environment.yaml/yml file.

  • Poetry with a pyproject.toml file.

A requirements.txt file is provided at https://github.com/RichardPilbery/DAA_DES/blob/main/requirements.txt

Additional requirements, such as the recommended/tested versions of Quarto and R, are detailed in the README.md.
Use FOSS languages FOSS provides freedom: it grants users the rights to adapt and share copies of their model however they choose. Python is an example of a FOSS language.

The model is written in Python.

Some wrangling code is written in R.

Some Microsoft Excel xlsx files are used for compatibility reasons and ease of use, with no FOSS alternative being able to fulfil the role in this instance. These can be opened with FOSS software such as LibreOffice.
Minimum documentation

At a minimum, you should include some documentation alongside your model that describes:

  1. What the model does.

  2. How to install and run the model to obtain results.

  3. How to vary parameters to run new experiments.

This can be done easily using a README.md file. This is a markdown file stored in the root of your repository.

 A model README is provided here: https://github.com/RichardPilbery/DAA_DES/blob/main/README.md
ORCID

An ORCID is a free, unique, persistent ID that identifies and links authors to their research. It ensures that any outputs and publications are correctly attributed to you.

It is recommended to include your ORCID in the README.md

 Contributor ORCIDs are provided in https://github.com/RichardPilbery/DAA_DES/tree/main?tab=readme-ov-file#contributors
Citation information Including citation instructions makes it easier for others to reference and give credit to your model. Platforms like GitHub support CITATION.cff, which are files that contain details like author names, version, and links to the original work. A citation file is provided at https://github.com/RichardPilbery/DAA_DES/blob/main/CITATION.cff
Remote code repository

Remote code repositories like GitHub, GitLab, and Bitbucket help manage and share code.

  • They provide version control, allowing developers to track changes, revert to previous versions, and collaborate through branching.

  • Users can clone a repository to use a model and pull updates as improvements are made.

  • Features like issues (for discussion and bug tracking) and releases (for tagging stable versions) make collaboration easier.

The core repository is hosted here: https://github.com/RichardPilbery/DAA_DES

There is also a fork here, which is the current source for the hosted web app and may be used for some development work: https://github.com/Bergam0t/DAA_DES
Open science archive To ensure simulation models remain accessible over time, they should be stored in open science archives like Zenodo, Figshare, and the Open Science Framework. These platforms provide DOIs (Digital Object Identifiers) for citation and follow principles that guarantee long-term storage and discoverability. Unlike GitHub, which can change or be deleted, archives preserve models permanently.

An Open science archive is currently available here, though note that this currently points towards the fork, not the original repository https://doi.org/10.5281/zenodo.15555520

These details will be updated with the DOI for the version of the model relevant to any publications.

Optional Components

Requirement Requirement Information (Source: https://des.hsma.co.uk/stars.html) Details
Enhanced Documentation

Going beyond the minimum documentation requirements, good documentation should include:

  • A plain-language summary of the project context and model.

  • Licence and citation details.

  • Contribution instructions.

  • Installation instructions.

  • A structured code walk through of the model.

  • Documentation of the modelling cycle using TRAnsparent and Comprehensive model Evaluation (TRACE) (Ayllón et al. (2021)).

  • Annotated simulation reporting guidelines (e.g. STRESS-DES).

  • Clear description of model validation including its intended purpose.

Enhanced documentation is published at https://bergam0t.quarto.pub/air-ambulance-simulation/, containing some of the following:

[ ] A plain-language summary of the project context and model.

[x] Licence and citation details.

[ ] Contribution instructions.

[ ] Installation instructions.

[ ] A structured code walk through of the model.

[ ] Documentation of the modelling cycle using TRAnsparent and Comprehensive model Evaluation (TRACE) (Ayllón et al. (2021)).

[ ] Annotated simulation reporting guidelines (e.g. STRESS-DES).

[ ] Clear description of model validation including its intended purpose.
Documentation Hosting Services like GitHub Pages, GitLab Pages, BitBucket Cloud, and Quarto Pub can host documentation websites for free.

Basic documentation is hosted at https://richardpilbery.github.io/DAA_DES/.

Enhanced documentation is hosted at https://bergam0t.quarto.pub/air-ambulance-simulation/
Online Coding Environment There are tools which enable users to run code online without any installation or downloads. A FOSS example for jupyter notebooks is BinderHub (https://mybinder.org) which creates an online Jupyter environment from a public GitHub or GitLab repository. It packages the code and any dependencies into a container, from which the notebooks can be run.

A devcontainer.json file has been provided in the .devcontainer folder. This enables opening up the development environment in Github Codespaces. To access this, ensure you are logged into GitHub, then look for the green ‘Code’ button at the top of this repository. Click on this and select ‘Create codespace on main’.

You can find out more about codespaces at github.com/features/codespaces.
Model Interface

Turning your model into an application will make it more accessible to non-technical users who may be unfamiliar with coding. Python options include:

A model interface is provided using Streamlit.

The web app can be run using the command

streamlit run app/app.py
Web App Hosting Services like Streamlit Community Cloud and ShinyApps offer free hosting tiers which can be used to deploy your web app, making it freely accessible via a website link.

The web app can also be accessed without needing to install anything at daa-des-demo.streamlit.app/.

However, not that this will run more slowly and will complete fewer runs by default due to limitations of the hosting platform; it is recommended to download the app and run it locally if you are not just looking to get an idea of the app’s capabilities.