hermes-agent/optional-skills/health/neuroskill-bci/references/metrics.md

NeuroSkill Metric Definitions & Interpretation Guide

⚠️ Research Use Only: All metrics are experimental and derived from consumer-grade hardware (Muse 2/S). They are not FDA/CE-cleared and must not be used for medical diagnosis or treatment.

---

Hardware & Signal Acquisition

NeuroSkill is validated for Muse 2 and Muse S headbands (with OpenBCI support in the desktop app), streaming at 256 Hz (EEG) and 64 Hz (PPG).

Electrode Positions (International 10-20 System)

Channel	Electrode	Position	Primary Signals
CH1	TP9	Left Mastoid	Auditory cortex, verbal memory, jaw-clench artifact
CH2	AF7	Left Prefrontal	Executive function, approach motivation, eye blinks
CH3	AF8	Right Prefrontal	Emotional regulation, vigilance, eye blinks
CH4	TP10	Right Mastoid	Prosody, spatial hearing, non-verbal cognition

Preprocessing Pipeline

1. Filtering: High-pass (0.5 Hz), Low-pass (50/60 Hz), Notch filter
2. Spectral Analysis: Hann-windowed FFT (512-sample window), Welch periodogram
3. GPU acceleration: ~125ms latency via gpu_fft

---

EEG Frequency Bands

Relative power values (sum ≈ 1.0 across all bands):

Band	Range (Hz)	High Means	Low Means
Delta (δ)	1–4	Deep sleep (N3), high-amplitude artifacts	Awake, alert
Theta (θ)	4–8	Drowsiness, REM onset, creative ideation, cognitive load	Alert, focused
Alpha (α)	8–13	Relaxed wakefulness, "alpha blocking" during effort	Active thinking, anxiety
Beta (β)	13–30	Active concentration, problem-solving, alertness	Relaxed, unfocused
Gamma (γ)	30–50	Higher-order processing, perceptual binding, memory	Baseline

JSON Field Names

"bands": {
  "rel_delta": 0.28, "rel_theta": 0.18, "rel_alpha": 0.32,
  "rel_beta": 0.17, "rel_gamma": 0.05
}

---

Core Composite Scores (0–1 Scale)

Focus

• Formula: σ(β / (α + θ)) — beta dominance over slow waves, sigmoid-mapped
• > 0.70: Deep concentration, flow state, task absorption
• 0.40–0.69: Moderate attention, some mind-wandering
• < 0.40: Distracted, fatigued, difficulty concentrating

Relaxation

• Formula: σ(α / (β + θ)) — alpha dominance, sigmoid-mapped
• > 0.70: Calm, stress-free, parasympathetic dominant
• 0.40–0.69: Mild tension present
• < 0.30: Stressed, anxious, sympathetic dominant

Engagement

• 0–1 scale: Active mental investment and motivation
• > 0.70: Mentally invested, motivated, active processing
• 0.40–0.69: Passive participation
• < 0.30: Bored, disengaged, autopilot mode

Meditation

• Composite: Combines alpha elevation, physical stillness (IMU), and HRV coherence
• > 0.70: Deep meditative state
• < 0.30: Active, non-meditative

Mood

• Composite: Derived from FAA, TAR, and BAR
• > 0.60: Positive affect, approach motivation
• < 0.40: Low mood, withdrawal tendency

Cognitive Load

• Formula: (P_θ_frontal / P_α_temporal) · f(FAA, TBR) — working memory usage
• > 0.70: Working memory near capacity, complex processing
• 0.40–0.69: Moderate mental effort
• < 0.40: Task is easy or automatic
• Interpretation: High load + high focus = productive struggle. High load + low focus = overwhelmed.

Drowsiness

• Composite: Weighted TAR + TBR + falling Spectral Centroid
• > 0.60: Sleep pressure building, micro-sleep risk
• 0.30–0.59: Mild fatigue
• < 0.30: Alert

---

EEG Ratios & Spectral Indices

Metric	Formula	Interpretation
FAA	ln(P_α_AF8) − ln(P_α_AF7)	Frontal Alpha Asymmetry. Positive = approach/positive affect. Negative = withdrawal/depression.
TAR	P_θ / P_α	Theta/Alpha Ratio. > 1.5 = drowsiness or mind-wandering.
BAR	P_β / P_α	Beta/Alpha Ratio. > 1.5 = alert, engaged cognition. Can also indicate anxiety.
TBR	P_θ / P_β	Theta/Beta Ratio. ADHD biomarker. Healthy ≈ 1.0, elevated > 1.5, clinical > 3.0.
APF	argmax_f PSD(f) in [7.5, 12.5] Hz	Alpha Peak Frequency. Typical 8–12 Hz. Higher = faster cognitive processing. Slows with age/fatigue.
SNR	10 · log₁₀(P_signal / P_noise)	Signal-to-Noise Ratio. > 10 dB = clean, 3–10 dB = usable, < 3 dB = unreliable.
Coherence	Inter-hemispheric coherence (0–1)	Cortical connectivity between hemispheres.
Mu Suppression	Motor cortex suppression index	Low values during movement or motor imagery.

---

Complexity & Nonlinear Metrics

Metric	Description	Healthy Range
Permutation Entropy (PE)	Temporal complexity. Near 1 = maximally irregular.	Consciousness marker
Higuchi Fractal Dimension (HFD)	Waveform self-similarity.	Waking: 1.3–1.8; higher = complex
DFA Exponent	Long-range correlations.	Healthy: 0.6–0.9
PSE	Power Spectral Entropy. Near 1.0 = white noise.	Lower = organized brain state
PAC θ-γ	Phase-Amplitude Coupling, theta-gamma.	Working memory mechanism
BPS	Band-Power Slope (1/f spectral exponent).	Steeper = inhibition-dominated

---

Consciousness Metrics

Derived from the nonlinear metrics above:

Metric	Scale	Interpretation
LZC	0–100	Lempel-Ziv Complexity proxy (PE + HFD). > 60 = wakefulness.
Wakefulness	0–100	Inverse drowsiness composite.
Integration	0–100	Cortical integration (Coherence × PAC × Spectral Entropy).

Status thresholds: ≥ 50 Green, 25–50 Yellow, < 25 Red.

---

Cardiac & Autonomic Metrics (from PPG)

Metric	Description	Normal / Green Range
HR	Heart rate (bpm)	55–90 (green), 45–110 (yellow), else red
RMSSD	Primary vagal tone marker (ms)	> 50 ms healthy, < 20 ms stress
SDNN	HRV time-domain variability (ms)	Higher = better
pNN50	Parasympathetic indicator (%)	Higher = more parasympathetic activity
LF/HF Ratio	Sympatho-vagal balance	> 2.0 = stress, < 0.5 = relaxation
Stress Index	Baevsky SI: AMo / (2 × MxDMn × Mo)	0–100 composite. > 200 raw = strong stress
SpO₂ Estimate	Blood oxygen saturation (uncalibrated)	95–100% normal (research only)
Respiratory Rate	Breaths per minute	12–20 normal

---

Motion & Artifact Detection

Metric	Description
Stillness	0–1 (1 = perfectly still). From IMU accelerometer/gyroscope.
Blink Count	Eye blinks detected (large spikes in AF7/AF8). Normal: 15–20/min.
Jaw Clench Count	High-frequency EMG bursts (> 30 Hz) at TP9/TP10.
Nod Count	Head nods detected via IMU.
Shake Count	Head shakes detected via IMU.
Head Pitch/Roll	Head orientation from IMU.

---

Signal Quality (Per Electrode)

Electrode	Range	Interpretation
TP9	0–1	≥ 0.9 = good, ≥ 0.7 = acceptable, < 0.7 = poor
AF7	0–1	Same thresholds
AF8	0–1	Same thresholds
TP10	0–1	Same thresholds

If any electrode is below 0.7, recommend the user adjust the headband fit or moisten the electrode contacts.

---

Sleep Staging

Based on 5-second epochs using relative band-power ratios and AASM heuristics:

Stage	Code	EEG Signature	Function
Wake	0	Alpha-dominant, BAR > 0.8	Conscious awareness
N1	1	Alpha → Theta transition	Light sleep onset
N2	2	Sleep spindles, K-complexes	Memory consolidation
N3 (Deep)	3	Delta > 20% of epoch, DTR > 2	Deep restorative sleep
REM	4	Active EEG, high Theta, low Delta	Emotional processing, dreaming

Healthy Adult Targets (~8h Sleep)

• N3 (Deep): 15–25% of total sleep
• REM: 20–25%
• Sleep Efficiency: > 85%
• Sleep Onset Latency: < 20 min

---

Composite State Patterns

Pattern	Key Metrics	Interpretation
Flow State	Focus > 0.75, Engagement > 0.70, Cognitive Load 0.50–0.70, HR steady	Optimal performance zone — protect it
Mental Fatigue	Focus < 0.40, Drowsiness > 0.60, TBR > 1.5, Theta elevated	Rest or break needed
Anxiety	Relaxation < 0.30, HR elevated, high Beta, high BAR, stress_index high	Calming intervention helpful
Peak Alert	Focus > 0.80, Engagement > 0.70, Drowsiness < 0.20	Best time for hard tasks
Recovery	Relaxation > 0.70, HRV (RMSSD) rising, Alpha dominant	Integration, light tasks only
Creative Mode	High Theta, high Alpha, low Beta, moderate focus	Ideation — don't force structure
Withdrawal	FAA < 0, low Mood, low Engagement	Approach motivation needed

---

ZUNA Embeddings

NeuroSkill uses the ZUNA Neural Encoder to convert 5-second EEG epochs into 128-dimensional vectors stored in an HNSW index:

• Search: Sub-millisecond approximate nearest-neighbor queries
• UMAP: GPU-accelerated 3D projection for visual comparison
• Storage: Local SQLite + HNSW index in ~/.skill/YYYYMMDD/