Future Packages

Planned packages for the full simulation and modeling pipeline

Not yet implemented These packages are designed but contain no code. The architecture is laid out in CLAUDE.md files. They build on the core contracts (Recording, MetricResult, ParameterVector, ModelOutput, Metric ABC, Model ABC) and the implemented model infrastructure (models-utils, Jansen-Rit).

concord-connectome

Structural connectivity — the physical wiring of the brain from diffusion MRI tractography. This is needed by neural models that couple brain regions together.

Planned scope

Load structural connectivity from FreeSurfer, MRtrix, or precomputed CSV/NumPy formats
Contact-to-node mapping: given electrode MNI coordinates, find which atlas region each contact belongs to
ConnectivityMatrix container: adjacency weights + fiber tract delays + region labels
Atlas support: Desikan-Killiany (68 regions), Destrieux (148 regions), Schaefer (configurable resolution)

Neural Model Packages

Each model implements the Model ABC and self-registers via entry_points. They take a ParameterVector and optionally a ConnectivityMatrix, and produce a ModelOutput. The foundation model (Jansen-Rit) and shared utilities (models-utils) are already implemented. The remaining models extend the same infrastructure:

concord-model-wendling

The Wendling (2002) extended Jansen-Rit model. Four populations: pyramidal cells, excitatory interneurons, slow GABA-A inhibitory interneurons, fast GABA-A inhibitory interneurons. The key addition is the fast inhibitory population, which allows the model to reproduce a spectrum of EEG patterns from background to ictal activity by adjusting a single gain parameter.

Reproduces: background EEG, rhythmic spikes, sustained discharge, seizure ictal patterns
Clinically validated against real iEEG recordings
Primary model for seizure simulation in Montage Concord

concord-model-epileptor

The Jirsa Epileptor (2014). A 5-variable phenomenological model designed specifically to capture the bifurcation structure of seizure dynamics — onset, sustained ictal activity, and offset.

Fast population (variables x₁, y₁): ictal discharge dynamics
Spike-wave population (variables x₂, y₂): slow spike-wave activity
Slow permittivity variable (z): controls seizure onset and termination via saddle-node / homoclinic bifurcations
Network capable: couple N Epileptors via ConnectivityMatrix with conduction delays
Each node can have different epileptogenicity (x₀ parameter) for realistic spatial seizure spread

concord-model-robinson

The Robinson thalamocortical model (2002). Models the cortex-thalamus-reticular nucleus loop, capturing the full spectrum of sleep-wake dynamics and arousal states.

Best model for sleep spindles, K-complexes, and arousal transitions
State transitions: awake → NREM → REM sleep
Thalamic relay nucleus + reticular nucleus + cortical populations

Extended Metric Packages

concord-metrics-connectivity

Measures statistical dependencies between pairs of channels — functional connectivity.

Bivariate: Phase Locking Value (PLV), Phase Lag Index (PLI), weighted PLI, coherence, imaginary coherence
Multivariate: Granger causality, Directed Transfer Function (DTF), Partial Directed Coherence (PDC)
Information-theoretic: mutual information, transfer entropy
Cross-frequency: phase-amplitude coupling (PAC), amplitude-amplitude coupling (AAC)
Output shape: (n_channels, n_channels) for pairwise metrics — square connectivity matrices

concord-metrics-event

Event detection and characterization.

Spike detection (amplitude threshold + morphology), spike rate per channel
DC shifts and infraslow activity detection
Seizure pattern classification (tonic, clonic, tonic-clonic, etc.)
Pre-ictal spectral acceleration (gamma power rise before onset)
Post-ictal suppression detection
Sleep spindles (12-14 Hz bursts), CCEPs (cortico-cortical evoked potentials)

concord-metrics-network

Graph-theoretic metrics applied to functional connectivity matrices.

Node metrics: degree, betweenness centrality, clustering coefficient, eigenvector centrality
Global metrics: small-world index, modularity, global/local efficiency
Epileptogenicity Index (EI): Bartolomei's EI — quantifies the propensity of each brain region to generate seizures based on high-frequency power dynamics at seizure onset
Operates on connectivity MetricResult (no hard import of connectivity package — receives arrays)

concord-metrics-nonlinear

Measures of signal complexity and chaos.

Entropy: sample entropy (SampEn), permutation entropy, approximate entropy (ApEn)
Chaos: Lyapunov exponents, correlation dimension (D₂)
Scaling: detrended fluctuation analysis (DFA), Hurst exponent
Statistical: kurtosis, skewness (deviations from Gaussianity)

concord-fit

The optimization engine that fits model parameters to recorded data by minimizing the distance between simulated and real metrics.

Planned scope

Optimization algorithms: differential evolution (global), CMA-ES (evolution strategy), Bayesian optimization
Discovery: finds all installed metrics and models via entry_points — no hard imports
Objective functions: distance between simulated MetricResult and measured MetricResult (e.g. PSD shape, band power, PLV)
Parallelization: distributes model evaluations across CPU cores (multiprocessing, since metrics/models are pickle-safe)
Checkpointing: saves optimization state so long runs can be resumed
Uses the existing ParameterVector container (already in concord-core) for parameter values + bounds