Specifies a hidden semi-Markov model

This function returns an object of class hsmm from the parameters passed as arguments.

specify_hsmm(
  J,
  state_names = NULL,
  state_colors = NULL,
  init = NULL,
  transition = NULL,
  sojourn = NULL,
  marg_em_probs = NULL,
  censoring_probs = NULL,
  verbose = FALSE
)

Arguments

J	an integer. The number of hidden states.
state_names	(optional) a vector of characters. Names associated to each state. Must be of length J. If unspecified, the states are numbered from 1 to J.
state_colors	(optional) a vector of color-specifying characters. Colors associated to each state. Must be of length J. If unspecified, the colors are picked from the viridis palette.
init	(optional) a vector of J double. The initial probabilities associated with each states. If values do not sum to 1 a warning message is displayed and the vector is divided by its sum. If unspecified (default), uniform initial probabilities are assumed.
transition	(optional) a J x J matrix of double. The matrix of transition probabilities in which the element (r, c) provides the probability of transitioning from state r to state c. The diagonal elements must be equal to zero except for absorbing states. For absorbing states, all the other elements of that row must be zero. For other states, if there are non-zero diagonal elements, a warning message is displayed and the elements are set to zero. If the sum over the rows is different that one, a warning message is displayed and the rows are divided by their sum. If unspecified (default), uniform transition probabilities are assumed between each state with no absorbing state.
sojourn	(optional) a list. The sojourn distributions. The sojourn distributions can be specified with the same distribution family for all states or each state can be specified independently. In the first case (same distribution family for all states), the list must have at least two elements: a type element which specifies the type of sojourn distributions and the other elements are the distribution parameters (each of length J). In the second case (different distribution families for each state), the list must have J elements. Each of these J element is a list in which the first element (type) specifies the distribution family and the remaining elements are the distribution parameters (each of length 1). Use the function available_sojourn_dist() to see the supported sojourn distributions and their parameters. Refer to the package vignette for examples. If unspecified (default), the sojourn distributions are assumed to be uniform (non-parametric) over 10 time-steps.
marg_em_probs	(optional) a list. The marginal emission distributions. The list has one element per variable. The name of that element must be the name of the variable. Variable names cannot contain the character '_'. Each element of the list is itself a list of at least two elements. The first one, named type, is used to specify the distribution family. Type available_marginal_emission_dist() to get the currently supported distribution families. The second element of the list, params, is a list that provides the parameters of the model in each state. The same function (available_marginal_emission_dist()) provides information on how these parameters must be specified. An optional third element can be added to the variable list: viz-options. This element is a list in which each element specifies a given visualization option. Type available_emission_viz_options() to obtain the list and description of the available visualization options for each distribution type. See function plot_hsmm_seq() for visualization of observation sequences. If unspecified (default), it is assumed that the model describes time-series of a single continuous variable normally distributed around j (the state index) with a unitary standard deviation.
censoring_probs	(optional) the probabilities of observations being censored in each state. Can be specified as a vector of length J of values between 0 (never censored) and 1 (always censored) or a a single value in [0,1] if the censoring probability is assumed to be identical in each state. If unspecified, the observations are assumed to never be censored (value 0) overall (individual variables may still be censored via their individual 'missing_prob'.)
verbose	a logical (default = FALSE). Should the function print additional information?

Value

An object of class hsmm which can be used to simulate time series with the simulate_hsmm() function or to decode time-series with the predict_states_hsmm() function. The returned hsmm object (model) can also be fit to specific sequences with the fit_hsmm() function.

See also

simulate_hsmm() to simulate a sequence of hidden states and observations following the model specifications, predict_states_hsmm() to predict the sequence of hidden states from observation time-series and fit_hsmm() to fit a model to sequences of observations.

Examples

my_model = specify_hsmm(
   J = 2,
   init = c(1,0),
   transition = matrix(c(0,1,1,0),2,2),
   sojourn = list(type = "gamma", shape = c(2,10), scale = c(10,3)),
   marg_em_probs = list(
       var1 = list(
           type = "norm",
           params = list(
               mean = c(0,1),
               sd = c(0.3,0.2)
               )
           ),
     var2 = list(
         type = "binom",
         params = list(
             size = rep(1,2),
             prob = c(0.2,0.8)
             )
         ),
     var3 = list(
         type = "non-par",
         params = list(
             values = c("a","b","c","d"),
             probs = matrix(c(0.7,0.1,0.1,0.1,
                            1/4,1/4,1/4,1/4), 4,2)
           ),
         viz_options = list(colors = c("black","slateblue1","#E90046","#0EC290"))
         )
     ),
   censoring_probs = list(p = c(0.1,0.2), q = matrix(c(0.1,0.2,0.3,0.4,0.5,0.6), nrow = 3, ncol = 2)),
   state_names = c("A","B"),
   state_colors = c("seagreen1","slategray")
)
class(my_model)
#> [1] "hsmm"
Xsim = simulate_hsmm(model = my_model, n_state_transitions = 20)
plot_hsmm_seq(model = my_model, X = Xsim)