To specify a model in fHMM, you only need to define the named list controls and pass it to fit_hmm, i.e.
define controls = list(<parameters>) and
call fit_hmm(controls) for estimation.
The list controls can contain the following parameters. You can either specify none, all, or selected parameters. Unspecified parameters are set to default values.
pathA character, setting the path where model results get saved. The default is path = tempdir() (the path of the per-session temporary directory). We recommend to set a path to your current working directory, e.g. path = ".".
idA character, which identifies a model. The default is id = "test". We recommend to set a meaningful identification, e.g. id = "dax_hmm_2_states".
modelThis control determines the type model that you want to estimate and can be one of
"hmm" (to estimate a hidden Markov model),
"hhmm" (to estimate a hierarchical hidden Markov model).
The default is model = "hmm".
statesThis control determines the number of states and depends on the control model.
If model = "hmm", states is an integer. If states = x, a hidden Marko model with x states is estimated.
If model = "hhmm", states is a numeric vector of length two. If states = c(x,y), a hierarchical hidden Markov model with x coarse-scale and y fine-scale states is estimated.
The default is states = 2, which defines a 2-state hidden Markov model.
sddsThis control determines the state-depenent distributions and depends on the control model.
If model = "hmm", states is one of the following values.
If model = "hhmm", states is a vector of length two, containing the following values. The first entry defines the state-depenent distribution for the coarse scale, the second entry for the fine scale, respectively.
The following state-depenent distributions can be defined:
"t", the t-distribution,
"t(x)", the t-distribution with x fixed degrees of freedom (x = Inf yields the normal distribution),
"gamma", the gamma distribution.
For example, sdds = c("t","t(1)") defines the t-distribution for the coarse scale (degrees of freedom get estimated) and the t-distribution with one degree of freedom for the fine scale.
The default is sdds = "t", which defines state-dependent t-distributions.
horizonThis control determines the length of the time horizon and depends on the control model.
If model = "hmm", horizon is an integer and determines the length of the time horizon for simulated data.
If model = "hhmm", horizon is a vector of length two. The first entry is numeric and defines the time horizon for the coarse scale for simulated data. The second entry defines the time horizon for the fine scale for simulated data and for empirical data and can be either numeric or one of
"w" for weekly fine-scale chunks,
"m" for monthly fine-scale chunks,
"q" for quarterly fine-scale chunks,
"y" for yearly fine-scale chunks.
The default is horizon = 1000, which simulates 1000 data points from a hidden Markov model.
dataA list which contains the following controls that specify the processing of data. If data = NA (the default), data gets simulated.
sourceEither a character (if model = "hmm") or a character vector of length 2 (if model = "hhmm"), containing the file names of the empirical data.
If source = NA or source = c(NA,NA), respectively, data is simulated.
If source = "x", data “x.csv” in folder “path/data” is modeled by a HMM.
If source = c("x","y"), data “x.csv” (type determined by cs_type) on the coarse scale and data “y.csv” in folder “path/data” on the fine scale is modeled by a HHMM.
columnEither a character (if model = "hmm") or a character vector of length 2 (if model = "hhmm"), containing the names of the desired columns of source.
truncateA vector of length 2, containing lower and upper date limits (each in format "YYYY-MM-DD") to select a subset of the empirical data (neither, one or both limits can be specified).
The default is truncate = c(NA,NA), i.e. no limits get specified.
cs_transformA character, determining the transformation of empirical coarse-scale data in hierarchical hidden Markov models.
The character has to be a function of x, where x is the corresponding fine-scale data. The function must concentrate x into a single value.
For example,
cs_transform = "mean(x)" defines the mean of the fine-scale data as the coarse-scale observation,
cs_transform = "mean(abs(x))" defines the mean of the absolute values of the fine-scale data as the coarse-scale observation,
cs_transform = "sum(abs(x))" defines the sum of the absolute values of the fine-scale data as the coarse-scale observation,
cs_transform = "(tail(x,1)-head(x,1))/head(x,1)" defines the relative change of the first and the last fine-scale observation as the coarse-scale observation.
Practically, any transformation can be defined.
log_returnsEither a boolean (if model = "hmm") or a boolean vector of length 2 (if model = "hhmm"), determining whether empirical data should be transformed to log-returns.
fitA list which contains the following controls that specify the estimation.
runsA numeric value, setting the number of optimization runs.
The default is runs = 100.
at_trueA boolean, determining whether the optimization is initialized at the true parameter values.
Only for simulated data, sets runs = 1 and accept = "all".
The default is at_true = FALSE.
seedA numeric value, setting a seed for the simulation and the optimization.
Per default, no seed is set.
acceptEither a numeric vector (containing acceptable exit codes of the nlm optimization) or the character "all" (accepting all codes).
The default is accept = c(1,2).
scale_parEither a numeric (if model = "hmm") or a numeric vector of length 2 (if model = "hhmm"), scaling the model parameters in a simulation on the coarse and fine scale, respectively.
The default is scale_par = 1, i.e. the model parameters for simulation do not get scaled.
resultsA list which contains the following controls that specify the output.
overwriteA boolean, determining whether overwriting of existing results (on the same id) is allowed. It is set to TRUE if id = "test".
The default is overwrite = FALSE.
ci_levelA numeric value between 0 and 1, setting the level for the confidence intervals of the model parameters.
The default is ci_level = 0.95.