update a fitted "hhh4" model

Re-fit a "hhh4" model with a modified control list.

Usage

# S3 method for class 'hhh4'
update(object, ..., S = NULL, subset.upper = NULL,
       use.estimates = object$convergence, evaluate = TRUE)

Arguments

object

a fitted "hhh4" model. Non-convergent fits can be updated as well.

...

components modifying the original control list for hhh4. Modifications are performed by modifyList(object$control, list(...)).

S

a named list of numeric vectors serving as argument for addSeason2formula, or NULL (meaning no modification of seasonal terms). This argument provides a convenient way of changing the number of harmonics in the formulae of the model components "ar", "ne" and "end" (to be used as names of the list). Non-specified components are not touched. Updating the formula of component comp works by first dropping all sine and cosine terms and then applying addSeason2formula with arguments S = S[[comp]] and period = frequency(object$stsObj), unless the component was originally disabled (f = ~ -1) when the harmonics are added to a simple intercept model and a warning is given.
Note that this step of updating seasonality is processed after modification of the control list by the ... arguments.

subset.upper

if a scalar value, refit the model to the data up to the time index given by subset.upper. The lower time index remains unchanged, i.e., control$subset[1]:subset.upper is used as the new subset. This argument is used by oneStepAhead.

use.estimates

logical specifying if coef(object) should be used as starting values for the new fit (which is the new default since surveillance 1.8-2, in case the original fit has converged). This works by matching names against the coefficients of the new model. Extra coefficients no longer in the model are silently ignored. Setting use.estimates = FALSE means to re-use the previous start specification object$control$start.
Note that coefficients can also receive initial values from an extra start argument in the update call (as in hhh4), which then takes precedence over coef(object).

evaluate

logical indicating if the updated model should be fitted directly (defaults to TRUE). Otherwise, the updated control list is returned.

Value

If evaluate = TRUE the re-fitted object, otherwise the updated control list for hhh4.

Author

Sebastian Meyer

See also

hhh4

Examples

data("salmonella.agona")
## convert to sts class
salmonella <- disProg2sts(salmonella.agona)

## fit a basic model
fit0 <- hhh4(salmonella,
            list(ar = list(f = ~1), end = list(f = addSeason2formula(~1))))

## the same, updating the minimal endemic-only model via 'S' (with a warning):
fit0.2 <- update(hhh4(salmonella), # has no AR component
                 S = list(ar = 0, end = 1))
local({
  fit0$control$start <- fit0.2$control$start <- NULL # obviously different
  stopifnot(all.equal(fit0, fit0.2))
})

## multiple updates: Poisson -> NegBin1, more harmonics
fit1 <- update(fit0, family = "NegBin1", S = list(end=2, ar=2))

## compare fits
AIC(fit0, fit1)
opar <- par(mfrow=c(2,2))
plot(fit0, type="fitted", names="fit0", par.settings=NULL)
plot(fit1, type="fitted", names="fit1", par.settings=NULL)
plot(fit0, fit1, type="season", components=c("end", "ar"), par.settings=NULL)
par(opar)