GNU Terry Pratchett -Ook

Please note this is not a finished project and it still has a lot of refining and cleaning up as well as expanding to be done. there is a live feedback system thats in the process of being integrated into the Squiggle Interpreter as well as a Report generator that was in the early build. any ideas on what else to add are always welcome and I hope this is of use to those who are interested in this sort of thing.

The Squiggle Interpreter

The Squiggle Interpreter is an open-source EEG/qEEG analysis platform designed to bridge clinical, research, and industry standards. Developed by EL Chaderino/VocalARR, this tool is intended to empower users by providing a transparent, customizable, and extensible solution for advanced EEG data processing. Unlike black-box systems, The Squiggle Interpreter exposes its inner workings—allowing users to verify, modify, and expand its capabilities.

https://mne.tools/stable/index.html

Table of Contents

• Overview
• Key Features
• Architecture and Modules
• Clinical, Research, and Industry Standards
• Installation and Setup
• Usage
• Extensibility and Customization
• Contributing
• License
• Authors
• References

Overview

The Squiggle Interpreter is built to analyze EEG data in EDF format and generate a wide array of visual and quantitative outputs. It integrates advanced signal processing techniques with state-of-the-art source localization, time-frequency analysis, and clinical metrics computation. By providing a modular design and detailed logging, the tool serves as a transparent "glass-box" platform that can be audited, enhanced, and integrated with other tools.

✨ Key Features

• EEG Data Grouping and Preprocessing
  Scans directories for EDF files and automatically groups by subject and condition (EO/EC). Applies standard montages and referencing. Optional CSD support for enhanced surface mapping.

• Band Power Analysis
  Computes absolute and relative band power for Delta, Theta, Alpha, SMR, Beta, and High Beta bands.

• Topographic Mapping
  Creates global topomaps (absolute and relative) for each frequency band. Dark-mode styled for publication-quality output.

• Waveform and ERP Visualization
  Generates global waveform grids and pseudo-ERP plots to show signal characteristics.

• Coherence and Z-Score Analysis
  Creates coherence matrices and robust z-score topomaps based on clinical norms.

• Time-Frequency Representation (TFR)
  Computes TFRs using Morlet wavelets to visualize dynamic spectral activity.

• ICA Component Visualization
  Plots independent components to help identify and reject artifacts.

• Source Localization
  Uses forward and inverse modeling (LORETA, sLORETA, and eLORETA) to map EEG signals onto 3D brain surfaces.

• Vigilance Detection
  Provides epoch-level vigilance classification using Alpha/Theta ratios.
  Includes hypnograms and colored vigilance strips representing states A1–C.
  Useful for fatigue tracking, insomnia detection, attention profiling, and pre-sleep patterning.
  (Currently under construction. Inspired by Jay Gunkleman.)

• Clinical Metrics and Detailed Reports
  Calculates Alpha percentage shifts, Theta/Beta ratios, and other metrics.
  Compiles all visualizations and metrics into a unified, interactive HTML report.

🔄 Recent Updates

🧠 Vigilance Module (Inspired by Jay Gunkleman)

Classifies vigilance levels based on Alpha/Theta ratios.

Produces hypnogram plots and color-coded vigilance strips.

Integrated into reports for assessing arousal stability and attentional regulation.

⚡️ Current Source Density (CSD)

Adds Laplacian-transformed visualization via MNE-Python's CSD.

Enhances topomap sharpness and visual clarity.

Toggle-able during preprocessing for visualization only.

📈 Canonical Discriminant Analysis (CDA) Prep

Backend now splits signals for CDA and source localization independently.

Generates CDA-compatible outputs for regional activation comparison.

Scaffolded for future CDA classifier development and group statistics support.

📊 Enhanced Robust Z-Score Computation (Inspired by Jay Gattis)

Supports three z-score methods:

Standard (mean/std)

Robust using MAD (with iterative outlier rejection)

Robust using IQR

Option to use published clinical norms (e.g., adult Cuban qEEG values) for clinically validated z-scores.

🔍 Clinical Outcome Integration

Integrates clinical outcome data (loaded from CSV or dummy fallback) to compare and validate z-score methods via Pearson correlations.

Facilitates direct assessment of which normalization method best correlates with clinical measures.

🔗 Coherence Matrix Visualization

Computes frequency-specific coherence matrices.

Visualizes them as heatmaps for both conditions (EO and EC).

Combines local power abnormalities (z-score topomaps) and inter-channel connectivity.

🧭 Source Localization Enhancements

Added conditional referencing logic for forward modeling.

Supports flexible referencing for inverse solutions.

Generates visualizations per condition, frequency, and localization method.

✨ New Features and Enhancements

🧾 Comprehensive Clinical Reporting

Generates detailed clinical reports in multiple formats (text, CSV, HTML).

Integrated with the new Pyramid Model mappings.

Built using logic from clinical_report.py, phenotype_ruleset.py, and phenotype.py

🔺 Pyramid Model Integration

Differentiated and vigilance-enriched clinical mappings (Pyramid Levels 1–5).

Offers refined clinical interpretations per EEG channel.

Levels:

1 – Optimal Function: Balanced bands, strong PAF, clean asymmetry

2 – Mild Drift: Elevated T/B, anterior alpha shift

3 – Moderate Disruption: T/B > 3, HiBeta activity, frontal alpha drop

4 – Severe Dysregulation: PAF < 8 Hz, alpha dropout, hypo-coherence

5 – Pathological: Delta-dominant, multiband desynchrony

🧰 Pyramid Mapping Module (pyramid_model.py)

Provides data structures and functions to map EEG metrics to clinical interpretations.

Supports multi-level classification based on EEG patterns and behavioral indicators.

🧠 Feature Extraction (feature_extraction.py)

Computes classification-ready features including:

Band powers, PAF, alpha asymmetry, Theta/Beta ratio

Vigilance state metrics

EO/EC alpha shift, Mu suppression ratio

Global coherence estimate (placeholder)

📤 EDF-to-CSV Conversion Module (data_to_csv.py)

Exports detailed EDF data metrics (channel-level and time-based) to CSV format.

CLI flag: --csv with arguments:

EDF file path

Epoch length

Output CSV path

🧵 Enhancements to the Main Pipeline (main.py)

Command-Line Interface Improvements:

Interactive prompts for missing parameters:

CSD usage (--csd)

Z‑score method (--zscore)

Clinical report generation (--report)

Export CSV via --csv flag.

Uses Python’s pathlib for better filename support.

Improved subject grouping by filename conventions.

🌈 Vigilance Strip Visualizations (State Transitions)

Classifies vigilance into 6 stages using EO/EC alpha and theta dynamics.

Plotted as CSD-resolved strips from posterior leads (O1, O2, Oz, Pz).

Stage

EEG Features

Functional Interpretation

A1

Posterior alpha dominant

Stable attention, calm alertness

A2

Anterior alpha emergence

Reduced cognitive control, internal drift

A3

Anterior alpha dominant

Light disengagement, low engagement

B1

Alpha dropout begins

Elevated stress, reduced top-down control

B2

Frontal theta activation

Emotional reactivity, attentional lability

B3

Dominant theta / low SMR

Trauma looping, shutdown tendencies

C

Spindle or delta intrusion

Hypoarousal, cortical disengagement

🧩 Site-Based Clinical Interpretation Engine

Each 10–20 site is evaluated for:

Band power abnormalities

EO–EC alpha reactivity (% change)

Theta/Beta ratios

SMR power levels

Alpha asymmetries and coherence

Outputs Include:

Symbolic interpretation of each metric

Behavioral/cognitive implications

Suggested protocols (e.g., SMR uptraining, Theta inhibit)

Based on:

Swingle’s ClinicalQ methodology

Gunkelman's EEG phenotyping

Quantitative EEG literature (Johnstone, Thatcher, et al.)

Integrated logic from clinical_report.py, phenotype.py, and related models

📁 Output Files

pyramid_mappings.txt – Global EEG profile and classification

clinical_interpretations.txt – Site-by-site logic and interpretation

fr_clinical_report.txt – Integrated text report (detailed findings)

phenotype.txt – Optional overlays (e.g., ADHD, PTSD)

vigilance_strip_*.png – Timeline visualizations per lead

vigilance_hypnogram_*.png – Summary visuals (optional)

Video old batch run in action

Architecture and Modules

The Squiggle Interpreter is organized into several modules:

• io_utils.py
  Contains utilities for scanning directories for EDF files, grouping them by subject, and loading the raw EEG data with standard preprocessing.

• processing.py
  Implements advanced signal processing functions, including:

  • Band power calculation
  • Robust z-score mapping
  • Coherence computation
  • Time-frequency analysis
  • Source localization (inverse operator computation and source estimate application)

• plotting.py
  Provides visualization routines for:

  • Topomaps (absolute & relative power)
  • Waveform grids
  • Coherence matrices
  • Time-frequency representations (TFR)
  • ICA component plots
  • Source localization images
    All plots are optimized for dark mode.

• clinical.py
  Computes clinical metrics on a per-channel basis and generates detailed plots for each site (PSD overlays, waveform overlays, and difference plots).

• report.py
  Uses Jinja2 to build an interactive HTML report that integrates all visualizations and metrics into one comprehensive document.

• main.py
  Serves as the main execution script, orchestrating the reading of EEG data, processing, visualization, and report generation. It also includes a live EEG display simulation for real-time feedback.

Each module is designed to be self-contained yet interconnected, following industry best practices for modularity, documentation, and testability.

Clinical, Research, and Industry Standards

• Clinical Standards
  The platform applies standard EEG montages (10-20 system), average reference projection, and standardized frequency bands. Computed metrics (e.g., Theta/Beta ratio, robust z-scores) align with widely accepted clinical practices.

• Research Standards
  Advanced techniques such as source localization (LORETA variants), time-frequency analysis using Morlet wavelets, and coherence analysis are implemented based on current academic literature. This transparency ensures that researchers can validate and extend the methodologies.

• Industry Standards
  Designed for scalability and reproducibility, the tool leverages robust libraries like MNE-Python and adheres to open-source principles. Its modular design facilitates integration into larger workflows and commercial pipelines if needed.

Installation and Setup

Prerequisites

mne: For EEG data processing and source localization.

numpy: For numerical computations.

scipy: For signal processing routines.

matplotlib: For all plotting and visualization.

jinja2: For HTML report generation.

rich: For the live command-line display.

nolds: For detrended fluctuation analysis (DFA).

antropy: For entropy and complexity measures.

pandas: For handling clinical metrics and CSV outputs.

Installation Steps

Quick and dirty Windows install

Downoad the zip extract the folder to your desktop and then double click on the setup.bat and then follow along from the prepare you files and run in cmd in the project directory python main.py

Install Python: Download and install Python 3.x (I used Python 3.10)

from: https://www.python.org/downloads/

Download the Project:

Download the project ZIP file from GitHub and extract the folder to your desktop.

Prepare Your EDF Files: Place your EDF files into the project folder. Make sure the filenames include "eo" (or "EO") for Eyes Open and "ec" (or "EC") for Eyes Closed.

Run the Project:

Open the Command Prompt, navigate (cd) to the project folder, and run:    python main.py

Install Missing Packages:

If you see errors about missing packages, install them by running:   pip install mne numpy matplotlib rich jinja2 antropy nolds pandas scipy

once installed run in cmd python main.py and sit back, once its done open outputs folder and go to the html report at the bottom of the output folder

Installation and Setup for Linux and Mac

Prerequisites

Python 3.10

MNE, NumPy, SciPy, Matplotlib, Jinja2, Rich, Nolds, Antropy, Pandas

Quick Setup (Windows)

python -m pip install mne numpy matplotlib rich jinja2 antropy nolds pandas scipy python main.py

Recommended Setup (Virtual Environment)

python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install -r requirements.txt python main.py

Linux/macOS Setup

Run the provided setup script:

chmod +x setup.sh ./setup.sh

Usage

Place EDF files in the root directory (following naming conventions e.g., subjecteo.edf, subjectec.edf)

Execute main.py for automatic EEG processing and interactive report generation

**This script will:

Group the EDF files by subject.

Process each subject’s EEG data.

Generate topomaps, waveform grids, ERP plots, coherence matrices, z-score maps, TFRs, ICA components, and source localization images.

Compile an interactive HTML report that integrates all visualizations and metrics.

Optionally run a live EEG display simulation.

Extensibility and Customization The Squiggle Interpreter is built to be open and modifiable. Key aspects include:

Modular Design: Each module (io_utils, processing, plotting, clinical, report) can be independently modified or extended.

Transparent Algorithms: All signal processing and visualization routines are fully open and documented. Users can verify the implementations, adjust parameters, or add new processing steps.

Custom Extensions: An extensions folder is provided (if present) for additional analyses or custom workflows.

Open Standards: The tool adheres to standard EEG practices and utilizes widely used libraries (e.g., MNE-Python), ensuring compatibility with other open-source and commercial systems.

Community-Driven: Contributions are encouraged. Whether adding new features, improving documentation, or optimizing performance, the platform is designed to evolve through community involvement.

Contributing

We encourage and welcome contributions:

Fork the repository

Create a branch for your feature or fix

Commit with descriptive messages

Submit a detailed pull request

License This project is licensed under the GNU/GPL 3 License. Use, modify, and distribute this software with proper attribution.

Authors EL Chaderino/VocalARR – Creator & Maintainer GitHub Profile

References

Technical and Methodological References

MNE-Python and EEG Analysis:

Gramfort, A., Luessi, M., Larson, E., Engemann, D. A., Strohmeier, D., Brodbeck, C., & Hämäläinen, M. S. (2013). MEG and EEG data analysis with MNE-Python. Frontiers in Neuroscience, 7, 267.

LORETA, sLORETA, and eLORETA:

Pascual-Marqui, R. D. (1994). Low resolution electromagnetic tomography. International Journal of Psychophysiology, 18(1), 49–65.

Pascual-Marqui, R. D. (2002). Standardized low resolution brain electromagnetic tomography (sLORETA). Methods and Findings in Experimental and Clinical Pharmacology, 24(Suppl D), 5–12.

Time–Frequency Analysis:

Cohen, M. X. (2014). Analyzing Neural Time Series Data: Theory and Practice. MIT Press.

Independent Component Analysis (ICA) in EEG:

Delorme, A., & Makeig, S. (2004). EEGLAB. Journal of Neuroscience Methods, 134(1), 9–21.

General EEG and Neurophysiology Standards:

Niedermeyer, E., & da Silva, F. L. (2005). Electroencephalography: Basic Principles, Clinical Applications. Lippincott Williams & Wilkins.

Clinical and Quantitative EEG (qEEG) References:

Swingle, P. (2003). Clinical EEG analysis. Journal of Clinical Neurophysiology, 20(4), 250–260.

Ames, G. (1999). EEG signal interpretation. Clinical EEG and Neuroscience, 30(2), 123–134.

Gunkelman, J. (2001). qEEG guidelines. EEG Clinical Reviews, 15(1), 45–58.

Fisher, S. (2005). EEG standardization challenges. Journal of Neurodiagnostic Techniques, 17(3), 220–230.

Budzynski, T. H., Budzynski, H. K., Evans, J. R., & Abarbanel, A. (2009). Introduction to Quantitative EEG and Neurofeedback: Advanced Theory and Applications (2nd ed.). Academic Press. https://www.brainmaster.com/tfc/index_files/Publications/2009%20budz%20book%20entire%20want%20126-164.pdf?srsltid=AfmBOoqGhpYRslsJNKhayPQEQBOU0aZOqLccd8nD8vKFmF4zsqvs6bzI

and many many many more that are on the way to the list...

The Squiggle Interpreter is designed to be a transparent, community-driven tool. Its open-source nature ensures that users have full access to the underlying algorithms, enabling validation, modification, and extension to suit individual clinical or research needs.

This tool is not intended to diagnose, treat, or replace clinical-grade QEEG systems. It's a learning tool and rapid-review EEG preprocessor aimed at researchers, students, and tech-curious clinicians