algo.hhh: Model fit based on the Held, Hoehle, Hofman paper
In jimhester/surveillance: Temporal and Spatio-Temporal Modeling and Monitoring of Epidemic Phenomena

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

Fits a Poisson/negative binomial model with mean μ_it (as described in Held/HÃ¶hle/Hofmann, 2005) to a multivariate time series of counts.

algo.hhh(disProgObj, control=list(lambda=TRUE, neighbours=FALSE, 
   linear=FALSE, nseason = 0,
   negbin=c("none", "single", "multiple"), 
   proportion=c("none", "single", "multiple"),lag.range=NULL), 
   thetastart=NULL, verbose=TRUE)

`disProgObj`	object of class `disProg`
`control`	control object: `lambda` If `TRUE` an autoregressive parameter λ is included, if `lambda` is a vector of logicals, unit-specific parameters λ_i are included. By default, observations y_t-lag at the previous time points, i.e. lag=1, are used for the autoregression. Other lags can be used by specifying `lambda` as a vector of integers, see Examples and Details. `neighbours` If `TRUE` an autoregressive parameter for adjacent units φ is included, if `neighbours` is a vector of logicals, unit-specific parameters φ_i are included. By default, observations y_t-lag at the previous time points, i.e. lag=1, are used for the autoregression. Other lags can be used by specifying `neighbours` as a vector of integers. `linear` a `logical` (or a vector of logicals) indicating wether a linear trend β (or a linear trend β_i for each unit) is included `nseason` Integer number of Fourier frequencies; if `nseason` is a vector of integers, each unit i gets its own seasonal parameters `negbin` if `"single"` negative binomial rather than poisson is used, if `"multiple"` unit-specific overdispersion parameters are used. `proportion` see Details `lag.range` determines which observations are used to fit the model
`thetastart`	vector with starting values for all parameters specified in the control object (for `optim`).
`verbose`	if `true` information about convergence is printed

This functions fits a model as specified in equations (1.2) and (1.1) in Held et al. (2005) to univariate time series, and as specified in equations (3.3) and (3.2) (with extensions given in equations (2) and (4) in Paul et al., 2008) to multivariate time series.

For univariate time series, the mean structure of a Poisson or a negative binomial model is

μ_t = λ y_t-lag + ν_t

where

log(ν_t) = α + β t + ∑_(j=1)^S (γ_(2j-1) * sin(ω_j * t) + γ_2j * cos(ω_j * t) )

and ω_j = 2 * π * j / period are Fourier frequencies with known period, e.g. period=52 for weekly data.

Per default, the number of cases at time point t-1, i.e. lag=1, enter as autoregressive covariates into the model. Other lags can also be considered.

For multivariate time series the mean structure is

μ_it = λ_i * y_i,t-lag + φ_i * ∑_(j ~ i) w_ji * y_j,t-lag + n_it * ν_it

where

log(ν_it) = α_i + β_i * t + ∑_(j=1)^S_i (γ_(i,2j-1) * sin(ω_j * t) + γ_(i,2j) * cos(ω_j * t) )

and n_it are standardized population counts. The weights w_ji are specified in the columns of the neighbourhood matrix disProgObj$neighbourhood.

Alternatively, the mean can be specified as

μ_it = λ_i *π_i * y_i,t-1 + ∑_(j ~ i) λ_j *(1-π_j)/|k ~ j| * y_j,t-1 + n_it * ν_it

if proportion="single" ("multiple") in the control argument. Note that this model specification is still experimental.

Returns an object of class ah with elements

`coefficients`	estimated parameters
`se`	estimated standard errors
`cov`	covariance matrix
`loglikelihood`	loglikelihood
`convergence`	logical indicating whether `optim` converged or not
`fitted.values`	fitted mean values μ_it
`control`	specified control object
`disProgObj`	specified `disProg`-object
`lag`	which lag was used for the autoregressive parameters lambda and phi
`nObs`	number of observations used for fitting the model

For the time being this function is not a surveillance algorithm, but only a modelling approach as described in the papers by Held et. al (2005) and Paul et. al (2008).

M. Paul, L. Held, M. HÃ¶hle

Held, L., HÃ¶hle, M., Hofmann, M. (2005) A statistical framework for the analysis of multivariate infectious disease surveillance counts, Statistical Modelling, 5, 187–199.

Paul, M., Held, L. and Toschke, A. M. (2008) Multivariate modelling of infectious disease surveillance data, Statistics in Medicine, 27, 6250–6267.

algo.hhh.grid, hhh4

# univariate time series: salmonella agona cases 
data(salmonella.agona)

model1 <- list(lambda=TRUE, linear=TRUE, 
               nseason=1, negbin="single")
               
algo.hhh(salmonella.agona, control=model1)

# multivariate time series: 
# measles cases in Lower Saxony, Germany
data(measles.weser)

# same model as above
algo.hhh(measles.weser, control=model1)

# include autoregressive parameter phi for adjacent "Kreise"
# specifiy start values for theta
model2 <- list(lambda = TRUE, neighbours = TRUE, 
               linear = FALSE, nseason = 1, 
               negbin = "single")
algo.hhh(measles.weser, control = model2, thetastart = rep(0, 20) )
                  
## weekly counts of influenza and meningococcal infections 
## in Germany, 2001-2006
data(influMen)

# specify model with two autoregressive parameters lambda_i, overdispersion
# parameters psi_i, an autoregressive parameter phi for meningococcal infections
# (i.e. nu_flu,t = lambda_flu * y_flu,t-1  
#  and  nu_men,t = lambda_men * y_men,t-1 + phi_men*y_flu,t-1 )
# and S=(3,1) Fourier frequencies
model <- list(lambda=c(TRUE,TRUE), neighbours=c(FALSE,TRUE),
              linear=FALSE,nseason=c(3,1),negbin="multiple")
              
# run algo.hhh
algo.hhh(influMen, control=model)

# now meningococcal infections in the same week should enter as covariates
# (i.e. nu_flu,t = lambda_flu * y_flu,t-1  
#  and  nu_men,t = lambda_men * y_men,t-1 + phi_men*y_flu,t )
model2 <- list(lambda=c(1,1), neighbours=c(NA,0),
              linear=FALSE,nseason=c(3,1),negbin="multiple")
              
algo.hhh(influMen, control=model2)