# Attention in Aversive Choice — Reproduction Package

Author: Brenden Eum (2024)

This folder is **self-contained**. It provides the full pipeline behind the paper — model-free analyses, model fitting, model comparison, out-of-sample simulation, and parameter recovery. See the bottom of this document for things not covered.

Only the processed data and code are part of this package. All derived outputs (model fits, simulations, figures) are regenerated by the scripts below.

---

## Requirements

- **R** 4.3.1 with: `tidyverse`, `lme4`, `broom.mixed`, `brms`, `bayesplot`,
  `effsize`, `plotrix`, `ggsci`, `ggpubr`, `ggnewscale`, `ggalluvial`, `glue`,
  `gridExtra`, `grid`, `gridtext`, `latex2exp`, `patchwork`, `readr`.
- **Julia** with the bundled toolbox `analysis/helpers/aDDM_fitting/ADDM.jl`
  (activate with `--project=analysis/helpers/aDDM_fitting/ADDM.jl`).

**Run every script from the `gain_loss_code` root directory.** All paths are
relative to this root, e.g.
`Rscript analysis/helpers/model_free_analysis/model_free_analysis_figures.R`.

Placeholders in file names: `{study}` = Study 1 (dots) / Study 2 (numeric);
`{dataset}` = exploratory/confirmatory/joint (E/C/J); `{condition}` = Gain/Loss.

---

## Data

Included: processed data in `data/processed_data/`
(`datasets/{e,c,j}cfr.RData`, and per-study `expdata*`/`fixations*` CSVs).
Raw eye-tracking data is not included (IRB); request it from
eum.brenden@gmail.com. Preprocessing scripts (`analysis/preprocessing/`) are
provided for reference but are not needed to reproduce the paper.

---

## 1. Model-free analyses (fast; need only the processed data)

In `analysis/helpers/model_free_analysis/`:

```
model_free_analysis_figures.R       # Fig 4, Fig 5, Fig 6, Supp Fig 1
model_free_analysis_regressions.R   # Supp Tables 1-4
RT_OV.R                             # Supp Fig 3
```

In `analysis/helpers/fix_cross_analysis/`:

```
fix_cross_analysis_figures.R        # Supp Figs 13-15 (Study 2 fixation-cross)
```

In `analysis/helpers/aDDM_analysis/`:

```
value_attention_effect_wrt_value.R  # Supp Fig 4 (attention x value interaction)
```

## 2. Model fitting (slow; regenerates the fits every model-based result needs)

`aDDM_fitting/fit_study.jl` fits the Hybrid aDDM (which nests DDM, AaDDM, RaDDM,
MARaDDM) per participant via grid search, and writes
`analysis/helpers/aDDM_fitting/results/study{study}{condition}/{model_comparison,model_posteriors}/`.

Loop over subjects (72 for Study 1, 50 for Study 2) and the four study-conditions:

```
# example: Study 1 Gain, all 72 subjects
for i in $(seq 1 72); do
  julia --project=analysis/helpers/aDDM_fitting/ADDM.jl --threads=4 \
    analysis/helpers/aDDM_fitting/fit_study.jl Study1G $i \
    analysis/helpers/aDDM_fitting/Study1_participants_j.csv \
    analysis/helpers/aDDM_fitting/results/study1G/
done
# repeat with Study1L / Study2G / Study2L (Study2 uses Study2_participants_j.csv, 50 subjects)
```

Grids live in `analysis/helpers/aDDM_fitting/parameter_grids/` (regenerate with
`make_parameter_grid.R`); likelihoods in `analysis/helpers/aDDM_fitting/custom_functions/`.

## 3. Model-based analyses (need the fits from step 2)

In `analysis/helpers/aDDM_analysis/`:

```
posterior_model_probabilities.R      # Fig 7 (+ Supp Fig 7 for E/C)
HybridaDDM_IndividualEstimates.R     # Fig 8 (Hybrid estimates)  [writes CSV]
RaDDM_IndividualEstimates.R          # Supp Fig 8               [writes CSV]
AddDDM_IndividualEstimates.R         # Supp Fig 9               [writes CSV]
theta_eta_correlations.R             # Supp Fig 10 (needs the 3 CSVs above)
subjects_using_same_model.R          # best-fitting model per participant
HybridaDDM_text_discussion.R         # in-text Hybrid stats (needs the 3 CSVs)
model_comparison_main_regression_test.R    # Table 1
model_comparison_second_regression_test.R  # RT(OV) test restricted to vDiff = 0
```

Out-of-sample predictions (simulate, then plot; in `aDDM_analysis/`):

```
HybridaDDM_simulate_out_of_sample.jl + HybridaDDM_plot_out_of_sample.R  # Fig 9
RaDDM_simulate_out_of_sample.jl      + RaDDM_plot_out_of_sample.R       # Supp Fig 11
AddDDM_simulate_out_of_sample.jl     + AddDDM_plot_out_of_sample.R      # Supp Fig 12
```

The simulate scripts read the `*_IndividualEstimates_J.csv` from step 3 and the
joint test data, writing to a dated folder under
`analysis/outputs/temp/out_of_sample_simulations/`. The plot scripts pick up the
most recent such run automatically.

## 4. Parameter recovery (Supp Fig 6)

In `analysis/helpers/parameter_recovery/`:

```
make_parameter_grid.R                       # writes parameter_grids/*
HybridaDDM_simulate_{Gain,Loss}.jl          # simulate data from known params
HybridaDDM_fit_{Gain,Loss}.jl               # refit
HybridaDDM_parameter_recovery_analysis.R    # Supp Fig 6
```

---

## Figure / table index

| Output | Script(s) |
|---|---|
| Fig 4, 5, 6; Supp Fig 1 | `model_free_analysis/model_free_analysis_figures.R` |
| Supp Tables 1-4 | `model_free_analysis/model_free_analysis_regressions.R` |
| Supp Fig 3 | `model_free_analysis/RT_OV.R` |
| Supp Fig 4 | `aDDM_analysis/value_attention_effect_wrt_value.R` |
| Supp Figs 13-15 | `fix_cross_analysis/fix_cross_analysis_figures.R` |
| Fig 7; Supp Fig 7 | `aDDM_analysis/posterior_model_probabilities.R` |
| Fig 8 | `aDDM_analysis/HybridaDDM_IndividualEstimates.R` |
| Supp Figs 8, 9 | `aDDM_analysis/{RaDDM,AddDDM}_IndividualEstimates.R` |
| Supp Fig 10 | `aDDM_analysis/theta_eta_correlations.R` |
| Fig 9; Supp Figs 11, 12 | `aDDM_analysis/{HybridaDDM,RaDDM,AddDDM}_{simulate,plot}_out_of_sample.*` |
| Table 1 | `aDDM_analysis/model_comparison_main_regression_test.R` |
| in-text Hybrid stats | `aDDM_analysis/HybridaDDM_text_discussion.R` |
| Supp Fig 6 | `parameter_recovery/HybridaDDM_*` |

---

## Scope

A few things to be aware of before running:

- **Fitting configuration.** The current version of `fit_study.jl` fixes the boundary-collapse rate to
  zero (`:decay=>0` in `my_fixed_params`), and the shipped grids in
  `parameter_grids/` cover `(d, sigma, theta, eta)`. The likelihood functions
  implement exponential collapse (`exp(-decay * t)`), so collapse can be
  estimated by adding a `decay` column to the grid CSVs. This grid column
  overrides the fixed value, and the fitted `decay` then appears in
  `model_posteriors/posteriors_df_*.csv`. Note that the `*_IndividualEstimates.R`
  scripts select `(d, sigma, theta, eta)` only, so they need a matching edit to
  carry `decay` downstream, and the trial simulators in
  `parameter_recovery/custom_simulators/` use hyperbolic rather than exponential
  collapse.
- **Fits are not shipped.** Step 2 must be run before any of step 3. Estimates
  produced from a different grid than the published one will not match the
  paper's numbers.
- **Datasets.** The fitting commands in step 2 use the joint (`_j`) participant
  lists. Supp Fig 7 additionally needs fits for the exploratory and confirmatory
  samples; run step 2 against those participant lists to produce them.
- **Supp Table 5** (the regression test on simulated data) is not generated by
  this package.

## Omitted Figures

- **Fig 1** is an illustrative aDDM example.
- **Fig 2, 3, Supp Fig 5** are not script-generated.
- **Supp Fig 2** simulated behavior of models that cannot explain our result (aDDM, OPPaDDM, TrOPPaDDM, etc.). Its scripts live in `analysis/helpers/aDDM_predictions/` (`simulate_predictions.jl` + `plot_predictions_{model}.R`). Simulation outputs are not part of the package, but can be regenerated.
