Neuroscience Figure Stack for Kahlus#

This note records the recommended plotting stack for Kahlus EEG/ridge diagnostics and future neuroscience figures. The goal is to avoid prompt-generated fake diagrams and instead generate figures from benchmark tensors with publication-style defaults.

Core recommendation#

Use data-driven Python figures, not hand-prompted SVG/JPG generation.

Recommended stack:

  1. MNE-Python for EEG/MEG/ECoG neurophysiology visualization

    • Raw traces, epochs, evoked responses, topomaps, PSDs, time-frequency plots, sensor layouts.

    • Standard in EEG papers and BCI tooling.

    • GitHub: mne-tools/mne-python

    • Docs include a dedicated “Make figures more publication ready” tutorial.

  2. MOABB for EEG benchmark conventions

    • Mother of All BCI Benchmarks.

    • Built on MNE-Python and scikit-learn.

    • Use as reference for reproducible EEG benchmark framing, dataset handling, and evaluation methodology.

    • GitHub: NeuroTechX/moabb

  3. Braindecode for deep-learning EEG paper conventions

    • PyTorch toolbox for raw EEG/ECoG/MEG decoding.

    • Good reference for model result plots, EEGNet-style context, and deep EEG benchmark presentation.

    • GitHub: braindecode/braindecode

  4. Matplotlib + SciencePlots for final publication styling

    • Matplotlib remains the base layer for paper figures.

    • SciencePlots provides publication-style rcParams for papers/theses.

    • Export both .png at 300+ DPI and .pdf/.svg vector versions.

    • GitHub: garrettj403/SciencePlots

  5. Seaborn / scipy / scikit-learn for statistics and diagnostics

    • Use for confidence intervals, distributions, correlation heatmaps, residual plots, and model metric summaries.

    • Keep plot rendering in Matplotlib so final layout is controlled.

  6. Nilearn only if Kahlus shifts to fMRI/brain-volume figures

    • Glass brain, surface maps, ROI/connectivity visualizations, statistical maps.

    • Not needed for current EEG ridge waveform diagnostics.

  7. pyNeuroML / libNeuroML only for NeuroML cell/network morphology and electrophysiology

    • NeuroML docs emphasize morphology plots, interactive 3D cell visualization, F-I curves, voltage traces.

    • Useful for NeuroML model documentation, not the current MOABB EEG ridge benchmark.

What the current Amrith request needs#

Amrith asked for analysis of the existing benchmark, not more benchmarks. For the EEG ridge baseline, the first figure packet should include:

  1. Raw EEG waveforms with the current window X_t and next-window target X_{t+1} labeled.

  2. The actual ridge design matrix shown as [windows × time, channels], matching the repo’s current linear_ridge implementation.

  3. Ridge predicted vs actual future EEG traces, with residuals and per-channel metrics.

  4. Autocorrelation / lag diagnostics explaining why a linear model can be strong.

  5. Ridge coefficient maps reshaped back into input-channel/output-channel or input-time/output-time structure.

  6. Optional MNE topomap if real channel names/positions are available.

Visual grammar#

  • White background.

  • No decorative gradients.

  • Use muted scientific colors:

    • input/current window: blue

    • target/future window: red/orange

    • actual signal: near-black

    • ridge prediction: red

    • residual/error: gray

  • Label panels as A, B, C, D when composing multi-panel figures.

  • Every schematic must be stamped SCHEMATIC, NOT BENCHMARK EVIDENCE.

  • Every benchmark figure must include data source, split, model, and metric in the caption or README.

  • Avoid dense overlapping lines. Show 4-8 channels max per waveform panel.

  • Export:

    • fig*.png at 300 DPI for slides/email

    • fig*.pdf for paper/docs

Implementation path#

Current script:

python3 scripts/analysis/plot_ridge_eeg_diagnostics.py

This generates schematic layout figures only.

For real benchmark evidence, create an .npz containing:

  • x_train: [windows, time, channels]

  • y_train: [windows, time, channels]

  • x_test: [windows, time, channels]

  • y_test: [windows, time, channels]

  • optional y_pred_test: exported ridge predictions from the benchmark run

  • optional sfreq

  • optional channel_names

Then run:

python3 scripts/analysis/plot_ridge_eeg_diagnostics.py \
  --npz path/to/real_benchmark_tensors.npz \
  --time-length 128 \
  --n-channels <N>

If real channel names and montage are available, extend the script with MNE:

import mne
info = mne.create_info(channel_names, sfreq, ch_types="eeg")
info.set_montage("standard_1020", on_missing="ignore")
mne.viz.plot_topomap(values, info)

Sources / reference projects#

  • MNE-Python: https://github.com/mne-tools/mne-python

  • MNE publication-ready figures tutorial: https://mne.tools/stable/auto_tutorials/visualization/10_publication_figure.html

  • MNE topomap examples: https://mne.tools/stable/auto_examples/visualization/evoked_topomap.html

  • MOABB: https://github.com/NeuroTechX/moabb

  • Braindecode: https://github.com/braindecode/braindecode

  • Nilearn plotting: https://nilearn.github.io/stable/plotting/index.html

  • NeuroML visualization docs: https://docs.neuroml.org/Userdocs/VisualisingCells.html

  • SciencePlots: https://github.com/garrettj403/SciencePlots