The Virtual Brain Ontology

The Virtual Brain Ontology

One specification for a whole brain-network simulation.

From one typed, ontology-grounded spec, tvbo compiles runnable code across many backends and a methods report — and grounds every parameter in a knowledge graph. Studies re-run without drift; models compare even when they share no notation.

Get started Explore the platform

The five steps this documentation follows

  1. 1

    Explore

    Find curated models, networks and published studies in the knowledge base.

  2. 2

    Specify

    Declare the experiment — dynamics, network, observations, figures.

  3. 3

    Generate

    Compile it to backend-native code, plots and a study directory.

  4. 4

    Run

    Execute on a laptop or a cluster, and read the result back.

  5. 5

    Share

    Publish to the platform, and export results as BIDS.

From one source
  • TVB
  • JAX
  • Julia
  • C / CUDA
  • Brian2
  • PyRates
  • NeuroML

Each step opens an overview of the pages beneath it, and every page carries the number of the step it belongs to, in the top-left corner.

From one specification, TVB-O compiles code and a methods report across backends and grounds every entity in a knowledge graph.
One specification, two payoffs — TVB-O compiles code and a methods report across backends (reproducible) and grounds every entity in a knowledge graph (comparable).

Python Software

The tvbo library — specify models, generate code across backends, and run simulations from Python.

API reference →

Platform

The hosted web app — browse models & networks, build experiments, and export, with no install.

Open the app ↗

Data Model

The typed metadata schema behind every spec — classes, fields, and constraints.

Explore the schema →

A first simulation

Install it, then run a whole brain. What a region does, the connectome the regions sit on, and how the result is drawn are one document. This page runs that document and shows what it produced; it contains no plotting code of its own.

from tvbo import SimulationStudy

study = SimulationStudy.from_file("examples/first-simulation/study.yaml")
result = study.run(root="_build/first-simulation")
result
* Owlready2 * Warning: ignoring cyclic subclass of/subproperty of, involving:
  http://uri.interlex.org/tgbugs/uris/readable/atlas/Space

INFO [tvbo.run] [+0s] STEP 1: Running simulation...
INFO [tvbo.run] [+1s]   Simulation period: 800.0 ms, dt: 0.1 ms
INFO [tvbo.run] [+1s]   Transient period: 300.0 ms (settled on (-300.0, 0], warm-started via update_history)
INFO [tvbo.run] [+2s]   Simulation complete.
INFO [tvbo.run] [+2s] Experiment complete.
INFO [tvbo.cli] done: ExperimentResult
INFO [tvbo.cli] wrote ['/Users/leonmartin_bih/tools/tvbo/docs/_build/first-simulation/derivatives/tvbo/exp-1_model-Generic2dOscillator_result.h5', '/Users/leonmartin_bih/tools/tvbo/docs/_build/first-simulation/derivatives/tvbo/exp-1_model-Generic2dOscillator_result.yaml', '/Users/leonmartin_bih/tools/tvbo/docs/_build/first-simulation/derivatives/tvbo/dataset_description.json']
INFO [tvbo.cli] rendering 1 figure(s) -> /Users/leonmartin_bih/tools/tvbo/docs/_build/first-simulation/docs/figures
wrote /Users/leonmartin_bih/tools/tvbo/docs/_build/first-simulation/docs/figures/first_simulation.gif (24 frames)
INFO [tvbo.cli] wrote /Users/leonmartin_bih/tools/tvbo/docs/_build/first-simulation/docs/figures/first_simulation.gif
INFO [tvbo.cli] wrote /Users/leonmartin_bih/tools/tvbo/docs/_build/first-simulation/docs/figures/scripts/plot_first_simulation.py
INFO [tvbo.cli] wrote /Users/leonmartin_bih/tools/tvbo/docs/_build/first-simulation/docs/figures/first_simulation.caption.qmd
wrote /Users/leonmartin_bih/tools/tvbo/docs/_build/first-simulation/docs/figures/first_simulation.png
StudyResult(experiments=['exp-1'], figures=['first_simulation'], results_root='_build/first-simulation/derivatives/tvbo')
first_simulation
Figure 1

Three panels of one movie, and not a line of plotting code behind them. (a) is the connectome the model actually ran on, its nodes coloured by the state they are in. (b) is that same state on the cortical surface, placed by region name rather than by array position, so a value cannot land on its neighbour. (c) is every region’s course, with a cursor marking the instant the other two panels show.

The document behind it

Both halves below are read out of the file the cell above just ran, so this page cannot drift away from what it showed you.

# The landing page's first simulation, run by `tvbo run study.yaml` or by `SimulationStudy.from_file(...).run()`. Its directory is the study root.
tvbo_class: tvbo:SimulationStudy

citekey: FirstSimulation
title: "A first whole-brain simulation"
label: "Eighty-seven regions on a structural connectome, coupled through their tract lengths"
description: >-
  A Generic2dOscillator in its limit-cycle regime on the Desikan-Killiany connectome, coupled linearly through the tract lengths so regions oscillate at a phase lag set by how far apart they are. The figure it declares is one movie: the state on the graph, the same state on the cortical surface, and every region's course with a cursor on the instant the other two panels show.

experiments:
    - id: 1
      label: "A whole-brain simulation"
      dynamics:
          name: Generic2dOscillator
          iri: tvbo:Generic2dOscillator
          # a = 2.0 is TVB's own limit-cycle setting for this model; the rest of the curated set stands.
          parameters: {a: {value: 2.0}}
      network:
          iri: tvbo:DesikanKilliany
          transforms:
              - name: weight
                equation: {rhs: "weight / mean(weight[weight > 0])"}
          coupling:
              c_glob:
                  iri: tvbo:Linear
                  delayed: true
                  incoming_states: [V]
                  parameters: {a: {value: 0.05}}
      integration: {method: Heun, step_size: 0.1, duration: 800.0, transient_time: 300.0}
figures:
    - name: first_simulation
      label: "A first whole-brain simulation"
      layout: "ab/cc"
      width: 170.0
      height: 120.0
      font_size: 7.0
      dpi: 100
      animation: {over: time, frames: 24, fps: 10, format: gif, still: 12}
      panels:
          a:
              kind: network
              label: "The connectome"
              layers:
                  - used: {experiment: 1, output: integration, sel: {variable: V}}
              opts:
                  network: tvbo:DesikanKilliany
                  projection: axial
                  cmap: magma
          b:
              kind: surface
              label: "On the cortex"
              layers:
                  - used: {experiment: 1, output: integration, sel: {variable: V}}
              opts:
                  atlas: tvbo:atlas/DesikanKilliany
                  template: fsaverage
                  hemi: both
                  view: dorsal
                  cmap: magma
                  symmetric: false
          c:
              kind: cartesian
              label: "Regional activity"
              layers:
                  - used: {experiment: 1, output: integration, sel: {variable: V}}
                    mark: line
                    frame: static
                    encoding: {x: time}
                    style: {opts: {linewidth: 0.4, alpha: 0.6}}
                  - used: {experiment: 1, output: integration, sel: {variable: V}}
                    mark: rule
                    frame: cursor
                    encoding: {x: time}
                    style: {color: "#111111", opts: {linewidth: 1.0}}
              opts:
                  xlabel: "Time [ms]"
                  ylabel: "V [a.u.]"

A figure in TVB-O is data, not a script: a mosaic of panels whose layers bind a field of the result container to a visual channel. The binding that says which data is typed prov:used, so declaring where a mark’s numbers come from is the provenance record. See Specify a figure.

The same specification, three ways to reach it

The recipe above is a file, and a file is only one of the places a specification can live. These are alternatives, not steps.

tvbo run examples/first-simulation/study.yaml     # run it, and render the figures it declares
tvbo export jax examples/first-simulation/study.yaml -o solve.py
from tvbo import SimulationStudy

result = SimulationStudy.from_file("examples/first-simulation/study.yaml").run()
result["exp-1"].integration.sel(node="ctx-lh-precentral")
from tvbo import SimulationExperiment

exp = SimulationExperiment(
    label="A whole-brain simulation",
    dynamics={"iri": "tvbo:Generic2dOscillator", "parameters": {"a": {"value": 2.0}}},
    network={
        "iri": "tvbo:DesikanKilliany",
        "coupling": {"c_glob": {"iri": "tvbo:Linear", "delayed": True, "incoming_states": ["V"]}},
    },
    integration={"method": "Heun", "step_size": 0.1, "duration": 800.0},
)
result = exp.run()

Where to start

Getting started

New to TVB-O: one equation to a whole brain, in a single sitting.

The SimulationExperiment

Want the spec: every top-level field, and which ones are required.

Linked experiments in a SimulationStudy

Replicating a paper: many experiments, one study, shared figures.

Interoperability

Coming from another tool: TVB, PyRates, NeuroML and the Julia backends.