FluHMM: Create a FluHMM object
In thlytras/FluHMM: Hidden Markov Model for influenza sentinel surveillance

Description Usage Arguments Details Value

This function takes the set of rates as input, fits the model in JAGS, and constructs a ‘FluHMM’ object. The object can then be used to generate MCMC samples, summarize and plot the results.

1 2	FluHMM(rates, seasonRates = rates, isolates = NULL, weights = NULL, logSE = NULL, K = 3, priors = NULL, initConv = TRUE, maxit = 95000)

`rates`	The set of weekly influenza-like illness / acute respiratory infection (ILI/ARI) rates obtained from sentinel surveillance, up to the current week, as a numeric vector.
`seasonRates`	The set of weekly ILI/ARI rates for the whole season, if available (i.e. if season has been compleated). This allows fitting the model for a partial season, but plotting it overlaid on the whole season, see `plot.FluHMM`.
`isolates`	A optional set of weekly numbers of influenza-positive lab isolates. Does not have to be of equal length with the set of rates. If specified, an object of class ‘FluJointHMM’ is produced (inheriting also from class ‘FluHMM’), which jointly models both series (the rates and the number of isolates) as observations from the same Hidden Markov states chain.
`weights`	A vector of of length equal to `length(rates)` containing observation weights for the rates. If `NULL`, all weights are set equal to 1.
`logSE`	An optional vector of length equal to `length(rates)` containing log standard errors for the rates. If `NULL`, the rates are treated in the model as "true" rates, i.e. without measurement error.
`K`	The first K observations (weeks) of the rates are considered a priori to belong in the pre-epidemic phase of the model. Set this to a higher level if you have lots of observations (more than 25) to speed up fitting of the model, as long as you are confident that the weeks really belong to the pre-epidemic phase.
`initConv`	If `TRUE` (the default), MCMC samples are generated from the chains until initial convergence, see details.
`maxit`	Maximum number of iterations performet for initial convergence, see `autoInitConv`.

The function constructs an object of class ‘FluHMM’, which contains all the input, model information and results, and can be processed further as required. The minimum input is the set of weekly ILI/ARI rates (argument rates) up to the current week. The function fits the appropriate model in JAGS (with or without measurement error, depending on the argument logSE, and with or without a submodel for the isolates, depending on the argument isolates), and generates posterior samples for 5000 iterations. Six MCMC chains are used.

Then, provided the argument initConv is TRUE (the default), the sample for sigma[1] (i.e. the standard deviation of the pre- and post-epidemic phases) is checked for convergence using the Gelman and Rubin diagnostic. This is defined as "initial convergence". If initial convergence has not been reached, the posterior sample is discarded, the chains are sampled again for 5000 iterations, and a new check is made. The process is repeated again until initial convergence is reached or after 95000 iterations. See autoInitConv for details.

After initial convergence is reached, a *new sample* should be generated for inference using update.FluHMM, with the number of iterations dependent on the desired precision. If full convergence is not reached, the object can be autoUpdated until full convergence.

An object of class ‘FluHMM’, which is a list with the following components:

model: The fitted model; an object of class ‘jags’
cSample: An ‘mcmc.list’ object containing the posterior samples for the variables in the model.
params: Mean and standard deviation of the parameters of interest.
states: A Nx5 matrix, where N==length(rates), containing the probabilities of each phase per week
mu: A vector with the fitted mean rates per week
elapsedTime: Total processing time spent fitting the model and sampling from the chains.
gelman: The Gelman-Rubin diagnostic for the main parameters in the model
converged: TRUE if full convergence has been reached, i.e. if the Gelman-Rubin diagnostic is less than 1.1 for all parameters in the model.
initConv: TRUE if "initial convergence" has been reached, i.e. if the Gelman-Rubin diagnostic for sigma[1] (the standard deviation of the pre- and post-epidemic phases) is less than 1.1 .
rates: The ILI/ARI rates that were used as input in the model.
seasonRates: The ILI/ARI rates for the entire season, if available.
weights: The set of observation weights used (usually a vector of ones).
logSE: The log standard error of the rates if available; NULL otherwise.