How shalindasilva1/detached-eeg works
Read the file tree as architecture
Key structure signals:
• Entrypoints
• src/pipeline.py → orchestrates the full run (config load → data load → splits → pre-transform → train/eval → save JSON)
• src/visualize_results.py → consumes results/*.json → outputs figures
• Core library / utilities
• src/utl/config.py → configuration loading / normalization (likely YAML)
• src/utl/bids.py → BIDS dataset discovery/loading
• src/utl/eeg.py → EEG-specific preprocessing/format conversion
• src/utl/splits.py → CV and specifically LOSO split logic
• Configs / environments
• config.yml → main runtime config
• environment.yml, requirements.txt → dependency/environment definition
• experiments/configs/*.yaml → experiment variants (cnn vs rocket, photic/rest etc.)
• Artifacts
• results/loso_results.json, results/cv_results.json → metrics
• results/figures/ → plots generated from results JSON
• Verification
pipeline.py → (preprocesses/reshapes) → via utl/eeg.py
5. pipeline.py → (creates folds) → via utl/splits.py → produces LOSO train/test indices
6. pipeline.py → (GPU pre-transform) → detach_rocket feature extraction → produces transformed feature matrices
pipeline.py → (trains) → ensemble models → (predicts) → fold metrics
8. pipeline.py → (aggregates) → subject-level metrics → (writes) → results/loso_results.json
visualize_results.py → (reads) → results/*.json → (writes) → results/figures/*
A conditional GPU path:
Architectural patterns to explicitly call out
This project is best represented as:
• Batch pipeline / offline experiment runner
• Configuration-driven execution
• config.yml + experiment YAMLs drive behavior; code is mostly orchestration + reusable utilities.
• Separation of concerns
• Orchestrator (pipeline.py) vs utilities (src/utl/*) vs reporting (visualize_results.py)
• Precomputation optimization
• “pre-transformation strategy” is a key architectural choice: expensive kernel extraction is done upfront (GPU), then reused across LOSO folds.
A callout annotation near “Detach-Rocket feature extraction”:
• “Extract 10,000+ kernels once on GPU upfront → reuse across LOSO folds (time optimization).”
• Python 3.10
• PyTorch + CUDA (for detach_rocket acceleration)
• detach-rocket (external algorithm implementation)
• BIDS (input data format contract)
• (Optionally) plotting stack for visualization (matplotlib/seaborn) if visible in requirements; otherwise just “Plotting”.
• Actors: Researcher/User
• Containers: Pipeline Runner, Visualization Runner, Dataset (BIDS), Results Store, GPU/CUDA (as infra)
• Purpose: show the big moving pieces and file-based interfaces.
• Expand Pipeline Runner into stages:
• Config Load → BIDS Load → EEG Preprocess → LOSO Splitter → Pre-transform (Rocket kernels) → Train Ensemble → Evaluate/Aggregate → Write JSON
• This is the “most accurate” depiction of this repository’s architecture.
Be “very detailed” by splitting into many components (without inventing services)
Because this is not microservices, detail comes from pipeline stages and module boundaries, not from adding fake servers.
Write Results → [results/loso_results.json]
Separate branch:
[User] → [visualize_results.py] → (reads) **[results/*.json] → [results/figures/*]**
• “Optimization: pre-transform once (GPU) then reuse across LOSO folds.”