# Pre-Data Freeze Checklist

> Generated from repository source files. Do not edit this page directly; edit the source file listed below and rerun `vp run docs:generate`.

> Source: `experiments/pre-data-freeze-checklist.md`

## Pre-Data Freeze Checklist

Status: `pre-data freeze draft`

This checklist must be completed before any Exp1-Exp4 data-collection session is treated as evidence for `SAH-BRI-Grasp`. It records what must be fixed before data are collected; it does not report results.

## Freeze Rule

A session is analysis-ready only if these items are recorded before the first trial:

* protocol version;
* software commit or release identifier;
* participant/session ID policy;
* hardware inventory;
* runtime interface version;
* state-machine version;
* middleware and message serialization;
* clock synchronization rule;
* runtime log storage rule;
* EEG montage and acquisition settings;
* visual stimulus and display settings;
* decoder/model settings;
* trial counts and randomization;
* advancement, safety, and exclusion thresholds;
* statistical analysis plan;
* calibration records for any physical robot session.

## Administrative Items

| Item | Status | Record Location |
| --- | --- | --- |
| protocol version naming | needs confirmation | `experiments/templates/session-record.md` |
| software commit capture | needs confirmation | `experiments/templates/session-record.md` |
| runtime interface version | needs confirmation | `system/runtime-interfaces.md` |
| state-machine version | needs confirmation | `system/state-machine.md` |
| participant ID scheme | needs confirmation | ethics/local study record |
| session ID scheme | needs confirmation | `experiments/templates/session-record.md` |
| data storage path | needs confirmation | local lab record |
| consent/ethics status | needs confirmation | local ethics record |

## Runtime And Logging Settings

| Item | Status | Notes |
| --- | --- | --- |
| middleware choice | draft frozen | canonical evidence log is file-first JSONL; ROS/local process bus may mirror records |
| message serialization | draft frozen | newline-delimited JSON records using `system/runtime-interfaces.md` |
| clock synchronization | partially frozen | `monotonic_ns` is primary timebase; multi-host sync method and error bound still need hardware confirmation |
| runtime log path | draft frozen | `data/runtime/<session_id>/events.jsonl` |
| state-transition log path | draft frozen | state transitions are records in the same canonical event log |
| replay mode | draft frozen | replay consumes original JSONL records and writes a separate replay log without rewriting original IDs |

## Participant And Trial Design

| Item | Status | Notes |
| --- | --- | --- |
| inclusion criteria | needs confirmation | define before recruitment |
| exclusion criteria | needs confirmation | include vision, fatigue, EEG quality, and safety constraints |
| participant count target | needs confirmation | do not infer from literature sample sizes |
| trial count per condition | needs confirmation | must be frozen per experiment |
| training/pilot/test split | draft rule frozen, values need confirmation | keep held-out test data isolated from tuning |
| randomization/blocking plan | draft rule frozen, values need confirmation | record order and seed if generated |

## EEG And BCI Settings

| Item | Status | Notes |
| --- | --- | --- |
| EEG device | needs confirmation | manufacturer/model required |
| sampling rate | needs confirmation | record raw and processed rates |
| reference and ground | needs confirmation | required for reproducibility |
| electrode montage | needs confirmation | exact channels for 16/12/8/6/3 sets |
| impedance/contact rule | needs confirmation | device-specific |
| filters and preprocessing | needs confirmation | high-pass, low-pass, notch, epoching |
| SSVEP decoder | needs confirmation | CCA/FBCCA/TRCA/other |
| MI decoder | needs confirmation | CSP/FBCSP/EEGNet/other |
| decoder training split | needs confirmation | no test-set tuning |
| confidence threshold | needs confirmation | freeze before online trials |

## ITR Definition

Candidate formula, supported by `SSVEP-005` and consistent with `BCI-001` metric framing:

```text
ITR = [log2(M) + P log2(P) + (1 - P) log2((1 - P) / (M - 1))] * 60 / T
```

Where:

| Symbol | Definition | Freeze Requirement |
| --- | --- | --- |
| `M` | number of selectable classes | record per condition |
| `P` | target-identification accuracy | compute from held-out or online trials |
| `T` | average seconds per accepted selection | report raw-window and practical-selection variants as defined in `experiments/analysis-plan.md` |

Report both raw-window ITR and practical-selection ITR if Exp1 uses different EEG-window and attention-shift assumptions.

## Visual Scene And Stimulus Settings

| Item | Status | Notes |
| --- | --- | --- |
| display model and refresh rate | needs confirmation | required for SSVEP timing |
| display size/resolution/viewing distance | needs confirmation | required for visual angle |
| SSVEP frequencies/phases | needs confirmation | avoid harmonic conflicts |
| flicker rendering method | needs confirmation | square/sinusoidal/coded modulation |
| candidate box size definition | needs confirmation | pixels and visual angle |
| candidate spacing definition | needs confirmation | pixels and visual angle |
| candidate freeze duration | needs confirmation | required before selection trials |
| YOLO detector version/model | needs confirmation | record model, weights, input size |
| candidate tracking rule | needs confirmation | track ID, loss, and jitter handling |

## Robot And Calibration Settings

| Item | Status | Notes |
| --- | --- | --- |
| robot model and controller | needs confirmation | required before Exp3 physical trials |
| camera/RGB-D model | needs confirmation | record intrinsics and frame rate |
| gripper/end-effector | needs confirmation | record grasp constraints |
| robot workcell layout | needs confirmation | include table, workspace, object placement |
| grasp-pose method | needs confirmation | YOLO alone is not grasp execution |
| hand-eye calibration record | template frozen, values need confirmation | required for physical trials |
| calibration target | template frozen, values need confirmation | target type, size, coordinate convention |
| solver and transform convention | template frozen, values need confirmation | transform names fixed in `exp03-closed-loop-grasping/hand-eye-calibration.md` |
| dry-run validation | needs confirmation | non-contact target checks before grasping |

## Safety And Advancement Thresholds

| Threshold | Status | Applies To |
| --- | --- | --- |
| minimum SSVEP selection accuracy | needs confirmation | Exp1, Exp3 |
| maximum target-lost rate | needs confirmation | Exp1, Exp3 |
| maximum candidate jitter | needs confirmation | Exp1, Exp3 |
| maximum MI false activation | needs confirmation | Exp2, Exp3 |
| minimum mode-switch success | needs confirmation | Exp2, Exp3 |
| calibration acceptance | template frozen, values need confirmation | Exp3 |
| maximum planning failure rate | needs confirmation | Exp3 |
| maximum safety-blocked command rate | needs confirmation | Exp3 |
| low-channel retention threshold | needs confirmation | Exp4 |

## Output Files To Fill During Each Session

Use:

* `experiments/templates/session-record.md`;
* `experiments/templates/threshold-freeze-record.md`;
* `experiments/templates/trial-log-schema.md`;
* `experiments/hardware-inventory.md`.

Do not promote a session to evidence until these records exist and match the protocol version.