EpiEstim (version 1.1-2)

EstimateR: Estimation of the instantaneous reproduction number

Description

EstimateR estimates the instantaneous reproduction number of an epidemic, given the incidence time series and the serial interval distribution.

Usage

EstimateR(I, T.Start, T.End, 
    method=c("NonParametricSI","ParametricSI","UncertainSI"), 
    n1=NULL, n2=NULL, Mean.SI=NULL, Std.SI=NULL,
    Std.Mean.SI=NULL, Min.Mean.SI=NULL, Max.Mean.SI=NULL, 
    Std.Std.SI=NULL, Min.Std.SI=NULL, Max.Std.SI=NULL,
    SI.Distr=NULL, Mean.Prior=5, Std.Prior=5, CV.Posterior=0.3, 
    plot=FALSE, leg.pos="topright")

Arguments

I

vector of non-negative integers containing the incidence time series.

T.Start,T.End

vectors of positive integers giving the starting end ending times of each window over which the reproduction number will be estimated. These must be in ascending order, and so that for all i, T.Start[i]<=T.End[i]. T.Start[1] should be strictly after the first day with non null incidence.

method

one of "NonParametricSI", "ParametricSI" or "UncertainSI" (see details).

n1

for method "UncertainSI" ; positive integer giving the size of the sample of pairs (Mean SI (serial interval), Std SI) to be drawn (see details).

n2

for method "UncertainSI" ; positive integer giving the size of the sample drawn from each posterior distribution conditional to a pair (Mean SI, Std SI) (see details).

Mean.SI

for method "ParametricSI" and "UncertainSI" ; positive real giving the mean serial interval (method "ParametricSI") or the average mean serial interval (method "UncertainSI", see details).

Std.SI

for method "ParametricSI" and "UncertainSI" ; non negative real giving the stadard deviation of the serial interval (method "ParametricSI") or the average standard deviation of the serial interval (method "UncertainSI", see details).

Std.Mean.SI

for method "UncertainSI" ; standard deviation of the distribution from which mean serial intervals are drawn (see details).

Min.Mean.SI

for method "UncertainSI" ; lower bound of the distribution from which mean serial intervals are drawn (see details).

Max.Mean.SI

for method "UncertainSI" ; upper bound of the distribution from which mean serial intervals are drawn (see details).

Std.Std.SI

for method "UncertainSI" ; standard deviation of the distribution from which standard deviations of the serial interval are drawn (see details).

Min.Std.SI

for method "UncertainSI" ; lower bound of the distribution from which standard deviations of the serial interval are drawn (see details).

Max.Std.SI

for method "UncertainSI" ; upper bound of the distribution from which standard deviations of the serial interval are drawn (see details).

SI.Distr

for method "NonParametricSI" ; vector of probabilities giving the discrete distribution of the serial interval, starting with SI.Distr[1] (probability that the serial interval is zero), which should be zero.

Mean.Prior

a positive number giving the mean of the common prior distribution for all reproduction numbers (see details).

Std.Prior

a positive number giving the standard deviation of the common prior distribution for all reproduction numbers (see details).

CV.Posterior

a positive number giving the aimed posterior coefficient of variation (see details).

plot

logical. If TRUE (default is FALSE), output is plotted (see value).

leg.pos

one of "bottomright", "bottom", "bottomleft", "left", "topleft", "top", "topright", "right", "center" or xy.coords(x, y), with x and y real numbers. This specifies the position of the legend in the plot. Alternatively, locator(1) can be used ; the user will then need to click where the legend needs to be written.

Value

a list with components:

R

a dataframe containing: the times of start and end of each time window considered ; the posterior mean, std, and 0.025, 0.05, 0.25, 0.5, 0.75, 0.95, 0.975 quantiles of the reproduction number for each time window.

SIDistr

a dataframe containing: for method "NonParametricSI", the mean and standard deviation of the discrete serial interval distribution; for method "ParametricSI", the discrete serial interval distribution; for method "UncertainSI", the means and standard deviations of the serial interval sampled to account for uncertainty on the serial interval distribution (see details).

Details

Analytical estimates of the instantaneous reproduction number for an epidemic over predefined time windows can be obtained within a Bayesian framework, for a given discrete distribution of the serial interval (see references).

The more incident cases are observed over a time window, the smallest the posterior coefficient of variation (CV, ratio of standard deviation over mean) of the reproduction number. An aimed CV can be specified in the argument CV.Posterior (default is 0.3), and a warning will be produced if the incidence within one of the time windows considered is too low to get this CV.

The methods vary in the way the serial interval distribution is specified. The plots are also different according to the method used.

----------------------- method "NonParametricSI" -----------------------

The discrete distribution of the serial interval is directly specified in the argument SI.Distr.

If plot is TRUE, 3 plots are produced. The first one shows the epidemic curve. The second one shows the posterior median and 95% credible interval of the reproduction number. The estimate for a time window is plotted at the end of the time window. The position of the legend on that graph can be monitored by the argument leg.pos (default is "topright"). The third plot shows the discrete distribution of the serial interval.

----------------------- method "ParametricSI" -----------------------

The mean and standard deviation of the continuous distribution of the serial interval are given in the arguments Mean.SI and Std.SI. The discrete distribution of the serial interval is derived automatically using DiscrSI.

If plot is TRUE, 3 plots are produced, which are identical to the ones for method "NonParametricSI" .

----------------------- method "UncertainSI" -----------------------

Method "UncertainSI" allows accounting for uncertainty on the serial interval distribution (see references). We allow the mean \(\mu\) and standard deviation \(\sigma\) of the serial interval to vary according to truncated normal distributions. We sample n1 pairs of mean and standard deviations, \((\mu^{(1)},\sigma^{(1)}),...,(\mu^{(n_2)},\sigma^{(n_2)})\), by first sampling the mean \(\mu^{(k)}\) from its truncated normal distribution (with mean Mean.SI, standard deviation Std.Mean.SI, minimum Min.Mean.SI and maximum Max.Mean.SI), and then sampling the standard deviation \(\sigma^{(k)}\) from its truncated normal distribution (with mean Std.SI, standard deviation Std.Std.SI, minimum Min.Std.SI and maximum Max.Std.SI), but imposing that \(\sigma^{(k)}<\mu^{(k)}\). This constraint ensures that the Gamma probability density function of the serial interval is null at \(t=0\). Warnings are produced when the truncated normal distributions are not symmetric around the mean. For each pair \((\mu^{(k)},\sigma^{(k)})\), we then draw a sample of size n2 in the posterior distribution of the reproduction number over each time window, conditionnally on this serial interval distribution. After pooling, a sample of size \(\code{n1}\times\code{n2}\) of the joint posterior distribution of the reproduction number over each time window is obtained. The posterior mean, standard deviation, and 0.025, 0.05, 0.25, 0.5, 0.75, 0.95, 0.975 quantiles of the reproduction number for each time window are obtained from this sample.

If plot is TRUE, 4 plots are produced. The first one shows the epidemic curve. The second one shows the posterior median and 95% credible interval of the reproduction number. The estimate for a time window is plotted at the end of the time window. The position of the legend on that graph can be monitored by the argument leg.pos (default is "topright"). The third and fourth plots show histograms of the sampled means and standard deviations of the serial interval.

References

Cori, A. et al. A new framework and software to estimate time-varying reproduction numbers during epidemics. (submitted)

See Also

OverallInfectivity, DiscrSI, WT

Examples

# NOT RUN {
## load data on pandemic flu in a school in 2009
data("Flu2009")

## estimate the instantaneous reproduction number (method "NonParametricSI")
EstimateR(Flu2009$Incidence, T.Start=2:26, T.End=8:32, method="NonParametricSI", 
    SI.Distr=Flu2009$SI.Distr, plot=TRUE, leg.pos=xy.coords(1,3))
# the second plot produced shows, at each each day, 
# the estimate of the instantaneous reproduction number over the 7-day window finishing on that day.

## estimate the instantaneous reproduction number (method "ParametricSI")
EstimateR(Flu2009$Incidence, T.Start=2:26, T.End=8:32, method="ParametricSI", 
    Mean.SI=2.6, Std.SI=1.5, plot=TRUE)
# the second plot produced shows, at each each day, 
# the estimate of the instantaneous reproduction number over the 7-day window finishing on that day.

## estimate the instantaneous reproduction number (method "UncertainSI")
EstimateR(Flu2009$Incidence, T.Start=2:26, T.End=8:32, method="UncertainSI", 
    Mean.SI=2.6, Std.Mean.SI=1, Min.Mean.SI=1, Max.Mean.SI=4.2, 
    Std.SI=1.5, Std.Std.SI=0.5, Min.Std.SI=0.5, Max.Std.SI=2.5, 
    n1=100, n2=100, plot=TRUE)
# the bottom left plot produced shows, at each each day, 
# the estimate of the instantaneous reproduction number over the 7-day window finishing on that day.

# }