Controls

The {fHMM} package allows for multiple hidden Markov model specifications, including different data transformations, state-dependent distributions, and a hierarchical model structure. This vignette1 outlines what and how specifications are possible.

library("fHMM")

The set_controls function

The {fHMM} philosophy is to start the modeling process by setting all data, model, and estimation specifications. This is done by defining a named list of controls and passing it to the set_controls() function. The function checks the specifications and returns an fHMM_controls object which stores all specifications and thereby provides required information for other {fHMM} functionalities.

Example specifications

For demonstration, we list example specifications using data from the Deutscher Aktienindex DAX2 (Janßen and Rudolph 1992):

download_data(symbol = "^GDAXI", file = "dax.csv")
#> Download successful.
#> * symbol: ^GDAXI
#> * from: 1987-12-30
#> * to: 2023-02-13
#> * path: C:\Users\Lennart\AppData\Local\Temp\Rtmp42gnFG\Rbuild186c5f42744c\fHMM\vignettes\dax.csv

HMMs for empirical data

The following lines of code specify a 3-state HMM with state-dependent t-distributions on the data in the file dax.csv. The dates are provided in the column called Date and the data in the column called Close. The logreturns = TRUE line transforms the index data to log-returns. The runs = 50 line sets the number of numerical optimization runs to 50.

controls <- list(
  states = 3,
  sdds   = "t",
  data   = list(file        = "dax.csv",
                date_column = "Date",
                data_column = "Close",
                logreturns  = TRUE),
  fit    = list(runs        = 50)
)
set_controls(controls)
#> fHMM controls:
#> * hierarchy: FALSE 
#> * data type: empirical 
#> * number of states: 3 
#> * sdds: t() 
#> * number of runs: 50

Simulated HMM data

The following specifies a 2-state HMM with state-dependent Gamma distributions, where the expectation values for state 1 and 2 are fixed to 0.5 and 2, respectively. The model will be fitted to 500 data points (horizon = 500), that are going to be simulated from this model specification.

controls <- list(
  states  = 2,
  sdds    = "gamma(mu = 0.5|2)",
  horizon = 500
)
set_controls(controls)
#> fHMM controls:
#> * hierarchy: FALSE 
#> * data type: simulated 
#> * number of states: 2 
#> * sdds: gamma(mu = 0.5|2) 
#> * number of runs: 100

Hierarchical HMMs

Specifying hierarchical HMMs is analogously, except that new parameters can be specified (for example period, see below) and some parameters now can be specified for both hierarchies.

controls <- list(
  hierarchy = TRUE,
  horizon   = c(100, 10),
  sdds      = c("t(df = 1)", "t(df = Inf)"),
  period    = "m"
)
set_controls(controls)
#> fHMM controls:
#> * hierarchy: TRUE 
#> * data type: simulated 
#> * number of states: 2 2 
#> * sdds: t(df = 1) t(df = Inf) 
#> * number of runs: 100

The help page of the set_controls() function provides an overview of all possible specifications.

?set_controls
set_controls R Documentation

Set and validate controls

Arguments

controls

A list of controls, see below.

Either none, all, or selected parameters can be specified. Unspecified parameters are set to default values (see the values in brackets below).

If hierarchy = TRUE, parameters marked with a (*) must be a vector of length 2, where the first entry corresponds to the coarse-scale and the second entry to the fine-scale layer.

  • hierarchy (FALSE): A logical, set to TRUE for an hierarchical HMM.

  • states (*) (2): An integer, the number of states of the underlying Markov chain.

  • sdds (*) (“t(df = Inf)”): A character, specifying the state-dependent distribution. One of “t” (the t-distribution), or “gamma” (the gamma distribution), or “lnorm” (the log-normal distribution). You can fix the parameters (mean mu, standard deviation sigma, degrees of freedom df) of these distributions via, e.g., “t(df = Inf)” or “gamma(mu = 0, sigma = 1)”. To fix different values of a parameter for different states, separate by "|", e.g. “t(mu = -1|1)”.

  • horizon (*) (100): A numeric, specifying the length of the time horizon. The first entry of horizon is ignored if data is specified.

  • period (“m”): Only relevant if hierarchy = TRUE and horizon[2] = NA. In this case, a character which specifies a flexible, periodic fine-scale time horizon and can be one of

    • “w” for a week,

    • “m” for a month,

    • “q” for a quarter,

    • “y” for a year.

  • data (NA): A list of controls specifying the data. If data = NA, data gets simulated (default). Otherwise:

    • file (*): Either:

      • A data.frame, which must have a column named date_column (with dates) and data_column (with financial data). If hierarchy = TRUE, this data.frame is used for both the coarse- and the fine-scale layer. To have different data sets for theses layers, file can be a list of two data.frame.

      • A character, the path to a .csv-file with financial data, which must have a column named date_column (with dates) and data_column (with financial data).

    • date_column (*) (“Date”): A character, the name of the column in file with dates. Can be NA in which case consecutive integers are used as time points.

    • data_column (*) (“Close”): A character, the name of the column in file with financial data.

    • from (NA): A character of the format “YYYY-MM-DD”, setting a lower data limit. No lower limit if from = NA. Ignored if controls\(data\)date_column is NA.

    • to (NA): A character of the format “YYYY-MM-DD”, setting an upper data limit. No upper limit if from = NA. Ignored if controls\(data\)date_column is NA.

    • logreturns (*) (FALSE): A logical, if TRUE the data is transformed to log-returns.

    • merge (function(x) mean(x)): Only relevant if hierarchy = TRUE. In this case, a function with one argument x, which merges a numeric vector of fine-scale data x into one coarse-scale observation. For example,

      • merge = function(x) mean(x) defines the mean of the fine-scale data as the coarse-scale observation,

      • merge = function(x) mean(abs(x)) for the mean of the absolute values,

      • merge = function(x) sum(abs(x)) for the sum of the absolute values,

      • merge = function(x) (tail(x,1)-head(x,1))/head(x,1) for the relative change of the first to the last fine-scale observation.

  • fit: A list of controls specifying the model fitting:

    • runs (100): An integer, setting the number of randomly initialized optimization runs from which the best one is selected as the final model.

    • origin (FALSE): A logical, if TRUE the optimization is initialized at the true parameter values. Only for simulated data. If origin = TRUE, this sets run = 1 and accept = 1:5.

    • accept (1:3): An integer (vector), specifying which optimization runs are accepted based on the output code of nlm.

    • gradtol (1e-6): A positive numeric value, passed on to nlm.

    • iterlim (200): A positive integer, passed on to nlm.

    • print.level (0): One of 0, 1, and 2 to control the verbosity of the optimization, passed on to nlm.

    • steptol (1e-6): A positive numeric value, passed on to nlm.

x

An object of class fHMM_controls.

…

Currently not used.

References

Janßen, B., and B. Rudolph. 1992. “Der Deutsche Aktienindex DAX.” Knapp Verlag.

  1. This vignette was build using R .4 with the {fHMM} 1.1.0 package.↩︎

  2. The download_data() function is explained in the vignette on data management.↩︎