From da95b18cc7db2d8f6ee4af8a680ad266ead64304 Mon Sep 17 00:00:00 2001 From: RJSheppard Date: Thu, 2 May 2024 11:21:11 +0100 Subject: [PATCH] There are a few parameter documentation things I think it would be good to tidy up. First, n_severe isn't a prevalence output (model.R). I've reorganised the parameter documentation list into an order I think is a bit more intuitive, with consistency between code and documentation. --- R/model.R | 13 +- R/parameters.R | 382 ++++++++++++++++++++++-------------------- man/get_parameters.Rd | 226 ++++++++++++++----------- man/run_simulation.Rd | 3 - 4 files changed, 332 insertions(+), 292 deletions(-) diff --git a/R/model.R b/R/model.R index 67f79758..2cfc7e75 100644 --- a/R/model.R +++ b/R/model.R @@ -11,7 +11,7 @@ #' * infectivity: the infectivity from humans towards mosquitoes #' * FOIM: the force of infection towards mosquitoes (per species) #' * mu: the death rate of adult mosquitoes (per species) -#' * EIR: the Entomological Inoculation Rate (per timestep, per species, over +#' * EIR: the Entomological Inoculation Rate (per timestep, per species, over #' the whole population) #' * n_bitten: number of humans bitten by an infectious mosquito #' * n_treated: number of humans treated for clinical or severe malaria this timestep @@ -36,19 +36,16 @@ #' inclusive age range at this timestep. This #' defaults to p_detect_730_3650. Other age ranges can be set with #' prevalence_rendering_min_ages and prevalence_rendering_max_ages parameters. -#' * n_severe: number of humans with a severe infection between an inclusive -#' age range at this timestep. Age ranges can be set with -#' severe_prevalence_rendering_min_ages and severe_prevalence_rendering_max_ages parameters. #' * n_inc: number of new infections for humans between an inclusive age range at this timestep. #' incidence columns can be set with #' incidence_rendering_min_ages and incidence_rendering_max_ages parameters. #' * p_inc: sum of probabilities of infection for humans between an inclusive age range at this timestep. #' incidence columns can be set with #' incidence_rendering_min_ages and incidence_rendering_max_ages parameters. -#' * n_inc_clinical: number of new clinical infections for humans between an inclusive age range at this timestep. +#' * n_inc_clinical: number of new clinical infections for humans between an inclusive age range at this timestep. #' clinical incidence columns can be set with #' clinical_incidence_rendering_min_ages and clinical_incidence_rendering_max_ages parameters. -#' * p_inc_clinical: sub of probabilities of clinical infection for humans between an inclusive age range at this timestep. +#' * p_inc_clinical: sub of probabilities of clinical infection for humans between an inclusive age range at this timestep. #' clinical incidence columns can be set with #' clinical_incidence_rendering_min_ages and clinical_incidence_rendering_max_ages parameters. #' * n_inc_severe: number of new severe infections for humans between an inclusive age range at this timestep. @@ -193,7 +190,7 @@ run_resumable_simulation <- function( #' @param correlations a list of correlation parameters for each population #' (default: NULL) #' @param mixing matrix of mixing coefficients for infectivity towards -#' mosquitoes. Rows = origin sites, columns = destinations. Each element must +#' mosquitoes. Rows = origin sites, columns = destinations. Each element must #' be between 0 and 1 and all rows must sum to 1. #' @return a list of dataframe of results #' @export @@ -280,7 +277,7 @@ run_metapop_simulation <- function( events = unlist(events), timesteps = timesteps ) - + lapply(renderer, function(r) r$to_dataframe()) } diff --git a/R/parameters.R b/R/parameters.R index 647b78b2..d8bff3d7 100644 --- a/R/parameters.R +++ b/R/parameters.R @@ -8,17 +8,39 @@ #' @param overrides a named list of parameter values to use instead of defaults #' The parameters are defined below. #' -#' fixed state transitions: +#' initial state proportions: +#' +#' * s_proportion - the proportion of `human_population` that begin as susceptible; default = 0.420433246 +#' * d_proportion - the proportion of `human_population` that begin with +#' clinical disease; default = 0.007215064 +#' * a_proportion - the proportion of `human_population` that begin as +#' asymptomatic; default = 0.439323667 +#' * u_proportion - the proportion of `human_population` that begin as +#' subpatents; default = 0.133028023 +#' * t_proportion - the proportion of `human_population` that begin treated; default = 0 +#' +#' human fixed state transitions: #' #' * dd - the delay for humans to move from state D to A; default = 5 #' * dt - the delay for humans to move from state Tr to S; default = 5 #' * da - the delay for humans to move from state A to U; default = 195 #' * du - the delay for humans to move from state U to S; default = 110 -#' * del - the delay for mosquitoes to move from state E to L; default = 6.64 -#' * dl - the delay for mosquitoes to move from state L to P; default = 3.72 -#' * dpl - the delay mosquitoes to move from state P to Sm; default = 0.643 -#' * mup - the rate at which pupal mosquitoes die; default = 0.249 -#' * mum - the rate at which developed mosquitoes die; default (An. gambiae) = .132 +#' +#' human demography parameters: +#' +#' * human_population - the initial number of humans to model; default = 100 +#' * average_age - the average age of humans (in timesteps), this is only used +#' if custom_demography is FALSE; default = 7663 +#' * custom_demography - population demography given; default = FALSE +#' +#' initial immunity values: +#' +#' * init_icm - the immunity from clinical disease at birth; default = 0 +#' * init_ivm - the immunity from severe disease at birth; default = 0 +#' * init_ib - the initial pre-erythrocitic immunity; default = 0 +#' * init_ica - the initial acquired immunity from clinical disease; default = 0 +#' * init_iva - the initial acquired immunity from severe disease; default = 0 +#' * init_id - the initial acquired immunity to detectability; default = 0 #' #' immunity decay rates: #' @@ -29,6 +51,26 @@ #' * rva - decay rate for acquired immunity to severe disease; default = 10950 #' * rid - decay rate for acquired immunity to detectability; default = 3650 #' +#' immunity boost grace periods: +#' +#' * ub - period in which pre-erythrocytic immunity cannot be boosted; default = 7.2 +#' * uc - period in which clinical immunity cannot be boosted; default = 6.06 +#' * uv - period in which severe immunity cannot be boosted; default = 11.4321 +#' * ud - period in which immunity to detectability cannot be boosted; default = 9.44512 +#' +#' maternal immunity parameters: +#' +#' * pcm - new-born clinical immunity relative to mother's; default = 0.774368 +#' * pvm - new-born severe immunity relative to mother's; default = 0.195768 +#' +#' unique biting rate: +#' +#' * a0 - age dependent biting parameter; default = 2920 +#' * rho - age dependent biting parameter; default = 0.85 +#' * sigma_squared - heterogeneity parameter; default = 1.67 +#' * n_heterogeneity_groups - number discretised groups for heterogeneity, used +#' for sampling mothers; default = 5 +#' #' probability of pre-erythrocytic infection: #' #' * b0 - maximum probability due to no immunity; default = 0.59 @@ -36,6 +78,15 @@ #' * ib0 - scale parameter; default = 43.9 #' * kb - shape parameter; default = 2.16 #' +#' probability of detection by light-microscopy when asymptomatic: +#' +#' * fd0 - time-scale at which immunity changes with age; default = 0.007055 +#' * ad - scale parameter relating age to immunity; default = 7993.5 +#' * gammad - shape parameter relating age to immunity; default = 4.8183 +#' * d1 - minimum probability due to immunity; default = 0.160527 +#' * id0 - scale parameter; default = 1.577533 +#' * kd - shape parameter; default = 0.476614 +#' #' probability of clinical infection: #' #' * phi0 - maximum probability due to no immunity; default = 0.792 @@ -53,22 +104,6 @@ #' * av - age dependent modifier; default = 2493.41 #' * gammav - age dependent modifier; default = 2.91282 #' -#' immunity reducing probability of detection: -#' -#' * fd0 - time-scale at which immunity changes with age; default = 0.007055 -#' * ad - scale parameter relating age to immunity; default = 7993.5 -#' * gammad - shape parameter relating age to immunity; default = 4.8183 -#' * d1 - minimum probability due to immunity; default = 0.160527 -#' * id0 - scale parameter; default = 1.577533 -#' * kd - shape parameter; default = 0.476614 -#' -#' immunity boost grace periods: -#' -#' * ub - period in which pre-erythrocytic immunity cannot be boosted; default = 7.2 -#' * uc - period in which clinical immunity cannot be boosted; default = 6.06 -#' * uv - period in which severe immunity cannot be boosted; default = 11.4321 -#' * ud - period in which immunity to detectability cannot be boosted; default = 9.44512 -#' #' infectivity towards mosquitoes: #' #' * cd - infectivity of clinically diseased humans towards mosquitoes; default = 0.068 @@ -76,61 +111,20 @@ #' * cu - infectivity of sub-patent infection; default = 0.0062 #' * ct - infectivity of treated infection; default = 0.021896 #' -#' unique biting rate: +#' mosquito fixed state transitions (including mortality): #' -#' * a0 - age dependent biting parameter; default = 2920 -#' * rho - age dependent biting parameter; default = 0.85 -#' * sigma_squared - heterogeneity parameter; default = 1.67 -#' * n_heterogeneity_groups - number discretised groups for heterogeneity, used -#' for sampling mothers; default = 5 -#' -#' mortality parameters: -#' -#' * average_age - the average age of humans (in timesteps), this is only used -#' if custom_demography is FALSE; default = 7663 -#' * pcm - new-born clinical immunity relative to mother's; default = 0.774368 -#' * pvm - new-born severe immunity relative to mother's; default = 0.195768 +#' * del - the delay for mosquitoes to move from state E to L; default = 6.64 +#' * dl - the delay for mosquitoes to move from state L to P; default = 3.72 +#' * dpl - the delay mosquitoes to move from state P to Sm; default = 0.643 #' * me - early stage larval mortality rate; default = 0.0338 #' * ml - late stage larval mortality rate; default = 0.0348 -#' -#' carrying capacity parameters: -#' -#' * model_seasonality - boolean switch TRUE iff the simulation models seasonal rainfall; default = FALSE -#' * g0 - rainfall fourier parameter; default = 2 -#' * g - rainfall fourier parameter; default = 0.3, 0.6, 0.9 -#' * h - rainfall fourier parameters; default = 0.1, 0.4, 0.7 -#' * gamma - effect of density dependence on late instars relative to early -#' instars; default = 13.25 -#' * rainfall_floor - the minimum rainfall value (must be above 0); default 0.001 -#' -#' initial state proportions: -#' -#' * s_proportion - the proportion of `human_population` that begin as susceptible; default = 0.420433246 -#' * d_proportion - the proportion of `human_population` that begin with -#' clinical disease; default = 0.007215064 -#' * a_proportion - the proportion of `human_population` that begin as -#' asymptomatic; default = 0.439323667 -#' * u_proportion - the proportion of `human_population` that begin as -#' subpatents; default = 0.133028023 -#' * t_proportion - the proportion of `human_population` that begin treated; default = 0 -#' -#' initial immunity values: -#' -#' * init_icm - the immunity from clinical disease at birth; default = 0 -#' * init_ivm - the immunity from severe disease at birth; default = 0 -#' * init_ib - the initial pre-erythrocitic immunity; default = 0 -#' * init_ica - the initial acquired immunity from clinical disease; default = 0 -#' * init_iva - the initial acquired immunity from severe disease; default = 0 -#' * init_id - the initial acquired immunity to detectability; default = 0 -#' -#' incubation periods: -#' -#' * de - Duration of the human latent period of infection; default = 12 -#' * delay_gam - Lag from parasites to infectious gametocytes; default = 12.5 -#' * dem - Extrinsic incubation period in mosquito population model; default = 10 +#' * mup - the rate at which pupal mosquitoes die; default = 0.249 +#' * mum - the rate at which developed mosquitoes die; default (An. gambiae) = .132 #' #' vector biology: #' species specific values are vectors +#' please set species parameters using the convenience function +#' `set_species` #' #' * beta - the average number of eggs laid per female mosquito per day; default = 21.2 #' * total_M - the initial number of adult mosquitos in the simulation; default = 1000 @@ -141,18 +135,30 @@ #' * Q0 - proportion of blood meals taken on humans; default = 0.92 #' * foraging_time - time spent taking blood meals; default = 0.69 #' -#' feeding cycle: -#' please set vector control strategies using `set_betnets` and `set_spraying` +#' seasonality and carrying capacity parameters: +#' please set flexible carrying capacity using the convenience function +#' `set_carrying_capacity` #' -#' * bednets - boolean for if bednets are enabled; default = FALSE -#' * phi_bednets - proportion of bites taken in bed; default = 0.85 -#' * k0 - proportion of females bloodfed with no net; default = 0.699 -#' * spraying - boolean for if indoor spraying is enabled; default = FALSE -#' * phi_indoors - proportion of bites taken indoors; default = 0.90 +#' * model_seasonality - boolean switch TRUE iff the simulation models seasonal rainfall; default = FALSE +#' * g0 - rainfall fourier parameter; default = 2 +#' * g - rainfall fourier parameter; default = 0.3, 0.6, 0.9 +#' * h - rainfall fourier parameters; default = 0.1, 0.4, 0.7 +#' * gamma - effect of density dependence on late instars relative to early +#' instars; default = 13.25 +#' * rainfall_floor - the minimum rainfall value (must be above 0); default 0.001 +#' * carrying_capacity; default = FALSE +#' * carrying_capacity_timesteps; default = NULL +#' * carrying_capacity_values; default = NULL#' +#' +#' parasite incubation periods: +#' +#' * de - duration of the human latent period of infection; default = 12 +#' * delay_gam - lag from parasites to infectious gametocytes; default = 12.5 +#' * dem - extrinsic incubation period in mosquito population model; default = 10 #' #' treatment parameters: -#' please set treatment parameters with the convenience functions in -#' `drug_parameters.R` +#' please set treatment parameters with the convenience functions +#' `set_drugs` and `set_clinical_treatment` #' #' * drug_efficacy - a vector of efficacies for available drugs; default = turned off #' * drug_rel_c - a vector of relative onward infectiousness values for drugs; default = turned off @@ -162,23 +168,36 @@ #' model prophylaxis for each drug; default = turned off #' * clinical_treatment_drugs - a vector of drugs that are available for #' clinically diseased (these values refer to the index in drug_* parameters); default = NULL, NULL, NULL -#' * clinical_treatment_coverage - a vector of coverage values for each drug; default = NULL, NULL, NULL +#' * clinical_treatment_coverage - a vector of coverage values for each drug; default = NULL, NULL, NULL#' +#' +#' MDA, SMC and PMC parameters: +#' please set these parameters with the convenience functions +#' `set_mda`, `set_smc` and `set_pmc`, +#' with `peak_season_offset` +#' +#' bednet, irs and mosquito feeding cycle parameters: +#' please set vector control strategies using `set_betnets` and `set_spraying` #' -#' PEV parameters: +#' * bednets - boolean for if bednets are enabled; default = FALSE +#' * phi_bednets - proportion of bites taken in bed; default = 0.85 +#' * k0 - proportion of females bloodfed with no net; default = 0.699 +#' * spraying - boolean for if indoor spraying is enabled; default = FALSE +#' * phi_indoors - proportion of bites taken indoors; default = 0.90 +#' +#' +#' PEV parameters: #' please set vaccine strategies with the convenience functions in -#' `pev_parameters.R:set_pev_epi` -#' `pev_parameters.R:set_mass_pev` +#' `pev_parameters.R::set_pev_epi` +#' `pev_parameters.R::set_mass_pev` #' #' * pev_doses - the dosing schedule before the vaccine takes effect; default = #' c(0, 1.5 * 30, 3 * 30) #' default = 365 #' -#' MDA, SMC and PMC parameters: -#' please set these parameters with the convenience functions in `mda_parameters.R` #' #' TBV parameters: #' please set TBV parameters with the convenience functions in -#' `vaccine_parameters.R:set_tbv` +#' `vaccine_parameters.R::set_tbv` #' #' * tbv_mt - effect on treated infectiousness; default = 35 #' * tbv_md - effect on diseased infectiousness; default = 46.7 @@ -192,11 +211,11 @@ #' * tbv_tra_mu - transmission reduction parameter; default = 12.63 #' * tbv_gamma1 - transmission reduction parameter; default = 2.5 #' * tbv_gamma2 - transmission reduction parameter; default = 0.06 -#' +#' #' Antimalarial resistance parameters: #' please set antimalarial resistance parameters with the convenience functions in #' `antimalarial_resistance.R:set_antimalarial_resistance` -#' +#' #' * antimalarial_resistance - boolean for if antimalarial resistance is enabled; default = FALSE #' * antimalarial_resistance_drug - vector of drugs for which resistance can be parameterised; default = NULL #' * antimalarial_resistance_timesteps - vector of time steps on which resistance updates occur; default = NULL @@ -210,29 +229,33 @@ #' * dt_slow_parasite_clearance - the delay for humans experiencing slow parasite clearance to move from state Tr to S; default = NULL #' #' rendering: -#' All values are in timesteps and all ranges are inclusive +#' All values are in timesteps and all ranges are inclusive. +#' Please set rendered age groups using the convenience function +#' `set_epi_outputs` #' -#' * prevalence_rendering_min_ages - the minimum ages for clinical prevalence -#' outputs; default = 730 -#' * prevalence_rendering_max_ages - the corresponding max ages; default = 3650 +#' * age_group_rendering_min_ages - the minimum ages for population size outputs; default = turned off +#' * age_group_rendering_max_ages - the corresponding max ages; default = turned off #' * incidence_rendering_min_ages - the minimum ages for incidence -#' outputs (includes asymptomatic microscopy +); default = turned off +#' outputs (D+Tr+A); default = turned off #' * incidence_rendering_max_ages - the corresponding max ages; default = turned off #' * clinical_incidence_rendering_min_ages - the minimum ages for clinical incidence outputs (symptomatic); default = 0 #' * clinical_incidence_rendering_max_ages - the corresponding max ages; default = 1825 #' * severe_incidence_rendering_min_ages - the minimum ages for severe incidence #' outputs; default = turned off #' * severe_incidence_rendering_max_ages - the corresponding max ages; default = turned off +#' * prevalence_rendering_min_ages - the minimum ages for clinical prevalence +#' outputs; default = 730 +#' * prevalence_rendering_max_ages - the corresponding max ages; default = 3650 +#' #' #' miscellaneous: #' -#' * human_population - the initial number of humans to model; default = 100 -#' * human_population_timesteps - the timesteps at which the population should -#' change; default = 0 #' * mosquito_limit - the maximum number of mosquitoes to allow for in the #' simulation; default = 1.00E+05 #' * individual_mosquitoes - boolean whether adult mosquitoes are modeled #' individually or compartmentally; default = TRUE +#' * human_population_timesteps - the timesteps at which the population should +#' change; default = 0 #' * r_tol - the relative tolerance for the ode solver; default = 1e-4 #' * a_tol - the absolute tolerance for the ode solver; default = 1e-4 #' * ode_max_steps - the max number of steps for the solver; default = 1e6 @@ -242,17 +265,28 @@ #' @export get_parameters <- function(overrides = list()) { parameters <- list( + # initial state proportions + s_proportion = 0.420433246, + d_proportion = 0.007215064, + a_proportion = 0.439323667, + u_proportion = 0.133028023, + t_proportion = 0, + # human fixed state transitions dd = 5, dt = 5, da = 195, du = 110, - del = 6.64, - dl = 3.72, - dpl = .643, - mup = .249, - mum = .132, - sigma_squared = 1.67, - n_heterogeneity_groups = 5, + # human demography parameters + human_population = 100, + average_age = 7663, + custom_demography = FALSE, + # initial immunities + init_ica = 0, + init_iva = 0, + init_icm = 0, + init_ivm = 0, + init_id = 0, + init_ib = 0, # immunity decay rates rm = 67.6952, rvm = 76.8365, @@ -260,24 +294,32 @@ get_parameters <- function(overrides = list()) { rc = 30 * 365, rva = 30 * 365, rid = 10 * 365, - # blood immunity parameters - b0 = 0.59, - b1 = 0.5, - ib0 = 43.9, - kb = 2.16, # immunity boost grace periods ub = 7.2, uc = 6.06, uv = 11.4321, ud = 9.44512, - # infectivity towards mosquitos - cd = 0.068, - gamma1= 1.82425, - cu = 0.0062, - ct = 0.021896, + # maternal immunity parameters + pcm = .774368, + pvm = .195768, # unique biting rate a0 = 8 * 365, rho = .85, + sigma_squared = 1.67, + n_heterogeneity_groups = 5, + enable_heterogeneity = TRUE, + # blood immunity parameters + b0 = 0.59, + b1 = 0.5, + ib0 = 43.9, + kb = 2.16, + # asymptomatic immunity to lm detection parameters + fd0 = 0.007055, + ad = 21.9 * 365, + gammad= 4.8183, + d1 = 0.160527, + id0 = 1.577533, + kd = .476614, # clinical immunity parameters phi0 = .792, phi1 = .00074, @@ -291,62 +333,44 @@ get_parameters <- function(overrides = list()) { av = 2493.41, gammav = 2.91282, iv0 = 1.09629, - # delay for infection - de = 12, - delay_gam = 12.5, - dem = 10, - # asymptomatic immunity parameters - fd0 = 0.007055, - ad = 21.9 * 365, - gammad= 4.8183, - d1 = 0.160527, - id0 = 1.577533, - kd = .476614, - # mortality parameters - average_age = 7663, - pcm = .774368, - pvm = .195768, - # carrying capacity parameters - g0 = 2, - g = c(.3, .6, .9), - h = c(.1, .4, .7), - gamma = 13.25, - model_seasonality = FALSE, - rainfall_floor = 0.001, - # larval mortality rates + # infectivity towards mosquitos + cd = 0.068, + gamma1= 1.82425, + cu = 0.0062, + ct = 0.021896, + # mosquito fixed state transitions (inc. mortality) + del = 6.64, + dl = 3.72, + dpl = .643, me = .0338, ml = .0348, - # initial state proportions - s_proportion = 0.420433246, - d_proportion = 0.007215064, - a_proportion = 0.439323667, - u_proportion = 0.133028023, - t_proportion = 0, - # initial immunities - init_ica = 0, - init_iva = 0, - init_icm = 0, - init_ivm = 0, - init_id = 0, - init_ib = 0, - # vector biology - beta = 21.2, - total_M = 1000, - init_foim= 0, + mup = .249, + mum = .132, # species-specific vector biology (default is An. gambiae s.s) species = 'gamb', species_proportions = 1, blood_meal_rates = 1/3, Q0 = .92, foraging_time = .69, - # bed nets - bednets = FALSE, - phi_bednets = .85, - k0 = .699, - # indoor spraying - spraying = FALSE, - phi_indoors = .90, - # treatment + beta = 21.2, + total_M = 1000, + init_foim= 0, + # carrying capacity parameters + g0 = 2, + g = c(.3, .6, .9), + h = c(.1, .4, .7), + gamma = 13.25, + model_seasonality = FALSE, + rainfall_floor = 0.001, + # flexible carrying capacity + carrying_capacity = FALSE, + carrying_capacity_timesteps = NULL, + carrying_capacity_values = NULL, + # parasite incubation delays + de = 12, + delay_gam = 12.5, + dem = 10, + # treatment parameters drug_efficacy = numeric(0), drug_rel_c = numeric(0), drug_prophylaxis_shape = numeric(0), @@ -354,9 +378,6 @@ get_parameters <- function(overrides = list()) { clinical_treatment_drugs = list(), clinical_treatment_timesteps = list(), clinical_treatment_coverages = list(), - # rts,s - pev = FALSE, - pev_doses = c(0, 1.5 * 30, 3 * 30), # MDA mda = FALSE, mda_drug = 0, @@ -376,6 +397,16 @@ get_parameters <- function(overrides = list()) { pmc_timesteps = NULL, pmc_coverages = NULL, pcs_ages = -1, + # bed nets + bednets = FALSE, + phi_bednets = .85, + k0 = .699, + # indoor spraying + spraying = FALSE, + phi_indoors = .90, + # pev + pev = FALSE, + pev_doses = c(0, 1.5 * 30, 3 * 30), # tbv tbv = FALSE, tbv_mt = 35, @@ -405,10 +436,6 @@ get_parameters <- function(overrides = list()) { late_parasitological_failure_probability = NULL, reinfection_during_prophylaxis_probability = NULL, dt_slow_parasite_clearance = NULL, - # flexible carrying capacity - carrying_capacity = FALSE, - carrying_capacity_timesteps = NULL, - carrying_capacity_values = NULL, # rendering prevalence_rendering_min_ages = 2 * 365, prevalence_rendering_max_ages = 10 * 365, @@ -423,30 +450,27 @@ get_parameters <- function(overrides = list()) { age_group_rendering_min_ages = numeric(0), age_group_rendering_max_ages = numeric(0), # misc - custom_demography = FALSE, - human_population = 100, - human_population_timesteps = 0, mosquito_limit = 100 * 1000, individual_mosquitoes = FALSE, - enable_heterogeneity = TRUE, + human_population_timesteps = 0, r_tol = 1e-4, a_tol = 1e-4, ode_max_steps = 1e6, progress_bar = FALSE ) - + # Override parameters with any client specified ones if (!is.list(overrides)) { stop('overrides must be a list') } - + for (name in names(overrides)) { if (!(name %in% names(parameters))) { stop(paste('unknown parameter', name, sep=' ')) } parameters[[name]] <- overrides[[name]] } - + props <- c( parameters$s_proportion, parameters$d_proportion, @@ -454,11 +478,11 @@ get_parameters <- function(overrides = list()) { parameters$u_proportion, parameters$t_proportion ) - + if (!approx_sum(props, 1)) { stop("Starting proportions do not sum to 1") } - + parameters } @@ -533,7 +557,7 @@ parameterise_total_M <- function(parameters, total_M) { } #' Use parameter draw from the join posterior -#' +#' #' Overrides default (median) model parameters with a single draw from the fitted #' joint posterior. Must be called prior to set_equilibrium. #' diff --git a/man/get_parameters.Rd b/man/get_parameters.Rd index e43792d5..bf7e5208 100644 --- a/man/get_parameters.Rd +++ b/man/get_parameters.Rd @@ -10,17 +10,42 @@ get_parameters(overrides = list()) \item{overrides}{a named list of parameter values to use instead of defaults The parameters are defined below. -fixed state transitions: +initial state proportions: +\itemize{ +\item s_proportion - the proportion of \code{human_population} that begin as susceptible; default = 0.420433246 +\item d_proportion - the proportion of \code{human_population} that begin with +clinical disease; default = 0.007215064 +\item a_proportion - the proportion of \code{human_population} that begin as +asymptomatic; default = 0.439323667 +\item u_proportion - the proportion of \code{human_population} that begin as +subpatents; default = 0.133028023 +\item t_proportion - the proportion of \code{human_population} that begin treated; default = 0 +} + +human fixed state transitions: \itemize{ \item dd - the delay for humans to move from state D to A; default = 5 \item dt - the delay for humans to move from state Tr to S; default = 5 \item da - the delay for humans to move from state A to U; default = 195 \item du - the delay for humans to move from state U to S; default = 110 -\item del - the delay for mosquitoes to move from state E to L; default = 6.64 -\item dl - the delay for mosquitoes to move from state L to P; default = 3.72 -\item dpl - the delay mosquitoes to move from state P to Sm; default = 0.643 -\item mup - the rate at which pupal mosquitoes die; default = 0.249 -\item mum - the rate at which developed mosquitoes die; default (An. gambiae) = .132 +} + +human demography parameters: +\itemize{ +\item human_population - the initial number of humans to model; default = 100 +\item average_age - the average age of humans (in timesteps), this is only used +if custom_demography is FALSE; default = 7663 +\item custom_demography - population demography given; default = FALSE +} + +initial immunity values: +\itemize{ +\item init_icm - the immunity from clinical disease at birth; default = 0 +\item init_ivm - the immunity from severe disease at birth; default = 0 +\item init_ib - the initial pre-erythrocitic immunity; default = 0 +\item init_ica - the initial acquired immunity from clinical disease; default = 0 +\item init_iva - the initial acquired immunity from severe disease; default = 0 +\item init_id - the initial acquired immunity to detectability; default = 0 } immunity decay rates: @@ -33,6 +58,29 @@ immunity decay rates: \item rid - decay rate for acquired immunity to detectability; default = 3650 } +immunity boost grace periods: +\itemize{ +\item ub - period in which pre-erythrocytic immunity cannot be boosted; default = 7.2 +\item uc - period in which clinical immunity cannot be boosted; default = 6.06 +\item uv - period in which severe immunity cannot be boosted; default = 11.4321 +\item ud - period in which immunity to detectability cannot be boosted; default = 9.44512 +} + +maternal immunity parameters: +\itemize{ +\item pcm - new-born clinical immunity relative to mother's; default = 0.774368 +\item pvm - new-born severe immunity relative to mother's; default = 0.195768 +} + +unique biting rate: +\itemize{ +\item a0 - age dependent biting parameter; default = 2920 +\item rho - age dependent biting parameter; default = 0.85 +\item sigma_squared - heterogeneity parameter; default = 1.67 +\item n_heterogeneity_groups - number discretised groups for heterogeneity, used +for sampling mothers; default = 5 +} + probability of pre-erythrocytic infection: \itemize{ \item b0 - maximum probability due to no immunity; default = 0.59 @@ -41,6 +89,16 @@ probability of pre-erythrocytic infection: \item kb - shape parameter; default = 2.16 } +probability of detection by light-microscopy when asymptomatic: +\itemize{ +\item fd0 - time-scale at which immunity changes with age; default = 0.007055 +\item ad - scale parameter relating age to immunity; default = 7993.5 +\item gammad - shape parameter relating age to immunity; default = 4.8183 +\item d1 - minimum probability due to immunity; default = 0.160527 +\item id0 - scale parameter; default = 1.577533 +\item kd - shape parameter; default = 0.476614 +} + probability of clinical infection: \itemize{ \item phi0 - maximum probability due to no immunity; default = 0.792 @@ -60,24 +118,6 @@ probability of severe infection: \item gammav - age dependent modifier; default = 2.91282 } -immunity reducing probability of detection: -\itemize{ -\item fd0 - time-scale at which immunity changes with age; default = 0.007055 -\item ad - scale parameter relating age to immunity; default = 7993.5 -\item gammad - shape parameter relating age to immunity; default = 4.8183 -\item d1 - minimum probability due to immunity; default = 0.160527 -\item id0 - scale parameter; default = 1.577533 -\item kd - shape parameter; default = 0.476614 -} - -immunity boost grace periods: -\itemize{ -\item ub - period in which pre-erythrocytic immunity cannot be boosted; default = 7.2 -\item uc - period in which clinical immunity cannot be boosted; default = 6.06 -\item uv - period in which severe immunity cannot be boosted; default = 11.4321 -\item ud - period in which immunity to detectability cannot be boosted; default = 9.44512 -} - infectivity towards mosquitoes: \itemize{ \item cd - infectivity of clinically diseased humans towards mosquitoes; default = 0.068 @@ -86,67 +126,21 @@ infectivity towards mosquitoes: \item ct - infectivity of treated infection; default = 0.021896 } -unique biting rate: -\itemize{ -\item a0 - age dependent biting parameter; default = 2920 -\item rho - age dependent biting parameter; default = 0.85 -\item sigma_squared - heterogeneity parameter; default = 1.67 -\item n_heterogeneity_groups - number discretised groups for heterogeneity, used -for sampling mothers; default = 5 -} - -mortality parameters: +mosquito fixed state transitions (including mortality): \itemize{ -\item average_age - the average age of humans (in timesteps), this is only used -if custom_demography is FALSE; default = 7663 -\item pcm - new-born clinical immunity relative to mother's; default = 0.774368 -\item pvm - new-born severe immunity relative to mother's; default = 0.195768 +\item del - the delay for mosquitoes to move from state E to L; default = 6.64 +\item dl - the delay for mosquitoes to move from state L to P; default = 3.72 +\item dpl - the delay mosquitoes to move from state P to Sm; default = 0.643 \item me - early stage larval mortality rate; default = 0.0338 \item ml - late stage larval mortality rate; default = 0.0348 -} - -carrying capacity parameters: -\itemize{ -\item model_seasonality - boolean switch TRUE iff the simulation models seasonal rainfall; default = FALSE -\item g0 - rainfall fourier parameter; default = 2 -\item g - rainfall fourier parameter; default = 0.3, 0.6, 0.9 -\item h - rainfall fourier parameters; default = 0.1, 0.4, 0.7 -\item gamma - effect of density dependence on late instars relative to early -instars; default = 13.25 -\item rainfall_floor - the minimum rainfall value (must be above 0); default 0.001 -} - -initial state proportions: -\itemize{ -\item s_proportion - the proportion of \code{human_population} that begin as susceptible; default = 0.420433246 -\item d_proportion - the proportion of \code{human_population} that begin with -clinical disease; default = 0.007215064 -\item a_proportion - the proportion of \code{human_population} that begin as -asymptomatic; default = 0.439323667 -\item u_proportion - the proportion of \code{human_population} that begin as -subpatents; default = 0.133028023 -\item t_proportion - the proportion of \code{human_population} that begin treated; default = 0 -} - -initial immunity values: -\itemize{ -\item init_icm - the immunity from clinical disease at birth; default = 0 -\item init_ivm - the immunity from severe disease at birth; default = 0 -\item init_ib - the initial pre-erythrocitic immunity; default = 0 -\item init_ica - the initial acquired immunity from clinical disease; default = 0 -\item init_iva - the initial acquired immunity from severe disease; default = 0 -\item init_id - the initial acquired immunity to detectability; default = 0 -} - -incubation periods: -\itemize{ -\item de - Duration of the human latent period of infection; default = 12 -\item delay_gam - Lag from parasites to infectious gametocytes; default = 12.5 -\item dem - Extrinsic incubation period in mosquito population model; default = 10 +\item mup - the rate at which pupal mosquitoes die; default = 0.249 +\item mum - the rate at which developed mosquitoes die; default (An. gambiae) = .132 } vector biology: species specific values are vectors +please set species parameters using the convenience function +\code{set_species} \itemize{ \item beta - the average number of eggs laid per female mosquito per day; default = 21.2 \item total_M - the initial number of adult mosquitos in the simulation; default = 1000 @@ -158,19 +152,32 @@ species specific values are vectors \item foraging_time - time spent taking blood meals; default = 0.69 } -feeding cycle: -please set vector control strategies using \code{set_betnets} and \code{set_spraying} +seasonality and carrying capacity parameters: +please set flexible carrying capacity using the convenience function +\code{set_carrying_capacity} \itemize{ -\item bednets - boolean for if bednets are enabled; default = FALSE -\item phi_bednets - proportion of bites taken in bed; default = 0.85 -\item k0 - proportion of females bloodfed with no net; default = 0.699 -\item spraying - boolean for if indoor spraying is enabled; default = FALSE -\item phi_indoors - proportion of bites taken indoors; default = 0.90 +\item model_seasonality - boolean switch TRUE iff the simulation models seasonal rainfall; default = FALSE +\item g0 - rainfall fourier parameter; default = 2 +\item g - rainfall fourier parameter; default = 0.3, 0.6, 0.9 +\item h - rainfall fourier parameters; default = 0.1, 0.4, 0.7 +\item gamma - effect of density dependence on late instars relative to early +instars; default = 13.25 +\item rainfall_floor - the minimum rainfall value (must be above 0); default 0.001 +\item carrying_capacity; default = FALSE +\item carrying_capacity_timesteps; default = NULL +\item carrying_capacity_values; default = NULL#' +} + +parasite incubation periods: +\itemize{ +\item de - duration of the human latent period of infection; default = 12 +\item delay_gam - lag from parasites to infectious gametocytes; default = 12.5 +\item dem - extrinsic incubation period in mosquito population model; default = 10 } treatment parameters: -please set treatment parameters with the convenience functions in -\code{drug_parameters.R} +please set treatment parameters with the convenience functions +\code{set_drugs} and \code{set_clinical_treatment} \itemize{ \item drug_efficacy - a vector of efficacies for available drugs; default = turned off \item drug_rel_c - a vector of relative onward infectiousness values for drugs; default = turned off @@ -180,25 +187,37 @@ model prophylaxis for each drug; default = turned off model prophylaxis for each drug; default = turned off \item clinical_treatment_drugs - a vector of drugs that are available for clinically diseased (these values refer to the index in drug_* parameters); default = NULL, NULL, NULL -\item clinical_treatment_coverage - a vector of coverage values for each drug; default = NULL, NULL, NULL +\item clinical_treatment_coverage - a vector of coverage values for each drug; default = NULL, NULL, NULL#' +} + +MDA, SMC and PMC parameters: +please set these parameters with the convenience functions +\code{set_mda}, \code{set_smc} and \code{set_pmc}, +with \code{peak_season_offset} + +bednet, irs and mosquito feeding cycle parameters: +please set vector control strategies using \code{set_betnets} and \code{set_spraying} +\itemize{ +\item bednets - boolean for if bednets are enabled; default = FALSE +\item phi_bednets - proportion of bites taken in bed; default = 0.85 +\item k0 - proportion of females bloodfed with no net; default = 0.699 +\item spraying - boolean for if indoor spraying is enabled; default = FALSE +\item phi_indoors - proportion of bites taken indoors; default = 0.90 } PEV parameters: please set vaccine strategies with the convenience functions in -\code{pev_parameters.R:set_pev_epi} -\code{pev_parameters.R:set_mass_pev} +\code{pev_parameters.R::set_pev_epi} +\code{pev_parameters.R::set_mass_pev} \itemize{ \item pev_doses - the dosing schedule before the vaccine takes effect; default = c(0, 1.5 * 30, 3 * 30) default = 365 } -MDA, SMC and PMC parameters: -please set these parameters with the convenience functions in \code{mda_parameters.R} - TBV parameters: please set TBV parameters with the convenience functions in -\code{vaccine_parameters.R:set_tbv} +\code{vaccine_parameters.R::set_tbv} \itemize{ \item tbv_mt - effect on treated infectiousness; default = 35 \item tbv_md - effect on diseased infectiousness; default = 46.7 @@ -232,30 +251,33 @@ please set antimalarial resistance parameters with the convenience functions in } rendering: -All values are in timesteps and all ranges are inclusive +All values are in timesteps and all ranges are inclusive. +Please set rendered age groups using the convenience function +\code{set_epi_outputs} \itemize{ -\item prevalence_rendering_min_ages - the minimum ages for clinical prevalence -outputs; default = 730 -\item prevalence_rendering_max_ages - the corresponding max ages; default = 3650 +\item age_group_rendering_min_ages - the minimum ages for population size outputs; default = turned off +\item age_group_rendering_max_ages - the corresponding max ages; default = turned off \item incidence_rendering_min_ages - the minimum ages for incidence -outputs (includes asymptomatic microscopy +); default = turned off +outputs (D+Tr+A); default = turned off \item incidence_rendering_max_ages - the corresponding max ages; default = turned off \item clinical_incidence_rendering_min_ages - the minimum ages for clinical incidence outputs (symptomatic); default = 0 \item clinical_incidence_rendering_max_ages - the corresponding max ages; default = 1825 \item severe_incidence_rendering_min_ages - the minimum ages for severe incidence outputs; default = turned off \item severe_incidence_rendering_max_ages - the corresponding max ages; default = turned off +\item prevalence_rendering_min_ages - the minimum ages for clinical prevalence +outputs; default = 730 +\item prevalence_rendering_max_ages - the corresponding max ages; default = 3650 } miscellaneous: \itemize{ -\item human_population - the initial number of humans to model; default = 100 -\item human_population_timesteps - the timesteps at which the population should -change; default = 0 \item mosquito_limit - the maximum number of mosquitoes to allow for in the simulation; default = 1.00E+05 \item individual_mosquitoes - boolean whether adult mosquitoes are modeled individually or compartmentally; default = TRUE +\item human_population_timesteps - the timesteps at which the population should +change; default = 0 \item r_tol - the relative tolerance for the ode solver; default = 1e-4 \item a_tol - the absolute tolerance for the ode solver; default = 1e-4 \item ode_max_steps - the max number of steps for the solver; default = 1e6 diff --git a/man/run_simulation.Rd b/man/run_simulation.Rd index 383b38f6..3ae13e03 100644 --- a/man/run_simulation.Rd +++ b/man/run_simulation.Rd @@ -52,9 +52,6 @@ prevalence_rendering_min_ages and prevalence_rendering_max_ages parameters. inclusive age range at this timestep. This defaults to p_detect_730_3650. Other age ranges can be set with prevalence_rendering_min_ages and prevalence_rendering_max_ages parameters. -\item n_severe: number of humans with a severe infection between an inclusive -age range at this timestep. Age ranges can be set with -severe_prevalence_rendering_min_ages and severe_prevalence_rendering_max_ages parameters. \item n_inc: number of new infections for humans between an inclusive age range at this timestep. incidence columns can be set with incidence_rendering_min_ages and incidence_rendering_max_ages parameters.