Package 'projections' - June 30, 2020 - CRAN
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
Package ‘projections’
June 30, 2020
Title Project Future Case Incidence
Version 0.5.1
Description
Provides functions and graphics for projecting daily incidence based on past incidence, and esti-
mates of the serial interval and reproduction number. Projections are based on a branching pro-
cess using a Poisson-distributed number of new cases per day, similar to the model used for esti-
mating R in 'EpiEstim' or in 'earlyR', and described by Nouvel-
let et al. (2017) . The package provides the S3 class 'projec-
tions' which extends 'matrix', with accessors and additional helpers for handling, subset-
ting, merging, or adding these objects, as well as dedicated printing and plotting methods.
Depends R (>= 3.5.0)
License MIT + file LICENSE
Encoding UTF-8
LazyData true
Suggests testthat, vdiffr, roxygen2, knitr, rmarkdown, outbreaks,
magrittr, distcrete
Imports stats, utils, incidence (>= 1.4.1), ggplot2, methods
RoxygenNote 7.1.1
URL http://www.repidemicsconsortium.org/projections
BugReports http://github.com/reconhub/projections/issues
NeedsCompilation no
Author Thibaut Jombart [aut, cre],
Pierre Nouvellet [aut],
Sangeeta Bhatia [ctb],
Zhian N. Kamvar [ctb],
Tim Taylor [ctb],
Stephane Ghozzi [ctb]
Maintainer Thibaut Jombart
Repository CRAN
Date/Publication 2020-06-30 10:50:07 UTC
12 as.matrix.projections
R topics documented:
as.matrix.projections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
build_projections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
cumulate.projections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
get_dates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
merge_add_projections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
merge_projections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
plot.projections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
print.projections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
summary.projections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
[.projections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Index 16
as.matrix.projections Conversion of projections objects
Description
These functions convert projections objects into other classes.
Usage
## S3 method for class 'projections'
as.matrix(x, ...)
## S3 method for class 'projections'
as.data.frame(x, ..., long = FALSE)
Arguments
x An projections object, or an object to be converted as projections (see de-
tails).
... Further arguments passed to other functions (no used).
long A logical indicating if the output data.frame should be ’long’, i.e. where a single
column containing ’groups’ is added in case of data computed on several groups.
Author(s)
Thibaut Jombart
See Also
the project function to generate the ’projections’ objects.build_projections 3
build_projections Constructor for projections objects
Description
This function builds a valid projections object from some input simulations and dates.
Usage
build_projections(x, dates = NULL, cumulative = FALSE, order_dates = TRUE)
Arguments
x A matrix of simulated incidence stored as integers, where rows correspond to
dates and columns to simulations.
dates A vector of dates containing one value per row in x; acceptable formats are:
integer, Date, and POSIXct; if NULL, the time steps will be counted, with the
first dates corresponding to 0.
cumulative A logical indicating if data represent cumulative incidence; defaults to FALSE.
order_dates A logical indicating whether the dates should be ordered, from the oldest to the
most recent one; ‘TRUE‘ by default.
Author(s)
Thibaut Jombart
See Also
the project function to generate the ’projections’ objects.
cumulate.projections Compute cumulative projections
Description
cumulate is an S3 generic to compute cumulative numbers defined in the package incidence. The
method for projections objects turns predicted incidences into cumulative incidences over time.
Usage
## S3 method for class 'projections'
cumulate(x)
Arguments
x A projections object.4 get_dates
Author(s)
Thibaut Jombart
See Also
The project function to generate the projections objects.
Examples
if (require(distcrete) &&
require(incidence)) {
## simulate basic epicurve
datmerge_add_projections 5
Details
• get_dates: get dates of the predictions.
Author(s)
Thibaut Jombart
Examples
if (require(distcrete) && require(incidence)) { withAutoprint({
## prepare input: epicurve and serial interval
dat6 merge_projections
Arguments
x A ‘list‘ of ‘projections‘ objects to be added.
a A ‘projections‘ object.
b A ‘projections‘ object.
Author(s)
Thibaut Jombart
Examples
if (require(incidence)) {
## make toy data and projections
set.seed(1)
iplot.projections 7
Usage
merge_projections(x)
Arguments
x A ‘list‘ of ‘projections‘ objects to be merged.
Author(s)
Thibaut Jombart
Examples
## generate toy data
dates8 plot.projections
Usage
## S3 method for class 'projections'
plot(x, ylab = NULL, title = NULL, ...)
add_projections(
p,
x,
quantiles = c(0.01, 0.05, 0.1, 0.5),
ribbon = TRUE,
boxplots = FALSE,
palette = quantile_pal,
quantiles_alpha = 1,
linetype = 1,
linesize = 0.5,
ribbon_quantiles = NULL,
ribbon_color = NULL,
ribbon_alpha = 0.3,
boxplots_color = "#47476b",
boxplots_fill = "grey",
boxplots_alpha = 0.8,
outliers = TRUE
)
Arguments
x A projections object.
ylab An optional label for the y-axis. If missing will default to "predicted incidence"
or, if cumulative, "predicted cumulative incidence"
title An optional title.
... Further arguments to be passed to add_projections.
p A previous incidence plot to which projections should be added.
quantiles A vector of quantiles to plot, automatically completed to be symmetric around
the median.
ribbon A logical indicating if a ribbon should be drawn; defaults to TRUE.
boxplots A logical indicating if boxplots should be drawn.
palette A color palette to be used for plotting the quantile lines; defaults to quantile_pal.
quantiles_alpha
A number used to control the transparency of the quantile lines, from 0 (full
transparency) to 1 (full opacity); defaults to 1.
linetype An integer indicating the type of line used for plotting the quantiles; defaults to
1 for a plain line.
linesize An integer indicating the size of line used for plotting the quantiles; defaults to
0.5.plot.projections 9
ribbon_quantiles
A vector of 2 quantiles to be used to determine the limits of the ribbon; if NULL
(default); uses the most extreme quantiles if available; if quantiles are not pro-
vided, the daily range will be used.
ribbon_color Any valid color, used for the ribbon.
ribbon_alpha A number used to control the transparency of the ribbon, from 0 (full trans-
parency) to 1 (full opacity); defaults to 0.3.
boxplots_color Any valid color, used for the boxplot.
boxplots_fill Any valid color, used for filling the boxplot.
boxplots_alpha A number used to control the transparency of the boxplots, from 0 (full trans-
parency) to 1 (full opacity); defaults to 0.8.
outliers A logical indicating if outliers should be displayed alongside the boxplots; de-
faults to TRUE.
Author(s)
Thibaut Jombart
See Also
project to generate projections
Examples
if (require(outbreaks) &&
require(distcrete) &&
require(incidence) &&
require(magrittr)) {
si10 print.projections
plot(proj, boxplots = TRUE, quantiles = FALSE, outliers = FALSE)
plot(proj, linetype = 3)
## adding them to incidence plot
plot(i) %>% add_projections(proj)
plot(i[1:160]) %>% add_projections(proj)
plot(i[1:160]) %>% add_projections(proj, boxplots = FALSE)
plot(i[1:160]) %>%
add_projections(proj, boxplots_alpha = .3, boxplots_color = "red")
## same, with customised quantiles and colors
quantilesproject 11
project Project future incidence
Description
This function simulates future incidence based on past incidence data, a selection of plausible re-
production numbers (R), and the distribution of the serial interval (time from primary onset to
secondary onset).
Usage
project(
x,
R,
si,
n_sim = 100,
n_days = 7,
R_fix_within = FALSE,
model = c("poisson", "negbin"),
size = 0.03,
time_change = NULL
)
Arguments
x An incidence object containing daily incidence; other time intervals will trig-
ger an error.
R A vector of numbers representing plausible reproduction numbers; for instance,
these can be samples from a posterior distribution using the ‘earlyR‘ or ‘Epi-
Estim‘ packages. If ‘time_change‘ is provided, then it must be a ‘vector‘ (for
fixed values of R per time window) or a ‘list‘ of vectors (for separate distribu-
tions of R per time window), with one element more than the number of dates
in ‘time_change‘.
si A function computing the serial interval, or a ‘numeric‘ vector providing its
mass function, starting a day 1, so that si[i] is the PMF for serial interval of
‘i‘. The model implicitly assumes that ‘si[0] = 0‘. For functions, we strongly
recommend using the RECON package distcrete to obtain such distribution
(see example).
n_sim The number of epicurves to simulate. Defaults to 100.
n_days The number of days to run simulations for. Defaults to 14.
R_fix_within A logical indicating if R should be fixed within simulations (but still varying
across simulations). If FALSE, R is drawn for every simulation and every time
step. Fixing values within simulations favours more extreme predictions (see
details)
model Distribution to be used for projections. Must be one of "poisson" or "negbin"
(negative binomial process). Defaults to poisson12 project
size size parameter of negative binomial distribition. Ignored if model is poisson
time_change an optional vector of times at which the simulations should use a different sam-
ple of reproduction numbers, provided in days into the simulation (so that day
’1’ is the first day after the input ‘incidence‘ object); if provided, ‘n‘ dates in
‘time_change‘ will produce ‘n+1‘ time windows, in which case ‘R‘ should be a
list of vectors of ‘n+1‘ ‘R‘ values, one per each time window.
Details
The decision to fix R values within simulations (R_fix_within) reflects two alternative views of
the uncertainty associated with R. When drawing R values at random from the provided sample,
(R_fix_within set to FALSE), it is assumed that R varies naturally, and can be treated as a random
variable with a given distribution. When fixing values within simulations (R_fix_within set to
TRUE), R is treated as a fixed parameter, and the uncertainty is merely a consequence of the estima-
tion of R. In other words, the first view is rather Bayesian, while the second is more frequentist.
Author(s)
Pierre Nouvellet (original model), Thibaut Jombart (bulk of the code), Sangeeta Bhatia (Negative
Binomial model), Stephane Ghozzi (bug fixes time varying R)
Examples
## example using simulated Ebola outbreak
if (require(outbreaks) &&
require(distcrete) &&
require(incidence) &&
require(magrittr)) {
sisummary.projections 13
set.seed(1)
R14 [.projections
Description
This method summarises predicted epidemic trajectories contained in a ‘projections‘ object by days,
deriving the mean, standard deviation, and user-specified quantiles for each day.
Usage
## S3 method for class 'projections'
summary(
object,
quantiles = c(0.025, 0.25, 0.5, 0.75, 0.975),
mean = TRUE,
sd = TRUE,
min = TRUE,
max = TRUE,
...
)
Arguments
object A ‘projections‘ object to summarise
quantiles A ‘numeric‘ vector indicating which quantiles should be computed; ignored if
‘FALSE‘ or of length 0
mean a ‘logical‘ indicating of the mean should be computed
sd a ‘logical‘ indicating of the standard deviation should be computed
min a ‘logical‘ indicating of the minimum should be computed
max a ‘logical‘ indicating of the maximum should be computed
... only preesnt for compatibility with the generic
if (require(incidence)) i[.projections 15
Usage
## S3 method for class 'projections'
x[i, j]
## S3 method for class 'projections'
subset(x, ..., from = NULL, to = NULL, sim = TRUE)
Arguments
x An projections object, generated by the function project.
i a subset of dates to retain
j a subset of groups to retain
... Further arguments passed to other methods (not used).
from The starting date; data strictly before this date are discarded.
to The ending date; data strictly after this date are discarded.
sim (optional) The simulations to retained, indicated as subsets of the columns of x.
Author(s)
Thibaut Jombart
See Also
The project function to generate the ’projections’ objects.Index
+.projections (merge_add_projections), 5
[.projections, 14
add_projections (plot.projections), 7
as.data.frame.projections
(as.matrix.projections), 2
as.matrix.projections, 2
build_projections, 3
cumulate.projections, 3
get_dates, 4
merge_add_projections, 5
merge_projections, 6
plot.projections, 7
print.projections, 10
project, 2–4, 7, 9, 11, 15
subset.projections ([.projections), 14
summary.projections, 13
16You can also read
