RewardsEEG_V3 - Stage-by-stage project notes (for report + reproducibility)

This document is intended to “lock in” the full analysis context inside the repository for future reference. Installation instructions will be provided shortly.

Project summary

Goal: Re-analysis of Hassall, Hunt & Holroyd (NeuroImage, 2022) “Task-level value affects trial-level reward processing” using a 12-subject BIDS EEG dataset (sub-27 … sub-38).

Core deliverables

• Replicate the paper’s RewP/ERP results with a transparent, reproducible pipeline.
• Add one additional analysis category (course requirement): Time–Frequency (TFR) on feedback epochs.

Main pipeline state: Average reference (restored as the primary analysis).
Sensitivity check: Mastoid (TP9/TP10) re-reference kept as a separate script/run for reporting only.

Repository layout (high level)

• bids/ — BIDS dataset (sub-27 … sub-38)
• configs/ — YAML configs:
  • analysis.yaml
  • paths.yaml
• scripts/ — custom analysis scripts (Stages 2–6b)
• outputs/
  • derivatives/ — pipeline + epochs + evokeds outputs
  • tables/ — CSV outputs per stage
  • qc/ — plots and sanity visualizations
  • logs/ — version captures and run summaries

Key methodological choices

• Referencing: Primary = average reference (main analysis).
  Sensitivity = TP9/TP10 mastoid re-ref (Stage 4b).
• Filtering: handled by mne-bids-pipeline config (documented in Stage 1 config).
• Artifact handling: ICA via mne-bids-pipeline (PICARD).
• Epoching: cue-locked and feedback-locked epochs from annotations; baseline and rejection defined in Stage 2.
• ERP metric: RewP at FCz in 240–340 ms (paper-like peak) and mean amplitude in the same window (additional ERP metric).
• Additional analysis category: Time–Frequency (TFR) with Morlet wavelets focusing on midfrontal theta.

Stage 1 - Preprocessing (mne-bids-pipeline)

Script/config: mne_bids_pipeline_config.py
Purpose: standard preprocessing and ICA (PICARD).
Primary output: clean raw FIF for each subject:

• outputs/derivatives/mne-bids-pipeline/sub-XX/eeg/*_proc-clean_raw.fif

Notes to mention

• This stage sets the baseline for reproducibility and version control.
• Keep the exact config in the repo and cite versions (MNE, Python, etc.).

Stage 2 - Epoch creation (cue + feedback)

Script: scripts/02_make_epochs.py
Inputs

• Stage 1 clean raw FIF from mne-bids-pipeline
• BIDS events/annotations

Epoching parameters

• tmin = -0.2 s
• cue epochs: tmax = 0.8 s
• feedback epochs: tmax = 0.6 s
• baseline: (-0.2, 0.0) s
• reject threshold: ~250 µV
• feedback pairing window: 10 s (pair cue→feedback)
• keeps only win/loss outcomes

Event codes (BrainVision S codes)

• cues: S2 / S12 / S22 / S32
• win feedback: S6 / S16 / S26 / S36
• loss feedback: S7 / S17 / S27 / S37

Outputs

• epochs:
  • outputs/derivatives/epochs/sub-XX/eeg/*_desc-cue_epo.fif
  • outputs/derivatives/epochs/sub-XX/eeg/*_desc-feedback_epo.fif
• QC tables:
  • outputs/tables/epoch_counts_by_subject.csv
  • outputs/tables/epoch_counts_by_condition.csv
• QC plot example:
  • outputs/qc/epochs_dropcounts.png

Stage 3 - Evoked creation (condition averages)

Script: scripts/03_make_evokeds.py
Purpose: compute subject-level evokeds grouped by:

• task_value × cue_value × outcome_label

Inputs

• Stage 2 epochs for cue and feedback

Outputs

• evokeds:
  • outputs/derivatives/evokeds/sub-XX/eeg/*_desc-cue_evokeds-ave.fif
  • outputs/derivatives/evokeds/sub-XX/eeg/*_desc-feedback_evokeds-ave.fif
• condition count table:
  • outputs/tables/evoked_counts_by_condition.csv

Sanity checks

• Confirm expected conditions exist and counts are nonzero.
• Confirm labels/metadata are standardized (task_value, cue_value, outcome_label).

Stage 4 - ERP figures + RewP extraction (subject + grand average)

Script: scripts/04_erp_and_rewp.py
Purpose

• Produce subject-level ERP outputs for documentation and group-level grand averages
• Compute RewP at FCz with:
  • paper-like peak in 240–340 ms window (win–loss)
  • mean amplitude in the same window (additional metric)

Core outputs

• subject-level metrics:
  • outputs/tables/stage4/rewp_by_subject.csv
• grand average summary tables (if generated):
  • outputs/tables/stage4/rewp_grand_summary.csv (optional)
  • outputs/tables/stage4/rewp_group_summary.csv (optional)
• key plots:
  • grand FCz feedback win/loss + win–loss
  • paper-style task×cue waveforms at FCz (8 traces) + 4 difference waves

Important interpretation note

• The paper’s central contrast (Mid-High vs High-High) may not replicate in this subset/pipeline.
• Trial counts can be uneven across conditions; keep count tables in the report.

Stage 4b - Mastoid re-reference sensitivity

Purpose: Demonstrate a methodological robustness check (reference choice) without changing the main analysis.

Approach

• Re-reference using TP9/TP10 and re-run the relevant ERP/RewP computations.
• Used only as a sanity/sensitivity section in the report.

Status

• Keep the Stage 4b script and outputs as a separate folder/run.
• Main analysis remains average reference.

Stage 5 - Group-level statistics + Cohen’s d (paired dz)

Script: scripts/05_stats_rewp_cohensd.py
Purpose: run paper-matched contrasts on RewP metrics (peak + mean) and compute effect sizes.

Contrasts (paired)

• Low-Low vs Mid-Low
• Mid-High vs High-High

Outputs

• outputs/tables/stage5/rewp_contrasts_stats.csv
• outputs/tables/stage5/rewp_condition_descriptives.csv
• outputs/tables/stage5/rewp_trialcount_summary.csv
• version log: outputs/logs/stage5_versions.txt
• QC plots under outputs/qc/stage5/

Interpretation snapshot (to be written with actual numbers from CSVs)

• Low-Low vs Mid-Low: often shows a reliable effect (esp. peak).
• Mid-High vs High-High: may be non-significant and/or directionally different from the paper.

Stage 6a - ERP “additional metric + robustness”

Purpose

• Treat mean-amplitude RewP as an added ERP metric and evaluate robustness via:
  • Wilcoxon
  • bootstrap CI
  • leave-one-subject-out (LOSO)

Outputs

• rewp_stage6_stats.csv
• rewp_stage6_loso.csv
• rewp_stage6_trialcount_summary.csv

Key takeaways

• Peak metric often more robust than mean metric.
• Robustness tools help explain discrepancies vs paper and sensitivity to subject influence.

Stage 6b - Time–Frequency additional analysis

Script: scripts/06b_time_frequency_feedback_theta.py
Purpose: a distinct analysis category beyond ERPs: TFR power on feedback epochs (FCz), focusing on theta.

Methods (Stage 6b)

Input: feedback epochs per subject:

• outputs/derivatives/epochs/sub-XX/eeg/sub-XX_task-casinos_desc-feedback_epo.fif

TFR parameters

• method: Morlet power
• freqs: 2–20 Hz (1 Hz steps)
• n_cycles: freqs/2
• decim: 4
• baseline: (-0.2, 0.0) s
• baseline mode: logratio
• channel: FCz

Primary theta ROI

• theta band: 4–8 Hz
• time window: 0.20–0.50 s
• computed separately for Win and Loss, then:
  • outcome metric: Loss − Win theta

Paper-matched condition set (for comparison)

• Low-Low, Mid-Low, Mid-High, High-High

Contrasts tested (paired) on Loss−Win theta

• Low-Low minus Mid-Low
• Mid-High minus High-High

Outputs (Stage 6b)

Tables:

• outputs/tables/stage6b/tfr_theta_by_subject.csv
• outputs/tables/stage6b/tfr_theta_loss_minus_win_by_subject.csv
• outputs/tables/stage6b/tfr_theta_contrasts_stats.csv
• outputs/tables/stage6b/tfr_theta_loso.csv
• outputs/tables/stage6b/stage6b_additional_analysis_summary.md

QC plots:

• outputs/qc/stage6b/tfr_grand_win.png
• outputs/qc/stage6b/tfr_grand_loss.png
• outputs/qc/stage6b/tfr_grand_diff_loss_minus_win.png
• outputs/qc/stage6b/theta_roi_by_condition.png
• outputs/qc/stage6b/theta_contrast_diffs.png

Version log:

• outputs/logs/stage6b/stage6b_versions.txt

Interpretation (Stage 6b)

Grand TFRs

• Win/Loss grand TFRs are broadly similar with coherent post-feedback low-frequency power changes at FCz.
• Grand Loss − Win shows a positive patch around ~4–10 Hz, strongest late (~0.40–0.55 s):
  • suggests loss evokes higher midfrontal low-frequency power than win, but later than classic early windows.

Theta ROI pattern by condition (4–8 Hz, 0.20–0.50 s)

• Low-Low: Loss > Win (small positive)
• Mid-Low: Loss > Win (largest positive)
• Mid-High: Loss < Win (reversal; negative Loss−Win)
• High-High: Loss > Win (small/moderate)

Why contrast stats can look “mixed”

• Low-Low vs Mid-Low not reliable: mixed subject directions (approx 7 vs 5) and an outlier (sub-34).
• Mid-High vs High-High directionally consistent:
  • 11/12 subjects show Mid-High − High-High < 0 (High-High larger Loss−Win theta),
  • one influential opposite outlier sub-28 with very large magnitude weakens the paired t-test while Wilcoxon can be significant.
  • Sensitivity note: dropping sub-28 makes the t-test much stronger (≈ p ~ 0.009).

Limitations / sanity notes

• Mid-High has low loss trial counts (min ~10, mean ~22), reducing stability.
• Low frequencies (2–3 Hz) near epoch edges can be susceptible to wavelet edge effects.

Repository link

• GitHub: https://github.com/SamBro2901/jubilant-engine