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 · Applied Electives ~4 min Used in L7.16 · Build the application

Downloads from ds-eegbci when you run it.

Download the notebook (.ipynb) Outputs below are the ones stored when it was executed — you do not need to run anything to read it.

nb-7-16-application · Build the application (L7.16)

Lesson L7.16 · Level 7 · Status draft — for expert review; uncertain points carry TODO(confirm).

The last lesson of the consumer-headset path is capstone-shaped: it asks for an application, and this notebook is the check-list run against one — the two example applications the library ships, run the way a learner runs them, with every rubric item judged from what they write rather than from what they print.

  1. The shape — source → gate → feature or decoder → loop → presenter — as alpha_bar.py on the shipped four-channel asset and on the synthetic stream, and the session.json fields the rubric reads.
  2. Packaging: a pip project that depends on the library, with a replay entry point, and the clean-venv check.
  3. The budget, exact rows beside the measured row, and the loopback probe within one block of the arithmetic.
  4. The gate suspending feedback across the planted artifact windows.
  5. Four sham modes, each sealed into its log; the blinding check; the CRED-nf report; the valid learning test beside the invalid trend.
  6. Pre-registration as a hash a commit can precede.
  7. The EO/EC switch — eo_ec_switch.py on the planted answer and on the occipitotemporal replica.
  8. A hardware run, documented: the record template with every value TODO(confirm).

Every number comes from replayed public data or the synthetic stream; no headset produced anything here.

In [1]:
# Setup: dependencies, the shared helpers, the course library, non-interactive plotting, a quiet downloader.
import importlib.util
import json
import logging
import subprocess
import sys
import tempfile
import time
import warnings
from pathlib import Path

_needed = ("mne", "scipy", "matplotlib", "pandas", "pooch", "sklearn", "pyriemann", "yaml")
_missing = [p for p in _needed if importlib.util.find_spec(p) is None]
if _missing:
    _req = next((d / "requirements.txt" for d in (Path.cwd(), *Path.cwd().parents)
                 if (d / "requirements.txt").exists()), None)
    _cmd = [sys.executable, "-m", "pip", "install", "-q"]
    _cmd += ["-r", str(_req)] if _req else ["mne==1.10.2", "pooch>=1.8", "scikit-learn>=1.5", "pyriemann>=0.8", "PyYAML>=6.0"]
    subprocess.check_call(_cmd)

_shared = next((d / "_shared" for d in (Path.cwd(), *Path.cwd().parents)
                if (d / "_shared" / "helpers_l7.py").exists()), None)
if _shared is None:
    # No checkout around this notebook -- a downloaded .ipynb, or a fresh Colab kernel. Fetch the shared
    # helpers the site publishes beside it. With a checkout present the walk-up above wins and nothing
    # is downloaded; the modules land in ./_shared/ and are reused on every later run.
    import json as _json
    import urllib.request as _urllib
    _base = "https://eeg.neurokinetikz.com/notebooks/_shared/"
    _shared = Path.cwd() / "_shared"
    _shared.mkdir(exist_ok=True)
    for _name in _json.loads(_urllib.urlopen(_base + "index.json").read())["modules"]:
        if not (_shared / _name).exists():
            _urllib.urlretrieve(_base + _name, _shared / _name)
sys.path.insert(0, str(_shared))
import helpers_l7 as L7
_loop = L7.import_eegloop()   # loop/eegloop on sys.path from any directory of a checkout; returns loop/
CONFIGS, EXAMPLES = _loop / "configs", _loop / "examples"

import helpers
import helpers_l7 as L7
import eegloop
from eegloop import StreamInfo, latency_budget_for, measure_loop_delay, print_budget
from eegloop.analysis import crednf_report, learning_test, naive_trend
from eegloop.feedback import CREDNF_ITEMS, ShamPolicy, SignalSpec, build_chain
from eegloop.present import CallbackPresenter
from eegloop.session import SessionReader, load_protocol, resolved, run_protocol
from eegloop.sources import ReplaySource, SyntheticSource
from eegloop.versions import config_hash

import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
import mne

mne.set_log_level("WARNING")
logging.getLogger("pooch").setLevel(logging.WARNING)
warnings.filterwarnings("ignore", category=RuntimeWarning)
warnings.filterwarnings("ignore", category=FutureWarning)
plt.rcParams["figure.dpi"] = 72

SOURCE = "replay"
LOCAL_RECORDING = None      # a path to a recording of your own: a second pass on it, never shipped

DATASET = "ds-eegbci"
OC4 = ["O1", "O2", "T7", "T8"]
SUBJECTS = list(range(1, 13))
SEED = 20260920
FS = 160.0
WORK = Path(tempfile.mkdtemp(prefix="nb-7-16-"))   # every session this notebook writes lives here and is deleted at the end
_edf_before = set(Path(mne.get_config("MNE_DATA", str(Path.home() / "mne_data"))).rglob("*.edf"))

def run_example(script, *args):
    # an example is a program: run it the way a learner does, and keep only what it says at the end
    r = subprocess.run([sys.executable, str(EXAMPLES / script), *map(str, args)], cwd=str(_loop), capture_output=True, text=True, timeout=600)
    tail = [ln for ln in r.stdout.replace("\r", "\n").splitlines() if ln.strip()][-3:]
    if r.returncode != 0:
        raise RuntimeError(f"{script} exited {r.returncode}: {r.stderr[-800:]}")
    return tail

def rubric_fields(session_dir):
    # the fields the rubric reads, from session.json alone
    s = SessionReader(session_dir).session
    rows = [(r["row"], f"{r['ms']:.0f} ms", r["detail"]) for r in s["budget"]["rows"]]
    st = s["stats"]
    return {"status": s["status"], "files": sorted(s["files"].values()) + [f for f in ("decoder.npz",) if (Path(session_dir) / f).exists()],
            "budget rows": rows, "budget total": f"{s['budget']['total_ms']:.0f} ms",
            "sealed_sham": s["sealed_sham"], "protocol_hash": s["protocol_hash"],
            "n_blocks": st["n_blocks"], "n_gated": st["n_gated"], "processing p50": f"{st['processing_ms']['p50']:.2f} ms",
            "versions": sorted(s["versions"])[:6]}

print(f"eegloop {eegloop.__version__} · mne {mne.__version__}")
eegloop 0.1.0 · mne 1.10.2

1 · The shape of an application, and what it writes

Source → gate → feature or decoder → loop → presenter. The library owns the first four and 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. It is run here twice as a program — 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 on the synthetic stream with the same channel names — and the rubric reads session.json, not the screen.

In [2]:
oc4_cfg = CONFIGS / "alpha-up-oc4-replay.yaml"
print("replica:", *run_example("alpha_bar.py", "--protocol", oc4_cfg, "--out", WORK / "oc4"), sep="\n  ")
p_oc4 = load_protocol(oc4_cfg)
syn = SyntheticSource("alpha-schedule", seed=SEED, ch_names=OC4, duration_s=p_oc4.total_duration_s + 1.0, pace="fast")
shown_syn = []
res_syn = run_protocol(p_oc4, source=syn, presenter=CallbackPresenter(lambda shown, **kw: shown_syn.append(shown)), out_dir=WORK / "syn")
print(f"\nsynthetic (the same protocol, seed {SEED}, channels renamed to the replica's): session {res_syn.status}, "
      f"{res_syn.stats['n_blocks']} blocks, {res_syn.stats['n_gated']} gated, {len(shown_syn)} presenter updates")
for name in ("oc4", "syn"):
    print(f"\n{name}/session.json — the fields the rubric reads")
    for k, v in rubric_fields(WORK / name).items():
        print(f"  {k:14s} {v}")
r_oc4 = SessionReader(WORK / "oc4")
gate_frac = r_oc4.session["stats"]["n_gated"] / r_oc4.session["stats"]["n_blocks"]
print(f"\nthe replica's gate fraction: {r_oc4.session['stats']['n_gated']} of {r_oc4.session['stats']['n_blocks']} blocks = {gate_frac:.3f} "
      f"(the gate L7.12 ran over all twelve subjects; its median unusable fraction was 0.053, with one subject near 1)")
replica:
    60.0 s  signal unusable — feedback held                             
  session ok: 300 blocks, 27 gated, budget 610.0 ms declared, processing measured p50 0.31 ms
  written to oc4/ (session.json, events.jsonl, signal.npz, protocol-resolved.json)

synthetic (the same protocol, seed 20260920, channels renamed to the replica's): session ok, 480 blocks, 7 gated, 480 presenter updates

oc4/session.json — the fields the rubric reads
  status         ok
  files          ['events.jsonl', 'protocol-resolved.json', 'session.json', 'signal.npz']
  budget rows    [('filter', '400 ms', 'fir 64 + rms 0 samples'), ('buffer', '200 ms', '32 samples, block-period'), ('processing', '10 ms', 'measured on this machine: p50 0.31 ms, p95 0.34 ms (stated 10)')]
  budget total   610 ms
  sealed_sham    eadca24373098fdc
  protocol_hash  6f4b07a591c7
  n_blocks       300
  n_gated        27
  processing p50 0.31 ms
  versions       ['PyYAML', 'brainflow', 'mne', 'mne-lsl', 'numpy', 'platform']

syn/session.json — the fields the rubric reads
  status         ok
  files          ['events.jsonl', 'protocol-resolved.json', 'session.json', 'signal.npz']
  budget rows    [('filter', '250 ms', 'fir 64 + rms 0 samples'), ('buffer', '125 ms', '32 samples, block-period'), ('processing', '10 ms', 'measured on this machine: p50 0.30 ms, p95 0.34 ms (stated 10)')]
  budget total   385 ms
  sealed_sham    eadca24373098fdc
  protocol_hash  6f4b07a591c7
  n_blocks       480
  n_gated        7
  processing p50 0.30 ms
  versions       ['PyYAML', 'brainflow', 'mne', 'mne-lsl', 'numpy', 'platform']

the replica's gate fraction: 27 of 300 blocks = 0.090 (the gate L7.12 ran over all twelve subjects; its median unusable fraction was 0.053, with one subject near 1)
In [3]:
fig, axes = plt.subplots(2, 1, figsize=(12, 5), sharex=True)
for ax, name, title in zip(axes, ("oc4", "syn"), ("shipped asset (S001 eyes closed, O1+O2 RMS 8–12 Hz)", f"synthetic alpha-schedule, seed {SEED}")):
    r = SessionReader(WORK / name)
    t, v = r.signal["times_s"], r.signal["values"]
    ok, phase = r.signal["gate_ok"], r.signal["phase"]
    ax.step(t, v, where="post", lw=0.9, color="C0", label="feedback value (raw, per block)")
    ax.fill_between(t, 0, np.nanmax(v) * 1.05, where=~ok, step="post", color="C3", alpha=0.18, label="gate closed / warming up")
    ax.axvline(t[np.argmax(phase == "train")], color="k", ls="--", lw=0.8, label="calibration → training")
    ax.set(ylabel="µV RMS", title=title); ax.legend(fontsize=8, loc="upper right")
axes[-1].set(xlabel="Time (s)"); plt.tight_layout(); plt.show()
Figure 1 of notebook nb-7-16-application, an output plot. The text around it states what it shows and the units of every axis.

2 · Packaging: a pip project that depends on the library

The rubric's first line is installs into a clean venv from the repository, and that is a claim only a clean environment can test. The shape of 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 CI runs, on a machine that has never seen a headset. Until the repository is public the dependency is a path (loop/); at release it becomes a version.

In [4]:
PYPROJECT = '''
[project]
name = "alpha-lamp"                        # your application
version = "0.1.0"
requires-python = ">=3.10"
dependencies = ["eegloop"]                 # from the course repository: pip install -e path/to/loop, until it is on an index
[project.optional-dependencies]
device = ["eegloop[brainflow]"]           # the headset driver, only where a headset is
decode = ["eegloop[decode]"]              # fitting a decoder; a frozen one replays without it
[project.scripts]
alpha-lamp = "alpha_lamp.cli:main"         # `alpha-lamp --source replay` is the default; `--source brainflow:<key>` is the exception
'''
CLEAN_VENV = '''
python -m venv .venv && . .venv/bin/activate
pip install -e path/to/eeg/loop            # the library, from the repository
pip install -e .                           # your application
alpha-lamp --source replay --out sessions/replay-check      # must complete and write session.json + events.jsonl
alpha-lamp --source synthetic --seed 20260920 --out sessions/synthetic-check
python -m pytest                           # your tests: the two runs above, and what section 3–6 check
'''
print("pyproject.toml, the shape:"); print(PYPROJECT)
print("the clean-venv check, run by hand once and by CI every time:"); print(CLEAN_VENV)
print("the library's own CI does the same for its examples: loop/tests/test_examples.py runs alpha_bar.py, eo_ec_switch.py and blink_switch.py as programs")
pyproject.toml, the shape:

[project]
name = "alpha-lamp"                        # your application
version = "0.1.0"
requires-python = ">=3.10"
dependencies = ["eegloop"]                 # from the course repository: pip install -e path/to/loop, until it is on an index
[project.optional-dependencies]
device = ["eegloop[brainflow]"]           # the headset driver, only where a headset is
decode = ["eegloop[decode]"]              # fitting a decoder; a frozen one replays without it
[project.scripts]
alpha-lamp = "alpha_lamp.cli:main"         # `alpha-lamp --source replay` is the default; `--source brainflow:<key>` is the exception

the clean-venv check, run by hand once and by CI every time:

python -m venv .venv && . .venv/bin/activate
pip install -e path/to/eeg/loop            # the library, from the repository
pip install -e .                           # your application
alpha-lamp --source replay --out sessions/replay-check      # must complete and write session.json + events.jsonl
alpha-lamp --source synthetic --seed 20260920 --out sessions/synthetic-check
python -m pytest                           # your tests: the two runs above, and what section 3–6 check

the library's own CI does the same for its examples: loop/tests/test_examples.py runs alpha_bar.py, eo_ec_switch.py and blink_switch.py as programs

3 · The budget, and the probe within one block of it

The protocol's chain declares its exact rows — the FIR's (N − 1)/2 samples, the block period, the stated processing time — and the runner replaces the processing row with what it measured. The loopback probe then times the whole chain from a burst to the value that shows it, at every alignment of the block grid. The rubric asks that the probe's measured value delay be within one block of the arithmetic, which is the criterion L7.13 used and the one eegloop probe prints.

In [5]:
spec = SignalSpec.from_config(p_oc4.signal)
one = StreamInfo(FS, ("O1",), kind="replay")
budget = latency_budget_for(build_chain(spec, one, p_oc4.block_samples, quality=None, include_smoother=False), fs=FS,
                            block_samples=p_oc4.block_samples, processing_ms=p_oc4.processing_ms, convention=p_oc4.buffer_convention)
print_budget(budget, title="alpha-up-oc4-replay: declared budget (160 Hz)")
measured_rows = r_oc4.session["budget"]["rows"]
print("\nthe session's processing row, as written:", measured_rows[2]["detail"])
probe_spec = spec.replace(channels=(), reference="none", reference_channels=())
factory = lambda: build_chain(probe_spec, one, p_oc4.block_samples, quality=None, include_smoother=False)
probe = measure_loop_delay(factory, fs=FS, block_samples=p_oc4.block_samples, centre_hz=float(sum(spec.band) / 2), smooth_s=spec.smooth_s)
block_ms = p_oc4.block_samples / FS * 1000
print(f"\nloopback probe at {probe['burst_hz']:g} Hz over {probe['alignments']} alignments:")
print(f"  filter delay  measured {probe['filter_ms']:7.2f} ms   expected {probe['expected_filter_ms']:7.2f} ms")
print(f"  value delay   measured {probe['value_ms']:7.2f} ms   expected {probe['expected_value_ms']:7.2f} ms   (range {probe['value_min_ms']:.2f}–{probe['value_max_ms']:.2f} ms over the block grid)")
probe_gap = abs(probe["value_ms"] - probe["expected_value_ms"])
assert probe_gap <= block_ms, probe_gap
print(f"  |measured − expected| = {probe_gap:.2f} ms ≤ one block ({block_ms:.0f} ms): the rubric's criterion, met")
alpha-up-oc4-replay: declared budget (160 Hz)
row          detail                                           samples        ms
--------------------------------------------------------------------------------
filter       fir 64 + rms 0 samples                             64.00    400.00
buffer       32 samples, block-period                           32.00    200.00
processing   stated, not measured                                1.60     10.00
--------------------------------------------------------------------------------
TOTAL        worst case, block-period                           97.60    610.00
             worst case, first-to-last                                   603.75
             mean over block position                                    510.00

loop update rate 5.00 Hz (32 samples at 160 Hz)

the session's processing row, as written: measured on this machine: p50 0.31 ms, p95 0.34 ms (stated 10)

loopback probe at 10 Hz over 32 alignments:
  filter delay  measured  400.00 ms   expected  400.00 ms
  value delay   measured  503.12 ms   expected  503.13 ms   (range 495.58–510.67 ms over the block grid)
  |measured − expected| = 0.00 ms ≤ one block (200 ms): the rubric's criterion, met

4 · The gate suspends feedback across 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, and a planted blink counts as covered when a closure falls between 0.2 s before it and 2 s after (the blink, then the hold).

In [6]:
p_syn = load_protocol(CONFIGS / "alpha-up-synthetic.yaml", {"source.scenario": "blinks"})
res_blinks = run_protocol(p_syn, out_dir=WORK / "blinks")
rb = SessionReader(WORK / "blinks")
closures = [g["t_s"] for g in rb.events("gate")]
onsets = [o for o in SyntheticSource("blinks", seed=p_syn.seed, duration_s=p_syn.total_duration_s + 1.0).truth["blink_onsets_s"] if o > p_syn.quality.window_s]
covered = sum(any(-0.2 <= t - o <= 2.0 for t in closures) for o in onsets)
labels = sorted({lab for g in rb.events("gate") for lab in g["labels"]})
print(f"{len(onsets)} planted blinks after warm-up, {len(closures)} gate closures logged (labels seen: {', '.join(labels)})")
print(f"planted blinks with a closure in [−0.2, +2.0] s: {covered} of {len(onsets)} = {covered / len(onsets):.2f}  (rubric: ≥ 0.90)")
assert covered / len(onsets) >= 0.9
4 planted blinks after warm-up, 32 gate closures logged (labels seen: blink, line-noise, warming-up)
planted blinks with a closure in [−0.2, +2.0] s: 4 of 4 = 1.00  (rubric: ≥ 0.90)

5 · Four sham modes, sealed; the blinding check; the CRED-nf report; the valid test beside the invalid one

The rubric asks that all four modes run and that each log records the sealed mode. The seal is a token only the protocol's seed unblinds — so a participant can be blind, and so can the file until the analysis is done. The blinding check is a question asked before unblinding: which condition did the participant think it was? Its answer goes into the run record, whatever it is. Then the report: crednf_report reads a log and marks each item satisfied, not satisfiable alone, or unsatisfied, with why; and the learning outcome is learning_test over sessions, with naive_trend printed beside it as what not to report.

In [7]:
tokens = {}
for mode in ("veridical", "sham-band", "sham-inverted", "sham-yoked"):
    ov = {"sham.mode": mode}
    if mode == "sham-yoked":
        ov["sham.donor"] = str(WORK / "veridical")
    p = load_protocol(oc4_cfg, ov)
    res = run_protocol(p, out_dir=WORK / mode)
    tokens[mode] = SessionReader(WORK / mode).sealed_sham
    print(f"{mode:14s} session {res.status}: {res.stats['n_blocks']} blocks, {res.stats['n_gated']} gated; sealed token {tokens[mode]}")
assert len(set(tokens.values())) == 4
print("\nunblinding, with the protocol's seed — the step that happens after the analysis, and after the participant's guess is on record:")
for mode, tok in tokens.items():
    print(f"  {tok} → {ShamPolicy.unblind(tok, p_oc4.seed)!r}")
try:
    ShamPolicy.unblind(tokens["sham-yoked"], p_oc4.seed + 1)
except ValueError as e:
    print(f"  with the wrong seed: {e}")
veridical      session ok: 300 blocks, 27 gated; sealed token eadca24373098fdc
sham-band      session ok: 300 blocks, 27 gated; sealed token 4fe15952e7e0874d
sham-inverted  session ok: 300 blocks, 27 gated; sealed token 6aa33c72484f8702
sham-yoked     session ok: 300 blocks, 27 gated; sealed token c595273d526c23a5

unblinding, with the protocol's seed — the step that happens after the analysis, and after the participant's guess is on record:
  eadca24373098fdc → 'veridical'
  4fe15952e7e0874d → 'sham-band'
  6aa33c72484f8702 → 'sham-inverted'
  c595273d526c23a5 → 'sham-yoked'
  with the wrong seed: no sham mode matches this token with this seed
In [8]:
# the valid test over sessions: twelve subjects' eyes-closed minutes through the same protocol, one session each
t0 = time.time()
values = {}
for s in SUBJECTS:
    raw = helpers.load_spine(DATASET, s, [2], verbose=False).pick(OC4)
    x = raw.get_data() * 1e6
    x = (x - x.mean(axis=1, keepdims=True))[:, :int(60 * FS)]
    src = ReplaySource(x, fs=FS, ch_names=OC4, pace="fast", block_samples=32)
    run_protocol(p_oc4, source=src, out_dir=WORK / f"S{s:03d}")
    values[s] = SessionReader(WORK / f"S{s:03d}").feedback[1]
print(f"{len(values)} replayed sessions through alpha-up-oc4-replay ({time.time() - t0:.1f} s)")
lt = learning_test([values[s] for s in SUBJECTS])
naive = [naive_trend(values[s], SessionReader(WORK / f"S{s:03d}").feedback[0]) for s in SUBJECTS]
n_naive = sum(1 for n in naive if n["p"] < 0.05)
print(f"learning_test over {lt['n_sessions']} sessions: mean change {lt['mean_change']:+.3f}, p = {lt['p']:.3f} ({'exact' if lt['exact'] else 'permuted'}), valid = {lt['valid']}")
print(f"naive_trend, per session: {n_naive} of {len(naive)} 'significant' at α = .05 on recordings in which no learning can occur; valid = {naive[0]['valid']}")
ry = SessionReader(WORK / "sham-yoked")
print("\nCRED-nf, from the yoked session's log alone:")
for item in crednf_report(ry.protocol, ry.session):
    print(f"  [{item['status']:22s}] {item['item'][:72]}…")
print("\n…with the pre-registration committed and the sessions tested:")
report = crednf_report(ry.protocol, ry.session, prereg_committed=True, sessions_tested=lt)
for item in report:
    print(f"  [{item['status']:22s}] {item['item'][:72]}…")
n_items = len(report); n_sat = sum(1 for i in report if i["status"] == "satisfied")
assert n_items == len(CREDNF_ITEMS) == 6
print(f"\n{n_items} items listed, {n_sat} satisfied; the sixth — blinding of the experimenter and the analyst — is about people, not files")
12 replayed sessions through alpha-up-oc4-replay (2.3 s)
learning_test over 12 sessions: mean change +0.040, p = 0.324 (exact), valid = True
naive_trend, per session: 8 of 12 'significant' at α = .05 on recordings in which no learning can occur; valid = False

CRED-nf, from the yoked session's log alone:
  [not-satisfiable-alone ] Pre-registration of the primary outcome and the control condition, befor…
  [satisfied             ] A control group or condition (sham feedback, an active alternative task,…
  [not-satisfiable-alone ] Blinding: the participant, and where possible the experimenter and the a…
  [satisfied             ] The feedback signal reported in full — the band, the derivation, the ref…
  [not-satisfiable-alone ] Evidence that the participants learned to change the targeted signal, re…
  [satisfied             ] The trial-level and session-level data made available so the analysis ca…

…with the pre-registration committed and the sessions tested:
  [satisfied             ] Pre-registration of the primary outcome and the control condition, befor…
  [satisfied             ] A control group or condition (sham feedback, an active alternative task,…
  [not-satisfiable-alone ] Blinding: the participant, and where possible the experimenter and the a…
  [satisfied             ] The feedback signal reported in full — the band, the derivation, the ref…
  [satisfied             ] Evidence that the participants learned to change the targeted signal, re…
  [satisfied             ] The trial-level and session-level data made available so the analysis ca…

6 items listed, 5 satisfied; the sixth — blinding of the experimenter and the analyst — is about people, not files

6 · Pre-registration as a hash a commit can precede

The session log carries the hash of the resolved protocol. A pre-registration is that protocol plus the outcome, the test and the control condition, committed to version control before the first session — and whether it was committed before is a fact about the repository, which is why the report will not tick the box from the file alone. The check is two commands, and the record keeps their answers: the commit that added prereg.yaml, and the started_at of the first session log.

In [9]:
h_session = r_oc4.session["protocol_hash"]
h_resolved = config_hash(resolved(p_oc4))
print(f"protocol hash in session.json: {h_session}   recomputed from the protocol file: {h_resolved}   equal: {h_session == h_resolved}")
h_changed = config_hash(resolved(load_protocol(oc4_cfg, {"reward.hi_z": 2.5})))
print(f"the same protocol with one threshold changed: {h_changed} — a different pre-registration")
prereg = {"protocol_hash": h_resolved,
          "outcome": "second-half minus first-half mean of the raw per-block 8–12 Hz RMS at O1+O2, as a fraction of the first half, per session",
          "test": "eegloop.analysis.learning_test, sign-flip across sessions, alternative 'greater', alpha 0.05",
          "control": "sham-yoked, sealed; unblinded after the analysis with the protocol seed",
          "blinding_check": "the participant's guess of the condition, recorded before unblinding"}
print(f"\nprereg.yaml hash: {config_hash(prereg)}")
print("the check (by hand, in the application's repository):")
print("  git log --format='%H %cI' -- prereg.yaml        # the commit that added it, and when")
print("  python -c \"import json; print(json.load(open('sessions/first/session.json'))['started_at'])\"   # must be later")
protocol hash in session.json: 6f4b07a591c7   recomputed from the protocol file: 6f4b07a591c7   equal: True
the same protocol with one threshold changed: 70e003f3a4f5 — a different pre-registration

prereg.yaml hash: dbda24b27d39
the check (by hand, in the application's repository):
  git log --format='%H %cI' -- prereg.yaml        # the commit that added it, and when
  python -c "import json; print(json.load(open('sessions/first/session.json'))['started_at'])"   # must be later

7 · The EO/EC switch: the planted answer, then the replica

eo_ec_switch.py is the calibrate-then-apply loop of L7.15 as an application: the protocol calibrates on cued eyes-closed and eyes-open periods, fits with folds in cue order, freezes the decoder into arrays, applies them, and each decision reaches a lamp function. Run as a program on the synthetic stream, it scores the planted answer — which says the loop is wired correctly and nothing else. Then the same protocol runs on the occipitotemporal replica: each subject's eyes-open and eyes-closed minutes cut into alternating 6-s periods with a cue at each boundary, replayed with the cues on the sample clock. Twelve subjects, up to seven scored periods each; the pooled number is the one that can be judged against a band. Read the gated blocks column first: a subject whose stream the gate holds unusable for most of the minute yields few or no calibration epochs, and a decoder that was never fitted makes no decision — the gate running first is supposed to do that.

In [10]:
print("synthetic:", *run_example("eo_ec_switch.py", "--out", WORK / "eoec-syn"), sep="\n  ")
p_eo = load_protocol(CONFIGS / "eo-ec-synthetic.yaml")
PERIOD, N_PER = 6.0, int(6.0 * FS)
rows, pooled_correct, pooled_n = [], 0, 0
t0 = time.time()
for s in SUBJECTS:
    runs = {}
    for run, label in ((1, "open"), (2, "closed")):
        raw = helpers.load_spine(DATASET, s, [run], verbose=False).pick(OC4)
        x = raw.get_data() * 1e6
        runs[label] = (x - x.mean(axis=1, keepdims=True))[:, :int(60 * FS)]
    segs, cues = [], []
    for k in range(10):
        for label in ("closed", "open"):
            cues.append((len(segs) * PERIOD, label))
            segs.append(runs[label][:, k * N_PER:(k + 1) * N_PER])
    stream = np.concatenate(segs, axis=1)
    src = ReplaySource(stream, fs=FS, ch_names=OC4, pace="fast", block_samples=32, markers=cues)
    res = run_protocol(p_eo, source=src, out_dir=WORK / f"eoec-S{s:03d}")
    o = res.stats["online"]
    rep = SessionReader(WORK / f"eoec-S{s:03d}").decoder()
    cv = getattr(rep, "report", None) or {}
    rows.append({"subject": f"S{s:03d}", "calibration epochs": res.stats["n_epochs_calibration"], "cv accuracy (cue order)": round(float(cv["cv_accuracy"]), 2) if "cv_accuracy" in cv else None,
                 "scored periods": o["n_decided"], "correct": o["n_correct"], "gated blocks": res.stats["n_gated"]})
    pooled_correct += o["n_correct"]; pooled_n += o["n_decided"]
tab = pd.DataFrame(rows)
print(tab.to_string(index=False))
lo, hi = eegloop.bci.chance_interval(pooled_n, 0.5)
pooled_acc = pooled_correct / pooled_n
n_calibrated = int((tab["scored periods"] > 0).sum())
print(f"\nreplica, pooled over the {n_calibrated} of {len(SUBJECTS)} subjects whose decoder was fitted: {pooled_correct} of {pooled_n} scored periods correct = {pooled_acc:.3f}; "
      f"chance band {lo:.3f}–{hi:.3f} for n = {pooled_n}  ({time.time() - t0:.1f} s)")
print(f"{len(SUBJECTS) - n_calibrated} subjects never decided: the gate held their stream unusable through most of the calibration (one of them is the popping subject L7.12 found), "
      f"so fewer than five epochs per class arrived and no decoder was frozen — the loop refuses rather than guesses")
print(f"per subject the band is {eegloop.bci.chance_interval(7, 0.5)[0]:.2f}–{eegloop.bci.chance_interval(7, 0.5)[1]:.2f} for seven periods: no single subject's row is evidence on its own")
print("the decoder's delay is its window:", SessionReader(WORK / 'eoec-S001').session["budget"]["decoder"]["note"][:60] + "…")
synthetic:
  session ok: 39 decisions; 7/7 cued periods correct (chance band 0.14–0.86 for n = 7)
  decoder latency 3000 ms — a window of 768 samples (3000 ms) is the delay; the causal filter before it adds 64 samples, exact; the decision rule's dwell is on top of both and is a choice, not a cost of the decoder
  written to eoec-syn/ (decoder.npz, session.json, events.jsonl, signal.npz)
subject  calibration epochs  cv accuracy (cue order)  scored periods  correct  gated blocks
   S001                  10                     1.00               5        5            53
   S002                   0                      NaN               0        0           345
   S003                   9                     1.00               5        4            48
   S004                  12                     1.00               7        7             4
   S005                  11                     1.00               5        3            10
   S006                  11                     0.63               6        3             7
   S007                   7                     1.00               5        3            73
   S008                  11                     1.00               7        6             7
   S009                   0                      NaN               0        0           378
   S010                   5                      NaN               0        0           121
   S011                  12                     1.00               7        7             7
   S012                  12                     0.90               7        6             4

replica, pooled over the 9 of 12 subjects whose decoder was fitted: 44 of 54 scored periods correct = 0.815; chance band 0.370–0.630 for n = 54  (4.5 s)
3 subjects never decided: the gate held their stream unusable through most of the calibration (one of them is the popping subject L7.12 found), so fewer than five epochs per class arrived and no decoder was frozen — the loop refuses rather than guesses
per subject the band is 0.14–0.86 for seven periods: no single subject's row is evidence on its own
the decoder's delay is its window: a window of 480 samples (3000 ms) is the delay; the causal f…

8 · 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 below is the one loop/HARDWARE.md carries; every value is TODO(confirm) until a run fills it.

In [11]:
RUN_RECORD = '''
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
'''
print(RUN_RECORD.strip("\n"))
print("\nfor comparison, the same rows from this notebook's replica session (a file, not a headset):")
st = r_oc4.session["stats"]; bud = r_oc4.session["budget"]
print(f"  rate, effective        {r_oc4.session['source']['fs']:g} Hz (a replay keeps its file's clock)")
print(f"  drops                  {st['drops_total']}")
print(f"  gate fraction          {st['n_gated']} / {st['n_blocks']} = {gate_frac:.3f}")
print(f"  processing, measured   p50 {st['processing_ms']['p50']:.2f} ms, p95 {st['processing_ms']['p95']:.2f} ms")
print(f"  loopback probe         {probe['value_ms']:.1f} ms measured, {probe['expected_value_ms']:.1f} ms expected")
print(f"  sealed mode            {r_oc4.session['sealed_sham']} → {ShamPolicy.unblind(r_oc4.session['sealed_sham'], p_oc4.seed)!r}")
print(f"  protocol hash          {r_oc4.session['protocol_hash']}")
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

for comparison, the same rows from this notebook's replica session (a file, not a headset):
  rate, effective        160 Hz (a replay keeps its file's clock)
  drops                  0
  gate fraction          27 / 300 = 0.090
  processing, measured   p50 0.31 ms, p95 0.34 ms
  loopback probe         503.1 ms measured, 503.1 ms expected
  sealed mode            eadca24373098fdc → 'veridical'
  protocol hash          6f4b07a591c7

Your own recording, if you have one

When LOCAL_RECORDING names a file — a .bin with its sidecar as eegloop run --record-raw writes it, or an .npz — the cell below runs this notebook's measurement on it and prints the result titled as yours; when it is None the cell is skipped entirely, so nothing empty ships. Nothing from your recording is written into this notebook's outputs on the site: it is a second pass, never shipped (CONTRACTS, Phase 5).

In [12]:
if LOCAL_RECORDING is not None:
    mine = ReplaySource(LOCAL_RECORDING, pace="fast", block_samples=32)
    wanted = set(p_oc4.signal.channels)
    if not wanted <= set(mine.info.ch_names):
        print(f"your recording has channels {mine.info.ch_names}; the protocol names {sorted(wanted)} — edit the protocol's signal.channels to run it on yours")
    else:
        res_mine = run_protocol(p_oc4, source=mine, out_dir=WORK / "mine")
        print(f"your recording — not shipped: session {res_mine.status}")
        for k, v in rubric_fields(WORK / "mine").items():
            print(f"  {k:14s} {v}")
else:
    print("LOCAL_RECORDING is None: skipped (set it to a .bin with its sidecar, or an .npz, to run the application's protocol over your own file and read the rubric fields)")
LOCAL_RECORDING is None: skipped (set it to a .bin with its sidecar, or an .npz, to run the application's protocol over your own file and read the rubric fields)

9 · The numbers the lesson's exercises ask for

In [13]:
print("nb-7-16-application — L7.16 numbers (draft; TODO(confirm) at author review)")
print()
print(f"(a) The replica session's gate fraction (alpha-up-oc4-replay on the shipped asset): {st['n_gated']} of {st['n_blocks']} blocks = {gate_frac:.3f}; "
      f"the loopback probe's value delay {probe['value_ms']:.1f} ms against {probe['expected_value_ms']:.1f} ms expected, |Δ| = {probe_gap:.1f} ms ≤ {block_ms:.0f} ms.")
print(f"(b) The EO/EC switch on the occipitotemporal replica, {n_calibrated} of {len(SUBJECTS)} subjects calibrated, up to 7 scored periods each: pooled accuracy {pooled_acc:.3f} on {pooled_n} "
      f"(chance band {lo:.3f}–{hi:.3f}); {len(SUBJECTS) - n_calibrated} subjects never calibrated because the gate held their stream unusable; the synthetic run scores its planted answer.")
print(f"(c) The rubric is self-graded: {covered} of {len(onsets)} planted artifact windows covered by the gate; 4 sham modes sealed and unblinded; "
      f"{n_items} CRED-nf items listed, {n_sat} satisfied with the pre-registration committed and {lt['n_sessions']} sessions tested; "
      f"naive_trend flags {n_naive} of {len(naive)} replayed sessions and is not the outcome.")
nb-7-16-application — L7.16 numbers (draft; TODO(confirm) at author review)

(a) The replica session's gate fraction (alpha-up-oc4-replay on the shipped asset): 27 of 300 blocks = 0.090; the loopback probe's value delay 503.1 ms against 503.1 ms expected, |Δ| = 0.0 ms ≤ 200 ms.
(b) The EO/EC switch on the occipitotemporal replica, 9 of 12 subjects calibrated, up to 7 scored periods each: pooled accuracy 0.815 on 54 (chance band 0.370–0.630); 3 subjects never calibrated because the gate held their stream unusable; the synthetic run scores its planted answer.
(c) The rubric is self-graded: 4 of 4 planted artifact windows covered by the gate; 4 sham modes sealed and unblinded; 6 CRED-nf items listed, 5 satisfied with the pre-registration committed and 12 sessions tested; naive_trend flags 8 of 12 replayed sessions and is not the outcome.

Cleanup

Only what this run fetched is deleted, and every session it wrote.

In [14]:
import shutil
shutil.rmtree(WORK, ignore_errors=True)
_edf_after = set(Path(mne.get_config("MNE_DATA", str(Path.home() / "mne_data"))).rglob("*.edf"))
_new = sorted(_edf_after - _edf_before)
for p_ in _new:
    p_.unlink(missing_ok=True)
assert len(tab) == len(SUBJECTS)
print(f"deleted {len(_new)} EDF file(s) this run fetched and the notebook's session directory; cohort {len(tab)}/{len(SUBJECTS)}")
deleted 0 EDF file(s) this run fetched and the notebook's session directory; cohort 12/12