Fits a baseline to case data

excessCases takes a time series of cases (daily or weekly) and fits a harmonic baseline. There is also an option to import influenza data from the CDC's NREVSS database and match it by state, or import Google search queries for RSV for the respective state. Dummy variables adjust for variations in average incidence between years, and interactions between RSV or flu allow these effects to vary over time.

excessCases(ds, sub.statevar = "none", statevar = "state",
  agevar = "none", datevar, covs = character(), use.syndromes,
  denom.var, adj.flu = "none", adj.rsv = "none", time.res = "day",
  extrapolation.date = "2020-03-01")

Arguments

ds

A data.frame, with a format similar to the one produced by the ts_format function. There should be a row for each time period (week or day), location (e.g. state, county), and age category. There must be a column for date (YYYY-MM-DD), age category, location, and the number of counts for each of the selected syndromes. There should also be a column with a denominator (e.g., total number of ED visits). If there is no denominator, create a variable with vector of 1s as a substitute.
sub.statevar

A string. Which variable in the input data frame contains the local geography identifier (e.g., county, borough)
statevar

A string. Which variable in the input data frame contains the state (2-digit state; e.g. 'NY')?
agevar

A string. Which variable in the input data frame contains the age group? Use 'none' if there is no age grouping in the data
datevar

A string. Which variable in the input data frame contains the date?
covs

A character vector. Which, if any, variables in ds should be treated as covariates in fitting the baseline model? Default is to not consider any variables in ds to be covariates.
use.syndromes

A vector with the variable names for syndromes to be tested (e.g., c('ILI','respiratory') ).
denom.var

A string. Which variable on the input dataframe should be used as the denominator? For instance, all ED visits.
adj.flu

A logical scalar. How should influenza be adjusted for when fitting the seasonal baseline? Possible values are 'none' for no adjustment (default); 'auto': automatically downloads NREVSS data from CDC and matches by state and week; or specify the name of a variable in the the input dataframe that contains a variable for influenza. The package cdcfluview is required to use 'auto'.
adj.rsv

A string. How should RSV be adjusted for when fitting the seasonal baseline? Possible values are 'none' for no adjustment (default); 'auto': automatically downloads the weekly volume of search queries for 'RSV' for the last 5 years from Google trends and matches by state. Note that a maximum of 5 states can be included on the input dataset when using the 'auto option'; Or specify the name of a variable in the the input dataframe that contains a variable for influenza.
time.res

One of c("day", "week", "month"). What is the data binned by?
extrapolation.date

The model is fit up to this date, and then extrapolated for all future dates. Defaults to "2020-03-01"
flu.import

A logical scalar. Import the latest influenza testing data from the CDC NREVSS system? If TRUE, the data will be downloaded and merge with the input dataframe by state and week. the flu variable will be included in the regressionwhen fitting the baseline
rsv.import

A logical scalar. Import weekly search volume for 'RSV' for the states in the input dataframe? This option can only be used if there are 5 or fewer states on the input dataset. This variable is included in the regression model when fitting the seasonal baseline.

Value

A list of lists with an entry for each syndrome, and sub-lists by age group and geography:

date: vector of dates used in the model. Use the helper function excessExtract to pull out specific components and organize them into an array

y: array of observed values for the syndromes

resid1: Observed/model fitted values

upi: upper 95

lpi: lower 95

sqrt.rsv: RSV variale used in the model (if any)

log.flu: flu variable used in the model (if any)

unexplained.cases: observed-expected(fitted)

denom: denominator used in the model

pred.var: variance of the prediction interval

Examples

 library(cdcfluview)
#> Warning: package 'cdcfluview' was built under R version 3.6.3
 ili.data <- ilinet(region = c("state"))
 ili.data$state <- state.abb[match(ili.data$region, state.name)]

 ili.data <- ili.data[, c("state", "week_start", "ilitotal", "total_patients")]
 ili.data <- ili.data[ili.data$state %in% c("CA", "NY", "WA", "NJ", "CT"), ]

 excess_cases <-
   excessCases(ds = ili.data,
               datevar = "week_start",
               agevar = "none",
               statevar = "state",
               denom.var = "total_patients",
               use.syndromes = c("ilitotal"),
               time.res = "week")