---
title: "Controls"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Controls}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
bibliography: ref.bib
link-citations: true
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "fHMM-"
)
```

The `{fHMM}` package allows for multiple hidden Markov model specifications, including different data transformations, state-dependent distributions, and a hierarchical model structure. This vignette^[This vignette was build using R `r paste(R.Version()[c("major", "minor")], collapse = ".")` with the `{fHMM}` `r utils::packageVersion("fHMM")` package.] outlines what and how specifications are possible.

We first load the package via the familiar `library()` call:

```{r load fHMM, message = FALSE}
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 DAX^[The `download_data()` function is explained in [the vignette on data management](https://loelschlaeger.de/fHMM/articles/v03_data_management.html).] [@jan92]:

```{r}
dax <- download_data(symbol = "^GDAXI")
head(dax)
```

### 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.

```{r, set controls emp hmm}
controls <- list(
  states = 3,
  sdds   = "t",
  data   = list(file        = dax,
                date_column = "Date",
                data_column = "Close",
                logreturns  = TRUE),
  fit    = list(runs        = 50)
)
set_controls(controls)
```

### 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.

```{r, set controls sim hmm}
controls <- list(
  states  = 2,
  sdds    = "gamma(mu = 0.5|2)",
  horizon = 500
)
set_controls(controls)
```

### 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.

```{r, set controls hhmm}
controls <- list(
  hierarchy = TRUE,
  horizon   = c(100, 10),
  sdds      = c("t(df = 1)", "t(df = Inf)"),
  period    = "m"
)
set_controls(controls)
```

The help page of the `set_controls()` function provides an overview of all possible specifications, it can be accessed via `help("set_controls", package = "fHMM")`.

## References