---
title: "Getting Started with AccumulatR"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with AccumulatR}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  markdown: 
    wrap: 72
---

`AccumulatR` describes responses as races between latent processes. This
guide introduces the model objects, data columns, and steps needed to
simulate observations and evaluate their likelihood.

```{r}
library(AccumulatR)
```

## The basic workflow

Most workflows in `AccumulatR` follow the same four steps:

1.  Define a model with accumulators, pools, and observed responses.
2.  Finalize that model with `finalize_model()`.
3.  Work with behavioral data, either simulated with `simulate()` or
    collected in an experiment.
4.  Prepare the data, build a model context, and evaluate candidate
    parameter values.

## Core ideas

### `trials`

`trials` identifies the behavioral observation. In the simplest case,
each row of your data corresponds to one trial.

### `R`

`R` is the observed response label on a trial. For a two-choice task,
typical values might be `"left"` and `"right"`, or `"red"` and
`"green"`, etc.

### `rt`

`rt` is the observed response time for `R`. The examples use seconds;
onsets and time parameters use the same units. In a single-response model,
`R = NA` and `rt = NA` record a trial with no observed response.

### Component

A component specifies which accumulators are active on a trial. It can
represent an observed trial type or an unobserved processing mode. A
`component` column in the data conditions on the named component;
omitting it or using `NA` averages over components. Each trial belongs
to one component. See [Working with Mixtures](mixtures.html) for examples.

### Onset

An `onset` is the time at which an accumulator becomes active. Most
accumulators start at time `0`, while in some cases, extra information
appears during the trial. In `AccumulatR`, an onset can be:

-   a fixed delay, such as `onset = 0.15`
-   a chained onset, such as `onset = after("A")`, meaning the process
    starts only after another accumulator (in this case `A`) or pool has
    finished

Both onset and non-decision time (`t0`) shift response times. The
difference is where they are supplied: `t0` belongs to the parameter
vector, while onset is declared in the model or supplied with trial
conditions. Omitted `t0` values default to zero.

## A minimal model

The example below defines a basic two-choice race model with two
lognormal accumulators.

```{r}
model <- race_spec() |>
  add_accumulator("left", "lognormal") |>
  add_accumulator("right", "lognormal") |>
  add_outcome("left", "left") |>
  add_outcome("right", "right") |>
  set_parameters(separate = list(m = TRUE, s = TRUE)) |>
  finalize_model()
```

## Simulated behavioral data

`build_param_matrix()` repeats a named parameter vector across trials.
It creates one row per accumulator per trial, with each trial's
accumulators in model order. Here six trials and two accumulators give
twelve parameter rows. `par_names(model)` lists the accepted parameter
names; `set_parameters()` determines which values are shared or separate.

```{r}
pars <- c(
  left.m = log(0.28), left.s = 0.16,
  right.m = log(0.35), right.s = 0.18
)

param_df <- build_param_matrix(model, pars, n_trials = 6)
sim <- simulate(model, param_df, seed = 123)

head(sim)
```

Each row is one trial, `R` is the observed response, and `rt` is the
response time.

## From behavioral data to likelihood

To fit a model, the usual pattern is:

```{r}
prepared <- prepare_data(model, sim[c("trials", "R", "rt")])
ctx <- make_context(model)
log_likelihood(ctx, prepared, param_df)
```

`prepare_data()` checks and arranges the observations, and `make_context()`
compiles the model's response rules. Reuse these objects while varying
parameters for the same model. Supply one parameter block per prepared
trial, in matching order.

`log_likelihood()` returns the summed log-likelihood; use `sum = FALSE`
for one value per trial. Response-time observations contribute densities,
so the result can be positive. See [A Simple Race Model](simple_model.html)
for an example using `optim()` to estimate parameters.