KO
|
EN
gitlite — search
Search
#javascript
#python
#hacktoberfest
#react
#ai
#typescript
#llm
#go
#golang
#android
#machine-learning
#rust
#deep-learning
#linux
The-Squiggle-Interpreter
★ 17
Open GitHub ↗
EDF EEG REPORT TOOL
Download README (.md)
Explore Similar Repositories
CodeWalker.API
:
Local API for Codewalker to automate model extraction.
PolyflowAutoBot-NTE
:
No description available.
XCXDE-ModLoader
:
exlaunch plugin for loading files outside of sts.ard in Xenoblade Chronicles X: Definitive Edition
tauri-plugin-machine-uid
:
Tauri Plugin for retrieving machine UID
FsMath
:
FsMath is a lightweight maths library designed for modern F# workflows
// repository documentation
Was this content helpful?
★ 0
(0 ratings)
Select Rating:
★
★
★
★
★
Submit Feedback
Recent Feedback
×
Download README
Do you want to download the
README.md
file for
The-Squiggle-Interpreter
?
Download (.md)
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](#overview) - [Key Features](#key-features) - [Architecture and Modules](#architecture-and-modules) - [Clinical, Research, and Industry Standards](#clinical-research-and-industry-standards) - [Installation and Setup](#installation-and-setup) - [Usage](#usage) - [Extensibility and Customization](#extensibility-and-customization) - [Contributing](#contributing) - [License](#license) - [Authors](#authors) - [References](#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) [](https://www.youtube.com/watch?v=2CinwFa5OXo "-older version concept scripts") Video old batch run in action [](https://www.youtube.com/watch?v=os_8XX3V8sk "EDF Batch run -older version") ## 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 [](https://www.youtube.com/watch?v=P-N9JAoza4E "Windows Install Video") 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 
