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.
- The shape — source → gate → feature or decoder → loop → presenter — as
alpha_bar.pyon the shipped four-channel asset and on the synthetic stream, and thesession.jsonfields the rubric reads. - Packaging: a pip project that depends on the library, with a replay entry point, and the clean-venv check.
- The budget, exact rows beside the measured row, and the loopback probe within one block of the arithmetic.
- The gate suspending feedback across the planted artifact windows.
- Four sham modes, each sealed into its log; the blinding check; the CRED-nf report; the valid learning test beside the invalid trend.
- Pre-registration as a hash a commit can precede.
- The EO/EC switch —
eo_ec_switch.pyon the planted answer and on the occipitotemporal replica. - 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.
# 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__}")
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.
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)")
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()
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.
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")
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.
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")
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).
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
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.
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}")
# 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")
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.
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")
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.
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] + "…")
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.
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']}")
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).
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)")
9 · The numbers the lesson's exercises ask for¶
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.")
Cleanup¶
Only what this run fetched is deleted, and every session it wrote.
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)}")