R: Define and validate model specifications

set_controls {fHMM}

R Documentation

Define and validate model specifications

Description

This function defines and validates specifications for model estimation.

Usage

set_controls(
  controls = list(),
  hierarchy = FALSE,
  states = if (!hierarchy) 2 else c(2, 2),
  sdds = if (!hierarchy) "normal" else c("normal", "normal"),
  horizon = if (!hierarchy) 100 else c(100, 30),
  period = if (hierarchy && is.na(horizon[2])) "m" else NA,
  data = NA,
  file = NA,
  date_column = if (!hierarchy) "Date" else c("Date", "Date"),
  data_column = if (!hierarchy) "Close" else c("Close", "Close"),
  from = NA,
  to = NA,
  logreturns = if (!hierarchy) FALSE else c(FALSE, FALSE),
  merge = function(x) mean(x),
  fit = list(),
  runs = 10,
  origin = FALSE,
  accept = 1:3,
  gradtol = 0.01,
  iterlim = 100,
  print.level = 0,
  steptol = 0.01
)

validate_controls(controls)

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

## S3 method for class 'fHMM_controls'
summary(object, ...)

Arguments

`controls`	Either a `list` or an object of class `fHMM_controls`. The `list` can contain the following elements, which are described in more detail below: `hierarchy`, defines an hierarchical HMM, `states`, defines the number of states, `sdds`, defines the state-dependent distributions, `horizon`, defines the time horizon, `period`, defines a flexible, periodic fine-scale time horizon, `data`, a `list` of controls that define the data, `fit`, a `list` of controls that define the model fitting Either none, all, or selected elements can be specified. Unspecified parameters are set to their default values. Important: Specifications in `controls` always override individual specifications.
`hierarchy`	A `logical`, set to `TRUE` for an hierarchical HMM. If `hierarchy = TRUE`, some of the other controls must be specified for the coarse-scale and the fine-scale layer. By default, `hierarchy = FALSE`.
`states`	An `integer`, the number of states of the underlying Markov chain. If `hierarchy = TRUE`, `states` must be a `vector` of length 2. The first entry corresponds to the coarse-scale layer, while the second entry corresponds to the fine-scale layer. By default, `states = 2` if `hierarchy = FALSE` and `states = c(2, 2)` if `hierarchy = TRUE`.
`sdds`	A `character`, specifying the state-dependent distribution. One of `"normal"` (the normal distribution), `"lognormal"` (the log-normal distribution), `"t"` (the t-distribution), `"gamma"` (the gamma distribution), `"poisson"` (the Poisson distribution). The distribution parameters, i.e. the mean `mu`, standard deviation `sigma` (not for the Poisson distribution), degrees of freedom `df` (only for the t-distribution), can be fixed via, e.g., `"t(df = 1)"` or `"gamma(mu = 0, sigma = 1)"`. To fix different values of a parameter for different states, separate by "\|", e.g. `"poisson(mu = 1\|2\|3)"`. If `hierarchy = TRUE`, `sdds` must be a `vector` of length 2. The first entry corresponds to the coarse-scale layer, while the second entry corresponds to the fine-scale layer. By default, `sdds = "normal"` if `hierarchy = FALSE` and `sdds = c("normal", "normal")` if `hierarchy = TRUE`.
`horizon`	A `numeric`, specifying the length of the time horizon. If `hierarchy = TRUE`, `horizon` must be a `vector` of length 2. The first entry corresponds to the coarse-scale layer, while the second entry corresponds to the fine-scale layer. By default, `horizon = 100` if `hierarchy = FALSE` and `horizon = c(100, 30)` if `hierarchy = TRUE`. If `data` is specified (i.e., not `NA`), the first entry of `horizon` is ignored and the (coarse-scale) time horizon is defined by available data.
`period`	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. By default, `period = "m"` if `hierarchy = TRUE` and `horizon[2] = NA`, and `NA` else.
`data`	Either `NA`, in which case data is simulated (the default), or a `list` of controls specifying the empirical data set. The `list` can contain the following elements, which are described in more detail below: `file`, defines the data set, `date_column`, defines the date column, `data_column`, defines the data column, `from`, defines a lower date limit, `to`, defines an upper date limit, `logreturns`, defines a data transformation to log-returns, `merge`, defines the merging for coarse-scale observations. Either none, all, or selected elements can be specified. Unspecified parameters are set to their default values, see below. Specifications in `data` override individual specifications.
`file`	A `data.frame` with data and dates for modeling. If `hierarchy = TRUE`, `file` can be a `list` of length 2. The first entry is a `data.frame` and provides the data for the coarse-scale layer, while the second entry corresponds to the fine-scale layer. If `file` is a single `data.frame`, then the same `data.frame` is used for both layers. Alternatively, it can be a `character` (of length two), the path to a .csv-file with financial data.
`date_column`	A `character`, the name of the column in `file` with dates. If `hierarchy = TRUE` and `file` is a `list` of two `data.frame`s, `data_column` must be a `vector` of length 2. The first entry corresponds to the coarse-scale layer, while the second entry corresponds to the fine-scale layer. By default, `date_column = "Date"`.
`data_column`	A `character`, the name of the column in `file` with observations. If `hierarchy = TRUE`, `data_column` must be a `vector` of length 2. The first entry corresponds to the coarse-scale layer, while the second entry corresponds to the fine-scale layer. By default, `data_column = "Close"` if `hierarchy = FALSE` and `data_column = c("Close", "Close")` if `hierarchy = TRUE`.
`from`	A `character` of the format `"YYYY-MM-DD"`, setting a lower date limit. No lower limit if `from = NA` (default).
`to`	A `character` of the format `"YYYY-MM-DD"`, setting an upper date limit. No lower limit if `to = NA` (default).
`logreturns`	A `logical`, if `TRUE` the data is transformed to log-returns. If `hierarchy = TRUE`, `logreturns` must be a `vector` of length 2. The first entry corresponds to the coarse-scale layer, while the second entry corresponds to the fine-scale layer. By default, `logreturns = FALSE` if `hierarchy = FALSE` and `logreturns = c(FALSE, FALSE)` if `hierarchy = TRUE`.
`merge`	Only relevant if `hierarchy = TRUE`. In this case, a `function` which merges an input numeric vector of fine-scale data `x` into one coarse-scale observation. For example, `merge = function(x) mean(x)` (default) 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. The `list` can contain the following elements, which are described in more detail below: `runs`, defines the number of numerical optimization runs, `origin`, defines initialization at the true parameters, `accept`, defines the set of accepted optimization runs, `gradtol`, defines the gradient tolerance, `iterlim`, defines the iteration limit, `print.level`, defines the level of printing, `steptol`, defines the minimum allowable relative step length. Either none, all, or selected elements can be specified. Unspecified parameters are set to their default values, see below. Specifications in `fit` override individual specifications.
`runs`	An `integer`, setting the number of randomly initialized optimization runs of the model likelihood from which the best one is selected as the final model. By default, `runs = 10`.
`origin`	Only relevant for simulated data, i.e., if the `data` control is `NA`. In this case, a `logical`. If `origin = TRUE` the optimization is initialized at the true parameter values. This sets `run = 1` and `accept = 1:5`. By default, `origin = FALSE`.
`accept`	An `integer` (vector), specifying which optimization runs are accepted based on the output code of `nlm`. By default, `accept = 1:3`.
`gradtol`	A positive `numeric` value, specifying the gradient tolerance, passed on to `nlm`. By default, `gradtol = 0.01`.
`iterlim`	A positive `integer` value, specifying the iteration limit, passed on to `nlm`. By default, `iterlim = 100`.
`print.level`	One of `0`, `1`, and `2` to control the verbosity of the numerical likelihood optimization, passed on to `nlm`. By default, `print.level = 0`.
`steptol`	A positive `numeric` value, specifying the step tolerance, passed on to `nlm`. By default, `gradtol = 0.01`.
`x`, `object`	An object of class `fHMM_controls`.
`...`	Currently not used.

Details

See the vignette on controls for more details.

Value

An object of class fHMM_controls, which is a list that contains model and estimation specifications.

Examples

# 2-state HMM with t-distributions for simulated data
set_controls(
  states = 2,   # the number of states
  sdds   = "t", # the state-dependent distribution
  runs   = 50   # the number of optimization runs
)

# 3-state HMM with normal distributions for the DAX closing prices
set_controls(
  states      = 3,
  sdds        = "normal",
  file        = download_data("^GDAXI"), # the data set
  date_column = "Date",                   # the column with the dates
  data_column = "Close"                   # the column with the data
)

# hierarchical HMM with Gamma and Poisson state distributions
set_controls(
  hierarchy = TRUE,                  # defines a hierarchy
  states    = c(3, 2),               # coarse scale and fine scale states
  sdds      = c("gamma", "poisson"), # distributions for both layers
  horizon   = c(100, NA),            # 100 simulated coarse-scale data points 
  period    = "m"                    # monthly simulated fine-scale data
)

# hierarchical HMM with data from .csv-file
set_controls(
  hierarchy = TRUE,
  states    = c(3, 2),
  sdds      = c("t", "t"),
  file      = c(               
    system.file("extdata", "dax.csv", package = "fHMM"),
    system.file("extdata", "dax.csv", package = "fHMM")
  ),
  date_column = c("Date", "Date"), 
  data_column = c("Close", "Close"),
  logreturns  = c(TRUE, TRUE)
)

[Package fHMM version 1.3.1 Index]