# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Overview

EEG analysis pipeline for a visual recognition experiment. Subjects view clear and scrambled images while EEG is recorded via a microEEG device (EDF format). The system computes peri-stimulus averages to detect neural responses to image presentation and recognition keypresses.

## Running the Analysis

```bash
python3 run_analysis.py
```

This is a standalone script (no Django required). It reads `AH_20260228_102752.edf`, `trialData.json`, and `recognitionPresses.json` from the script directory and writes PNG plots to `output/`.

Dependencies: `numpy`, `scipy`, `matplotlib`, `pyedflib`

## Architecture

There are two versions of the analysis code:

- **`run_analysis.py`** — Standalone script. Hardcoded to Trial #144 (subject AH1). This is the active entrypoint. Configuration constants at the top control the EDF file path, trial timestamp, and EDF start time.

- **`analysis.py`** — Original Django management command (`Command` class extending `BaseCommand`). Reads Trial objects from the database (depends on `Trial.models` and `Dataset.models`). Not runnable standalone — requires the parent Django project. Kept as reference.

- **`models.py`** — Django model definitions for `Subject` and `Trial`. The `Trial` model stores EDF files, trial metadata, recognition press data, and analysis output images as `FileField`s.

## Key Domain Concepts

- **Peri-stimulus average (PSA)**: Averages EEG signal segments time-locked to stimulus events. The core computation in `peri_stimulus_average()` / `periStimulusAverage()`.
- **Channels analyzed**: O1, O2, T5, T6 (occipital and temporal electrodes). CH21 and Cz used as optical trigger / reference channels.
- **Clear vs scrambled images**: Clear images are the actual stimuli; scrambled are controls. Both come from `trialData.json` keyed by `values[2]` (`"false"` = clear).
- **Recognition presses**: Keypress timestamps from `recognitionPresses.json`. Matched to stimuli within a 1000ms prompt delay window with a 200ms minimum reaction time filter.
- **Time alignment**: Trial timestamps and EDF start times are reconciled to align behavioral events with EEG samples. JavaScript version 1.1 adds a -300ms time offset.

## Plots Generated

1. Signal alignment — full EEG with image/keypress event markers
2. Peri-stimulus average — averaged across all clear-image presentations
3. Filtered PSA — only stimuli followed by a recognition keypress
4. Keypress-locked PSA — time-locked to stimulus onset for trials with keypresses
5. Peri-non-stimulus average — averaged across scrambled-image presentations

## Signal Processing Pipeline

60 Hz notch filter (IIR, Q=30) applied to remove line noise. Sample frequency read from EDF headers (typically 250 Hz). The bandpass filter (0.04–0.12 Hz) is defined but currently bypassed — `bandpass=diff` is used directly.