diff --git a/NAMESPACE b/NAMESPACE index a82181c79..b3b690a55 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -663,7 +663,6 @@ export(xds_lines_Y) export(xds_lines_Y_fracs) export(xds_lines_Z) export(xds_lines_Z_fracs) -export(xds_lines_aEIR) export(xds_plot_EIR) export(xds_plot_M) export(xds_plot_PR) diff --git a/R/adult-basicM.R b/R/adult-basicM.R index d80eb9e1f..6e8c681e5 100644 --- a/R/adult-basicM.R +++ b/R/adult-basicM.R @@ -66,15 +66,16 @@ Update_MYZt.basicM <- function(t, y, pars, s) { #' @export make_MYZpar.basicM = function(MYZname, pars, s, MYZopts=list()){ setup_as = with(MYZopts, ifelse(exists("setup_as"), setup_as, "RM")) - if(setup_as == "GeRM"){ - MYZpar <- create_MYZpar_GeRM(pars$nPatches, MYZopts) - } else { - MYZpar <- create_MYZpar_RM(pars$nPatches, MYZopts) - } - class(MYZpar) <- 'basicM' - pars$MYZpar[[s]] = MYZpar - return(pars) -} + with(MYZopts,{ + if(setup_as == "GeRM"){ + MYZpar <- create_MYZpar_GeRM(pars$nPatches, MYZopts) + } else { + MYZpar <- create_MYZpar_RM(pars$nPatches, MYZopts) + } + class(MYZpar) <- 'basicM' + pars$MYZpar[[s]] = MYZpar + return(pars) +})} diff --git a/R/adult-interface.R b/R/adult-interface.R index 1c7535e6f..b1b9a9106 100644 --- a/R/adult-interface.R +++ b/R/adult-interface.R @@ -13,26 +13,6 @@ dMYZdt <- function(t, y, pars, s) { UseMethod("dMYZdt", pars$MYZpar[[s]]) } -#' @title Compute steady states for \eqn{\cal MYZ} models -#' @description This method dispatches on the type of `MYZpar`. -#' @param Lambda the daily emergence rate of adult mosquitoes -#' @param kappa net infectiousness -#' @param MYZpar a list that defines an adult model -#' @return none -#' @export -xde_steady_state_MYZ = function(Lambda, kappa, MYZpar){ - UseMethod("xde_steady_state_MYZ", MYZpar) -} - -#' @title Compute the steady states as a function of the daily EIR -#' @description This method dispatches on the type of `MYZpar`. -#' @param Lambda the daily emergence rate of adult mosquitoes -#' @param MYZpar a list that defines an adult model -#' @return none -#' @export -xde_steady_state_M = function(Lambda, MYZpar){ - UseMethod("xde_steady_state_M", MYZpar) -} #' @title A function to set up adult mosquito models #' @description This method dispatches on `MYZname`. @@ -230,3 +210,24 @@ get_g = function(pars, s=1){ get_sigma = function(pars, s=1){ UseMethod("get_sigma", pars$MYZpar[[s]]$baseline) } + +#' @title Compute steady states for \eqn{\cal MYZ} models +#' @description This method dispatches on the type of `MYZpar`. +#' @param Lambda the daily emergence rate of adult mosquitoes +#' @param kappa net infectiousness +#' @param MYZpar a list that defines an adult model +#' @return none +#' @export +xde_steady_state_MYZ = function(Lambda, kappa, MYZpar){ + UseMethod("xde_steady_state_MYZ", MYZpar) +} + +#' @title Compute the steady states as a function of the daily EIR +#' @description This method dispatches on the type of `MYZpar`. +#' @param Lambda the daily emergence rate of adult mosquitoes +#' @param MYZpar a list that defines an adult model +#' @return none +#' @export +xde_steady_state_M = function(Lambda, MYZpar){ + UseMethod("xde_steady_state_M", MYZpar) +} diff --git a/R/adult-si.R b/R/adult-si.R index 581bc119d..9c3a78dd5 100644 --- a/R/adult-si.R +++ b/R/adult-si.R @@ -7,10 +7,12 @@ #' \deqn{ #' \begin{array}{rr} #' dM/dt =& \Lambda &- \Omega \cdot M \\ -#' dY/dt =& f q \kappa (M-Y) &- \Omega \cdot Y +#' dY/dt =& f q \kappa (M-Y) &- \Omega \cdot Y \\ #' \end{array}. #' } -#' The model assumes \eqn{Z = \Upsilon Y} +#' and infectious mosquitoes are by the variable +#' \deqn{Z = e^{-\Omega \tau} \cdot Y} +#' #' @inheritParams dMYZdt #' @return a [numeric] vector #' @export diff --git a/R/adult-trivial.R b/R/adult-trivial.R index 17afcd0cd..7524c7bed 100644 --- a/R/adult-trivial.R +++ b/R/adult-trivial.R @@ -8,7 +8,7 @@ F_fqZ.trivial <- function(t, y, pars, s) { f = get_f(pars, s) q = get_q(pars, s) - Z = with(pars$MYZpar[[s]], Z*season(t)*trend(t)) + Z = with(pars$MYZpar[[s]], Z*F_season(t)*F_trend(t)) return(f*q*Z) } @@ -19,7 +19,7 @@ F_fqZ.trivial <- function(t, y, pars, s) { #' @export F_eggs.trivial <- function(t, y, pars, s) { with(pars$MYZpar[[s]], - return(eggs*season(t)*trend(t)) + return(eggs*F_season(t)*F_trend(t)) )} #' @title Blood feeding rate of the infective mosquito population @@ -79,13 +79,13 @@ xde_steady_state_MYZ.trivial = function(Lambda, kappa, MYZpar){with(MYZpar,{ #' @param q the human fraction #' @param Z the human fraction #' @param eggs the human fraction -#' @param season a seasonality function -#' @param trend a trend function +#' @param F_season a F_seasonality function +#' @param F_trend a F_trend function #' @return none #' @export create_MYZpar_trivial = function(nPatches, MYZopts, f = 1, q = 1, Z=1, eggs=1, - season = F_flat, trend=F_flat){ + F_season = F_flat, F_trend=F_flat){ with(MYZopts,{ MYZpar <- list() MYZpar$nPatches <- nPatches @@ -106,8 +106,8 @@ create_MYZpar_trivial = function(nPatches, MYZopts, MYZpar$Z <- checkIt(Z, nPatches) MYZpar$eggs <- checkIt(eggs, nPatches) - MYZpar$season <- season - MYZpar$trend <- trend + MYZpar$F_season <- F_season + MYZpar$F_trend <- F_trend return(MYZpar) })} diff --git a/R/aquatic-basicL.R b/R/aquatic-basicL.R index 84c6f8983..4b0c69674 100644 --- a/R/aquatic-basicL.R +++ b/R/aquatic-basicL.R @@ -166,7 +166,7 @@ create_Linits_basicL = function(nHabitats, Lopts=list(), L=1){with(Lopts,{ #' @title Parse the variable names for the basicL model #' @description Implements [parse_Lorbits] for basicL competition model. #' @inheritParams parse_Lorbits -#' @return [list] +#' @return a parsed [list]; the variables are attached by name #' @export parse_Lorbits.basicL <- function(outputs, pars, s) { L = outputs[,pars$ix$L[[s]]$L_ix] diff --git a/R/aquatic-trivial.R b/R/aquatic-trivial.R index bbe60ced0..ed1bb26e8 100644 --- a/R/aquatic-trivial.R +++ b/R/aquatic-trivial.R @@ -5,26 +5,27 @@ #' @inheritParams F_emerge #' @return a [numeric] vector of length `nHabitats` #' @export -F_emerge.trivial <- function(t, y, pars, s) { - with(pars$Lpar[[s]], Lambda*season(t)*trend(t)) -} +F_emerge.trivial <- function(t, y, pars, s) {with(pars$Lpar[[s]],{ + emergents = Lambda*F_season(t)*F_trend(t) + return(emergents) +})} #' @title Make parameters for trivial aquatic mosquito model #' @param nHabitats the number of habitats in the model #' @param Lopts a [list] that overwrites default values #' @param Lambda vector of mean emergence rates from each aquatic habitat -#' @param season a function that gives a seasonal pattern -#' @param trend a function that returns a temporal trend +#' @param F_season a function that gives a F_seasonal pattern +#' @param F_trend a function that returns a temporal F_trend #' @return none #' @export create_Lpar_trivial = function(nHabitats, Lopts=list(), - Lambda=1000, season=F_flat, trend=F_flat){ + Lambda=1000, F_season=F_flat, F_trend=F_flat){ with(Lopts,{ Lpar = list() class(Lpar) <- "trivial" Lpar$Lambda = checkIt(Lambda, nHabitats) - Lpar$season = season - Lpar$trend = trend + Lpar$F_season = F_season + Lpar$F_trend = F_trend Lpar$baseline = "trivial" class(Lpar$baseline) = "trivial" return(Lpar) diff --git a/R/human-trivial.R b/R/human-trivial.R index 152a162af..3f468d1b7 100644 --- a/R/human-trivial.R +++ b/R/human-trivial.R @@ -7,7 +7,7 @@ #' @export F_X.trivial <- function(t, y, pars, i) { H = F_H(t, y, pars, i) - X = with(pars$Xpar[[i]], H*kappa*season(t)*trend(t)) + X = with(pars$Xpar[[i]], H*kappa*F_season(t)*F_trend(t)) return(X) } @@ -25,18 +25,18 @@ F_H.trivial <- function(t, y, pars, i) { #' @param Xopts a [list] #' @param kappa net infectiousness #' @param HPop initial human population density -#' @param season a seasonality function -#' @param trend a trend function +#' @param F_season a F_seasonality function +#' @param F_trend a F_trend function #' @return a [list] #' @export create_Xpar_trivial <- function(nPatches, Xopts, kappa=.1, HPop=1, - season=F_flat, trend=F_flat){with(Xopts,{ + F_season=F_flat, F_trend=F_flat){with(Xopts,{ Xpar <- list() class(Xpar) <- c('trivial') Xpar$H = checkIt(HPop, nPatches) Xpar$kappa= checkIt(kappa, nPatches) - Xpar$season = season - Xpar$trend = trend + Xpar$F_season = F_season + Xpar$F_trend = F_trend return(Xpar) })} diff --git a/R/plot-terms.R b/R/plot-terms.R index 6a04f6373..a2ae0397f 100644 --- a/R/plot-terms.R +++ b/R/plot-terms.R @@ -4,39 +4,37 @@ #' @param i the host species index #' @param clrs a vector of colors #' @param llty an integer (or integers) to set the `lty` for plotting -#' @param stable a logical: set to FALSE for `orbits` and TRUE for `stable_orbits` -#' @param add_axes a logical: plot axes only if TRUE +#' @param add a logical: plot axes only if FALSE #' #' @export -xds_plot_EIR <- function(pars, i=1, clrs="black", llty=1, stable=FALSE, add_axes=TRUE){ - - tm = pars$outputs$time +xds_plot_EIR <- function(pars, i=1, clrs="black", llty=1, add=FALSE){ + times = pars$outputs$time EIR = get_EIR(pars, i) - if(add_axes==TRUE){ - plot(tm, EIR, type = "n", + + if(add==FALSE){ + plot(times, 0*times, type = "n", xlab = "Time", ylab = "dEIR", ylim = range(0, EIR)) } - xds_lines_EIR(tm, EIR, pars$nStrata[i], clrs, llty) + xds_lines_EIR(times, EIR, pars$nStrata[i], clrs, llty) } #' Add lines for the EIR *vs.* time #' -#' @param tm the time +#' @param times the time #' @param EIR the entomological inoculation rate #' @param nStrata the number of human / host population strata #' @param clrs a vector of colors #' @param llty an integer (or integers) to set the `lty` for plotting #' #' @export -xds_lines_EIR <- function(tm, EIR, nStrata, clrs="black", llty=1){ - +xds_lines_EIR <- function(times, EIR, nStrata, clrs="black", llty=1){ if(nStrata==1) - graphics::lines(tm, EIR, col=clrs, lty = llty) + graphics::lines(times, EIR, col=clrs, lty = llty) if(nStrata>1){ if(length(clrs)==1) clrs=rep(clrs, nStrata) if(length(llty)==1) llty=rep(llty, nStrata) for(i in 1:nStrata) - graphics::lines(tm, EIR[,i], col=clrs[i], lty = llty) + graphics::lines(times, EIR[,i], col=clrs[i], lty = llty) } } @@ -47,38 +45,19 @@ xds_lines_EIR <- function(tm, EIR, nStrata, clrs="black", llty=1){ #' @param i the host species index #' @param clrs a vector of colors #' @param llty an integer (or integers) to set the `lty` for plotting -#' @param stable a logical: set to FALSE for `orbits` and TRUE for `stable_orbits` -#' @param add_axes a logical: plot axes only if TRUE +#' @param stable a logical: set to FALSE for `orbits` and FALSE for `stable_orbits` +#' @param add a logical: plot axes only if FALSE #' #' @export -xds_plot_aEIR <- function(pars, i=1, clrs="black", llty=1, stable=FALSE, add_axes=TRUE){ - vars=with(pars$outputs,if(stable==TRUE){stable_orbits}else{orbits}) - - tm = vars$terms$time - aEIR = 365*vars$terms$eir[[i]] - if(add_axes==TRUE) - plot(tm, aEIR, type = "n", xlab = "Time", ylab = "aEIR", ylim = range(0, aEIR)) +xds_plot_aEIR <- function(pars, i=1, clrs="black", llty=1, stable=FALSE, add=FALSE){ + times = pars$outputs$time + EIR = get_EIR(pars, i) - xds_lines_aEIR(tm, aEIR, pars$Hpar[[i]]$nStrata, clrs, llty) -} + aEIR = 365*EIR + if(add==FALSE) + plot(times, 0*times, type = "n", xlab = "Time", ylab = "aEIR", ylim = range(0, aEIR)) -#' Add lines for the annualized EIR *vs.* t -#' -#' @param tm the time -#' @param EIR the entomological inoculation rate -#' @param nStrata the number of human / host population strata -#' @param clrs a vector of colors -#' @param llty an integer (or integers) to set the `lty` for plotting -#' -#' @export -xds_lines_aEIR <- function(tm, EIR, nStrata, clrs="black", llty=1){ - aeir = 365*EIR - if(nStrata==1) graphics::lines(tm, aeir, col=clrs) - if(nStrata>1){ - if (length(clrs)==1) clrs=rep(clrs, nStrata) - for(i in 1:nStrata) - graphics::lines(tm, aeir[,i], col=clrs[i]) - } + xds_lines_EIR(times, aEIR, pars$nStrata[i], clrs, llty) } #' Plot the prevalence / parasite rate (PR) from a model of human infection and immunity @@ -87,38 +66,39 @@ xds_lines_aEIR <- function(tm, EIR, nStrata, clrs="black", llty=1){ #' @param i the host species index #' @param clrs a vector of colors #' @param llty an integer (or integers) that specifies `lty` for plotting -#' @param stable a logical: set to FALSE for `orbits` and TRUE for `stable_orbits` -#' @param add_axes a logical: plot axes only if TRUE +#' @param add a logical: plot axes only if FALSE #' #' @export -xds_plot_PR = function(pars, i=1, clrs="black", llty=1, stable=FALSE, add_axes=TRUE){ +xds_plot_PR = function(pars, i=1, clrs="black", llty=1, add=FALSE){ + terms = pars$outputs$orbits$XH[[1]] + times = pars$outputs$time tm = pars$outputs$time - if(add_axes==TRUE){ - plot(tm, 0*tm + 1, type = "n", ylim = c(0,1), + if(add==FALSE){ + plot(times, 0*times, type = "n", ylim = c(0,1), ylab = "Prevalence", xlab = "Time") } - xds_lines_PR(tm, pars$outputs$orbits$XH[[1]]$true_pr, pars$nStrata[i], clrs, llty) + xds_lines_PR(times, terms$true_pr, pars$nStrata[i], clrs, llty) } #' Add lines for the prevalence / parasite rate (PR) from a model of human infection and immunity #' -#' @param tm the time +#' @param times the time #' @param PR the computed parasite rate #' @param nStrata the number of human / host population strata #' @param clrs a vector of colors #' @param llty an integer (or integers) that specifies `lty` for plotting #' #' @export -xds_lines_PR = function(tm, PR, nStrata, clrs="black", llty=1){ +xds_lines_PR = function(times, PR, nStrata, clrs="black", llty=1){ - if(nStrata==1) graphics::lines(tm, PR, col=clrs[1], lty = llty[1]) + if(nStrata==1) graphics::lines(times, PR, col=clrs[1], lty = llty[1]) if(nStrata>1){ if (length(clrs)==1) clrs=rep(clrs, nStrata) if (length(llty)==1) llty=rep(llty, nStrata) for(i in 1:nStrata) - graphics::lines(tm, PR[,i], col=clrs[i], lty = llty[i]) + graphics::lines(times, PR[,i], col=clrs[i], lty = llty[i]) } } diff --git a/R/xds_setup.R b/R/xds_setup.R index 7277923f9..63bb72732 100644 --- a/R/xds_setup.R +++ b/R/xds_setup.R @@ -2,7 +2,7 @@ #' @title Basic Setup: Make a Fully Defined **`xds`** Object #' -#' @description Make a fully defined **`xds`** object: +#' @description Make an **`xds`** *model object*: #' #' - Define the dynamical components: #' - \eqn{\cal XH} - a model for human / host infection dynamics of class **`Xname`** with trivial demographics @@ -10,8 +10,8 @@ #' - \eqn{\cal L} - a model for aquatic mosquito ecology of class **`Lname`** #' - Define basic structural parameters for a single host and vector population: #' - \eqn{n_p} or `nPatches` - the number of patches -#' - \eqn{n_q} or `nHabitats` - the number and locations of aquatic habitats -#' - \eqn{n_h} or `nStrata` - the number of human / host population strata and basic demographic information +#' - \eqn{n_q} or `nHabitats <- length(membership)` - the number and locations of aquatic habitats +#' - \eqn{n_h} or `nStrata <- length(residence)` - the number of human / host population strata and basic demographic information #' - Configure some of the basic elements #' - Search weights for human population strata #' - Search weights for aquatic habitats @@ -53,53 +53,48 @@ #' - vector control, vaccines, or other mass #' @seealso [make_xds_template] #' @param xds is `xde`/`dts` for differential / difference equations -#' @param dlay is either "ode" or "dde" -#' @param MYZname a character string defining a \eqn{\cal MYZ} model #' @param Xname a character string defining a \eqn{\cal X} model +#' @param Xopts a list to configure the X model +#' @param MYZname a character string defining a \eqn{\cal MYZ} model +#' @param MYZopts a list to configure the MYZ model #' @param Lname a character string defining a \eqn{\cal L} model +#' @param Lopts a list to configure the L model #' @param nPatches is the number of patches -#' @param membership is a vector that describes the patch where each aquatic habitat is found -#' @param residence is a vector that describes the patch where each human stratum lives #' @param HPop is the number of humans in each patch -#' @param Xday is the run-time time step for X component (in days): integer or 1/integer -#' @param MYZday is the run-time time step for MYZ component (in days): integer or 1/integer -#' @param Lday is the run-time time step for L component (in days): integer or 1/integer +#' @param residence is a vector that describes the patch where each human stratum lives +#' @param membership is a vector that describes the patch where each aquatic habitat is found #' @param searchB is a vector of search weights for blood feeding #' @param TimeSpent is either a TimeSpent matrix or a string to call a function that sets it up #' @param calK is either a calK matrix or a string that defines how to set it up #' @param searchQ is a vector of search weights for egg laying -#' @param MYZopts a list to configure the MYZ model -#' @param Xopts a list to configure the X model -#' @param Lopts a list to configure the L model +#' @param dlay is either "ode" or "dde" +#' @param Xday is the run-time time step for X component (in days): integer or 1/integer +#' @param MYZday is the run-time time step for MYZ component (in days): integer or 1/integer +#' @param Lday is the run-time time step for L component (in days): integer or 1/integer #' @param BFopts a list to configure the blood feeding model #' @param model_name is a name for the model (arbitrary) #' @return an **`xds`** object #' @export -xds_setup = function(xds = 'xde', dlay = 'ode', - ### Dynamical Components - MYZname = "RM", +xds_setup = function(xds = 'xde', Xname = "SIS", + Xopts = list(), + MYZname = "RM", + MYZopts = list(), Lname = "trivial", - ### Model Structure + Lopts = list(), nPatches = 1, - membership=1, - residence=1, - HPop=1000, - ### Runtime Time parameters - Xday = 1, - MYZday = 1, - Lday = 1, - ### Setup Parameters + HPop = 1000, + residence = 1, + membership = 1, searchB = 1, TimeSpent = list(), - calK = list(), + calK = list(), searchQ = 1, - ### Options - MYZopts = list(), - Xopts = list(), - Lopts = list(), + Xday = 1, + MYZday = 1, + Lday = 1, BFopts = list(), - ### Name + dlay = 'ode', model_name = "unnamed" ){ stopifnot(length(HPop) == length(residence)) @@ -326,9 +321,11 @@ xds_setup_aquatic = function(xds = 'xde', dlay = 'ode', #' @param model_name a name for the model #' @return an **`xds`** object #' @export -xds_setup_human = function(xds = 'xde', dlay = 'ode', +xds_setup_human = function(Xname = "SIS", + Xopts = list(), + + xds = 'xde', dlay = 'ode', ### Dynamical Components - Xname = "SIS", ### Model Structure nPatches=1, residence=1, @@ -339,7 +336,6 @@ xds_setup_human = function(xds = 'xde', dlay = 'ode', TimeSpent = list(), ### Options MYZopts = list(), - Xopts = list(), BFopts = list(), ### Name model_name = "unnamed" diff --git a/README.md b/README.md index 41e592d7e..b4eaaede5 100644 --- a/README.md +++ b/README.md @@ -19,17 +19,17 @@ Also see the related vignette [*Getting Started*](https://dd-harp.github.io/ramp ## What is RAMP? -RAMP -- **R**obust **A**nalytics for **M**alaria **P**olicy -- is a bespoke inferential system for malaria decision support and adaptive malaria control. A core goal for RAMP is to characterize, quantify, and propagate uncertainty in conventional analysis and through simulation-based analytics. +RAMP -- **R**obust **A**nalytics for **M**alaria **P**olicy -- describes bespoke inferential systems for malaria decision support and adaptive malaria control that go to great lengths to characterize, quantify, and propagate uncertainty. RAMP includes conventional analysis and simulation-based analytics. ## What is **`ramp.xds`**? -**`ramp.xds`** is an R software package that supports nimble model building for simulation-based analytics and malaria research. It was designed to help research scientists and policy analysts set up, analyze, solve, and use dynamical systems models describing the epidemiology, spatial transmission dynamics, and control of malaria and other mosquito-transmitted pathogens. The software also supports nimble model building and analysis for mosquito ecology, with the capability to handle forcing by weather and other exogenous variables. +**`ramp.xds`** is an R software package that supports nimble model building for simulation-based analytics and malaria research. The software was designed to help research scientists and policy analysts set up, analyze, solve, and use dynamical systems models describing the epidemiology, spatial transmission dynamics, and control of malaria and other mosquito-transmitted pathogens. The software also supports nimble model building and analysis for mosquito ecology, with the capability to handle forcing by weather and other exogenous variables. -**`ramp.xds`** has been designed to serve the needs of malaria programs, where mathematical models are used for decision support and adaptive malaria control in a defined geographical area. Mechanistic models describing malaria transmission in a place that have been fitted to available data and that have quantified uncertainty are a synthesis of malaria intelligence. In this formulation, the models can facilitate complex analysis, extending our innate mental capabilities. As the needs of a malaria program changes, the models can be modified -- simplified or extended -- to serve the tasks at hand. +**`ramp.xds`** has been designed to serve the needs of malaria programs, where mathematical models are used for decision support and adaptive malaria control in a defined geographical area. Mechanistic models that have been fitted to data describing malaria in a place provide a synthesis of *malaria intelligence.* These models can facilitate complex analysis, extending our innate mental capabilities. By characterizing and quantifying uncertainty, and then propagating the uncertainty through the analysis, simulation-based analytics serve as a platform for giving robust policy advice and for adaptive malaria control. As the needs of a malaria program changes, the models can be modified -- simplified or extended -- to serve the tasks at hand. **`ramp.xds`** was developed to apply malaria theory: it outputs standard, observable malaria metrics, and it easily solve dynamical systems, computes steady states and stable orbits, and computes the spatio-temporal vectorial capacity and the basic and adjusted reproductive numbers for malaria parasites. -*** +## A Software Ecosystem for Robust, Simulation-based Analytics **`ramp.xds`** is part of a suite of R packages developed to support RAMP: diff --git a/_pkgdown.yml b/_pkgdown.yml index c93608901..18e5e98ba 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -12,23 +12,17 @@ navbar: - text: Understanding ramp.xds href: articles/Understanding_ramp.xds.html - text: Modular Forms for Disease Dynamics - href: articles/modularity.html + href: articles/modular_forms.html - text: 5-3-4 Spatial Example href: articles/ex_534.html - text: Spatial Metrics href: articles/spat_metric.html - text: Vector Control Example href: articles/vc_lemenach.html - - text: Contributing - href: articles/Contributing.html - text: Heterogeneous Transmission href: articles/heterogeneous_transmission.html - - text: Heterogeneous Biting - href: articles/heterogeneous_biting.html - - text: Heterogeneous Mixing - href: articles/heterogeneous_mixing.html - - text: Environmental Heterogeneity - href: articles/environmental_heterogeneity.html + - text: Contributing + href: articles/Contributing.html - text: Mosquito - Adult menu: - text: Adult Mosquitoes @@ -42,7 +36,7 @@ navbar: - text: Mosquito - Aquatic menu: - text: Aquatic - Trivial (forced) model - href: articles/aqua_trivial.html + href: articles/aqua_trace.html - text: Basic Competition href: articles/aqua_basic.html - text: Human / Host @@ -1030,9 +1024,8 @@ reference: Basic visualization of the transmission terms contents: - xds_plot_EIR - - xds_lines_EIR - xds_plot_aEIR - - xds_lines_aEIR + - xds_lines_EIR - xds_plot_PR - xds_lines_PR - title: Functions and Utilities diff --git a/docs/404.html b/docs/404.html index f2bcd65cb..49abf72c9 100644 --- a/docs/404.html +++ b/docs/404.html @@ -58,7 +58,7 @@ Understanding ramp.xds
library(ramp.xds)
library(viridisLite)
Models for adult mosquito ecology, behavior, and infection dynamics
-pose some problems for their extensibility. The models in
-ramp.xds
were included for several
-reasons:
ramp.xds
are all variants of basic
+models for mosquito infection dynamics. ramp.library
+includes an expanded set of models for adult mosquitoes, including some
+behavioral state models (see MYZ-Overview).
+The dynamical terms rquired by \(\cal
+MYZ\) models are:
+Lambda
or \(\Lambda\) - the emergence rates of adult
+mosquitoes in the patches
kappa
or \(\kappa\)
+- net infectiousness (NI), the probability a mosquito becomes infected
+after blood feeding on a human. The dynamical terms output by \(\cal MYZ\) models are:
F_fqZ
outputs the number of bites by infectious
+mosquitoes, per patch, per day
F_fqM
outputs the number of bites by mosquitoes, per
+patch, per day
F_eggs
outputs the number of eggs laid by
+mosquitoes, per patch, per day
In this vignette, we discuss the challenge of extensibility, +in particular, the challenges of modeling malaria transmission by +mosquitoes as a changing baseline that has been modified by +vector control.
+The models in ramp.xds
were included
+for several reasons:
They serve as an important set of models to test the software;
The basic mosquito models in ramp.xds
-are variants of George Macdonald mathematical models, developed with
-help from P. Armitage. The variables for all the models in
-ramp.xds
are mosquito densities, and the
-default model is from Aron & May, 1982.
These models all use a common set of parameters:
+\(f\) the patch-specific overall +feeding rates
\(q\) the patch-specific human +fraction
\(g\) the patch-specific +mortality rate
\(\sigma\) the patch-specific +emigration rate
\(\mu\) patch-specific mortality +associated with emigration
\(\nu\) patch-specific +egg-laying rates
\(\cal K\) a dispersal +matrix
ramp.xds
there are several versions of
basic models for mosquito infection dynamics. These models make similar
assumptions about mosquito ecology and infection dynamics. (The
equations are in the documentation for The four models are
basicM
- see [dMYZdt.basicM] does not
-include any infection dynamics.basicM
- no infection dynamics (see dMYZdt.basicM)
-basicM <- xds_setup(MYZname = "basicM", Xname = "trivial", Xopts = list(kappa = .1, Y=0, Z=0))
+basicM <- xds_setup(Xname = "trivial", Xopts = list(kappa = .1),
+ MYZname = "basicM")
+
basicM <- xde_solve(basicM, Tmax=80)
si
- A standard SI compartmental model
-for infection, see [dMYZdt.si].
-RM <- xds_setup(MYZname = "RM", Xname = "trivial", Xopts = list(kappa = .1), MYZopts = list(Y=0, Z=0))
+RM <- xds_setup(Xname = "trivial", Xopts = list(kappa = .1),
+ MYZname = "RM", MYZopts = list(Y=0, Z=0))
+
RM <- xde_solve(RM, Tmax=80)
If \(M\) and \(\kappa\) have reached the steady state, then the fraction of infected mosquitoes, \(y=Y/M\) is given by:
\[y =
@@ -341,13 +373,13 @@ This is equivalent to Macdonald’s formula. In Standard outputs are: The outputs from solving a system of equations include: The software was designed to be fully modular. A basic requirement
+for full modularity is that every dynamical component must include a
+trace module. In each For more information, see the vignette Trace
+Functions From a design perspective, the setup interface can’t possibly
@@ -413,10 +440,10 @@ returns the same values as the function call: Structural Parameters are also configured using
NOTE: As demos for these advanced options get
developed, we will add the links here. Advanced Setup Options: During basic setup, most
-advanced options are not defined. Advanced Setup Options: During basic setup, two
+advanced options can be configured, but most of the advanced options
+must be added after basic setup. Spatial Heterogeneity – Human Mobility – Malaria Importation includes travel and
+visitors Travel Malaria –In basic setup, travel malaria is set up
+to model exposure while traveling, but time spent traveling and the
+travel FoI are set to zero. Visiting – In basic setup, visiting is set up but the
+availability of visitors is set to zero. Exposure – Since catch counts data for
mosquitoes are usually well-described by the negative binomial
distribution family, Human Demography – In basic setup, the human
+model environmental
+heterogeneity based on a probability distribution function
+describing the number of infective bites per person. By default,
+ Human Demography – In basic setup, the human
demographic model is the trivial model, but it can be
-configured with births, deaths, and aging. Travel Malaria – In basic setup, travel malaria
-is set up to model exposure while traveling, but time spent traveling
-and the travel FoI are set to zero. Visiting – In basic setup, visiting is set up
-but the availability of visitors is set to zero. Forcing – handles exogenous forcing by setting
-up the functions that compute exogenous variables, including
-weather and hydrology. Control – handles malaria control and vector
-control. Bionomics – handles functional responses to
-exogenous forcing variables and computes a
-baseline. Vital dynamics: births, deaths Migration Cohort dynamics and aging Pregnancy Forcing – set up exogenous forcing, including
+exogenous variables (e.g. weather and hydrology) and
+the functional responses to compute mosquito bionomic
+parameters Vector Control – set up vector control,
+including Health Systems – a variety of functions to
+handle surveillance and malaria control through health systems,
+including care seeking, mass vaccination, IPTp Multiple Vector Species – Each vector species
has spatial structure, but it is also possible to configure other vector
species (or type). a mean value, or a scaling argument a function that returns a seasonal signal, configured with a line
-in the appropriate options list,
- a function that returns a trend, configured with a line in the
-appropriate options list, a function that returns a F_seasonal signal, configured with a
+line in the appropriate options list,
+ a function that returns a F_trend, configured with a line in the
+appropriate options list,
+ The trivial modules each returns different values: \(\cal L\) - The trivial aquatic
module is set up by Both the function the function Infectiousnessxds_plot_Z(sei, llty=1, clrs="darkblue")
xds_plot_Z(si, add=TRUE, clrs = "darkred")
xds_plot_Z(RM, add=TRUE, clrs = "orange")
-
+
xds_plot_Z_fracs(sei, clrs="darkblue")
xds_plot_Z_fracs(RM, add=T, clrs = "orange")
xds_plot_Z_fracs(sei, add=T, clrs="darkblue")
xds_plot_Z_fracs(si, add=T, clrs = "darkred")
ramp.xds
this set of equations is
implemented. This sets up and solves a model with \(\kappa\) and \(\Lambda\) passed as constant values, and a
@@ -359,7 +391,7 @@ Infectiousnessxds_plot_M(rm)
xds_plot_Y(rm, add=TRUE)
xds_plot_Z(rm, add=TRUE)
-
+
Macdonald’s Formula
@@ -373,11 +405,12 @@
Macdonald’s FormulaLo = list(season = function(t){1+sin(2*pi*t/365)},
trend = function(t){exp(-t/1000)},
Lambda =5)
-rm = xds_setup(Xname = "trivial", Xopts = list(kappa=0.1), Lname = "trivial", Lopts = Lo, HPop=10)
+rm = xds_setup(Xname = "trivial", Xopts = list(kappa=0.1), HPop=10,
+ Lname = "trivial", Lopts = Lo)
rm <- xde_solve(rm, 3680, dt=10)
xds_plot_M(rm)
@@ -116,7 +107,7 @@
Demo
names(model$outputs)
-## [1] "time" "last_y" "orbits" "terms" "deout"
Trivial Models and Trace Functions
+
+trace
module, no variables
+are defined, but the dynamical terms needed by related dynamical
+components include a fully configurable trace function. In
+above example, the \(\cal L\) component
+was trivial, but we can create a new model by modifying the old one.
+First, we define F_season
and the mean values of
+Lambda
+
model_1 <- make_Lpar("trivial", model, 1, Lo)
+model_1 <- last_to_inits(model_1)
+
model_1 <- xde_solve(model_1, Tmax=365*3)
+
par(mfrow = c(1,2))
+xds_plot_X(model_1)
+xds_plot_M(model_1)
+xds_plot_Y(model_1, add=T)
+xds_plot_Z(model_1, add=T)
Model Building
Basic Setup
+
model1 = xds_setup()
+
model2 = xds_setup(Xname = "SIS", MYZname = "RM", Lname = "trivial")
xde_setup.
In basic setup, users can configure a malaria
@@ -466,33 +493,52 @@ Advanced Setup
+
@@ -116,7 +107,7 @@
+
+ramp.xds
has
implemented a step between the computation of the EIR and the FoI to
-model environmental heterogeneity, based on a probability
-distribution function describing the number of infective bites per
-person. By default, xds_setup
configures a Poisson model,
-but this can be changed.xds_setup
configures a Poisson model, but this can be
+changed.
+
+
+
@@ -116,7 +107,7 @@
@@ -116,7 +107,7 @@
@@ -116,7 +107,7 @@
Trace Functions
trace functions have three parts:
season = function(t){...}
trend = function(t){...}
F_season = function(t){...}
F_trend = function(t){...}
@@ -269,11 +266,11 @@ create_Lpar_trivial.
The function
-F_emerge()
returns Lambda*season(t)*trend(t).
-To override the defaults, Lopts
must be a named list that
-sets the values of the elements:F_emerge()
returns
+Lambda*F_season(t)*F_trend(t).
To override the defaults,
+Lopts
must be a named list that sets the values of the
+elements:
-
Lambda = c(...)
season = function(t){...}
trend = function(t){...}
Lambda = c(...)
is theF_season = function(t){...}
F_trend = function(t){...}
Trace Functions
values will return either F_fqZ
or F_eggs
@@ -244,7 +241,7 @@ F_fqZ
and F_eggs
use the same
+seasonality and trend functions:
+
+F_season = function(t){...}
F_trend = function(t){...}
F_fqZ()
returns
-f*q*Z*season(t)*trend(t)
. To configure,
+f*q*Z*F_season(t)*F_trend(t)
. To configure,
MYZopts
should be a named list that sets the values of the
elements:
f = c(...)
q = c(...)
Z = c(...)
season = function(t){...}
trend = function(t){...}
F_eggs()
returns
-eggs*season(t)*trend(t)
; to override the defaults,
+eggs*F_season(t)*F_trend(t)
; to override the defaults,
MYZopts
must be a named list that sets the values of the
elements:
-
eggs = c(...)
season = function(t){...}
trend = function(t){...}
eggs = c(...)
Trace Functions
for human / host infection and immunity is set up by
create_Xpar_trivial.
F_X
calls
F_H
and then returns
-H*kappa*season(t)*trend(t)
+H*kappa*F_season(t)*F_trend(t)
F_H
is configured in xds_setup
by
passing HPop = ...
Trace Functions
F_X
should be in the interval \([0,H]:\)
kappa = c(...)
season = function(t){...}
trend = function(t){...}
F_season = function(t){...}
F_trend = function(t){...}
Emergence
-
Lo = list(season = function(t){1+sin(2*pi*t/365)},
- trend = function(t){(1+t/250)*exp(-t/1000)},
+
Lo = list(F_season = function(t){1+sin(2*pi*t/365)},
+ F_trend = function(t){(1+t/250)*exp(-t/1000)},
Lambda =5)
rm = xds_setup(Xname = "trivial", Xopts = Xo, HPop=10,
Lname = "trivial", Lopts = Lo)
@@ -291,7 +288,7 @@
Emergencexds_plot_M(rm)
xds_plot_Y(rm, add=T)
xds_plot_Z(rm, add=T)
Blood feeding is an interaction among humans and mosquitoes. Parasite
-transmission is heterogeneous because mosquito populations are spatially
-heterogeneous and because human behaviors are heterogeneous.
-Heterogeneous blood feeding and transmission is an important aspect of
-malaria transmission dynamics and control, and it has been implemented
-in ramp.xds
through several related concepts and
-constructs.
Mosquito populations are heterogeneous over space and
-time. Spatial dynamics in ramp.xds
are organized around the
-concept of a patch. The adult mosquito populations in each
-state are assumed to be homogeneously distributed within each
-patch.
Human populations: and human behaviors are heterogeneous
-in ways that affect exposure and transmission. The design of
-ramp.xds
makes it possible to sub-divide the human
-population into an arbitrary number of homogeneous strata.
Blood feeding is an interaction between mosquitoes and
-humans that gives rise to parasite transmission. The design of
-ramp.xds
has a new model for blood feeding that
-incorporates various kinds of heterogeneous transmission.
Heterogeneous transmission includes several concepts:
+Heterogeneous transmission includes several closely related +concepts:
Heterogeneous Biting describes differences among population strata in the average rate of exposure. In effect, heterogeneous biting is a kind of -frailty. Heterogeneous biting is implemented through blood -feeding search weights.
ramp.xds
,
+heterogeneous biting is implemented through blood feeding search
+weights.Environmental
Heterogeneity describes the distribution of the expected
-number of bites in a homogenous populations stratum. For example, if the
+number of bites in otherwise homogeneous populations strata; if the
expected number of bites is Gamma distributed, then the number
of bites, per person, would have a negative binomial distribution.
-Environmental heterogeneity is implemented through a function
-F_foi
that converts the daily entomological inoculation
-rate into a daily force of infection (in Exposure
) under
-some probabilistic model for the distribution of the
+Environmental heterogeneity is implemented in Exposure
+through a function F_foi
or F_ar
that converts
+the daily entomological inoculation rate into a daily force of infection
+under some probabilistic model for the distribution of the
expectation.
Heterogeneous Mixing describes departures in a model from the idealized @@ -228,11 +199,227 @@
Blood feeding by mosquitoes plays a core role in transmission. In
+simple models, the blood feeding parameters are often treated as being a
+result of some innate biological constraints on mosquito species. In
+ramp.xds
, blood feeding is motivated by
+searching for resources and handled by a rigid but configurable
+interface that guarantees mathematical consistency.
+Blood feeding is thus an interaction among humans and mosquitoes. This
+interface computes:
The overall blood feeding rate, (e.g. the parameter +\(f\));
The human fraction (e.g. the parameter \(q\));
The availability of humans / hosts or other vertebrates for +mosquitoes searching for blood;
The mixing matrix, \(\beta\);
Parasite transmission is spatially heterogeneous because mosquito
+populations have preferences for resources whose availability is
+spatially heterogeneous. Available resources can be modified, in part,
+because human behaviors are heterogeneous. Heterogeneous blood feeding
+and transmission is an important aspect of malaria transmission dynamics
+and control, and it has been implemented in ramp.xds
+through several related concepts and constructs.
Mosquito populations are heterogeneous over space and
+time. Spatial dynamics in ramp.xds
are organized around the
+concept of a patch. The adult mosquito populations in each
+state are assumed to be homogeneously distributed within each
+patch.
Human populations: and human behaviors are heterogeneous
+in ways that affect exposure and transmission. The design of
+ramp.xds
makes it possible to sub-divide the human
+population into an arbitrary number of homogeneous strata.
Blood feeding is an interaction between mosquitoes and
+humans that gives rise to parasite transmission. The design of
+ramp.xds
has a new model for blood feeding that
+incorporates various kinds of heterogeneous transmission.
In mechanistic models of malaria, the hazard rate for exposure is +generally assumed to be a linear function of the entomological +inoculation rate. In the following, we assume that the number of bites +per person over a day (or over some longer interval, \(\tau\)), is a random variable, and we +formulate approximating models for attack rates and hazard rates.
+We let \(E\) denote the EIR, the +expected number of bites per person over a day. If we assume that the +distribution of the daily EIR is Poisson, and if a fraction \(b\) of infective bites cause an infection, +then the relationship between the between EIR and the FoI is a Poisson +compounded with a binomial, which is also Poisson:
+\[ +Z \sim F_E(z) = \mbox{Poisson}(z, \mbox{mu} = bE(t)) +\]
+Over a day, the daily attack rate, \(\alpha\), is the fraction of individuals +who received at least one infection, or:
+\[ +\begin{array}{rl} +\alpha &= 1-F_E(0) \\ &= 1-\mbox{Poisson}(0, \mbox{mu} = bE(t)) +\\ +&= 1- e^{-bE(t)} \\ +\end{array} +\]
+The daily FoI, \(h\), is given by a +generic formula:
+\[ +\alpha = 1 - e^{-h} \mbox{ or equivalently } h = -\ln (1-\alpha) +\]
+In this case, the relationship between the FoI and the EIR is:
+\[ + h(t) = b E(t) +\]
+It is highly mathematically convenient that the relationship is +invariant with respect to the sampling period.
+If we assume the number of infective bites, per person, per day, has +a Gamma distribution in a population, then we could model the number of +infective bites as a Gamma - Poisson mixture process, or a negative +binomial distribution. Under this model, the counts for bites by +sporozoite positive mosquitoes over one day, \(Z\), would be a negative binomial random +variable with mean \(E\):
+\[ +Z \sim F_E(z) = \mbox{NB}(z, \mbox{mu} = bE(t), \mbox{size} = 1/\phi) +\]
+Assuming an infectious bite causes an infection with probability +\(b\), the daily attack rate is:
+\[ +\begin{array}{rl} +\alpha &= 1-F_E(0) \\ &= 1-\mbox{NB}(0, \mbox{mu} = b E(t), +\mbox{size} = 1/\phi) \\ +&= 1- \left(1+b E(t)\phi \right)^{-1/\phi} +\end{array} +\]
+This is consistent with a formula that has a continuous daily +FoI:
+\[ + h = \frac{\ln \left(1 + bE(t)\phi \right)} {\phi} +\]
+Heterogeneous Biting is defined throughout the
+ramp.xds
implementation and documentation as a difference
+in the relative biting rates for two strata that are otherwise
+identical. The implementation relies on two concepts:
blood feeding search weights or \(\left\{\omega\right\}\) describe +multiplicative differences among population strata in their availability +to blood feeding mosquitoes
relative biting rates or \(\left\{\xi\right\}\)
To be more rigorous, let \(E\) +denote the average daily entomological inoculation rate (dEIR) +for a population with multiple strata, and \(\xi_i\) the frailty term, then the dEIR for +the \(i^{th}\) stratum is: \[E_i = \xi_i E.\]
+The implementation is part of a coherent model for blood feeding that +serves at the interface between models of parasite/pathogen infections +in humans (i.e. \(\cal X\)), +and models of parasite infections in mosquitoes (i.e. \(\cal YZ\)). In this vignette, we introduce +the concept of heterogeneous biting and its implementation in +the blood feeding model using blood feeding search +weights.
+A flexible implementation is handled through the blood feeding model, +which includes the the concepts of blood feeding search weights +and availability. The search weights, \(\left\{\omega\right\}\), are a measure of +how easy it is for mosquitoes to find and blood feed on a host.
+We let \(H_i\) denote the size of +the \(i^{th}\) population, where \[H = \sum_i H_i.\] The total +availability of humans for blood feeding is:
+\[W = \sum_i \omega_i H_i.\] +Availability is used to compute the overall blood feeding rate for +mosquitoes and the human fraction (human blood meals as a fraction of +all blood meals). If we assign a biting weight to a stratum, then the +fraction of bites received by that stratum is:
+\[ \frac{\omega_i H_i}W.\] +Example 1: For example, suppose that there are 200 +people with a biting weight of 2.25 and 800 people with a biting weight +of 1. In this model, the first stratum would get 36% of the total +bites:
+
+2.25*200/(2.25*(200) + 1*(800))
+#> [1] 0.36
The relative biting rates are defined at the top.
+The relative biting rates are constrained such that \[\sum_i \xi_i \frac{H_i}H = 1\]
+Example 2:
+For example, if 20% of the population gets bitten at a rate that is +80% higher than the population average, then the other 80% must get +bitten (on average) at a rate that is 80% of the population average.
+
+1.8*0.2+ 0.8*0.8
+#> [1] 1
Relative biting rates are computed automatically from the blood +feeding search weights, \(\left\{\omega\right\},\) where
+\[\xi_i = +\omega_i\frac{H}{W}.\]
+Example 3 computes the search weights from the +biting weights
+
+searchWts = c(2.25, 1)
+Hi = c(200, 800)
+H = sum(Hi)
+W = sum(searchWts*Hi)
+xi = searchWts*H/W
+xi
+#> [1] 1.8 0.8
+sum(xi*Hi)/H
+#> [1] 1
Heterogeneous blood feeding is a basic feature of malaria
+transmission (see Heterogeneous Transmission.
+In exDE,
the term heterogeneous biting is
+used to describe departures from the ideal assumption of
+mass-action, a topic explored by Perkins TA, et al.
+(2013)1.
+. Other departures from being well-mixed fall under the
+category of heterogeneous mixing. Computation of the mixing
+matrix, \(\beta\), is described in
+detail by Wu SL, et al., (2023)2.
Perkins TA, Scott TW, Le Menach A, Smith DL (2013). +Heterogeneity, mixing, and the spatial scales of mosquito-borne pathogen +transmission. PLoS Comput Biol 9: e1003327, https://doi.org/10.1371/journal.pcbi.1003540↩︎
Wu SL, Henry JM, Citron DT, et al. (2023). +Spatial dynamics of malaria transmission. PLoS Comput Biol 19: e1010684, +https://doi.org/10.1371/journal.pcbi.1010684↩︎
A Modular Form for disease dynamics is a stylized
-way of writing the dynamical systems that emphasizes the modular
-structure of the process. A mathematical framework for building models
-of malaria dynamics and control (and other mosquito-borne pathogens) was
-described in Spatial Dynamics of Malaria Transmission, and the
-framework was implemented in ramp.xds.
The forms we
-describe here rewrite models so that they closely resemble their
-implementation in ramp.xds
, which makes it possible to
-relate written equations and computed code.
For an extended discussion of modularity, see the closely related -vignettes Understanding ramp.xds and Generalized Modularity and Extensibility
+A modular form is a stylized way of writing down a
+dynamical systems that emphasizes the structure of the underlying
+process. The modular structure of ramp.xds
+can be understood through the use of these forms. The forms we describe
+here rewrite models so that they closely resemble their implementation
+in ramp.xds
, which makes it possible to relate written
+equations and computed code.
A mathematical framework for building modular models of malaria
+dynamics and control (and other mosquito-borne pathogens) was described
+in Spatial Dynamics of Malaria Transmission, and that
+framework has been implemented in ramp.xds.
There is no standard form for writing down systems of -differential equations: here, a standard form is any way of -writing down a system of equations that does not emphasize the -modularity, or not a modular form.
+differential equations, but many forms are used, depending on context. +For comparison, we writing down a system of equations that does not +emphasize the modularity, or not a modular form.To illustrate the modular form, we start with the Ross-Macdonald-style model in Box 1.
and now we can rewrite the equation
\[ -dI/dt = h H (H-I) - r I +dI/dt = h (H-I) - r I \]
Next, we isolate the equation describing mosquito infection dynamics, we note that it depends on a term that we will call the net infectiousness (NI).
-\[\kappa = c \frac IH\]
-The term \(c I\) is the density of -infected humans, weighted by their infectiousness.
+\[\kappa = \frac XH\]
+The term \[ X = c I\] is the +density of infected humans, weighted by their infectiousness.
We note that \(fq\kappa\) is the FoI for mosquito infections, and now we can rewrite the equation for mosquitoes:
diff --git a/docs/articles/modularity.html b/docs/articles/modularity.html index 9448b6d79..7d2923ea1 100644 --- a/docs/articles/modularity.html +++ b/docs/articles/modularity.html @@ -59,7 +59,7 @@ Understanding ramp.xds
xde_solve(itn_mod, 1830, dt=15) -> itn_mod
-par(mfrow = c(3,3))
-with(itn_mod$outputs,{
- with(itn_mod$outputs$orbits$MYZ[[1]],{
- plot(time, Z[,1], type = "l")
- plot(time, Z[,2], type = "l")
- plot(time, Z[,3], type = "l")
- })
- with(itn_mod$outputs$orbits$X[[1]],{
+par(mfrow = c(2,1))
+require(viridisLite)
+#> Loading required package: viridisLite
+xds_plot_Y(itn_mod, clrs=turbo(3), llty=2)
+xds_plot_Z(itn_mod, clrs=turbo(3), add=T)
+xds_plot_aEIR(itn_mod)
+par(mfrow = c(2,3))
+
+with(itn_mod$outputs$orbits$XH[[1]],{
plot(time, I[,1], type = "l")
plot(time, I[,2], type = "l")
plot(time, I[,3], type = "l")
- })
- with(itn_mod$outputs$terms,{
+})
+
+with(itn_mod$outputs$terms,{
plot(time, EIR[,1], type = "l")
plot(time, EIR[,2], type = "l")
plot(time, EIR[,3], type = "l")
- })
-})
ramp.xds
RAMP – Robust Analytics for Malaria Policy – is a bespoke inferential system for malaria decision support and adaptive malaria control. A core goal for RAMP is to characterize, quantify, and propagate uncertainty in conventional analysis and through simulation-based analytics.
+RAMP – Robust Analytics for Malaria Policy – describes bespoke inferential systems for malaria decision support and adaptive malaria control that go to great lengths to characterize, quantify, and propagate uncertainty. RAMP includes conventional analysis and simulation-based analytics.
ramp.xds
?
ramp.xds
is an R software package that supports nimble model building for simulation-based analytics and malaria research. It was designed to help research scientists and policy analysts set up, analyze, solve, and use dynamical systems models describing the epidemiology, spatial transmission dynamics, and control of malaria and other mosquito-transmitted pathogens. The software also supports nimble model building and analysis for mosquito ecology, with the capability to handle forcing by weather and other exogenous variables.
ramp.xds
has been designed to serve the needs of malaria programs, where mathematical models are used for decision support and adaptive malaria control in a defined geographical area. Mechanistic models describing malaria transmission in a place that have been fitted to available data and that have quantified uncertainty are a synthesis of malaria intelligence. In this formulation, the models can facilitate complex analysis, extending our innate mental capabilities. As the needs of a malaria program changes, the models can be modified – simplified or extended – to serve the tasks at hand.
ramp.xds
is an R software package that supports nimble model building for simulation-based analytics and malaria research. The software was designed to help research scientists and policy analysts set up, analyze, solve, and use dynamical systems models describing the epidemiology, spatial transmission dynamics, and control of malaria and other mosquito-transmitted pathogens. The software also supports nimble model building and analysis for mosquito ecology, with the capability to handle forcing by weather and other exogenous variables.
ramp.xds
has been designed to serve the needs of malaria programs, where mathematical models are used for decision support and adaptive malaria control in a defined geographical area. Mechanistic models that have been fitted to data describing malaria in a place provide a synthesis of malaria intelligence. These models can facilitate complex analysis, extending our innate mental capabilities. By characterizing and quantifying uncertainty, and then propagating the uncertainty through the analysis, simulation-based analytics serve as a platform for giving robust policy advice and for adaptive malaria control. As the needs of a malaria program changes, the models can be modified – simplified or extended – to serve the tasks at hand.
ramp.xds
was developed to apply malaria theory: it outputs standard, observable malaria metrics, and it easily solve dynamical systems, computes steady states and stable orbits, and computes the spatio-temporal vectorial capacity and the basic and adjusted reproductive numbers for malaria parasites.
ramp.xds
is part of a suite of R packages developed to support RAMP:
ramp.xds
is the core computational engine for simulation-based analytics. It includes a basic set of models – enough to design, verify, and demonstrate the basic features of modular software.
vector of mean emergence rates from each aquatic habitat
a function that gives a seasonal pattern
a function that gives a F_seasonal pattern
a function that returns a temporal trend
a function that returns a temporal F_trend
the human fraction
a seasonality function
a F_seasonality function
a trend function
a F_trend function
initial human population density
a seasonality function
a F_seasonality function
a trend function
a F_trend function
si
Mosquito Model
+and infectious mosquitoes are by the variable
+$$Z = e^{-\Omega \tau} \cdot Y$$
xds_plot_EIR()
Plot the EIR vs. time
Add lines for the EIR vs. time
Plot the annualized EIR vs. time
Add lines for the annualized EIR vs. t
Add lines for the EIR vs. time
a parsed list; the variables are attached by name
diff --git a/docs/reference/parse_Lorbits.html b/docs/reference/parse_Lorbits.html index 9c382db3b..ee4b75a02 100644 --- a/docs/reference/parse_Lorbits.html +++ b/docs/reference/parse_Lorbits.html @@ -42,7 +42,7 @@ Understanding ramp.xdsxds_lines_EIR(tm, EIR, nStrata, clrs = "black", llty = 1)
xds_lines_EIR(times, EIR, nStrata, clrs = "black", llty = 1)
the time
xds_lines_PR(tm, PR, nStrata, clrs = "black", llty = 1)
xds_lines_PR(times, PR, nStrata, clrs = "black", llty = 1)
the time
xds_plot_EIR(
- pars,
- i = 1,
- clrs = "black",
- llty = 1,
- stable = FALSE,
- add_axes = TRUE
-)
xds_plot_EIR(pars, i = 1, clrs = "black", llty = 1, add = FALSE)
an integer (or integers) to set the lty
for plotting
a logical: set to FALSE for orbits
and TRUE for stable_orbits
a logical: plot axes only if TRUE
a logical: plot axes only if FALSE
xds_plot_PR(
- pars,
- i = 1,
- clrs = "black",
- llty = 1,
- stable = FALSE,
- add_axes = TRUE
-)
xds_plot_PR(pars, i = 1, clrs = "black", llty = 1, add = FALSE)
an integer (or integers) that specifies lty
for plotting
a logical: set to FALSE for orbits
and TRUE for stable_orbits
a logical: plot axes only if TRUE
a logical: plot axes only if FALSE
a logical: set to FALSE for orbits
and TRUE for stable_orbits
a logical: set to FALSE for orbits
and FALSE for stable_orbits
a logical: plot axes only if TRUE
a logical: plot axes only if FALSE
xds
Object
Make a fully defined xds
object:
Define the dynamical components:
\(\cal XH\) - a model for human / host infection dynamics of class Xname
with trivial demographics
Make an xds
model object:
Define the dynamical components:
\(\cal XH\) - a model for human / host infection dynamics of class Xname
with trivial demographics
\(\cal MYZ\) - a model for adult mosquito ecology and infection dynamics of class MYZname
\(\cal L\) - a model for aquatic mosquito ecology of class Lname
Define basic structural parameters for a single host and vector population:
\(n_p\) or nPatches
- the number of patches
\(n_q\) or nHabitats
- the number and locations of aquatic habitats
\(n_h\) or nStrata
- the number of human / host population strata and basic demographic information
\(n_q\) or nHabitats <- length(membership)
- the number and locations of aquatic habitats
\(n_h\) or nStrata <- length(residence)
- the number of human / host population strata and basic demographic information
Configure some of the basic elements
Search weights for human population strata
Search weights for aquatic habitats
xds
Object
xds_setup(
xds = "xde",
- dlay = "ode",
- MYZname = "RM",
Xname = "SIS",
+ Xopts = list(),
+ MYZname = "RM",
+ MYZopts = list(),
Lname = "trivial",
+ Lopts = list(),
nPatches = 1,
- membership = 1,
- residence = 1,
HPop = 1000,
- Xday = 1,
- MYZday = 1,
- Lday = 1,
+ residence = 1,
+ membership = 1,
searchB = 1,
TimeSpent = list(),
calK = list(),
searchQ = 1,
- MYZopts = list(),
- Xopts = list(),
- Lopts = list(),
+ Xday = 1,
+ MYZday = 1,
+ Lday = 1,
BFopts = list(),
+ dlay = "ode",
model_name = "unnamed"
)
is xde
/dts
for differential / difference equations
is either "ode" or "dde"
a character string defining a \(\cal X\) model
a list to configure the X model
a character string defining a \(\cal MYZ\) model
a character string defining a \(\cal X\) model
a list to configure the MYZ model
a character string defining a \(\cal L\) model
is the number of patches
is a vector that describes the patch where each aquatic habitat is found
a list to configure the L model
is a vector that describes the patch where each human stratum lives
is the number of patches
is the number of humans in each patch
is the run-time time step for X component (in days): integer or 1/integer
is the run-time time step for MYZ component (in days): integer or 1/integer
is a vector that describes the patch where each human stratum lives
is the run-time time step for L component (in days): integer or 1/integer
is a vector that describes the patch where each aquatic habitat is found
is a vector of search weights for egg laying
a list to configure the MYZ model
is the run-time time step for X component (in days): integer or 1/integer
a list to configure the X model
is the run-time time step for MYZ component (in days): integer or 1/integer
a list to configure the L model
is the run-time time step for L component (in days): integer or 1/integer
a list to configure the blood feeding model
is either "ode" or "dde"
is a name for the model (arbitrary)
xds
Object to Study Human / Host Epide
xds_setup_human(
+ Xname = "SIS",
+ Xopts = list(),
xds = "xde",
dlay = "ode",
- Xname = "SIS",
nPatches = 1,
residence = 1,
HPop = 1000,
@@ -178,7 +170,6 @@ Make an xds
Object to Study Human / Host Epide
searchB = 1,
TimeSpent = list(),
MYZopts = list(),
- Xopts = list(),
BFopts = list(),
model_name = "unnamed"
)
xds
Object to Study Human / Host Epide
a character string defining a X model
list to configure the X model
is xde
/dts
for differential / difference equations'
either "ode" or "dde"
a character string defining a X model
the number of patches
list to configure the MYZ model
list to configure the X model
list to configure the blood feeding model