CoriEstimator.RdAn estimator of the reproduction number (\(R_t\)) using a renewal equation method.
Version: 0.03
Generated: 2022-05-24T22:12:30.975629
| r0Mean | r0Mean - The mean of the gamma distribution of the baseline prior assumption about R0 - the theorerical reproduction number in an infinite pool of evenly mixing susceptible individuals - (java expects a double) |
|---|---|
| r0SD | r0SD - The SD of the prior gamma distribution - (java expects a double) |
| maxWindow | maxWindow - The maximum sliding window over which to estimate \(R_t\). - (java expects a int) |
The renewal equation method depends on a time series of infections, and on the infectivity profile - a measure of the probability that a secondary infection occurred on a specific day after the primary case, given a secondary infection occurred. A Bayesian framework is then used to update a prior probabilistic estimate of \(R_t\) on any given day with both information gained from the time series of infections in the epidemic to date and the infectivity profile to produce a posterior estimate of \(R_t\). This is based on the article:<br>
<br>A. Cori, N. M. Ferguson, C. Fraser, and S. Cauchemez, ‘A New Framework and Software to Estimate Time-Varying Reproduction Numbers During Epidemics’, Am J Epidemiol, vol. 178, no. 9, pp. 1505–1512, Nov. 2013, doi: 10.1093/aje/kwt133.<br>
<br> and the implementation of it in the R Library EpiEstim. It assumes that infections (or other type of observation) are a Poisson distributed process and that the reproduction number is a gamma distributed quantity. The estimates of \(R_t\) may be aggregated over a specific "window" to provide a more stable estimate.
J$CoriEstimator$defaultEpiEstim(infectivityProfile, meanR0, sdR0, window)
J$CoriEstimator$defaultUncertainEpiEstim(infectivityProfiles, meanR0, sdR0, window, n2)
instance$withInfectivityProfile(infectivityProfile, replace)
instance$estimateRt(incidence, dateColName, incidenceColName)
instance$estimateRtSingle(incidence, dateColName, incidenceColName)
instance$estimateRtFromRates(rates, dateColName, rateColName, samplesPerProfile)
instance$estimateRtFromSingleRate(rate, dateColName, rateColName, samplesPerProfile)
instance$clone()
instance$print()
new()The Estimator is configured with the baseline \(R_0\) assumptions which are used as prior values for \(R_t\) when no other values are available, or the @link CoriEstimator#withDefaultPrior() option is used.
J = jepidemic::JavaApi$get() J$CoriEstimator$new(r0Mean, r0SD, maxWindow)
r0Mean - The mean of the gamma distribution of the baseline prior assumption about R0 - the theorerical reproduction number in an infinite pool of evenly mixing susceptible individuals - (java expects a double)
r0SD - The SD of the prior gamma distribution - (java expects a double)
maxWindow - The maximum sliding window over which to estimate \(R_t\). - (java expects a int)
R6 CoriEstimator object:
not available
legacySupport()no description
J = jepidemic::JavaApi$get() instance = J$CoriEstimator$new(...); instance$legacySupport(on)
on - a boolean flag to switch on (TRUE) or off (FALSE) eipestim naming convention - (java expects a boolean)
R6 CoriEstimator object: the estimator itself (a fluent method)
not available
defaultEpiEstim()Produces a CoriEstimator that is configured to behave like the default settings of EpiEstim. In that it uses a fixed prior for Rt and returns a fixed window size<br><br>
J = jepidemic::JavaApi$get() J$CoriEstimator$defaultEpiEstim(infectivityProfile, meanR0, sdR0, window)
infectivityProfile - a vector with the discrete probability distribution of the serial interval with \(P_(t=0) = 0\) - (java expects a RNumericVector)
meanR0 - the mean prior of R0 - (java expects a double)
sdR0 - the sd prior of R0 - (java expects a double)
window - the window size - (java expects a int)
R6 CoriEstimator object: a default cori estimator
not available
defaultUncertainEpiEstim()Produces a CoriEstimator that is configured to behave like the default settings of EpiEstim. In that it uses a fixed prior for Rt and returns a fixed window size and aggregates uncertain SI distributions with a random resampling strategy<br><br>
J = jepidemic::JavaApi$get() J$CoriEstimator$defaultUncertainEpiEstim(infectivityProfiles, meanR0, sdR0, window, n2)
infectivityProfiles - a numeric matrix with the discrete probability distribution of the serial interval with \(P_(t=0) = 0\) - (java expects a RNumericArray)
meanR0 - the mean prior of R0 - (java expects a double)
sdR0 - the sd prior of R0 - (java expects a double)
window - the window size - (java expects a int)
n2 - the number of samples to use for estimating confidence limits on bootstrapped infectivity profiles - (java expects a int)
R6 CoriEstimator object: a default cori estimator
not available
selectSpecificWindow()The select methods define how the posterior estimate of \(R_t\) is selected. In this case a set value for the window is used. This must be less or equal to the value of maxWindow supplied in the CoriEstimator::new constructor. The window defines how many data points prior to the time of the estimate are used to synthesise the posterior estimate of \(R_t\), and so tends to reduce the uncertainty around the value of \(R_t\), but longer values of window introduces temporal uncertainty into the estimates. This is as implemented in EpiEstim (with a default value of 7 for the window).
J = jepidemic::JavaApi$get() instance = J$CoriEstimator$new(...); instance$selectSpecificWindow(window)
window - a number of days - (java expects a int)
R6 CoriEstimator object: The estimator itself (a fluent method)
not available
selectAdaptiveWindow()The adaptive windowing strategy selects a posterior estimate of \(R_t\) by selecting the shortest window length (> minWindow) which spans at least incidenceSum infection (or observation) counts. This ensures that where numbers are low the estimation window is lengthened (up ot the value of maxWindow provided to the CoriEstimator::new constructor) to include more data at the cost of temporal precision. This prevents stochastic noise from dominating the estimates of \(R_t\).
J = jepidemic::JavaApi$get() instance = J$CoriEstimator$new(...); instance$selectAdaptiveWindow(incidenceSum, minWindow)
incidenceSum - the number of cases that must be observed in a window. It there are fewer that this the window will be lengthened. Larger values lead to smoother estiamtes at the cost of reduced temporal precision. - (java expects a double)
minWindow - the minimum size of the window that will be selected. In times of very high case numbers a minimum window prevents spurious outliers from completely dominating that days estimate of \(R_t\). - (java expects a int)
R6 CoriEstimator object: The estimator itself (a fluent method)
not available
selectMinimumUncertainty()The minimum uncertainty strategy aims to select a window for the posterior \(R_t\) estimate based on minimising a combined value for uncertainty. The uncertainty in this case is the product of the (timeVsRt)th root of SD of the posterior estimate and the window size to the power of timeVsRt. <br><br>
$$window^timeVsRt * SD_posterior^1timeVsRt$$
J = jepidemic::JavaApi$get() instance = J$CoriEstimator$new(...); instance$selectMinimumUncertainty(timeVsRt, minWindow)
timeVsRt - the relative importance parameter. Values above one favour temporal certainty; values under one favour \(R_t\) estimate certainty - (java expects a double)
minWindow - the minimum size of the window that will be selected. - (java expects a int)
R6 CoriEstimator object: The estimator itself (a fluent method)
not available
selectMixtureCombination()The mixture combination strategy for selecting a posterior \(R_t\) involves finding all the estimates that have a window that span the estimate date (this may involve longer windowed estimate from dates in the future) and estimating a gamma distribution with the same mean and SD as the mixture of all the estimates. This combined estimate involves estimates of all different windows.
J = jepidemic::JavaApi$get() instance = J$CoriEstimator$new(...); instance$selectMixtureCombination()
none
R6 CoriEstimator object: The estimator itself (a fluent method)
not available
selectWeightedMixtureCombination()The mixture combination strategy for selecting a posterior \(R_t\) involves finding all the estimates that have a window that span the estimate date (this may involve longer windowed estimate from dates in the future) and estimating a gamma distribution with the same mean and SD as the mixture of all the estimates. This combined estimate involves estimates of all different windows.
J = jepidemic::JavaApi$get() instance = J$CoriEstimator$new(...); instance$selectWeightedMixtureCombination(weights)
weights - the weighting of the different windows according to their length as a vector which much be the same length as the longest window, maxTau. - (java expects a RNumericVector)
R6 CoriEstimator object: The estimator itself (a fluent method)
not available
withDefaultPrior()This sets the selection strategy for prior estimate of the reproduction number to be the fixed R0 value provided to the CoriEstimator::new constructor. All estimates use the same prior and this is equivalent to the strategy implemented in EpiEstim (which has a default value of 5 for the mean and 5 for the SD of the R0 prior). This is an uninformed prior strategy.
J = jepidemic::JavaApi$get() instance = J$CoriEstimator$new(...); instance$withDefaultPrior()
none
R6 CoriEstimator object: The estimator itself (a fluent method)
not available
withFixedPrior()This sets the selection strategy for prior estimate of the reproduction number to be fixed value. All estimates use the same value as an uninformed prior, but enables us to compare the impact of different priors.
J = jepidemic::JavaApi$get() instance = J$CoriEstimator$new(...); instance$withFixedPrior(mean, sd)
mean - the mean of the fixed prior \(R_t\) - (java expects a double)
sd - the sd of the fixed prior \(R_t\) - (java expects a double)
R6 CoriEstimator object: The estimator itself (a fluent method)
not available
withAdaptivePrior()This sets the prior to be the posterior for the previous timestep, but with the SD of the previous posterior widened to allow the equivalent of a random walk. The widening factor defines how much change we expect to see in each time step
J = jepidemic::JavaApi$get() instance = J$CoriEstimator$new(...); instance$withAdaptivePrior(factor)
factor - must be above 1 (or else the estimate will become locked on a specific value) - (java expects a double)
R6 CoriEstimator object: The estimator itself (a fluent method)
not available
collectResampledQuantiles()This configures how the estimator combines multiple estimates of \(R_t\) using different infectivity profiles. In this case the estimator will randomly sample from the selected posterior gamma distribution produced for each infectivity profile. These samples are combined and a mean, sd and empirical quantiles calculated.
J = jepidemic::JavaApi$get() instance = J$CoriEstimator$new(...); instance$collectResampledQuantiles(sampleSize)
sampleSize - the number of samples to draw for each posterior estimate of \(R_t\). This number will be multiplied by the number of infectivity profile estimates and the number time points, so should not be set too high or it will lead to memory consumption issues. This is the equivalent of the $n2$ parameter in EpiEstim - (java expects a int)
R6 CoriEstimator object: The estimator itself (a fluent method)
not available
collectMixtureQuantiles()This configures how the estimator combines multiple estimates of \(R_t\) using different infectivity profiles. In this case it calculates a mixture distribution of all the posterior estimates, and combined values for mean, and standard deviation, of the mixture plus the quantiles using a brent solver.
J = jepidemic::JavaApi$get() instance = J$CoriEstimator$new(...); instance$collectMixtureQuantiles()
none
R6 CoriEstimator object: The estimator itself (a fluent method)
not available
collectMixtureApproximation()This configures how the estimator combines multiple estimates of \(R_t\) using different infectivity profiles. In this case it calculates a mixture distribution of all the posterior estimates, and then estimates a single gamma distribution with the same mean and SD as the mixture. This will only be a valid approximation if all the posterior estimates are close to each other, which will be the case if the infectivitiy profiles are fairly similar. It shoudl tend to produce estimates with less confidence. It is however the quickest method.
J = jepidemic::JavaApi$get() instance = J$CoriEstimator$new(...); instance$collectMixtureApproximation()
none
R6 CoriEstimator object: The estimator itself (a fluent method)
not available
detailedOutput()Configure the estimator to output full details for all infectivity profiles.
J = jepidemic::JavaApi$get() instance = J$CoriEstimator$new(...); instance$detailedOutput()
none
R6 CoriEstimator object: The estimator itself (a fluent method)
not available
withInfectivityProfile()Configure the estimator with an infectivity profile. At least one profile must be added
J = jepidemic::JavaApi$get() instance = J$CoriEstimator$new(...); instance$withInfectivityProfile(infectivityProfile, replace)
infectivityProfile - A numeric vector of the daily discrete probability of a secondary infection event occurring given an infected individual. It is assumed that this vector starts at time zero with a probability of zero. - (java expects a RNumericVector)
replace - replace the existing infectivity profile with this new one? if false then the profile is added to a list. - (java expects a boolean)
R6 CoriEstimator object: The estimator itself (a fluent method)
not available
withInfectivityProfileMatrix()Configure the estimator with an infectivity profile by specifying it as a matrix. This will replace all previously set profiles.
J = jepidemic::JavaApi$get() instance = J$CoriEstimator$new(...); instance$withInfectivityProfileMatrix(infectivityProfiles)
infectivityProfiles - A numeric array of the daily discrete probability of a secondary infection event occurring given an infected individual. It is assumed that this vector starts at time zero with a probability of zero. - (java expects a RNumericArray)
R6 CoriEstimator object: The estimator itself (a fluent method)
not available
atStartOfTimeseries()If the timeseries is at the start then we can safely impute zero values prior to the start of the timeseries. If the timeseries starts in the middle of the epidemic we must infer the infections prior to the beginning of the time series if we are to prevent sudden jumps in the estimates over the initial part of the timeseries.
J = jepidemic::JavaApi$get() instance = J$CoriEstimator$new(...); instance$atStartOfTimeseries()
none
R6 CoriEstimator object: The estimator itself (a fluent method)
not available
inMiddleOfTimeseries()If the timeseries starts in the middle of the epidemic we must infer the infections prior to the beginning of the time series if we are to prevent sudden jumps in the estimates over the initial part of the timeseries. This is done using the supplied value of R0 to infer a growth rate.
J = jepidemic::JavaApi$get() instance = J$CoriEstimator$new(...); instance$inMiddleOfTimeseries()
none
R6 CoriEstimator object: The estimator itself (a fluent method)
not available
estimateRt()Estimates \(R_t\) for a one or more timeseries of infections in an epidemic, where the supplied dataframe is grouped
J = jepidemic::JavaApi$get() instance = J$CoriEstimator$new(...); instance$estimateRt(incidence, dateColName, incidenceColName)
incidence - a dataframe containing at least 2 columns (one containing a date, the other a numeric count of cases). The dataframe may be grouped, in which case grouping is preserved, and each group is treated as a seperate time seriesincidenceColName - the name of the incidence column - (java expects a RDataframe)
dateColName - the name of the date column - (java expects a String)
incidenceColName - the name of the incidence column - (java expects a String)
RDataframe: a dataframe, containing either a summary of the estimates of \(R_t\) with mean, sd, and quantiles for each day, or a full breakdown of the component \(R_t\) estimates.
not available
estimateRtSingle()Estimates \(R_t\) for a single timeseries of infections in an epidemic.
J = jepidemic::JavaApi$get() instance = J$CoriEstimator$new(...); instance$estimateRtSingle(incidence, dateColName, incidenceColName)
incidence - a dataframe containing at least 2 columns (one containing a date, the other a numeric count of cases). The dataframe may be grouped, in which case grouping is preservedincidenceColName - the name of the incidence column - (java expects a RDataframe)
dateColName - the name of the date column - (java expects a String)
incidenceColName - the name of the incidence column - (java expects a String)
RDataframe: a dataframe, containing either a summary of the estimates of \(R_t\) with mean, sd, and quantiles for each day, or a full breakdown of the component \(R_t\) estimates.
not available
estimateRtFromRates()Estimates \(R_t\) for a one or more timeseries of infections in an epidemic, where the supplied dataframe is grouped
J = jepidemic::JavaApi$get() instance = J$CoriEstimator$new(...); instance$estimateRtFromRates(rates, dateColName, rateColName, samplesPerProfile)
rates - a dataframe containing at least 2 columns (one containing a date, the other a numeric poission rate of cases). The dataframe may be grouped, in which case grouping is preserved, and each group is treated as a seperate time series - (java expects a RDataframe)
dateColName - the name of the date column - (java expects a String)
rateColName - the name of the rate column - (java expects a String)
samplesPerProfile - the number of times to bootstrap per infectivity profile - (java expects a int)
RDataframe: a dataframe, containing either a summary of the estimates of \(R_t\) with mean, sd, and quantiles for each day, or a full breakdown of the component \(R_t\) estimates.
not available
estimateRtFromSingleRate()Estimates \(R_t\) for a single timeseries of infections in an epidemic.
J = jepidemic::JavaApi$get() instance = J$CoriEstimator$new(...); instance$estimateRtFromSingleRate(rate, dateColName, rateColName, samplesPerProfile)
rate - a dataframe containing at least 2 columns (one containing a date, the other a numeric estimate of possion rate of cases). The dataframe may be grouped, in which case grouping is preservedrateColName - the name of the estimated poisson rate - (java expects a RDataframe)
dateColName - the name of the date column - (java expects a String)
rateColName - the name of the estimated poisson rate - (java expects a String)
samplesPerProfile - the number of times to bootstrap per infectivity profile - (java expects a int)
RDataframe: a dataframe, containing either a summary of the estimates of \(R_t\) with mean, sd, and quantiles for each day, or a full breakdown of the component \(R_t\) estimates.
not available
if (FALSE) { J = jepidemic::JavaApi$get(); instance = J$CoriEstimator$new(r0Mean, r0SD, maxWindow) ## ----------------------------------- ## Method `CoriEstimator$legacySupport` ## ----------------------------------- ## ----------------------------------- ## Method `CoriEstimator$defaultEpiEstim` ## ----------------------------------- ## ----------------------------------- ## Method `CoriEstimator$defaultUncertainEpiEstim` ## ----------------------------------- ## ----------------------------------- ## Method `CoriEstimator$selectSpecificWindow` ## ----------------------------------- ## ----------------------------------- ## Method `CoriEstimator$selectAdaptiveWindow` ## ----------------------------------- ## ----------------------------------- ## Method `CoriEstimator$selectMinimumUncertainty` ## ----------------------------------- ## ----------------------------------- ## Method `CoriEstimator$selectMixtureCombination` ## ----------------------------------- ## ----------------------------------- ## Method `CoriEstimator$selectWeightedMixtureCombination` ## ----------------------------------- ## ----------------------------------- ## Method `CoriEstimator$withDefaultPrior` ## ----------------------------------- ## ----------------------------------- ## Method `CoriEstimator$withFixedPrior` ## ----------------------------------- ## ----------------------------------- ## Method `CoriEstimator$withAdaptivePrior` ## ----------------------------------- ## ----------------------------------- ## Method `CoriEstimator$collectResampledQuantiles` ## ----------------------------------- ## ----------------------------------- ## Method `CoriEstimator$collectMixtureQuantiles` ## ----------------------------------- ## ----------------------------------- ## Method `CoriEstimator$collectMixtureApproximation` ## ----------------------------------- ## ----------------------------------- ## Method `CoriEstimator$detailedOutput` ## ----------------------------------- ## ----------------------------------- ## Method `CoriEstimator$withInfectivityProfile` ## ----------------------------------- ## ----------------------------------- ## Method `CoriEstimator$withInfectivityProfileMatrix` ## ----------------------------------- ## ----------------------------------- ## Method `CoriEstimator$atStartOfTimeseries` ## ----------------------------------- ## ----------------------------------- ## Method `CoriEstimator$inMiddleOfTimeseries` ## ----------------------------------- ## ----------------------------------- ## Method `CoriEstimator$estimateRt` ## ----------------------------------- ## ----------------------------------- ## Method `CoriEstimator$estimateRtSingle` ## ----------------------------------- ## ----------------------------------- ## Method `CoriEstimator$estimateRtFromRates` ## ----------------------------------- ## ----------------------------------- ## Method `CoriEstimator$estimateRtFromSingleRate` ## ----------------------------------- }