R6 class for HMM hidden process model
Contains the parameters and model formulas for the hidden process model.
## ------------------------------------------------ ## 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)
new()Create new MarkovChain object
MarkovChain$new(
data = NULL,
formula = NULL,
n_states,
tpm = NULL,
initial_state = "estimated",
fixpar = NULL,
ref = 1:n_states,
gam_args = NULL
)
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.
gam_args: Named list of arguments passed to mgcv::gam() in MarkovChain$make_mat(), e.g., "knots". Use at your own risk.
A new MarkovChain object
# 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)
formula()Formula of MarkovChain model
MarkovChain$formula()
formulas()List of formulas for MarkovChain model
MarkovChain$formulas()
tpm()Get transition probability matrices
MarkovChain$tpm(t = 1, linpred = NULL)
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
Array with one slice for each transition probability matrix
ref()Indices of reference elements in transition probability matrix
MarkovChain$ref()
ref_mat()Matrix of reference elements in transition probability matrix
MarkovChain$ref_mat()
ref_delta0()Indices of reference elements in initial distribution
MarkovChain$ref_delta0()
coeff_fe()Current parameter estimates (fixed effects)
MarkovChain$coeff_fe()
delta()Stationary distribution
MarkovChain$delta(t = NULL, linpred = NULL)
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
Matrix of stationary distributions. Each row corresponds to a row of the design matrices, and each column corresponds to a state.
delta0()Initial distribution
MarkovChain$delta0(log = FALSE, as_matrix = TRUE)
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.
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)
stationary()Use stationary distribution as initial distribution?
MarkovChain$stationary()
fixpar()Fixed parameters
MarkovChain$fixpar(all = FALSE)
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)
coeff_re()Current parameter estimates (random effects)
MarkovChain$coeff_re()
X_fe()Fixed effect design matrix
MarkovChain$X_fe()
X_re()Random effect design matrix
MarkovChain$X_re()
lambda()Smoothness parameters
MarkovChain$lambda()
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.
MarkovChain$sd_re()
nstates()Number of states
MarkovChain$nstates()
terms()Terms of model formulas
MarkovChain$terms()
unique_ID()Number of time series
MarkovChain$unique_ID()
initial_state()Initial state (see constructor argument)
MarkovChain$initial_state()
empty()Empty model? (for simulation only)
MarkovChain$empty()
gam_args()Extra arguments for mgcv::gam (passed to make_matrices)
MarkovChain$gam_args()
update_tpm()Update transition probability matrix
MarkovChain$update_tpm(tpm)
tpm: New transition probability matrix
update_coeff_fe()Update coefficients for fixed effect parameters
MarkovChain$update_coeff_fe(coeff_fe)
coeff_fe: Vector of coefficients for fixed effect parameters
update_coeff_re()Update coefficients for random effect parameters
MarkovChain$update_coeff_re(coeff_re)
coeff_re: Vector of coefficients for random effect parameters
update_X_fe()Update design matrix for fixed effects
MarkovChain$update_X_fe(X_fe)
X_fe: new design matrix for fixed effects
update_X_re()Update design matrix for random effects
MarkovChain$update_X_re(X_re)
X_re: new design matrix for random effects
update_delta0()Update initial distribution
MarkovChain$update_delta0(delta0)
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.
update_lambda()Update smoothness parameters
MarkovChain$update_lambda(lambda)
lambda: New smoothness parameter vector
update_fixpar()Update information about fixed parameters
MarkovChain$update_fixpar(fixpar)
fixpar: New list of fixed parameters, in the same format expected by MarkovChain$new()
make_mat()Make model matrices
MarkovChain$make_mat(data, new_data = NULL)
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.
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
make_mat_grid()Design matrices for grid of covariates
Used in plotting functions such as HMMplot_stat_dist
MarkovChain$make_mat_grid(var, data, covs = NULL, n_grid = 1000)
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.
A list with the same elements as the output of make_mat, plus a data frame of covariates values.
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).
MarkovChain$tpm2par(tpm)
tpm: Transition probability matrix
Vector of parameters on linear predictor scale
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.
MarkovChain$par2tpm(par)
par: Vector of parameters on working scale
Transition probability matrix
linpred()Linear predictor for transition probabilities
MarkovChain$linpred()
simulate()Simulate from Markov chain
MarkovChain$simulate(n, data = NULL, new_data = NULL, silent = FALSE)
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
Sequence of states of simulated chain
formulation()Print model formulation
MarkovChain$formulation()
print()Print MarkovChain object
MarkovChain$print()
clone()The objects of this class are cloneable with this method.
MarkovChain$clone(deep = FALSE)
deep: Whether to make a deep clone.
Related functions from the same R package