---
title: "using_time_models"
author: "Victor Navarro"
output: rmarkdown::html_vignette
bibliography: references.bib
csl: apa.csl
vignette: >
  %\VignetteIndexEntry{using_time_models}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r set-options, echo=FALSE, cache=FALSE}
options(width = 300)
```

```{R, include = FALSE}
knitr::opts_chunk$set(
  fig.width = 7,
  collapse = TRUE,
  comment = "#>",
  message = FALSE,
  warning = FALSE
)
```

## Time models in calmr

Version 0.5 of `calmr` introduced its first time-based model, 
ANCCR [@jeong_mesolimbic_2022], and with it, 
I wrote several additional tools for future time-based models.

#### Changes to trial-based models

The biggest change in `calmr` version 0.5 is the use of the ">" character and its effect on 
trial-based models. With the advent of time-based models, some generalizations had to be made 
to enable those models to update across adjacent trial periods. You can learn more about this 
in the [directional_models](directional_models.html) vignette.

#### Specifying a design for time-based models

The designs for time-based models are nearly identical to those for trial-based models. 
However, clever use of the ">" character will
enrich them. Let's specify a serial feature discrimination experiment:

```{r, message = TRUE}
library(calmr)
fpfn <- data.frame(
  group = c("FP", "FN"),
  phase1 = c("!100F>T>(US)/100T", "!100F>T/100T>(US)")
)
parse_design(fpfn)
```


We can manually specify the timing for the above experiment by calling the `get_timings()` function.
Manipulating the list returned by that function will result in a manipulation of the timing between the 
experimental events.

```{r}
ts <- get_timings(fpfn, model = "ANCCR")
ts
```


And now let's get the parameters for the ANCCR model.

```{r}
pars <- get_parameters(fpfn, model = "ANCCR")
# increase learning rates
pars$alpha_reward <- 0.8
pars$alpha <- 0.08
# increase sampling interval to speed up the model
pars$sampling_interval <- 5
pars
```

Let's make the model's experience and look at the first 20 entries.

```{r}
experiment <- make_experiment(fpfn,
  parameters = pars,
  timings = ts,
  model = "ANCCR"
)
head(experiences(experiment)[[1]], 20)
```

As you can see above, there are several rows per trial, each specifying a different stimulus.
Time-based models like ANCCR run over a time log because they make ample 
use of the temporal difference between events.

Let's run the model and see some plots.

```{r}
experiment <- run_experiment(experiment)
```
```{r}
# Action values
patch_plots(plot(experiment, type = "action_values"))
# ANCCR
patch_plots(plot(experiment, type = "anccrs"))
# Dopamine transients
patch_plots(plot(experiment, type = "dopamines"))
```

And that's it! Easy, right?

#### References