MarkovChain: R6 class for HMM hidden process model
In TheoMichelot/hmmTMB: Fit Hidden Markov Models using Template Model Builder
MarkovChain 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 = NULL,
formula = NULL,
n_states,
tpm = NULL,
initial_state = "estimated",
fixpar = NULL,
ref = 1:n_states
)
Arguments
dataData frame, needed to create model matrices, and to identify the
number of time series (which each have a separate initial distribution)
formulaEither (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_statesNumber of states. If not specified, then formula
needs to be provided as a matrix, and n_states is deduced from its dimensions.
tpmOptional 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_stateSpecify 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
fixparList 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).
refVector 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
tTime index or vector of time indices; default = 1. If t = "all"
then all transition probability matrices are returned.
linpredOptional 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
tTime 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.
linpredOptional 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
logLogical 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_matrixLogical 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
allLogical. 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 empty()
Empty model? (for simulation only)
Usage
MarkovChain$empty()
Method update_tpm()
Update transition probability matrix
Usage
MarkovChain$update_tpm(tpm)
Arguments
tpmNew transition probability matrix
Method update_coeff_fe()
Update coefficients for fixed effect parameters
Usage
MarkovChain$update_coeff_fe(coeff_fe)
Arguments
coeff_feVector 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_reVector 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_fenew design matrix for fixed effects
Method update_X_re()
Update design matrix for random effects
Usage
MarkovChain$update_X_re(X_re)
Arguments
X_renew design matrix for random effects
Method update_delta0()
Update initial distribution
Usage
MarkovChain$update_delta0(delta0)
Arguments
delta0Either 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
lambdaNew smoothness parameter vector
Method update_fixpar()
Update information about fixed parameters
Usage
MarkovChain$update_fixpar(fixpar)
Arguments
fixparNew 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
dataData frame containing all needed covariates
new_dataOptional 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
varName of variable
dataData frame containing the covariates
covsOptional 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_gridGrid 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
tpmTransition 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
parVector 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
nNumber of time steps to simulate
dataOptional data frame containing all needed covariates
new_dataOptional 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.
silentif 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
deepWhether 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)
TheoMichelot/hmmTMB documentation built on Dec. 13, 2024, 11:52 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| MarkovChain | 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 = NULL, formula = NULL, n_states, tpm = NULL, initial_state = "estimated", fixpar = NULL, ref = 1:n_states )
Arguments
dataData frame, needed to create model matrices, and to identify the number of time series (which each have a separate initial distribution)
formulaEither (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
refargument). (Default: no covariate dependence.)n_statesNumber of states. If not specified, then
formulaneeds to be provided as a matrix, and n_states is deduced from its dimensions.tpmOptional 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_stateSpecify 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
fixparList 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).
refVector 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
tTime index or vector of time indices; default = 1. If t = "all" then all transition probability matrices are returned.
linpredOptional 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
tTime 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.
linpredOptional 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
logLogical 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_matrixLogical 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
allLogical. 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 empty()
Empty model? (for simulation only)
Usage
MarkovChain$empty()
Method update_tpm()
Update transition probability matrix
Usage
MarkovChain$update_tpm(tpm)
Arguments
tpmNew transition probability matrix
Method update_coeff_fe()
Update coefficients for fixed effect parameters
Usage
MarkovChain$update_coeff_fe(coeff_fe)
Arguments
coeff_feVector 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_reVector 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_fenew design matrix for fixed effects
Method update_X_re()
Update design matrix for random effects
Usage
MarkovChain$update_X_re(X_re)
Arguments
X_renew design matrix for random effects
Method update_delta0()
Update initial distribution
Usage
MarkovChain$update_delta0(delta0)
Arguments
delta0Either 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
lambdaNew smoothness parameter vector
Method update_fixpar()
Update information about fixed parameters
Usage
MarkovChain$update_fixpar(fixpar)
Arguments
fixparNew 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
dataData frame containing all needed covariates
new_dataOptional 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
varName of variable
dataData frame containing the covariates
covsOptional 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_gridGrid 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
tpmTransition 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
parVector 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
nNumber of time steps to simulate
dataOptional data frame containing all needed covariates
new_dataOptional 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.silentif 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
deepWhether 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)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.