From 3b05f7253623aa5b804dd5a2e1bf026e188fb62d Mon Sep 17 00:00:00 2001 From: Lydia Haile Date: Thu, 4 Jul 2024 12:49:45 +0100 Subject: [PATCH] added vignette for resumable simulations --- vignettes/Resumable.Rmd | 203 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 203 insertions(+) create mode 100644 vignettes/Resumable.Rmd diff --git a/vignettes/Resumable.Rmd b/vignettes/Resumable.Rmd new file mode 100644 index 00000000..0c7ab475 --- /dev/null +++ b/vignettes/Resumable.Rmd @@ -0,0 +1,203 @@ + +--- +title: "Resumable Simulations" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{Resumable} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +```{r, include = FALSE, message=FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + comment = "#>", + dpi=300, + fig.width = 7 +) +``` + +```{r setup, message=FALSE, class.source = 'fold-hide'} +# Load the requisite packages: +library(malariasimulation) +library(dplyr) + +# Set colour palette: +cols <- c("#E69F00", "#56B4E9", "#009E73", "#F0E442", "#0072B2", "#D55E00", "#CC79A7") + +plot_incidence<- function(output, label){ + output$incidence <-1000 *output$n_inc_clinical_0_1825 / output$n_0_1825 + output$time_year<- output$timestep / 365 + + plot(x = output$time_year, y = output$incidence, type = "l", + xlab = "Years", ylab = "Clinical incidence per 1,000 under 5", col = cols[1], + ylim = c(min(output$incidence)-0.25, max(output$incidence)+0.25), + xaxs = "i", yaxs = "i") + curve_values <- loess(incidence ~ time_year, data = output, + span = 0.3, method = "loess") + lines(output$time_year, predict(curve_values), + col = cols[5], lwd = 3) + title(main = label) +} +``` + +In this vignette, we will demonstrate how to run a resumable malariasimulation model. This functionality can be useful to set time-varying parameters that can not be specified otherwise via malariasimulation helper functions. This can help save computational time in scenario modelling, where model parameters are the same between runs until an intervention is introduced. + + +# Run a simple simulation +To begin, we can run a regular simulation using `malariasimulation::run_simulation` for 10 years. + + +```{r} +year <- 365 +month <- 30 +eir<- 35 + +# pull standard parameters +params <- get_parameters( + list( + human_population = 10000, + individual_mosquitoes = FALSE, + clinical_incidence_rendering_min_ages = 0, + clinical_incidence_rendering_max_ages = 5 * year + ) +) + + +params <- set_equilibrium(parameters = params, init_EIR = eir) + +output<- run_simulation(params, timesteps= 10 * year) + + +plot_incidence(output, label= 'Incidence for control run') + + + +``` + +# Run a resumable simulation + +Instead of running a simulation for the entire time horizon, we can choose to run an initial simulation, save the simulation state, and then resume at a specified point using `run_resumable_simulation`. + +The arguments are as follows: + +* *timesteps* : timestep to stop the simulation +* *parameters*: input parameters +* *correlations*: correlation parameters +* *intial_state*: the state from which to resume the simulation (not needed for the first phase) +* *restore_random_state*: boolean, choice to restore the random number generator's state from the checkpoint + +Here, we will run a 10-year simulation for the first 5 years, stop, and then resume the simulation for the following 5 years. + +```{r resumable_simulation} +year<- 365 +initial_timesteps<- 5 * year +total_timesteps<- 10* year +eir<- 35 + + +params <- get_parameters( + list( + human_population = 10000, + individual_mosquitoes = FALSE, + clinical_incidence_rendering_min_ages = 0, + clinical_incidence_rendering_max_ages = 5 * year + ) +) + +params <- set_equilibrium(parameters = params, init_EIR = eir) + +# Run first phase of simulation +first_phase<- malariasimulation:::run_resumable_simulation(parameters = params, timesteps= initial_timesteps) + +# View model output from the first phase of the simulation +head(first_phase$data) + +# plot the first 5 years +plot_incidence(first_phase$data, label = 'Incidence for first phase') + +# Run second phase of simulation +second_phase<- malariasimulation:::run_resumable_simulation(timesteps= total_timesteps, + parameters = params, + initial_state = first_phase$state, + restore_random_state = TRUE) +# plot the latter 5 years +plot_incidence(second_phase$data, label = 'Incidence for second phase') + + +# bind the model outputs from first and second phase together +full_output<- rbind(first_phase$data, second_phase$data) + +# plot entire simulation period +plot_incidence(full_output, label = 'Incidence for full run') + + +``` + + +# Introduce interventions to a resumable simulation + +In this example, we will introduce a new intervention in the second phase of a resumable simulation. Note that, because of how event scheduling works, we must enable the new intervention in the inital phase of the simulation as well, with a coverage value of 0. + + +```{r intervention_resumable} +year<- 365 +initial_timesteps<- 5 * year +total_timesteps<- 10* year +eir<- 35 + +params <- get_parameters( + list( + human_population = 10000, + individual_mosquitoes = FALSE, + clinical_incidence_rendering_min_ages = 0, + clinical_incidence_rendering_max_ages = 5 * year + ) +) + +params <- set_equilibrium(parameters = params, init_EIR = eir) + +# Introduce transmission-blocking vaccine in initial phase with coverage value of 0 +tbv_timesteps<- 7* year + +params<- params |> + set_tbv(timesteps=tbv_timesteps, + coverage=0, ages=0:5) + +# update vaccine parameters so coverage is 100% +tbv_params<- params |> + set_tbv(timesteps=tbv_timesteps, + coverage=1, ages=0:5) + +# Run first phase of simulation +set.seed(7) +first_phase<- malariasimulation:::run_resumable_simulation(parameters = params, timesteps= initial_timesteps) + +# Run second phase of simulation +second_phase<- malariasimulation:::run_resumable_simulation(timesteps= total_timesteps, + parameters = tbv_params, + initial_state = first_phase$state, + restore_random_state = TRUE) +# bind the model outputs from first and second phase together +full_output<- bind_rows(first_phase$data, second_phase$data) + +# Run a control run for entire simulation period +set.seed(7) +control<- malariasimulation:::run_simulation(parameters = params, timesteps= total_timesteps) + + +# plot the first 5 years +plot_incidence(first_phase$data, label= 'Incidence for first phase') + +# plot the latter 5 years +plot_incidence(second_phase$data, label= 'Incidence for phase where vaccine was introduced') + +# plot entire simulation period +plot_incidence(full_output, label = 'Incidence for full run') + +plot_incidence(control, label= 'Incidence for control run') + +``` + + +