Merge pull request #89 from pythonhealthdatascience/dev

Dev

Author: amyheather

.Rbuildignore

@@ -3,6 +3,7 @@
 ^.*\.Rproj$
 ^\.Rproj\.user$
 ^LICENSE\.md$
+^CODE_OF_CONDUCT\.md$
 ^CONTRIBUTING\.md$
 ^docs$
 ^images$

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_mms/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_mms/blob/main/CODE_OF_CONDUCT.md) for details.

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: simulation
 Type: Package
 Title: Simulation
-Version: 0.1.0
+Version: 0.4.0
 Authors@R: c(
     person(
       "Amy", "Heather",
@@ -18,7 +18,6 @@ LazyData: true
 RoxygenNote: 7.3.2
 Imports:
     simmer,
-    magrittr,
     dplyr,
     purrr,
     rlang,
@@ -42,5 +41,6 @@ Suggests:
     lubridate,
     plotly,
     covr,
-    DT
+    DT,
+    queueing
 Config/testthat/edition: 3

NAMESPACE

@@ -11,6 +11,7 @@ export(calc_mean_wait)
 export(calc_unseen_mean)
 export(calc_unseen_n)
 export(calc_utilisation)
+export(check_log_file_path)
 export(confidence_interval_method)
 export(filter_warmup)
 export(get_run_results)
@@ -53,7 +54,6 @@ importFrom(ggplot2,ggsave)
 importFrom(ggplot2,labs)
 importFrom(ggplot2,theme_minimal)
 importFrom(gridExtra,marrangeGrob)
-importFrom(magrittr,"%>%")
 importFrom(purrr,reduce)
 importFrom(rlang,.data)
 importFrom(simmer,add_generator)

R/choose_replications.R

@@ -114,7 +114,9 @@ WelfordStats <- R6Class("WelfordStats", list( # nolint: object_name_linter
   #' @description Computes the precision of the confidence interval expressed
   #' as the percentage deviation of the half width from the mean.
   deviation = function() {
-    self$half_width() / self$mean
+    mw <- self$mean
+    if (is.na(mw) || mw == 0L) return(NA_real_)
+    self$half_width() / mw
   }
 ))
 
@@ -413,7 +415,13 @@ ReplicationsAlgorithm <- R6Class("ReplicationsAlgorithm", list( # nolint: object
 
     # Whilst have not yet got all metrics marked as solved = TRUE, and still
     # under replication budget + lookahead...
-    while (!all(unlist(lapply(solutions, function(x) x$solved))) &&
+    is_all_solved <- function(solutions_list) {
+      statuses <- unlist(lapply(solutions_list, function(x) x$solved))
+      # If any are NA or FALSE, treat as not solved
+      all(statuses)
+    }
+
+    while (!is_all_solved(solutions) &&
              self$reps < self$replication_budget + self$klimit()) {
 
       # Increment counter
@@ -455,6 +463,7 @@ ReplicationsAlgorithm <- R6Class("ReplicationsAlgorithm", list( # nolint: object
             # If precision was not achieved, ensure nreps is None (e.g. in cases
             # where precision is lost after a success)
             solutions[[metric]]$nreps <- NA
+            solutions[[metric]]$target_met <- 0L
           }
 
         }

R/get_run_results.R

@@ -37,7 +37,8 @@ get_run_results <- function(results, run_number) {
       calc_mean_serve_length(results[["arrivals"]], results[["resources"]]),
       calc_utilisation(results[["resources"]]),
       calc_unseen_n(results[["arrivals"]]),
-      calc_unseen_mean(results[["arrivals"]])
+      calc_unseen_mean(results[["arrivals"]]),
+      calc_mean_time_in_system(results[["arrivals"]])
     )
     # Combine metrics + replication number in a single dataframe
     dplyr::bind_cols(tibble(replication = run_number), metrics)
@@ -319,3 +320,24 @@ calc_unseen_mean <- function(arrivals, groups = NULL) {
                 names_glue = "mean_waiting_time_unseen_{resource}") |>
     ungroup()
 }
+
+
+#' Calculate the mean time in the system for finished patients.
+#'
+#' @param arrivals Dataframe with times for each patient with each resource.
+#' @param groups Optional list of columns to group by for the calculation.
+#'
+#' @return Tibble with column containing the mean time in the system.
+
+calc_mean_time_in_system <- function(arrivals, groups = NULL) {
+  # If provided, group the dataset
+  if (!is.null(groups)) {
+    arrivals <- group_by(arrivals, across(all_of(groups)))
+  }
+  # Calculate number of arrivals
+  arrivals |>
+    summarise(
+      mean_time_in_system = mean(.data[["time_in_system"]], na.rm = TRUE)
+    ) |>
+    ungroup()
+}