fit_model {fHMM}

Model fitting

Description

This function fits a hidden Markov model via numerical likelihood maximization.

Usage

fit_model(
  data,
  controls = data[["controls"]],
  fit = list(),
  runs = 10,
  origin = FALSE,
  accept = 1:3,
  gradtol = 0.01,
  iterlim = 100,
  print.level = 0,
  steptol = 0.01,
  ncluster = 1,
  seed = NULL,
  verbose = TRUE,
  initial_estimate = NULL
)

Arguments

data

An object of class fHMM_data.

controls

Either a list or an object of class fHMM_controls.

The list can contain the following elements, which are described in more detail below:

• hierarchy, defines an hierarchical HMM,

• states, defines the number of states,

• sdds, defines the state-dependent distributions,

• horizon, defines the time horizon,

• period, defines a flexible, periodic fine-scale time horizon,

• data, a list of controls that define the data,

• fit, a list of controls that define the model fitting

Either none, all, or selected elements can be specified.

Unspecified parameters are set to their default values.

Important: Specifications in controls always override individual specifications.

fit

A list of controls specifying the model fitting.

The list can contain the following elements, which are described in more detail below:

• runs, defines the number of numerical optimization runs,

• origin, defines initialization at the true parameters,

• accept, defines the set of accepted optimization runs,

• gradtol, defines the gradient tolerance,

• iterlim, defines the iteration limit,

• print.level, defines the level of printing,

• steptol, defines the minimum allowable relative step length.

Either none, all, or selected elements can be specified.

Unspecified parameters are set to their default values, see below.

Specifications in fit override individual specifications.

runs

An integer, setting the number of randomly initialized optimization runs of the model likelihood from which the best one is selected as the final model.

By default, runs = 10.

origin

Only relevant for simulated data, i.e., if the data control is NA.

In this case, a logical. If origin = TRUE the optimization is initialized at the true parameter values. This sets run = 1 and accept = 1:5.

By default, origin = FALSE.

accept

An integer (vector), specifying which optimization runs are accepted based on the output code of nlm.

By default, accept = 1:3.

gradtol

A positive numeric value, specifying the gradient tolerance, passed on to nlm.

By default, gradtol = 0.01.

iterlim

A positive integer value, specifying the iteration limit, passed on to nlm.

By default, iterlim = 100.

print.level

One of 0, 1, and 2 to control the verbosity of the numerical likelihood optimization, passed on to nlm.

By default, print.level = 0.

steptol

A positive numeric value, specifying the step tolerance, passed on to nlm.

By default, gradtol = 0.01.

ncluster

Set the number of clusters for parallel optimization runs to reduce optimization time. By default, ncluster = 1 (no clustering).

seed

Set a seed for the generation of initial values. No seed by default.

verbose

Set to TRUE to print progress messages.

initial_estimate

Optionally defines an initial estimate for the numerical likelihood optimization. Good initial estimates can improve the optimization process. Can be:

• NULL (the default), in this case

  • applies a heuristic to calculate a good initial estimate

  • or uses the true parameter values (if available and data$controls$origin is TRUE)

• or an object of class parUncon (i.e., a numeric of unconstrained model parameters), for example the estimate of a previously fitted model (i.e. the element model$estimate).

Details

Multiple optimization runs starting from different initial values are computed in parallel if ncluster > 1.

Value

An object of class fHMM_model.

Examples

### 2-state HMM with normal distributions

# set specifications
controls <- set_controls(
  states = 2, sdds = "normal", horizon = 100, runs = 10
)

# define parameters
parameters <- fHMM_parameters(controls, mu = c(-1, 1), seed = 1)

# sample data
data <- prepare_data(controls, true_parameter = parameters, seed = 1)

# fit model
model <- fit_model(data, seed = 1)

# inspect fit
summary(model)
plot(model, "sdds")

# decode states
model <- decode_states(model)
plot(model, "ts")

# predict
predict(model, ahead = 5)