---
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 = "#>",
  tidy = TRUE
)
library("printr")
```

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()[6:7], collapse = ".")` with the `{fHMM}` `r utils::packageVersion("fHMM")` package.] outlines what and how specifications are possible.

```{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.] [@jan92]:

```{r}
download_data(symbol = "^GDAXI", file = "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.

```{r, set controls emp hmm}
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)
```

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

```{r, set_controls help page, printr.help.sections=c('arguments')}
?set_controls
```

## References

