Crate open_eeg_codec_standard

Expand description

§OpenECS — the Open EEG Codec Standard

OpenECS is a vendor-neutral, codec-agnostic benchmark for evaluating EEG compression quality. Any codec — lossless, lossy, neural, classical, hybrid, in any language — can declare compliance with an OpenECS quality tier by passing the standard test suite against a hash-pinned holdout corpus. No self-reported numbers, no cherry-picked patients: standardized corpus, standardized metrics, deterministic pass/fail.

The crate is open-eeg-codec-standard; the library is open_eeg_codec_standard; the reference CLI is openecs.

§Tiers (strictness order L < N < C < M < A)

Tier	Name	Intent
L	Lossless	bit-exact reconstruction (PRD == 0 exactly)
N	Near-Lossless	small error, shape preserved (R≥0.99, PRD≤5 %)
C	Clinical	a neurologist cannot distinguish the recon
M	Monitoring	automated analysis preserved
A	Alerting	event detection preserved

A codec declares e.g. “I am ECS-C compliant at CR=42:1” and the harness verifies or rejects the claim. Grades render as ECS-<tier>.

§Layout

levels — the spec: tier table + the grade gate logic.
metrics — canonical metric formulas (PRD, Pearson R, SNR, CR…).
bands — per-EEG-band fidelity helpers.
adapter — the Codec trait + reference adapters (store, gzip, zstd).
adapters_external — the file-based contract for ANY external codec.
harness — the compliance grader + corpus runner.
corpus / manifest — hash-pinned corpus + codec manifests.
report / report_html — submission JSON + the HTML report.
term / charts / stats — terminal read-out, charts, CIs.

Modules§

adapter: Reference codec adapters.
adapters_external: Generic external-codec adapter — grade ANY conformant codec, in ANY language, with no Rust.
bands: Per-EEG-band fidelity helpers.
charts: Charts — graphs for the read-out (host-side DX).
corpus: Corpus manifest loader + integrity verifier (SPEC/OpenECS-v1.0.md §8).
edf: Minimal pure-Rust EDF (European Data Format) reader.
harness: Compliance test harness — the OpenECS dispatch engine.
levels: OpenECS tier spec and the grading gate.
manifest: Codec manifest loader (SPEC/OpenECS-v1.0.md §7).
metrics: Canonical OpenECS metric formulas — one definition each.
report: Reporting — the standard OpenECS report, JSON serialization, and the human-readable summary + cross-codec leaderboard.
report_html: Self-contained HTML report — the shareable artifact (host-side DX).
stats: Statistical rigor for codec comparison (host-side; not on the grade path).
subprocess: Shared subprocess + file-IO primitives for the file-driven codec adapters.
suites: Codec-agnostic benchmark batteries — the native Rust port of the black-box benchmark logic that used to live in Eagle’s Python tests/benchmarks/ + tools/.
term: Terminal rendering — colored, boxed, chart-y read-outs (host-side DX).

Constants§

SPEC_MAJOR: The major component of SPEC_VERSION. A grader accepts a manifest whose major is this or older, and refuses a newer major it does not implement (see the spec’s version policy).
SPEC_VERSION: The OpenECS specification version this crate implements (see SPEC/). Stamped onto every emitted report and submission. The tier ladder L < N < C < M < A is part of OpenECS v1.0.

Functions§

spec_major: Parse the major component of a "MAJOR.MINOR" spec-version string.