Set and validate controls — set

This function sets and validates the specification of controls for model estimation with the {fHMM} package.

Usage

set_controls(controls = NULL)

# S3 method for fHMM_controls
print(x, ...)

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.

Value

An object of class fHMM_controls.

Details

See the vignettes for more details on how to specify controls.

Examples

### HMM controls for simulation
controls <- list(
  states  = 2,
  sdds    = "t(mu = 0)",
  fit     = list("runs" = 50)
)
set_controls(controls)
#> fHMM controls:
#> * hierarchy: FALSE 
#> * data type: simulated 
#> * number of states: 2 
#> * sdds: t(mu = 0) 
#> * number of runs: 50  

### HMM controls with empirical data 
data <- download_data("^GDAXI", file = NULL)
controls <- list(
  states  = 3,
  sdds    = "lnorm",
  data    = list(
    "file"        = data, 
    "date_column" = "Date", 
    "data_column" = "Adj.Close"
  )
)
set_controls(controls)
#> fHMM controls:
#> * hierarchy: FALSE 
#> * data type: empirical 
#> * number of states: 3 
#> * sdds: lnorm() 
#> * number of runs: 100  

### HMM controls with empirical data from .csv-file
controls <- list(
  states  = 4,
  sdds    = "t",
  data    = list(
    "file"        = system.file("extdata", "dax.csv", package = "fHMM"), 
    "date_column" = "Date", 
    "data_column" = "Close",
    "logreturns"  = TRUE
  )
)
set_controls(controls)
#> fHMM controls:
#> * hierarchy: FALSE 
#> * data type: empirical 
#> * number of states: 4 
#> * sdds: t() 
#> * number of runs: 100  

### HHMM controls for simulation
controls <- list(
  hierarchy = TRUE,
  states    = c(3, 2)
)
set_controls(controls)
#> fHMM controls:
#> * hierarchy: TRUE 
#> * data type: simulated 
#> * number of states: 3 2 
#> * sdds: t() t() 
#> * number of runs: 100  

### HHMM controls with empirical data
controls <- list(
  hierarchy = TRUE,
  states  = c(3, 2),
  sdds    = c("t", "t"),
  data    = list(
    "file"        = list(dax, vw), 
    "date_column" = c("Date", "Date"), 
    "data_column" = c("Close", "Close"),
    "logreturns"  = c(TRUE, TRUE)
  )
)
set_controls(controls)
#> fHMM controls:
#> * hierarchy: TRUE 
#> * data type: empirical 
#> * number of states: 3 2 
#> * sdds: t() t() 
#> * number of runs: 100