nimbleSMC (version 0.11.0)

buildIteratedFilter2: Create an IF2 algorithm.

Description

Create an IF2 algorithm for a given NIMBLE state space model.

Usage

buildIteratedFilter2(
  model,
  nodes,
  params = NULL,
  baselineNode = NULL,
  control = list()
)

Arguments

model

A NIMBLE model object, typically representing a state space model or a hidden Markov model.

nodes

A character vector specifying the stochastic latent model nodes over which the particle filter will stochastically integrate to estimate the log-likelihood function. All provided nodes must be stochastic. Can be one of three forms: a variable name, in which case all elements in the variable are taken to be latent (e.g., 'x'); an indexed variable, in which case all indexed elements are taken to be latent (e.g., 'x[1:100]' or 'x[1:100, 1:2]'); or a vector of multiple nodes, one per time point, in increasing time order (e.g., c("x[1:2, 1]", "x[1:2, 2]", "x[1:2, 3]", "x[1:2, 4]")).

params

A character vector specifying the top-level parameters to obtain maximum likelihood estimates of. If unspecified, parameter nodes are specified as all stochastic top level nodes which are not in the set of latent nodes specified in nodes.

baselineNode

A character vector specifying the node that is the latent node at the "0th" time step. The first node in nodes should depend on this baseline, but baselineNode should have no data depending on it. If NULL (the default), any initial state is taken to be fixed at the values present in the model at the time the algorithm is run.

control

A list specifying different control options for the IF2 algorithm. Options are described in the ‘details’ section below.

Reparameterization

The IF2 algorithm perturbs the parameters using a normal distribution, which may not be optimal for parameters whose support is not the whole real line, such as variance parameters, which are restricted to be positive. We recommend that users reparameterize the model in advance, e.g., writing variances and standard deviations on the log scale and probabilities on the logit scale. This requires specifying priors directly on the transformed parameters.

Parameter prior distributions

While NIMBLE's IF2 algorithm requires prior distributions on the parameters, the IF2 algorithm produces maximum likelihood estimates and does not directly use those prior distributions. We require the prior distributions to be stated only so that we can automatically determine which model nodes are the parameters. The IF2 algorithm also makes use of any bounds on the parameters.

Diagnostics and information stored in the algorithm object

The IF2 algorithm stores the estimated MLEs, one from each iteration, in estimates. It also stores standard deviation of the particles from each iteration, one per parameter, in estSD. Finally it stores the estimated log-likelihood at the estimated MLE from each iteration in logLik.

Author

Nicholas Michaud, Dao Nguyen, and Christopher Paciorek

Details

Each of the control() list options are described in detail below:

sigma

A vector specifying a non-negative perturbation magnitude for each element of the params argument. Defaults to a vector of 1's.

initParamSigma

An optional vector specifying a vector of standard deviations to use when simulating an initial particle swarm centered on the initial value of the parameters. Defaults to sigma.

inits

A vector specifying an initial value for each element of the params argument. Defaults to the parameter values in the model at the time the model is built.

timeIndex

An integer used to manually specify which dimension of the latent state variable indexes time. Only needs to be set if the number of time points is less than or equal to the size of the latent state at each time point.

initModel

A logical value indicating whether to initialize the model before running the filtering algorithm. Defaults to TRUE.

The IF2 agorithm uses iterated filtering to estimate maximum likelihood values for top-level parameters for a state space model.

The resulting specialized IF2 algorithm will accept the following arguments:

m

A single integer specifying the number of particles to use for each run of the filter.

n

A single integer specifying the number of overall filter iterations to run.

alpha

A double specifying the cooling factor to use for the IF2 algorithm.

The run fuction will return a vector with the estimated MLE. Additionally, once the specialized algorithm has been run, it can be continued for additional iterations by calling the continueRun method.

References

Ionides, E.L., D. Nguyen, Y. Atchad\'e, S. Stoev, and A.A. King (2015). Inference for dynamic and latent variable models via iterated, perturbed Bayes maps. Proceedings of the National Academy of Sciences, 112(3), 719-724.

See Also

Other particle filtering methods: buildAuxiliaryFilter, buildBootstrapFilter, buildEnsembleKF, buildLiuWestFilter

Examples

## For illustration only.
exampleCode <- nimbleCode({
  x0 ~ dnorm(0, var = 1)
  x[1] ~ dnorm(.8 * x0, var = 1)
  y[1] ~ dnorm(x[1], var = .5)
  for(t in 2:10){
    x[t] ~ dnorm(.8 * x[t-1], sd = sigma_x)
    y[t] ~ dnorm(x[t], var = .5)
  }
  sigma_x ~ dunif(0, 10)
})

model <- nimbleModel(code = exampleCode, data = list(y = rnorm(10)),
                     inits = list(x0 = 0, x = rnorm(10), sigma_x = 1))
my_IF2 <- buildIteratedFilter2(model, 'x', params = 'sigma_x')
## Now compile and run, e.g.,
## Cmodel <- compileNimble(model)
## Cmy_IF2 <- compileNimble(my_IF2, project = model)
## MLE estimate of a top level parameter named sigma_x:
## sigma_x_MLE <- Cmy_IF2$run(m = 10000, n = 50, alpha = 0.2)
## visualize progression of the estimated log-likelihood
## ts.plot(Cmy_IF2$logLik)
## Continue running algorithm for more precise estimate:
## sigma_x_MLE <- Cmy_IF2$continueRun(n = 50, alpha = 0.2)