Build the application

The path's capstone-shaped lesson. An application is source → gate → feature or decoder → loop → presenter, with the library owning the first four and the protocol file naming every decision in them; it is packaged as a pip project that depends on the library with a replay entry point, so it runs and its CI runs where no headset is; its budget carries a measured row and the loopback probe is within one block of the arithmetic; its gate suspends feedback across the planted artifact windows; its four sham modes are sealed into their logs; its pre-registration is a hash a commit precedes; its learning outcome is the valid test and its report is the six CRED-nf items; and a run on a headset is documented in a record with every value measured, and no efficacy claim.

~90 min Notebook: nb-7-16-application

Prerequisites: L7.15 · A first BCI on four channels, L7.14 · A protocol that can fail: sham, blinding, pre-registration, the valid test

14 claims on this page are unverified. TODO(confirm) marks a specific statement the author has not yet checked against a primary source. Everything else on this page has been reviewed. Treat a marked claim as provisional and go to the cited source rather than quoting the sentence.

What you will be able to do

  • Structure an application as source → gate → feature or decoder → loop → presenter, with a measured processing row
  • Package it as a pip project that depends on the library, with a replay entry point that runs without a headset
  • Run the software loopback probe and report the budget with its measured and decision sections
  • Document a hardware session with a sealed sham mode, a session log, a blinding check and no efficacy claim

Why this matters

Every lesson of this path built one piece: a stream you can trust, a gate that runs first, a feedback signal stated in full, a protocol that can fail, a decoder frozen into arrays. This one assembles them into a thing a person can run, and holds it to a rubric that a continuous-integration job can judge — because the difference between an application and a demo is that the application can be checked by someone who was not there. The rubric is deliberately shaped so that most of it is judged from files the library writes: session.json, events.jsonl, the resolved protocol, the frozen decoder. What cannot be judged from files — that a person was blind, that a commit preceded the data — the rubric says so, and the run record carries it as a statement rather than a tick.

Concepts

The shape: source → gate → feature or decoder → loop → presenter

The library owns the first four; the protocol file names every decision in them; the application is the presenter and whatever it drives. alpha_bar.py is the smallest one — a protocol, a source and a show function that prints a bar — and eo_ec_switch.py is the smallest decoder application, a lamp that closing the eyes turns on. Both are run in the notebook as programs, the way a learner runs them: once on the site’s shipped four-channel asset (60 s of ds-eegbci S001 eyes closed on O1/O2/T7/T8, the occipitotemporal-4 replica) and once on the synthetic stream with the same channel names. What the rubric reads is not the screen but what the run wrote: status, the files, the budget’s rows with the processing row replaced by what was measured (p50 0.30 ms on the machine that ran the notebook, against a stated 10 ms), the sealed sham token, the protocol hash, the block and gate counts. On the replica the gate closed on 27 of 300 blocks, a fraction of 0.090, through the same gate L7.12 ran over all twelve subjects.

What this lesson connects to

No device is named, and no number from one appears. The replica is ds-eegbci cut to the occipitotemporal-4 geometry; the synthetic stream is the library’s. The same protocol on the synthetic stream reports a budget of 385 ms rather than 610 ms — the synthetic source runs at 256 Hz and the replica at 160 Hz, so the FIR’s 64 samples and the 32-sample block are worth fewer milliseconds. The budget is a fact about a rate, and a protocol carried to a headset carries its rows to that headset’s rate.

Packaging: a pip project that depends on the library

The rubric’s first line is installs into a clean venv from the repository, which is a claim only a clean environment can test — the same test C7 puts on a reproduction. The project is small: a pyproject.toml that depends on eegloop, one module with the presenter, and a console entry point whose default source is replay, so the application runs, and its tests run, on a machine that has never seen a headset. The driver is an optional extra installed only where a headset is. The notebook prints the shape and the clean-venv sequence; the library’s own CI does the same for its examples in loop/tests/test_examples.py, which runs alpha_bar.py, eo_ec_switch.py and blink_switch.py as programs on the asset and on the synthetic stream and asserts the rubric’s file-checkable items.

The budget, measured; the probe, within one block

The chain declares its exact rows — the FIR’s (N − 1)/2 samples, the block period, a stated processing time — and the runner replaces the processing row with what it measured. Then the loopback probe times the whole chain from a burst to the value that shows it, at every alignment of the block grid: on the replica’s chain the value delay measures 503.1 ms against 503.1 ms expected, and the rubric’s criterion is that the two be within one block (200 ms) of each other. That criterion is loose on purpose: an unsmoothed chain meets it to the sample, and a smoothed one — L7.13’s 616 ms against 510 — meets it too while making the smoother’s cost visible. What fails it is a chain with a step nobody declared.

The gate over the planted artifact windows

The rubric asks that the gate closed across at least nine in ten of the planted artifact windows. The synthetic blinks scenario plants blinks at known times; the alpha protocol runs over it; every closure is in events.jsonl with its labels; a planted blink counts as covered when a closure falls between 0.2 s before it and 2 s after. The notebook finds 4 of 4 covered. This is the acceptance test of L7.12 turned into a line a CI job can fail.

Four sham modes, sealed; the blinding check

All four modes run on the asset and each log records its sealed mode — a token only the protocol’s seed unblinds, so the participant can be blind and so can the file until the analysis is done. The four tokens differ; each unblinds to its mode with the seed; a wrong seed unblinds nothing. The blinding check is a question asked before unblinding — which condition did the participant think it was? — and its answer goes into the run record whatever it is. A single person running their own sessions is neither blind as experimenter nor as analyst, and the report keeps saying so.

Pre-registration as a hash a commit can precede

session.json carries the hash of the resolved protocol, and the notebook shows that recomputing it from the file gives the same twelve characters while changing one threshold gives different ones. A pre-registration is that protocol plus the outcome, the test, the control condition and the blinding check, committed before the first session. Whether it was committed before is a fact about the repository — git log on prereg.yaml against the started_at of the first log — which is why crednf_report marks the item not satisfiable alone from a file and satisfied only when told the commit precedes the data.

The valid test, and the report

Twelve subjects’ eyes-closed minutes through the protocol, one session each: learning_test over the sessions gives a mean change of +0.040 with p = 0.324 (exact, 4096 sign patterns), which is the correct null on recordings in which nobody can learn; naive_trend on the same sessions flags 8 of 12 as significant, and is printed beside it labelled valid: False as what not to report. crednf_report from the yoked session’s log alone marks three items satisfied and three not satisfiable alone; with the pre-registration committed and the sessions tested, five of six are satisfied, and the sixth — blinding of the experimenter and the analyst — is about people, not files.

The EO/EC switch on the replica

eo_ec_switch.py on the synthetic stream scores its planted answer, 7 of 7, which says the loop is wired correctly and nothing else. On the replica — each subject’s eyes-open and eyes-closed minutes cut into alternating 6-s periods with a cue at each boundary, the cues on the sample clock — 9 of 12 subjects calibrated and their decoders were right on 44 of 54 scored periods, 0.815 against a chance band of 0.37–0.63. Read the gated-blocks column of the table before the accuracy: three subjects never decided because the gate held their stream unusable through most of the calibration (one is the popping subject L7.12 found), fewer than five epochs per class arrived, and no decoder was frozen. The loop refused rather than guessed, and that is the gate running first doing exactly what L7.12 asked of it. The decoder’s delay is its 3-s window, stated as such, plus the causal filter’s 64 samples; the dwell before a decision is a choice.

A hardware run, documented

Nothing from a headset appears on a page, and a single self-run supports no efficacy claim whatever it shows. What a run does produce is a record, and the rubric’s last item is that the record exists with every value measured from the session directory or the eegloop check report — never typed from a product page. The template is in loop/HARDWARE.md and the notebook prints it beside the same rows from the replica session; every value in it is TODO(confirm) until a run fills it:

device class            TODO(confirm)   frontotemporal-4 | occipitotemporal-4 | …
board key               TODO(confirm)   a key of `eegloop devices`
driver / firmware       TODO(confirm)   session.json → versions
rate, nominal           TODO(confirm)   Hz, from the board table
rate, effective         TODO(confirm)   Hz, `eegloop check` → rate over the timestamps' span
drops                   TODO(confirm)   samples lost over the session (events.jsonl kind=gap; the package counter)
gate fraction           TODO(confirm)   n_gated / n_blocks from session.json → stats
processing, measured    TODO(confirm)   p50 / p95 ms from session.json → budget (the row marked measured)
loopback probe          TODO(confirm)   ms, software probe on this chain (required); electrical loopback optional
sealed mode             TODO(confirm)   the token from session.json, unblinded with the protocol's seed after the session
blinding check          TODO(confirm)   what the participant said the condition was, before unblinding
protocol hash           TODO(confirm)   session.json → protocol_hash, and the commit that carries prereg.yaml
claim                   a single self-run supports no efficacy claim

An electrical loopback into the electrodes — a known signal injected at the input and timed to the display — would measure what the software probe cannot, the headset’s own acquisition delay; it is optional and its method is TODO(confirm) per device. The software probe is the required measurement.

The data behind this lesson

ds-eegbci (ODC-By 1.0): S001–S012, R01 and R02 on O1, O2, T7, T8; the shipped asset is S001 R02, 60 s, demeaned. The library’s synthetic alpha-schedule, blinks and eo-ec scenarios, seed 20260920. No headset produced anything on this page.

Explore

This lesson has no widget; the application is the artefact. w-latency-budget in feedback mode (L7.13) is where the budget and the probe can be turned by hand.

Practice

Build the application: the two example applications run as programs on the shipped four-channel asset and the synthetic stream, the session.json fields the rubric reads, a pip project shape with a replay entry point, the budget with its measured row and the loopback probe within one block of it, the gate over planted artifact windows, four sham modes sealed and unblinded, the CRED-nf report with the valid learning test beside the invalid trend, pre-registration as a hash a commit can precede, the EO/EC switch on the planted answer and on the occipitotemporal replica, and the hardware-run record with every value TODO(confirm) nb-7-16-application

Level 7 ~4 min
notebooks/L7/nb-7-16-application.ipynb

Downloads from ds-eegbci.

Open in Colab Download Read it here

Exercises

Exercise ex-7-16-gate-fraction

Numeric

The notebook runs the alpha protocol over the shipped four-channel asset (60 s of ds-eegbci S001 eyes closed on O1/O2/T7/T8) and reads the gate's counts from session.json. What fraction of the 300 blocks did the gate close? Answer as a fraction between 0 and 1, to two decimals.

fraction

Accepted within ±0.01 fraction.

Exercise ex-7-16-eo-ec-pooled

Numeric

The notebook runs the EO/EC switch's protocol on the occipitotemporal replica: twelve ds-eegbci subjects, each subject's eyes-open and eyes-closed minutes cut into alternating 6-s periods with a cue at each boundary, calibrate on the first 76 s, apply to the rest. Pooled over the subjects whose decoder was fitted, what fraction of the scored periods did the frozen decoder get right? Answer to two decimals.

fraction

Accepted within ±0.03 fraction.

Exercise ex-7-16-rubric

Checklist (self-graded)

Your application is in a repository with a CI job. Tick each rubric item that the job can judge from the files the library writes, and leave unticked the ones that need a person, a commit or a headset.

Checklist

0 / 7 checked. Self-graded.

Pitfalls

Pitfall

A vendor-derived column is not the signal

Symptom
A "focus", "calm" or band-power column from the headset's export is used as the feedback signal or as a feature, and nobody can say how it was computed.
Cause

A consumer export is a vendor product, not a raw file with metadata attached. Most of its columns are computed on the device or in its app from the electrodes, through a pipeline whose parameters are proprietary, may change with a firmware update, and may already include a notch, a smoothing and a per-user normalisation that nobody wrote down. A quality score is an impedance-like indicator on the…

Detect
  • Can you write the computation down — band, window, filter, reference, normalisation, update rate? If not, it is a vendor column. - Is the column written on every row, or only when the firmware updates it? A periodic report padded with blanks is not a per-sample signal. - Does its scale have units? A number from 0 to 100 or 0 to 4 with no unit is a score, not a power. - Compute the quantity you…
Fix
  • Compute the feedback signal, the features and the outcome from the raw electrode columns, with the band, the window, the filter and the reference stated — L7.13’s SignalSpec is the shape of that statement — and log the parameters with the session. - Keep the vendor columns as what they are: a description of the device’s own view, useful for reading and never used as truth. Show them next to you…

Full entry with example →

Pitfall

Dropped samples and clock drift

Symptom
Events drift relative to the data across the recording.
Cause

Two mechanisms, often together. Dropped samples: the acquisition buffer overflows (a busy computer, a slow disk, a wireless link) and a block of samples is lost without a gap being written; every later sample is now earlier in the file than it was in time, by the length of the dropped block, and events timestamped by a separate clock no longer match. Clock drift: two devices with their own oscill…

Detect
  • Compare the sample count with the sampling rate times the recorded duration (from an independent clock: the file’s start and end timestamps, or the stimulus log). - Plot the interval between successive periodic events (a fixed-rate stimulus, a clock marker) across the recording: dropped samples show as a jump, drift as a slope. - Look for discontinuities in the data at the moment of a drop: an…
Fix
  • Prevent it at acquisition: hardware triggers on the amplifier’s own clock, adequate buffers, a wired link, and a periodic hardware sync pulse recorded in both streams. - For drift with a known reference (a sync pulse or periodic marker), resample or linearly rescale the event times to the EEG clock; LSL-style recordings store the offsets needed to do it. - For dropped samples that can be locate…

Full entry with example →

Terms used here

Every term this lesson leans on, with the one-line meaning. Follow a term for its full entry.

Sham feedback
Feedback that looks and moves like the real thing but carries no information about the participant's target signal — the control a neurofeedback claim needs.
Pre-registration
The outcome, test and control condition written down and committed before any data exist, so the analysis cannot be chosen after seeing the result.
Chance band
The interval of accuracies a classifier with no information reaches by luck in n trials; an accuracy is evidence only when it clears it.