---
title: "calmr_basics"
author: "Victor Navarro"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{calmr_basics}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Your first simulation

To perform your first simulation you will need:

1. A data.frame specifiying the experiment design, and
2. A list with the parameters for the model you'll be using.

## The design data.frame

For this example we will use a blocking design.

```{r}
library(calmr)

my_blocking <- data.frame(
  Group = c("Exp", "Control"),
  Phase1 = c("10A(US)", "10C(US)"),
  R1 = c(FALSE, FALSE),
  Phase2 = c("10AB(US)", "10AB(US)"),
  R2 = c(FALSE, FALSE),
  Test = c("1#A/1#B", "1#A/1#B"),
  R3 = c(FALSE, FALSE)
)
# parsing the design and showing the original and what was detected
parsed <- parse_design(my_blocking)
parsed
```


A few rules about the design data.frame:

1. Each row represents a group.
2. The first column contains the group labels.
3. The remaining columns are organized in pairs (trials in a phase, and whether to randomize them)

The trials in each phase column are specified using a very rigid notation. A few observations about it:

1. Trials are preceded by a number. That number represents 
the number of times that trial will be given in each phase. 
"10A(US)" means that the "A(US)" trial will be given 10 times.
2. The presence and absence of the unconditioned stimulus are 
not denoted with the traditional "+" and "-" symbols. Instead, 
here we use parenthesis to denote "complex" stimuli. These can 
be thought of as an element with a complex name (i.e., with 
more than one character). As such, "(US)" specifies a single 
element to represent the US.
3. In the same vein, multiple characters with no parentheses 
denote individual elements.
For example, "AB" implies the presence of two stimuli, A and B.
4. The "/" character is used as a trial separator 
(it does not imply randomization by itself). 
Thus, "1A/1B" specifies that a single "A" trial 
and a single "B" trial will be given during that phase. 
Recall that randomization of trials within a phase is 
specified by the column after it (above, R1, R2, and R3).
5. The "#" character is used to denote probe trials. 
In contrast to real life, probe trials here entail no 
update of the model's associations. As such, 
probe trials can be used to track the development 
of key associations, with no repercussion to what 
the model learns on normal training trials.

If you want to check whether your phase string will work with the simulator, 
you can use `phase_parser`.
The function returns a list with a lot of information, 
so let's print only some of the fields.

```{r, error = TRUE}
# not specifying a number of AB trials. Error!
phase_parser("AB/10AC")
# putting the probe symbol out of order. Error!
phase_parser("#10A")
# considering a configural cue for elements AB
trial <- phase_parser("10AB(AB)(US)")
# different USs
trial <- phase_parser("10A(US1)/10B(US2)")
```


## The parameters list

Now we need to pick a model and its parameters.

To get the models currently supported in `calmr`, you can call `supported_models()`.

```{r}
supported_models()
```

After choosing a model, you can get default parameters for your design with `get_parameters`.
```{r}
my_pars <- get_parameters(my_blocking, model = "RW1972")
# Increasing the beta parameter for US presentations
my_pars$betas_on["US"] <- .6
my_pars
```


### Simulating

With all of the above, we can run our simulation using the `run_experiment` function.
This function also takes extra arguments to manipulate the number of iterations to run the experiment for, 
and whether to organize trials in miniblocks (see `help(make_experiment)` for additional details).
Below, we run the experiment for 5 iterations.

```{r}
my_experiment <- run_experiment(
  my_blocking, # note we do not need to pass the parsed design
  model = "RW1972",
  parameters = my_pars,
  iterations = 5
)
# returns an CalmrExperiment object
class(my_experiment)
# CalmrExperiment is an S4 class, so it has slots
slotNames(my_experiment)
# the experience given to group Exp on the first iteration
my_experiment@experiences[[1]]
# the number of times we ran the model (groups x iterations)
length(experiences(my_experiment))
# an experiment has results with different levels of aggregation
class(my_experiment@results)
slotNames(my_experiment@results)
# shorthand method to access aggregated_results
results(my_experiment)
```

If you are an advanced R user you will be able to dig into the data straight away.

However, the package also includes some methods to get a quick look at the results.

## Plotting

Let's use `plot` method to create some plots.
Each model supports different types of plots according to the results they can produce
(e.g., associations, responses, saliences, etc.)

```{r}
# get all the plots for the experiment
plots <- plot(my_experiment)
names(plots)
# or get a specific type of plot
specific_plot <- plot(my_experiment, type = "vs")
names(specific_plot)
# show which plots are supported by the model we are using
supported_plots("RW1972")
```

In this case, the RW model supports both associations and responses.

### Stimulus associations

The columns below are the phases of the design and the rows denote 
the source of the association.
The colors within each panel determine the target of the association.

```{r}
plot(my_experiment, type = "vs")
```

### Responding

Fairly similar to the above, but this time responding is a function of 
the stimuli presented on a trial.

```{r}
plot(my_experiment, type = "rs")
```

## Graphing

You can also take a look at the state of the model's associations at any 
point during training, using the `graph` method in your experiment.

```{r}
my_graph_opts <- get_graph_opts("small")
graph(my_experiment, t = 20, options = my_graph_opts)
```

## Final thoughts

The `calmr` package was designed to simulate quickly: 
write your design and get a glance at model predictions. 

Yet, the package also has some features for advanced R users, 
so make sure to check the other vignettes when you are ready.

