← Back to home

Research prototype

CerebralFlow

A research prototype for moving physiological signals through validation before they drive coupled-oscillator simulations.

Python · SciPy · NumPy · Kuramoto 2025 GitHub repo ↗

SUMMARY

Brain-dynamics digital-twin framework using Hilbert phases, PLI/wPLI connectivity, surrogate testing, and time-varying Kuramoto networks.

Problem

Brain-signal pipelines can fool themselves if connectivity estimates are not checked against a null model before driving a simulation.

What I built

I built a pipeline from physiological signals to Hilbert phases, PLI/wPLI connectivity, surrogate null tests, and a time-varying Kuramoto oscillator network.

Architecture / system design

The architecture gates each stage: signal -> phase extraction -> connectivity -> statistical null test -> generative Kuramoto simulation.

Failure modes / what broke

The central failure mode is false structure: without surrogate testing, the simulation can faithfully reproduce noise dressed up as connectivity.

Proof / metrics / tests

The case study preserves the validation pipeline and the Kuramoto architecture diagram from the current page.

Lessons learned

For research software, the most important engineering boundary is often the statistical one: prevent one stage from laundering assumptions into the next.

field notes

Expanded field notes

WHAT MAKES THIS RIGOROUS

A research-engineering prototype: a pipeline with clear stages (signal → connectivity → validation → generative simulation), each one independently inspectable, with a statistical null model so the output of one stage is not allowed to fool the next.

CerebralFlow is a research-prototype framework for constructing "digital twins" of brain dynamics — pipelines that take physiological signals, extract a functional network from them, validate that network against random null models, and then drive a generative simulation that reproduces the observed activity.

The signal side uses Hilbert transforms to extract instantaneous phase and intrinsic frequency per channel. The connectivity side uses Phase Lag Index and weighted PLI to estimate coupling while suppressing volume-conduction artifacts. The validation side generates phase-shuffled surrogates and runs a significance test — so you know whether the connectivity you measured is real structure or noise dressed up as structure.

DESIGN NOTE

The unglamorous part of neural-signal work is that correlation between two phase-locked sine waves isn't connectivity — volume conduction will fake any structure you want. PLI throws away the zero-lag component on principle. Surrogate testing then proves the remainder is non-random. Without these two steps the simulation is decorative; with them, it's a hypothesis.

The simulation engine is a time-varying Kuramoto network — a coupled-oscillator model whose generative dynamics, calibrated to the data, can be perturbed to ask "what happens if we stimulate node X?" That's the digital-twin promise: you simulate before you intervene.

example pipeline output

step 1   signal data inversion
  extracted phases shape: (10, 1024)
  estimated frequencies:   mean = 10.12 Hz

step 1.5 statistical validation (surrogates)
  generating 20 phase-shuffled surrogates...
  observed mean connectivity: 0.4215
  surrogate mean (N=20):      0.4208
  z-score: 0.15  ·  p-value: 0.4500
  result is NOT statistically significant
   (expected — input was random noise)

step 1.6 advanced connectivity (PLI)
  PLI matrix mean: 0.3805

step 9   closed-loop optimization
  final error: 1.0520

pipeline completed successfully.

fig. 9 — signals become connectivity become a generative model — validated against random nulls before anything is simulated.

hover or tab through any stage to trace the pipeline

contact

Open to backend systems, AI infrastructure, and product engineering roles.

yehiasaidgewily@gmail.com GitHub LinkedIn