# MATLAB port of the tDCS GLM analysis — Design

**Date:** 2026-07-20
**Status:** Approved (design)
**Location:** `analysis/matlab/`
**Ports:** the Python analysis in `analysis/` (`tdcs_glm.py`, `METHODS.md`) to MATLAB.

## Goal

Reproduce the tDCS reaching analysis in MATLAB: consume raw exports from the app,
derive the day-window × merge-scenario variations, run each scenario
independently via `switch/case`, and print the raw GLM output plus a
plain-language interpretation. Include a `matlab.unittest` test suite.

## Environment

- MATLAB **R2025b** + **Statistics and Machine Learning Toolbox** installed at
  `~/matlab` (via `mpm`). Requires the user's license to be **activated** before
  anything runs (`~/matlab/bin/activate_matlab.sh`, or a license file in
  `~/matlab/licenses/`).
- Headless execution: `~/matlab/bin/matlab -batch "<cmd>"`. Tests run via
  `matlab -batch "run_tests"`. **The MATLAB code and tests cannot be executed in
  the dev environment until the license is active** — they are written first and
  run once licensing is in place.

## Modeling engine

MATLAB has no GEE; the port uses **`fitglme`** (generalized linear mixed model)
with a **per-subject random intercept** as the single primary estimator — this
folds the Python GEE + random-intercept models into one native tool. The Python
mixed model already agreed with its GEE, so results should track. Reference group
is **Electrode-Box-B2**; `day_c` is the mean-centered training day and
`day_c2 = day_c^2` captures the plateau.

Models per scenario (on the scenario's data table):

- **Count:** `success ~ group + day_c + day_c2 + (1|subject)`, `Distribution='Poisson'` → IRRs vs B2.
- **Rate:** `success ~ group + day_c + day_c2 + (1|subject)`, `Distribution='Binomial'`, `BinomialSize=total` → odds ratios. Zero-attempt sessions (`total==0`, undefined rate) are dropped for this model only; the count model keeps them (they are genuine 0-success observations).
- **Learning rate:** `success ~ group*day_c + day_c2 + (1|subject)`, Poisson → group×day slope differences + a joint `coefTest`.
- **Per-animal:** collapse each animal to one number (mean count; pooled rate = Σsuccess/Σtotal), then `ttest2` (Welch) and `ranksum` (Mann-Whitney, one-sided) — the honest small-n check.
- **`unmerged_*` scenarios only:** classify Box-A and Right-Electrode against **both** anchors via `coefTest` contrasts → A2-like / B2-like / ambiguous.

## Data flow

```
raw/raw_success.csv ┐
raw/raw_total.csv   ┴─ tdcs_load_data → long table {subject,group,day,success,total}
                                     → tdcs_scenario_data(scenario)
                                     → filtered+merged table (saved: derived/<scenario>.csv)
                                     → fitglme models → console + results/<scenario>.txt
```

### Raw files (produced now, in the website's export format)

Two app-style matrices, identical to the app's **Export Data** output with
X = "# Days Reach", Group by = "Group":

- `raw/raw_success.csv` — Data = Success
- `raw/raw_total.csv` — Data = Total attempts

Format (both):
```
Data,<metric>
<blank>
Group,<group per subject column>
# Days Reach,<subject headers>
<day>,<value per subject>
...
```

These are generated from the running app (via the same export logic) and are
byte-for-byte what the UI would export; the user can regenerate them from the UI.

### `tdcs_load_data.m`

Parses the matrix format (skips the `Data,` line and blank line, reads the
`Group` row, the `# Days Reach` + subject-header row, then the day rows),
reshapes both matrices to long, and joins on (subject, day) to produce one table
with `subject, group, day, success, total`. Drops blank cells; applies day ≥ 0.
Returns the full long table (all 5 groups, Box-A included).

## Scenarios (`switch/case`, 6 self-contained cases)

`tdcs_glm(scenario)` dispatches on the scenario name; each case runs end-to-end
and can be run alone. Cases:

| case | merge | window |
|---|---|---|
| `unmerged_full` | 5 groups (classify Box-A & Right) | days 0–26 |
| `unmerged_d0_10` | 5 groups | days 0–10 |
| `mergeA2_full` | Box-A→A2, Right→B2 | 0–26 |
| `mergeA2_d0_10` | Box-A→A2, Right→B2 | 0–10 |
| `mergeB2_full` | Box-A→B2, Right→B2 | 0–26 |
| `mergeB2_d0_10` | Box-A→B2, Right→B2 | 0–10 |

Merge maps: `mergeA2 = {Electrode-Box-A→Electrode-Box-A2, Right-Electrode→Electrode-Box-B2}`;
`mergeB2 = {Electrode-Box-A→Electrode-Box-B2, Right-Electrode→Electrode-Box-B2}`.
Each case saves its derived scenario table to `derived/<scenario>.csv`.

`run_all.m` loops all six; `run_tests.m` runs the test suite.

## Printed output per scenario

To console and `results/<scenario>.txt`:

1. **Descriptives** — per group: n_subjects, n_sessions, mean success count, pooled rate.
2. **Raw GLM** — the literal `fitglme` fixed-effects table (Estimate, SE, tStat, pValue, CI) for count and rate models, plus the learning-rate joint test statistic/p.
3. **Interpretation** — plain language mirroring the Python verdicts: H2 (B2 vs A2) as IRR/OR + one-sided p + SUPPORTED/not; per-animal p-values; classification (unmerged only); and the standing caveats (n=3–4/group, single-subject fragility, count vs rate).

## Files

```
analysis/matlab/
  raw/raw_success.csv, raw/raw_total.csv        # generated inputs (website format)
  tdcs_load_data.m                               # parse + reshape + join → long table
  tdcs_scenario_data.m                           # apply merge map + day window; save derived
  tdcs_models.m                                  # fit GLMMs, per-animal tests, classification, contrasts
  tdcs_report.m                                  # format descriptives + raw GLM + interpretation
  tdcs_glm.m                                     # switch/case entry over the 6 scenarios
  run_all.m, run_tests.m
  derived/  results/                             # outputs (created at runtime)
  tests/
    tLoadData.m        # join correctness (verified cells), day filter, zero-attempt drop
    tScenarioData.m    # per-scenario groups/subject counts, window caps
    tModels.m          # golden-value/direction checks vs the Python numbers (loose tolerance)
```

## Testing

`matlab.unittest`, run headless via `matlab -batch "run_tests"`:

- **Data:** `tdcs_load_data` join correct — verified cells (e.g. Vu-vuong day0 success=18, total=61; Banh-mi-1 day0 success=13) and per-group subject counts; day≥0 and zero-attempt handling.
- **Scenario derivation:** each scenario yields the right groups/subjects (`mergeB2` → B2=5 subjects, A2=3; `mergeA2` → 4/4/4; `d0_10` caps at day 10) and saves `derived/<scenario>.csv`.
- **Model sanity / golden values:** GLM results land near the Python numbers within a loose tolerance and match direction — e.g. `mergeB2_full` rate H2 odds ≈ 1.4–1.6 with B2>A2; anchor H2 supported on rate; `unmerged` classification labels. GLMM ≠ GEE exactly, so magnitude tolerances are wide but sign/ordering checks are strict.

Executed once the license is active; written but unrun until then (flagged in the report).

## Out of scope (YAGNI)

- Re-implementing GEE / cluster-robust sandwich SEs (using native `fitglme` instead).
- The learning-curve plots (the Python `.png`s remain; not re-created in MATLAB unless asked).
- Changing the Python analysis (it stays as the reference).
- Bayesian mixed model (the Python MAP sensitivity has no direct `fitglme` analog and is dropped; the GLMM *is* the random-intercept model).