Merge pull request #21 from pythonhealthdatascience/dev

Dev

Author: amyheather

CITATION.cff

@@ -14,10 +14,15 @@ authors:
     email: a.heather2@exeter.ac.uk
     affiliation: University of Exeter
     orcid: 'https://orcid.org/0000-0002-6596-3479'
+  - given-names: Tom
+    family-names: Monks
+    email: t.m.w.monks@exeter.ac.uk
+    affiliation: University of Exeter Medical School
+    orcid: http://orcid.org/0000-0003-2631-4481
 repository-code: >-
   https://github.com/pythonhealthdatascience/rdesrap_stroke
 abstract: >-
   Reproducible analytical pipeline (RAP) for R discrete-event simulation (DES)
   implementing the Stroke Capacity Planning Model from Monks et al. 2016.
-version: 0.2.0
-date-released: '2025-08-12'
+version: 0.3.0
+date-released: '2025-11-07'

CODE_OF_CONDUCT.md

@@ -0,0 +1,127 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org/), version 2.1,
+available at
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct/>.
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/inclusion).
+
+For answers to common questions about this code of conduct, see the FAQ at
+<https://www.contributor-covenant.org/faq/>. Translations are available at
+<https://www.contributor-covenant.org/translations/>.

CONTRIBUTING.md

@@ -1,16 +1,124 @@
 # Contributing
 
-🎉 Thank you for checking out our project! 🎉
+Thank you for your interest in contributing! 🤗
 
-This file contains guidelines on how to get in touch with us and potentially contribute towards this repository.
+This file covers:
 
-## Email
+* 🐞 Workflow for bug reports, feature requests and documentation improvements
+* 🚀 Workflow for code contributions (bug fixes, enhancements)
+* 🛠️ Development and testing
+* 📦 Updating the package
+* 🤝 Code of conduct
 
-You can contact the researchers on this project using the provided email addresses in `CITATION.cff`.
+<br>
 
-## Suggesting changes
+## 🐞 Workflow for bug reports, feature requests and documentation improvements
 
-If you spot an issue, you are welcome to raise this either by:
+Before opening an issue, please search [existing issues](https://github.com/pythonhealthdatascience/rdesrap_stroke/issues) to avoid duplicates. If an issue exists, you can add a comment with additional details and/or upvote (👍) the issue. If there is not an existing issue, please open one and provide as much detail as possible.
 
-* Using **GitHub Issues**.
-* **Forking** the repository, make your changes and submit a pull request for review.
+* **For feature requests or documentation improvements**, please describe your suggestion clearly.
+* **For bugs**, include:
+    * Steps to reproduce.
+    * Expected and actual behaviour.
+    * Environment details (operating system, R version, dependencies).
+    * Relevant files (e.g. problematic `.qmd` files).
+
+### Handling bug reports (for maintainers):
+
+* Confirm reproducibility by following the reported steps.
+* Label the issue appropriately (e.g. `bug`).
+* Request additional information if necessary.
+* Link related issues or pull requests.
+* Once resolved, close the issue with a brief summary of the fix.
+
+<br>
+
+## 🚀 Workflow for code contributions (bug fixes, enhancements)
+
+1. Fork the repository and clone your fork.
+
+2. Create a new branch for your feature or fix:
+
+```{.bash}
+git checkout -b my-feature
+```
+
+3. Make your changes and commit them with clear, descriptive messages using the [conventional commits standard](https://www.conventionalcommits.org/en/v1.0.0/).
+
+4. Push your branch to your fork:
+
+```{.bash}
+git push origin my-feature
+```
+
+5. Open a pull request against the main branch. Describe your changes and reference any related issues.
+
+<br>
+
+## 🛠️ Development and testing
+
+### Dependencies
+
+Set up the R environment using `renv` (recommended):
+
+```{.r}
+renv::init()
+renv::restore()
+```
+
+If you encounter issues restoring the exact environment, you can install dependencies from `DESCRIPTION` and generate your own lock file:
+
+```{.r}
+renv::init()
+renv::install()
+renv::snapshot()
+```
+
+Some packages (e.g. `igraph`) may require system libraries. For example, for Ubuntu:
+
+```{.bash}
+sudo apt install build-essential gfortran
+sudo apt install libglpk-dev libxml2-dev
+```
+
+<br>
+
+### Tests
+
+Run tests:
+
+```{.r}
+devtools::test()
+```
+
+Compute test coverage:
+
+```{.r}
+devtools::test_coverage()
+```
+
+<br>
+
+### Linting
+
+```{.r}
+lintr::lint_dir()
+```
+
+<br>
+
+## 📦 Updating the package
+
+If you are a maintainer and need to publish a new release:
+
+1. Update `NEWS.md`.
+
+2. Update the version number in `DESCRIPTION`, `CITATION.cff` and `CITATION`, and update the date in `CITATION.cff`.
+
+3. Create a release on GitHub, which will automatically archive to Zenodo.
+
+<br>
+
+## 🤝 Code of conduct
+
+Please be respectful and considerate. See the [code of conduct](https://github.com/pythonhealthdatascience/rdesrap_stroke/blob/main/CODE_OF_CONDUCT.md) for details.

DESCRIPTION

@@ -1,12 +1,17 @@
 Package: simulation
 Type: Package
 Title: Simulation
-Version: 0.1.0
+Version: 0.3.0
 Authors@R: c(
     person(
       "Amy", "Heather",
       email = "a.heather2@exeter.ac.uk",
       role = c("aut", "cre")
+    ),
+    person(
+      "Tom", "Monks",
+      email = "t.m.w.monks@exeter.ac.uk",
+      role = c("ctb")
     )
   )
 URL: https://github.com/pythonhealthdatascience/rdesrap_stroke

NAMESPACE

@@ -26,6 +26,7 @@ importFrom(dplyr,group_by)
 importFrom(dplyr,mutate)
 importFrom(dplyr,rowwise)
 importFrom(dplyr,ungroup)
+importFrom(future,availableCores)
 importFrom(future,multisession)
 importFrom(future,plan)
 importFrom(future,sequential)
@@ -46,7 +47,16 @@ importFrom(simmer,simmer)
 importFrom(simmer,timeout)
 importFrom(simmer,trajectory)
 importFrom(simmer,wrap)
+importFrom(stats,rbeta)
+importFrom(stats,rbinom)
+importFrom(stats,rchisq)
 importFrom(stats,rexp)
+importFrom(stats,rgamma)
+importFrom(stats,rgeom)
 importFrom(stats,rlnorm)
+importFrom(stats,rnorm)
+importFrom(stats,rpois)
+importFrom(stats,rt)
+importFrom(stats,runif)
 importFrom(stats,setNames)
 importFrom(utils,capture.output)

NEWS.md

@@ -1,3 +1,20 @@
+# Stroke capacity planning model: R DES RAP 0.3.0
+
+Introduces a code of conduct and new test, and includes improvements to documentation, contributor and parameter use.
+
+## New features
+
+* Add `CODE_OF_CONDUCT.md`.
+* Add test for model with no arrivals.
+
+## Other changes
+
+* Greatly improved/expanded `CONTRIBUTING.md`.
+* Add Tom to `CITATION.cff` and `DESCRIPTION`.
+* Corrections to docstrings (e.g., add missing `@importFrom`).
+* `verbose` is local parameter in `model` rather than part of `param` list.
+* Improvements to `README.md`.
+
 # Stroke capacity planning model: R DES RAP 0.2.0
 
 Introduces `DistributionRegistry` with JSON-based parameters, replacing individual parameter functions and CSV. Also add test coverage, add file path check, and documentation and dependency management updates.
@@ -26,4 +43,4 @@ Introduces `DistributionRegistry` with JSON-based parameters, replacing individu
 * Reproduction of paper results (`rmarkdown/analysis.Rmd`).
 * Other RMarkdown files to generate results for tests, demonstrate logging, and how parameters can be loaded from a csv (`rmarkdown/`).
 * Back, functional and unit tests (`tests/`).
-* Other features include continuous integration (tests and linting), checklists, R environment, and other metadata.
+* Other features include continuous integration (tests and linting), checklists, R environment, and other metadata.

R/add_patient_generator.R

@@ -18,7 +18,6 @@
 #' arrival intervals (e.g., \code{param$asu_arrivals$stroke = 10}).
 #'
 #' @importFrom simmer add_generator
-#' @importFrom stats rexp
 #'
 #' @return The modified Simmer environment with the new patient generator added.
 #' @export

R/create_asu_trajectory.R

@@ -15,7 +15,6 @@
 #'
 #' @importFrom simmer branch get_attribute log_ release seize set_attribute
 #' @importFrom simmer timeout trajectory
-#' @importFrom stats rlnorm
 #'
 #' @return Simmer trajectory object. Defines patient journey logic through the
 #' healthcare system.

R/create_rehab_trajectory.R

@@ -15,7 +15,6 @@
 #'
 #' @importFrom simmer get_attribute log_ release seize set_attribute timeout
 #' @importFrom simmer trajectory
-#' @importFrom stats rlnorm
 #'
 #' @return Simmer trajectory object. Defines patient journey logic through the
 #' healthcare system.

R/distribution_registry.R

@@ -13,7 +13,11 @@
 #' at any time, use `register()`.
 #'
 #' @docType class
+#'
 #' @importFrom R6 R6Class
+#' @importFrom stats rbeta rbinom rchisq rexp rgeom rgamma rlnorm rnorm rpois
+#' @importFrom stats rt runif
+#'
 #' @export
 
 DistributionRegistry <- R6Class("DistributionRegistry", list( # nolint: object_name_linter