Frontend (JavaScript)

Browser-side dashboard: ES modules, Plotly, panel system, 3D brain visualization

File Overview

Module Dependency Graph

graph TD
  HTML["index.html"]
  APP["app.js\nMain entry point — imports everything"]
  PANELS["panels.js\nPanel registry, layout"]
  TS["timeseries.js\nPure render"]
  SP["spectral.js\nPure render"]
  MT["metrics.js\nPure render"]
  BR["brain.js\nSelf-contained:\nfetches + renders"]
  BW["browser.js\nBIDS navigator +\nfolder picker"]

  HTML --> APP
  APP --> PANELS & TS & SP & MT & BR & BW

The render modules (timeseries.js, spectral.js, metrics.js) are pure: they take data and a DOM element, produce a Plotly chart, and have no side effects. They do not hold any application state — that lives only in app.js.

app.js — Main Controller

Application state object

const state = {
  info:        null,    // response from /api/load: channels, fs, duration, etc.
  channels:    [],      // currently selected channels (subset of info.channels)
  montage:     "monopolar",
  notchMode:   "none",
  viewRange:   null,    // [t_start, t_end] for current zoom window, or null = full
  activeMetric: null,   // for metric panels
};

apiFetch

async function apiFetch(url, options = {}) {
  const res = await fetch(url, options);
  if (!res.ok) throw new Error(await res.text());
  return res.json();
}

All server calls go through apiFetch. If the server returns an error status, it throws with the error message so it can be shown to the user.

Load sequence

1. User types path and presses Load
2. apiFetch("POST /api/load", {path}) — stores result in state.info
3. buildSidebar(state.info) — renders channel list grouped by electrode prefix
4. applyLayout(currentGrid) — triggers all panel render functions

Sidebar

Channels are grouped by electrode prefix — the alphabetic part of names like "SEEG1" → prefix "SEEG". The regex /^(.+?)\d+$/ extracts the prefix.

Status indicators (colored dots) are derived from channel_metadata.status and channel_metadata.status_description:

Filter buttons

Three filter modes change which channels are in state.channels, then re-render time series and PSD:

• All — all channels
• SOZ — only channels with status_description = "soz"
• Good — only channels with status = "good"

Montage switching

async function switchMontage(montage) {
  const result = await apiFetch("/api/montage", {
    method: "POST",
    headers: {"Content-Type": "application/json"},
    body: JSON.stringify({ montage }),
  });
  state.info.channels = result.channels;
  state.info.channel_metadata = result.channel_metadata;
  state.montage = montage;
  buildSidebar(state.info);   // channel names change in bipolar
  rerenderAll();
}

Zoom/pan coordination

The time series panel registers a Plotly zoom/pan listener via onZoomPan(div, callback) (from timeseries.js). When the user zooms, the callback fires with the new [t_start, t_end], which is stored in state.viewRange and a new /api/timeseries request is made for just that window — providing dynamic level-of-detail.

panels.js — Layout System

The dashboard uses a configurable grid of panels. Each panel type has a registered render function. The layout is stored in localStorage so it persists between sessions.

Panel types

Layout presets

Key functions

timeseries.js

spectral.js

metrics.js

brain.js — 3D Brain Visualization

Renders a 3D scatter plot of electrode contacts positioned in MNI space, with each contact colored by a metric value that animates over time.

Two-resolution strategy

Metric options (BRAIN_METRICS)

• line_length
• hjorth_activity (component 0)
• hjorth_mobility (component 1)
• band_power: gamma (index 4)
• band_power: high_gamma (index 5)
• band_power: beta (index 3)

Key internal functions

Styling (style.css)

Dark theme. Key design choices:

• Paper color: #1a1d27 — dark blue-gray
• Plot background: #0f1117 — near-black
• Sidebar: collapsible, groups channels by electrode with status dots
• Grid: CSS Grid layout, configurable columns/rows per preset
• Modals: file browser and layout editor use the same dark overlay style