manage: Adaptive Management of Epidemiological Interventions
In amei: Adaptive Management of Epidemiological Interventions

Description Usage Arguments Details Value Note Author(s) References See Also Examples

This function adaptively manages an epidemic by learning about (parameters determining) its behavior online and adjusting an optimal vaccination strategy accordingly

manage(init, epistep, vacgrid, costs, T = 40, Tstop = T, 
     pinit = list(b = 0.1, k = 0.02, nu = 0.2, mu = 0.1), 
     hyper = list(bh = c(1,3), kh = c(1,3), nuh = c(1,1), muh = c(1,1)),
     vac0=list(frac=0, stop=0), MCvits = 10, MCMCpits = 1000, 
     bkrate = 1, vacsamps = 100, start = 8, ...)

`init`	a `list` containing scalar entries `$S0`, `$I0`, `$R0`, `$D0` depicting the initial number of susceptibles, infecteds, recovereds, and dead individuals in the outbreak; an `"epiman"` object may also be provided in order to continue managing an ongoing epidemic (see Details)
`epistep`	a function which moves the epidemic ahead one time-step; see `epistep`
`T`	the long-term horizon used to calculate optimal vaccination strategies
`Tstop`	the maximum number of time steps during which the epidemic is allowed to evolve; default is identical to `T`
`vacgrid`	a `list` containing vector entries `$fracs` and `$stops` indicating the permissible fractions (in [0,1]) of the population to be vaccinated and the (positive integer) of stopping thresholds having a maximum of `init$S0`; can be `NULL`, see details below
`costs`	a `list` containing scalar entries `$vac`, `$death` and `$infect` depicting the costs associated with a single vaccination or death, or the daily cost of maintaining an infected individual, respectively; can be `NULL`, but only when `vacgrid = NULL` also
`pinit`	a `list` containing scalar entries `$b`, `$k`, `$nu`, and `$mu` depicting the initial values of parameters of the SIR model representing the transmission probability, clumpiness parameter, the recovery probability, and the mortality probability, respectively, which are subsequently sampled by MCMC from the posterior
`hyper`	a `list` containing 2-vector entries describing parameters to the prior distribution of the parameters listed in the `pinit` argument. The prior for `b` follows a gamma distribution with parameters $`$bh`$ where the shape is given by `bh[1]` and scale by `bh[2]`. The prior for `k` specified by parameters `$kh` is similar. The prior(s) for `nu` and `mu` are specified through p_r and p_d, respectively, which follow Beta distributions and the default specification is uniform. See `vignette("amei")` for more details
`vac0`	the initial (static) vaccination policy to be used before estimation of parameters begins (at `start`). This is a `list` with scalar entries `$frac` and `$stop` depicting the fraction to be vaccinated at each time step, and the vaccination (stopping) threshold, respectively. The default corresponds to no initial vaccination
`MCvits`	scalar number of Monte Carlo iterations of forward epidemic evolution used at each time step to determine the optimal vaccination policy
`MCMCpits`	scalar number of Markov chain Monte Carlo iterations used at each step to estimate the SIR model parameters
`bkrate`	number of samples of `b` and `k`, relative to `mu` and `nu` before a sample of all four parameters is saved; this acknowledges that `b` and `k` are correlated and thus mix slower than `mu` and `nu`
`vacsamps`	used to thin the MCMC samples of the parameters sampled from the posterior that are used to calculate optimal vaccination policies; this should be an integer scalar such that `0 < vacsamps <= MCMCpits`
`start`	at what time, after time 1 where the state is given by `init`, should vaccinations be allowed to start
`...`	additional arguments passed to a user-defined `epistep` function

At each time step of the epidemic – evolving stochastically according to the initialization in init and progression described by epistep – the parameters are inferred by sampling from their posterior distribution conditioned on the available data via MCMC. These samples are fed into the Monte Carlo method for determining the optimal vaccination strategy for (the remainder) of the epidemic. That policy is then enacted, and then time is incremented.

Parameter estimation (alone) can be performed by specifying the “null” vaccination grid vacgrid = NULL, i.e., with vac0.

It is possible to “continue” managing an epidemic by specifying the output of manage, an "epiman"-class object, as the init argument and specifying a finishing time (T) which is greater than the finishing time used to create the object (in the previous call to manage); see example below.

For more details on the parameterization and simulation of the SIR model, etc., and the calculation of the optimal vaccination strategy, see vignette("amei")

management returns an object of class "epiman", which is a list containing the components listed below.

`soln`	a `data.frame` describing the evolution of the epidemic giving the following for each time step (in columns): a time index (`$TIME`); the total number of susceptibles (`\$S`), infecteds (`$I`), recovereds (`$R`), and deads (`$D`); the number of people who became infected (`$itilde`), recovered (`$rtilde`), or died (`$dtilde`), in that particular time step; the total number vaccinated (`$V`), or culled (`$QC`, not supported in this version); and the corresponding cumulative cost of the epidemic (`$C` so far)
`prime`	a `data.frame` describing the changes in susceptibles and infecteds due to a vaccination strategy
`vacgrid`	a copy of the input `vacgrid`
`pols`	a `data.frame` describing the policy enacted at each time step with columns giving the fraction of the population vaccinated (`$frac`), and the (stopping) threshold (`$stop`)
`vactimes`	a scalar integer vector indicating the times at which vaccinations actually occurred; this coincides with changes to `soln$V`
`samp`	`data.frame` containing samples from the posterior distribution of the parameters `$b`, `$k`, `$nu`, and `$mu` collected during the final time step

It may be important to plot the epidemic trajectory, with the generic method plot.epiman, or inspect the output $soln[T,], to check that the full dynamics of the epidemic have played out in the number of time steps, T, alotted

Daniel Merl <danmerl@gmail.com>
Leah R. Johnson <lrjohnson@uchicago.edu>
Robert B. Gramacy <rbgramacy@chicagobooth.edu>
and Mark S. Mangel <msmangl@ams.ucsc.edu>

D. Merl, L.R. Johnson, R.B. Gramacy, and M.S. Mangel (2010). “amei: An R Package for the Adaptive Management of Epidemiological Interventions”. Journal of Statistical Software 36(6), 1-32. http://www.jstatsoft.org/v36/i06/

D. Merl, L.R. Johnson, R.B. Gramacy, M.S. Mangel (2009). “A Statistical Framework for the Adaptive Management of Epidemiological Interventions”. PLoS ONE, 4(6), e5807. http://www.plosone.org/article/info:doi/10.1371/journal.pone.0005807

epistep, MCmanage, plot.epiman

## manage an epidemic evolving according to epistep with
## with the following initial population
init <- list(S0=762, I0=1, R0=0, D0=0) 

## construct a grid of valid vaccination strategies
## and specify costs
vacgrid <- list(fracs=seq(0,1.0,0.1), stops=seq(2,init$S0-75,75))
costs <- list(vac=2, death=4, infect=1)

## adaptively manage the epidemic
out.man <- manage(init, epistep, vacgrid, costs)

## plot the trajectories of SIR and the associated costs
plot(out.man)
plot(out.man, type="cost")
getcost(out.man)

## plot the samples from the posterior distribution of
## the parameters obtained during the last time step
true <- as.list(formals(epistep)$true)
plot(out.man, type="params", true=true)

## Bobby isnt really sure what this is plotting
plot(out.man, type="fracs")
plot(out.man, type="stops")

## managing an epidemic in two stages
out.man <- manage(init, epistep, vacgrid, costs, Tstop=10)
plot(out.man)
out.man <- manage(out.man, epistep, vacgrid, costs, Tstop=20)
plot(out.man)