Merge pull request #7 from pythonhealthdatascience/defaults

feat(defaults)+style(notebooks): extract parameter list within model(), and set .Rmd output as github_document

Author: amyheather

.Rbuildignore

@@ -9,5 +9,5 @@
 ^\.github$
 ^\.lintr$
 ^outputs$
-^notebooks$
+^rmarkdown$
 ^CITATION\.cff$

.github/workflows/R-CMD-check.yaml

@@ -4,6 +4,7 @@ on:
   push:
     branches: [main, master]
   pull_request:
+  workflow_dispatch:
 
 name: R-CMD-check.yaml
 

.github/workflows/lint.yaml

@@ -3,6 +3,8 @@
 
 on:
   push:
+    branches: [main]
+  pull_request:
   workflow_dispatch:
 
 name: lint
@@ -30,6 +32,6 @@ jobs:
         run: lintr::lint_package()
         shell: Rscript {0}
 
-      - name: Lint notebooks
-        run: lintr::lint_dir("notebooks")
+      - name: Lint rmarkdown
+        run: lintr::lint_dir("rmarkdown")
         shell: Rscript {0}

NAMESPACE

@@ -2,7 +2,6 @@
 
 export(Defaults)
 export(defaults)
-export(get_param)
 export(model)
 export(process_replications)
 export(trial)

R/defaults.R

@@ -92,25 +92,11 @@ Defaults <- R6Class( # nolint
 #' `defaults()` is a wrapper which enables us to create a new instance of
 #' the class without needing to run `Defaults[["new"]]()` every time.
 #'
+#' @return Instance of the Defaults class.
+#' 
 #' @export
 #' @rdname defaults
 
 defaults <- function() {
   return(Defaults[["new"]]())
 }
-
-#' Wrapper for Defaults() R6 class, to get the list of parameters.
-#'
-#' `get_param()` is a wrapper which enables us to extract the list of
-#' parameters from the class more easily. For example, if we create
-#' `param_class <- defaults()`, we can then run `get_param(param_class)`
-#' instead of `param_class[["get]]()`.
-#'
-#' @param param_class Instance of the Defaults parameter class.
-#'
-#' @export
-#' @rdname defaults
-
-get_param <- function(param_class) {
-  return(param_class[["get"]]())
-}

R/model.R

@@ -1,7 +1,7 @@
 #' Run simulation
 #'
 #' @param run_number Integer representing index of current simulation run.
-#' @param param List containing parameters for the simulation.
+#' @param param_class Instance of Defaults containing model parameters.
 #'
 #' @importFrom simmer trajectory seize timeout release simmer add_resource
 #' @importFrom simmer add_generator run wrap get_mon_arrivals
@@ -12,7 +12,14 @@
 #' @return Named list with two tables: monitored arrivals and resources
 #' @export
 
-model <- function(run_number, param) {
+model <- function(run_number, param_class) {
+
+  # Extract parameter list from the parameter class
+  # It is important to do this within the model function (rather than
+  # beforehand), to ensure any updates to the parameter list undergo
+  # checks from the Defaults R6 class (i.e. ensuring they are replacing
+  # existing keys in the list)
+  param <- param_class[["get"]]()
 
   # Check all inputs are valid
   valid_inputs(run_number, param)

R/trial.R

@@ -4,31 +4,35 @@
 #' `mcLapply`` does not work on Windows and `future_lapply`` would often get
 #' stuck.
 #'
-#' @param param List containing parameters for the simulations.
+#' @param param_class Instance of Defaults containing model parameters.
 #'
 #' @importFrom parallel detectCores makeCluster stopCluster clusterEvalQ
 #' @importFrom parallel clusterExport parLapply
 #'
 #' @return Named list with two tables: monitored arrivals and resources.
 #' @export
 
-trial <- function(param) {
-  if (param[["cores"]] == 1L) {
+trial <- function(param_class) {
+  # Get specified number of cores
+  n_cores <- param_class[["get"]]()[["cores"]]
+  n_runs <- param_class[["get"]]()[["number_of_runs"]]
+
+  if (n_cores == 1L) {
 
     # Sequential execution
     results <- lapply(
-      1L:param[["number_of_runs"]],
-      function(i) simulation::model(run_number = i, param = param)
+      1L:n_runs,
+      function(i) simulation::model(run_number = i, param_class = param_class)
     )
 
   } else {
     # Parallel execution
 
     # Create a cluster with specified number of cores
-    if (param[["cores"]] == -1L) {
+    if (n_cores == -1L) {
       cores <- detectCores() - 1L
     } else {
-      cores <- param[["cores"]]
+      cores <- n_cores
     }
     cl <- makeCluster(cores)
 
@@ -37,13 +41,13 @@ trial <- function(param) {
 
     # Run simulations in parallel
     results <- parLapply(
-      cl, 1L:param[["number_of_runs"]],
-      function(i) simulation::model(run_number = i, param = param)
+      cl, 1L:n_runs,
+      function(i) simulation::model(run_number = i, param_class = param_class)
     )
   }
 
   # Combine the results from multiple replications into just two dataframes
-  if (param[["number_of_runs"]] > 1L) {
+  if (n_runs > 1L) {
     all_arrivals <- do.call(
       rbind, lapply(results, function(x) x[["arrivals"]])
     )

README.md

@@ -46,7 +46,7 @@ This repository provides a template for building discrete-event simulation (DES)
 
 ✨ **Design practices:** Functions are documented with `roxygen2` docstrings and `lintr` is used to lint `.R` and `.Rmd` files.
 
-🧱 **Package structure:** The simulation code (`R/`) is structured as a little local R package. It is installed in our environment using `devtools::install()` and then `library(simulation)`. This means it can easily be used anywhere else in the directory - here, in `notebooks/` and `tests/` - without needing any additional code (e.g. no need to run `source()` with paths to the files).
+🧱 **Package structure:** The simulation code (`R/`) is structured as a little local R package. It is installed in our environment using `devtools::install()` and then `library(simulation)`. This means it can easily be used anywhere else in the directory - here, in `rmarkdown/` and `tests/` - without needing any additional code (e.g. no need to run `source()` with paths to the files).
 
 <details markdown="1">
 <summary><b>More information about the package structure</b></summary>
@@ -57,7 +57,7 @@ This repository provides a template for building discrete-event simulation (DES)
 
 * Encourages well-organised repository following **standardised** established R package structure, which ensures that the model and analysis code are kept seperate.
 * Useful "built-in" features like **tests**, documentation of functions using **Roxygen**, documentation of data, and **package checks** (e.g. checking all imports are declared).
-* If your analysis has a short run time, the `.Rmd` files could be stored in a `vignettes/` folder which will mean they **re-run with every package build/check**, and so any new run issues will be identified. However, in this project, the analysis was instead stored in `notebooks/` as the file paths to save outputs cause errors in `vignettes/` (as they will differ between your runs of the notebook, and runs during the package build process).
+* If your analysis has a short run time, the `.Rmd` files could be stored in a `vignettes/` folder which will mean they **re-run with every package build/check**, and so any new run issues will be identified. However, in this project, the analysis was instead stored in `rmarkdown/` as the file paths to save outputs cause errors in `vignettes/` (as they will differ between your runs of the notebook, and runs during the package build process).
 * Meet packaging **requirement** on the NHS "Levels of RAP" framework.
 
 For more information on the rationale behind structuring research as an R package, check out:
@@ -156,7 +156,7 @@ sudo apt install libglpk-dev libxml2-dev
 
 🔎 Choose your desired licence (e.g. <https://choosealicense.com/>). If keeping an MIT licence, just modify the copyright holder in `LICENSE` and `LICENSE.md`.
 
-🔎 Review the example DES implementation in `R/` and `notebooks/`. Modify and extend the code as needed for your specific use case.
+🔎 Review the example DES implementation in `R/` and `rmarkdown/`. Modify and extend the code as needed for your specific use case.
 
 🔎 Check you still fulfil the criteria in `docs/nhs_rap.md` and `docs/heather_2025.md`.
 
@@ -188,10 +188,10 @@ You can lint the `.R` and `.Rmd` files by running:
 
 ```
 lintr::lint_package()
-lintr::lint_dir("notebooks")
+lintr::lint_dir("rmarkdown")
 ```
 
-The `lint_package()` function will run on files typically included in a package (i.e. `R/`, `tests/`). This will not include `notebooks/` as it is not typical/excluded from our package build, and so we can lint that by specifying the directory for `lint_dir()`.
+The `lint_package()` function will run on files typically included in a package (i.e. `R/`, `tests/`). This will not include `rmarkdown/` as it is not typical/excluded from our package build, and so we can lint that by specifying the directory for `lint_dir()`.
 
 <br>
 
@@ -211,10 +211,10 @@ repo/
 ├── docs/                       # Documentation
 ├── images/                     # Image files and GIFs
 ├── man/                        # Function documentation generated by roxygen
-├── notebooks/                  # Run DES model and analyse results
 ├── outputs/                    # Folder to save any outputs from model
 ├── R/                          # Local package containing code for the DES model
 ├── renv/                       # Instructions for creation of R environment
+├── rmarkdown/                  # .Rmd files to run DES model and analyse results
 ├── tests/                      # Unit and back testing of the DES model
 ├── .gitignore                  # Untracked files
 ├── .lintr                      # Lintr settings
@@ -236,7 +236,7 @@ repo/
 
 ## ⏰ Run time and machine specification
 
-The overall run time will vary depending on how the template model is used. A few example implementations are provided in `notebooks/` and the run times for these were:
+The overall run time will vary depending on how the template model is used. A few example implementations are provided in `rmarkdown/` and the run times for these were:
 
 * `analysis.Rmd`: 42s
 * `choosing_parameters.Rmd`: 56s