---
  title: "An example on how to evaluate manually constructed event models"
  author: "Nina Purg, Jure Demšar and Grega Repovš"
  date: "`r Sys.Date()`"
  output:
    html_vignette:
    toc: yes
---

<!--
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
  %\VignetteIndexEntry{An example on how to evaluate manually constructed event models}
-->

```{r, message=FALSE, warning=FALSE, echo=FALSE}
# knitr options
knitr::opts_chunk$set(fig.width=6, fig.height=4.5)
```

The **autohrf** package is not only useful for preparing model specifications and then automatically finding the models that best fit the underlying data. In this example we show how you can use the **autohrf** package to investigate the quality of manually constructed models.

Let us start this example by loading required libraries and the data from the spatial working memory study.

```{r}
# libraries
library(autohrf)

# load the data
df <- swm
head(df)
```

The loaded data frame has 11520 observations, each with 3 variables (roi, t, and y) **roi** denotes the region of interest, **t** the time stamp and **y** the value of the BOLD signal. Note that input data for the **autohrf** package should be always organized in this manner.

Next, we construct three different models, one with three events, one with four events and one with five events. When manually constructing event models we need to create a data frame which has an entry (observation) for each of the events in the model. For each of the events we need to provide its name, its start time and its duration.

```{r}
# a model with three event predictors
model1 <- data.frame(event = c("encoding", "delay", "response"),
                     start_time = c(0, 0.15, 10),
                     duration = c(0.15, 9.85, 3))

# a model with four event predictors
model2 <- data.frame(event = c("encoding", "delay", "probe", "response"),
                     start_time = c(0, 0.15, 10, 10.5),
                     duration = c(0.15, 9.85, 0.5, 2.5))

# a model with five event predictors
model3 <- data.frame(event = c("stimulus", "encoding", "delay", "probe", "response"),
                     start_time = c(0, 0.15, 2, 10, 10.5),
                     duration = c(0.15, 1.85, 8, 0.5, 2.5))
```

Once we construct our models we can use the **evaluate_model** function to obtain the model fitness to the measured data.

```{r}
# evaluate models
em1 <- evaluate_model(df, model1, tr = 1)
em2 <- evaluate_model(df, model2, tr = 1)
em3 <- evaluate_model(df, model3, tr = 1)
```

We can also use the **plot_model** function to visually inspect how model fits the underlying data.

```{r}
# plot models fit to the data
plot_model(em1)
plot_model(em2)
plot_model(em3)
```