MarkovChain {hmmTMB}R Documentation

R6 class for HMM hidden process model

Description

Contains the parameters and model formulas for the hidden process model.

Methods

Public methods

Method new()

Create new MarkovChain object

Usage
MarkovChain$new(
  data,
  formula = NULL,
  n_states,
  tpm = NULL,
  initial_state = "estimated",
  fixpar = NULL,
  ref = 1:n_states
)
Arguments
data

Data frame, needed to create model matrices, and to identify the number of time series (which each have a separate initial distribution)

formula

Either (1) R formula, used for all transition probabilities, or (2) matrix of character strings giving the formula for each transition probability, with "." along the diagonal (or for reference elements; see ref argument). (Default: no covariate dependence.)

n_states

Number of states. If not specified, then formula needs to be provided as a matrix, and n_states is deduced from its dimensions.

tpm

Optional transition probability matrix, to initialise the model parameters (intercepts in model with covariates). If not provided, the default is a matrix with 0.9 on the diagonal.

initial_state

Specify model for initial state distribution. There are five different options:

  • "estimated": a separate initial distribution is estimated for each ID (default)

  • "stationary": the initial distribution is fixed to the stationary distribution of the transition probability matrix for the first time point of each ID

  • "shared": a common initial distribution is estimated for all IDs

  • integer value between 1 and n_states: used as the known initial state for all IDs

  • vector of integers between 1 and n_states (of length the number of IDs): each element is used as the known initial state for the corresponding ID

fixpar

List with optional elements "hid" (fixed parameters for transition probabilities), "lambda_hid" (fixed smoothness parameters), and "delta0" (fixed parameters for initial distribution). Each element is a named vector of coefficients that should either be fixed (if the corresponding element is set to NA) or estimated to a common value (using integers or factor levels).

ref

Vector of indices for reference transition probabilities, of length n_states. The i-th element is the index for the reference in the i-th row of the transition probability matrix. For example, ref = c(1, 1) means that the first element of the first row Pr(1>1) and the first element of the second row Pr(2>1) are used as reference elements and are not estimated. If this is not provided, the diagonal transition probabilities are used as references.

Returns

A new MarkovChain object

Examples
# Load data set from MSwM package
data(energy, package = "MSwM")

# Create 2-state covariate-free model and initialise transition 
# probability matrix
hid <- MarkovChain$new(data = energy, n_states = 2,
                       tpm = matrix(c(0.8, 0.3, 0.2, 0.7), 2, 2))

# Create 2-state model with non-linear effect of Oil on all transition 
# probabilities
hid <- MarkovChain$new(data = energy, n_states = 2,
                       formula = ~ s(Oil, k = 5, bs = "cs"))

# Create 2-state model with quadratic effect of Oil on Pr(1 > 2)
structure <- matrix(c(".", "~poly(Oil, 2)",
                      "~1", "."),
                    ncol = 2, byrow = TRUE)
hid <- MarkovChain$new(data = energy, n_states = 2,
                       formula = structure)

Method formula()

Formula of MarkovChain model

Usage
MarkovChain$formula()

Method formulas()

List of formulas for MarkovChain model

Usage
MarkovChain$formulas()

Method tpm()

Get transition probability matrices

Usage
MarkovChain$tpm(t = 1, linpred = NULL)
Arguments
t

Time index or vector of time indices; default = 1. If t = "all" then all transition probability matrices are returned.

linpred

Optional custom linear predictor

Returns

Array with one slice for each transition probability matrix

Method ref()

Indices of reference elements in transition probability matrix

Usage
MarkovChain$ref()

Method ref_mat()

Matrix of reference elements in transition probability matrix

Usage
MarkovChain$ref_mat()

Method ref_delta0()

Indices of reference elements in initial distribution

Usage
MarkovChain$ref_delta0()

Method coeff_fe()

Current parameter estimates (fixed effects)

Usage
MarkovChain$coeff_fe()

Method delta()

Stationary distribution

Usage
MarkovChain$delta(t = NULL, linpred = NULL)
Arguments
t

Time point(s) for which stationary distribution should be returned. If t = "all", all deltas are returned; else this should be a vector of time indices. If NULL (default), the stationary distribution for the first time step is returned.

linpred

Optional custom linear predictor

Returns

Matrix of stationary distributions. Each row corresponds to a row of the design matrices, and each column corresponds to a state.

Method delta0()

Initial distribution

Usage
MarkovChain$delta0(log = FALSE, as_matrix = TRUE)
Arguments
log

Logical indicating whether to return the log of the initial probabilities (default: FALSE). If TRUE, then the last element is excluded, as it is not estimated.

as_matrix

Logical indicating whether the output should be formatted as a matrix (default). If as_matrix is FALSE and log is TRUE, the result is formatted as a column vector.

Returns

Matrix with one row for each time series ID, and one column for each state. For each ID, the i-th element of the corresponding row is the probability Pr(S[1] = i)

Method stationary()

Use stationary distribution as initial distribution?

Usage
MarkovChain$stationary()

Method fixpar()

Fixed parameters

Usage
MarkovChain$fixpar(all = FALSE)
Arguments
all

Logical. If FALSE, only user-specified fixed parameters are returned, but not parameters that are fixed for some other reason (e.g., from '.' in formula)

Method coeff_re()

Current parameter estimates (random effects)

Usage
MarkovChain$coeff_re()

Method X_fe()

Fixed effect design matrix

Usage
MarkovChain$X_fe()

Method X_re()

Random effect design matrix

Usage
MarkovChain$X_re()

Method lambda()

Smoothness parameters

Usage
MarkovChain$lambda()

Method sd_re()

Standard deviation of smooth terms

This function transforms the smoothness parameter of each smooth term into a standard deviation, given by SD = 1/sqrt(lambda). It is particularly helpful to get the standard deviations of independent normal random effects.

Usage
MarkovChain$sd_re()

Method nstates()

Number of states

Usage
MarkovChain$nstates()

Method terms()

Terms of model formulas

Usage
MarkovChain$terms()

Method unique_ID()

Number of time series

Usage
MarkovChain$unique_ID()

Method initial_state()

Initial state (see constructor argument)

Usage
MarkovChain$initial_state()

Method update_tpm()

Update transition probability matrix

Usage
MarkovChain$update_tpm(tpm)
Arguments
tpm

New transition probability matrix

Method update_coeff_fe()

Update coefficients for fixed effect parameters

Usage
MarkovChain$update_coeff_fe(coeff_fe)
Arguments
coeff_fe

Vector of coefficients for fixed effect parameters

Method update_coeff_re()

Update coefficients for random effect parameters

Usage
MarkovChain$update_coeff_re(coeff_re)
Arguments
coeff_re

Vector of coefficients for random effect parameters

Method update_X_fe()

Update design matrix for fixed effects

Usage
MarkovChain$update_X_fe(X_fe)
Arguments
X_fe

new design matrix for fixed effects

Method update_X_re()

Update design matrix for random effects

Usage
MarkovChain$update_X_re(X_re)
Arguments
X_re

new design matrix for random effects

Method update_delta0()

Update initial distribution

Usage
MarkovChain$update_delta0(delta0)
Arguments
delta0

Either a matrix where the i-th row is the initial distribution for the i-th time series in the data, or a vector which is then used for all time series. Entries of each row of delta0 should sum to one.

Method update_lambda()

Update smoothness parameters

Usage
MarkovChain$update_lambda(lambda)
Arguments
lambda

New smoothness parameter vector

Method update_fixpar()

Update information about fixed parameters

Usage
MarkovChain$update_fixpar(fixpar)
Arguments
fixpar

New list of fixed parameters, in the same format expected by MarkovChain$new()

Method make_mat()

Make model matrices

Usage
MarkovChain$make_mat(data, new_data = NULL)
Arguments
data

Data frame containing all needed covariates

new_data

Optional new data set, including covariates for which the design matrices should be created. This needs to be passed in addition to the argument 'data', for cases where smooth terms or factor covariates are included, and the original data set is needed to determine the full range of covariate values.

Returns

A list with elements:

X_fe

Design matrix for fixed effects

X_re

Design matrix for random effects

S

Smoothness matrix for random effects

ncol_fe

Number of columns of X_fe for each parameter

ncol_re

Number of columns of X_re and S for each random effect

Method make_mat_grid()

Design matrices for grid of covariates

Used in plotting functions such as HMM$plot_tpm and HMM$plot_stat_dist

Usage
MarkovChain$make_mat_grid(var, data, covs = NULL, n_grid = 1000)
Arguments
var

Name of variable

data

Data frame containing the covariates

covs

Optional named list for values of covariates (other than 'var') that should be used in the plot (or dataframe with single row). If this is not specified, the mean value is used for numeric variables, and the first level for factor variables.

n_grid

Grid size (number of points). Default: 1000.

Returns

A list with the same elements as the output of make_mat, plus a data frame of covariates values.

Method tpm2par()

Transform transition probabilities to working scale

Apply the multinomial logit link function to get the corresponding parameters on the working scale (i.e., linear predictor scale).

Usage
MarkovChain$tpm2par(tpm)
Arguments
tpm

Transition probability matrix

Returns

Vector of parameters on linear predictor scale

Method par2tpm()

Transform working parameters to transition probabilities

Apply the inverse multinomial logit link function to transform the parameters on the working scale (i.e., linear predictor scale) into the transition probabilities.

Usage
MarkovChain$par2tpm(par)
Arguments
par

Vector of parameters on working scale

Returns

Transition probability matrix

Method linpred()

Linear predictor for transition probabilities

Usage
MarkovChain$linpred()

Method simulate()

Simulate from Markov chain

Usage
MarkovChain$simulate(n, data = NULL, new_data = NULL, silent = FALSE)
Arguments
n

Number of time steps to simulate

data

Optional data frame containing all needed covariates

new_data

Optional new data set, including covariates for which the design matrices should be created. This needs to be passed in addition to the argument 'data', for cases where smooth terms or factor covariates are included, and the original data set is needed to determine the full range of covariate values.

silent

if TRUE then no messages are printed

Returns

Sequence of states of simulated chain

Method formulation()

Print model formulation

Usage
MarkovChain$formulation()

Method print()

Print MarkovChain object

Usage
MarkovChain$print()

Method clone()

The objects of this class are cloneable with this method.

Usage
MarkovChain$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.

Examples


## ------------------------------------------------
## Method `MarkovChain$new`
## ------------------------------------------------

# Load data set from MSwM package
data(energy, package = "MSwM")

# Create 2-state covariate-free model and initialise transition 
# probability matrix
hid <- MarkovChain$new(data = energy, n_states = 2,
                       tpm = matrix(c(0.8, 0.3, 0.2, 0.7), 2, 2))

# Create 2-state model with non-linear effect of Oil on all transition 
# probabilities
hid <- MarkovChain$new(data = energy, n_states = 2,
                       formula = ~ s(Oil, k = 5, bs = "cs"))

# Create 2-state model with quadratic effect of Oil on Pr(1 > 2)
structure <- matrix(c(".", "~poly(Oil, 2)",
                      "~1", "."),
                    ncol = 2, byrow = TRUE)
hid <- MarkovChain$new(data = energy, n_states = 2,
                       formula = structure)
[Package hmmTMB version 1.0.2 Index]