The Virtual Brain Data Model

Metadata schema for simulation studies using The Virtual Brain neuroinformatics platform or other dynamic network models of large-scale brain activity.

URI: https://w3id.org/tvbo

Name: tvb-datamodel

Classes

Class Description
Aggregation Specifies how to aggregate values across a dimension
Algorithm A complete specification of an iterative parameter tuning algorithm
AlgorithmInclude Reference to an included algorithm with optional argument overrides
Argument A function argument with explicit value specification
BidsEntities BIDS filename entities (BEP017-aligned) for provenance and data discovery
BoundaryCondition
BrainRegionSeries A series whose values represent latitude
BranchSwitch Specification for switching from a detected bifurcation point to a new branch…
Callable
        ClassReference Reference to a class that can be instantiated and called
Case
ConditionalBlock A single condition and its corresponding equation segment
Continuation Complete specification of a numerical continuation / bifurcation analysis
Coupling
CouplingInput Specification of a coupling input channel for multi-coupling dynamics
DataSource Specification for loading external/empirical data
DerivedVariable
DifferentialOperator
Discretization Discretization method for boundary value problems in continuation (periodic o…
Distribution A probability distribution for sampling parameters or initial conditions
Dynamics
Edge An edge in a network
Equation
        TemporalApplicableEquation
Event A discrete or continuous event that modifies the system during simulation
ExecutionConfig Configuration for computational execution (parallelization, precision, hardwa…
Exploration Parameter space exploration (grid search, sweep)
File
Function A function with explicit input -> transformation -> output flow
        LossFunction A loss function for optimization with optional aggregation
FunctionCall Invocation of a function in a pipeline
GraphGenerator Backend-agnostic graph generator specification
InitialState How to obtain the starting equilibrium or periodic orbit for continuation
Matrix Adjacency matrix of a network
Mesh
NDArray
Network Network specification with nodes, edges, and reusable coupling configurations
Node A node in a network with its own dynamics and properties
Noise
Observation Unified class for all observation/measurement specifications
        DerivedObservation Observation derived from one or more other observations
OptimizationStage A single stage in a multi-stage optimization workflow
        Optimization Configuration for parameter optimization
Option A toolkit-specific key-value option (string name + string value)
Parameter
        DerivedParameter
Parcellation
PDE Partial differential equation problem definition
PDESolver
Provenance W3C PROV-O aligned provenance
RandomStream
Range Specifies a range for array generation, parameter bounds, or grid exploration
RegionMapping Maps vertices to parent regions for hierarchical/aggregated coupling
Sample
SimulationExperiment
SimulationStudy
SoftwareEnvironment
SoftwarePackage Identity information about a software package independent of a specific versi…
SoftwareRequirement
Solver Lightweight specification of a numerical ODE solver / integrator
        Integrator Fixed-step or adaptive ODE integrator with TVB-specific extensions (noise, tr…
SpatialDomain
SpatialField
StateValue A named state variable value for per-node initialization
StateVariable
        FieldStateVariable
Stimulus
TimeSeries Time series data from simulations or measurements
Tractogram Reference to tractography/diffusion MRI data used to derive structural connec…
TuningObjective Defines what the tuning algorithm optimizes for
UpdateRule Defines how a parameter is updated based on observables

Slots

Slot Description
abs_tol Absolute tolerance for ODE integration
absolute_value Absolute value of the score at the time of assessment
accelerator Hardware accelerator: ‘cpu’, ‘gpu’, ‘tpu’
acquisition Acquisition protocol or scanner information
acronym
active_contacts
additional_equations
additive Indicates whether the noise is additive
affect Affect function: what happens when the event triggers
affect_negative Affect on downcrossing (continuous events only)
affect_parameters Parameter symbols modifiable in the affect function
affect_states State variable symbols modifiable in the affect function
age
aggregate How to aggregate the result across dimensions
aggregation How to aggregate over time
algorithm Optimizer for this stage: ‘adam’, ‘adamw’, ‘sgd’, etc
algorithms Iterative parameter tuning algorithms (FIC, EIB, etc
amplitude
anatomicalAxesOrientation Add the axes orientation in standard anatomical terms (XYZ)
apply_every Apply update every N iterations
apply_on_dimension Which dimension to apply the transformation on
arguments Parameters/arguments for the function
atlas
autonomous Whether the system is autonomous (equations do not depend explicitly on time …
average Averaging mode across trials
axesOrigin Enter the origin (central point where all axes intersect)
axis Dimension along which the distribution is sampled
baseline_value Preoperative baseline value of the score
batch_size Batch size for vectorized operations (None = auto)
bc_type
bids BIDS filename entities for this dataset
bids_dir Path to BEP017-compliant BIDS directory for loading connectivity matrices
bothside Continue branch in both directions
boundaries
boundary_conditions
bounds Constraints on parameter values after update
branches Child branches to continue from detected bifurcation points (PO from Hopf, fo…
build_hash Deterministic hash/fingerprint of the resolved dependency set
call_args Arguments passed when calling the instance (call)
callable Software implementation reference (if software-based)
cases
center Add the center coordinate of this entity
class_call Class instantiation and call (alternative to callable/function)
class_reference Direct class reference (alternative to pipeline)
clinical_improvement Observed improvement relative to baseline based on a defined score
clinical_scores
coefficient
cohort BIDS cohort- entity (e
color Add the color code used for visual representation of this entity
comment
condition The condition for this block (e
condition_parameters Parameter symbols accessible in the condition function
condition_states State variable symbols accessible in the condition function
conditional
conditionals Conditional logic for piecewise equations
connectivity
connectivity_ref Reference to connectivity data (_conndata-network_connectivity
constructor_args Arguments passed to init when instantiating the class
contact_id Identifier (e
contacts List of physical contacts along the electrode
container_image Container image reference (e
continuation Override solver settings for this branch
continuations Numerical continuation and bifurcation analysis specifications
coordinate 3D coordinate of the contact center in the defined coordinate space
coordinate_space
coordinates Node coordinates (x,y,z) in the given coordinate space
correlated
correlation
coupling Reusable coupling configurations referenced by edges (e
coupling_function Mathematical function defining the coupling
coupling_inputs
coupling_terms
coupling_variable Whether this state variable is transmitted to connected nodes through the cou…
data
data_file Path to companion data file
data_source
dataLocation
dataset_id
dataset_path Dataset path for array-valued parameters
date_created ISO 8601 (prov:generatedAtTime)
default
defaultImage Add all image files used as visual representation of this common coordinate s…
definition
degree Polynomial degree per mesh interval for collocation
delayed
delta_p Initial parameter offset from the bifurcation point
depends_on Algorithm to use as starting point for optimization
derivative_initial_value Initial value for the first time derivative, used when equation_order > 1
derived_from
derived_from_model
derived_observations Observations derived from combining other observations
derived_parameters
derived_variables
description
descriptor Short alphanumeric identifier for the BIDS desc- filename entity (e
detect_bifurcation Bifurcation detection level
detect_fold Enable fold (limit point) detection
diagnosis
dimension Dimensionality of the coupling input (number of coupled values)
dimension_labels Ordered labels for the matrix columns (dim-1) when the matrix is non-square
directed Whether to generate a directed graph
discretization Discretization method for the branch solution
distance_unit Unit for distances/lengths in the network
distribution Distribution for sampling initial conditions per node
doi
domain
downsample_period Intermediate downsampling period (ms)
ds Initial arc-length step size
ds_max Maximum adaptive step size
ds_min Minimum adaptive step size
dt Time step (s)
dtype Data type for matrix values
duration
dynamics Dictionary of dynamics models keyed by name
ecosystem Package ecosystem or index (e
edge_matrix_files
edges List of directed edges with coupling references (optional, for explicit edge …
efield Metadata about the E-field result for this setting
electrode_id Unique identifier for this electrode
electrode_reference
electrodes
element Element/node index this range applies to
element_domains Per-element domain overrides for heterogeneous parameters
element_type
elements Connectivity (indices) or file reference to topology
engine Primary engine (must appear in environment
entities
environment
environment_type Category: conda, venv, docker, etc
equation
equation_order Order of the time derivative on the LHS
equation_type Type of equation: ‘differential’ (default) means dx/dt = rhs, ‘algebraic’ mea…
evaluator Who performed the rating (e
event_type Type of event trigger mechanism
events Events attached to this node (e
execution Per-optimization execution configuration (overrides experiment-level defaults…
explorations Parameter exploration/grid search specifications
explored_values Explicit explored values for this element
expression The equation to apply when the condition is met
extension
field Primary field being solved for (deprecated; use state_variables)
field_dynamics
file
find_fixpoint Whether to find a fixed point (steady state) before time integration
format Storage format in binary companion (dense, csr, coo)
free
free_parameters Parameters to optimize in this stage
freeze_parameters Parameters from previous stages to freeze (keep at optimized value but not up…
frequency
function Custom distribution function (PDF or sampling callable)
functions
gaussian Indicates whether the noise is Gaussian
generated_at Timestamp when this TimeSeries was generated
generated_by Software/agent identifier (prov:wasGeneratedBy)
geometry Optional file for geometry/ROI mask (e
graph_generator Graph generator specification
groups
handedness
has_reference
hash Build or artifact hash for exact reproducibility (wheel, sdist, image layer)
head
hemisphere Add the hemisphere of this entity
heterogeneous
hi Upper bound or stopping value
history
homepage
hyperparameters Stage-specific hyperparameters (e
id Unique node identifier
imaging_modality Type of imaging modality (BOLD, EEG, MEG, etc
includes Include update rules from other algorithms with optional argument overrides
incoming_states References to state variables from connected nodes (source)
initial_expression Analytic initial condition for the field
initial_state How to obtain the initial equilibrium
initial_value
inner_coupling For hierarchical coupling: inner coupling applied at regional level
input Simple input reference: name of previous function’s output in pipeline
integration Integration settings for optimization simulations (overrides experiment defau…
intensity Optional scalar or vector intensity parameter for noise
intermediate_expressions
iri
key Key/variable name within the file (for
keys Named keys for multi-dimensional coupling
label
labels_dimensions Mapping of dimension names to their labels (JSON-encoded dict)
labels_ordering Ordering of dimensions: Time, State Variable, Space, Mode
latex
learning_rate
learning_rate_schedule Learning rate schedule: ‘constant’, ‘linear’, ‘exponential’
learning_rate_warmup Linear warmup of learning rate from 0 to learning_rate over n_iterations
lefthandside
license
linear_solver Linear solver for the Newton bordered system
lo Lower bound or starting value
loader Callable that loads the data (e
local_coupling_term
local_states References to state variables from local node (target)
log_scale Whether to use logarithmic spacing
loss Loss function call
manufacturer
max_bisection_steps Maximum bisection steps for bifurcation point localization
max_iterations
max_steps Maximum continuation steps
mesh
mesh_file Path to external mesh file (GIFTI, VTK, MSH, FreeSurfer, etc
mesh_format Explicit format override (gifti, freesurfer, meshio, vtk, gmsh)
mesh_intervals Number of mesh intervals (time slices) for collocation or trapezoid methods
method Discretization method
metric Metric equation for matching (e
modality Imaging modality or simulation output type
mode
model
model_equation_ref BIDS ModelEq reference: path to _eq
model_param_ref BIDS ModelParam reference: path to _param
model_type Coarse classification of this model (mean_field, neural_mass, phase_oscillato…
modes
modified
module
modules (Deprecated) Former ad-hoc list; use environment
n Number of points (alternative to step for grid exploration)
n_inversion Number of eigenvalue sign inversions to flag a bifurcation
n_iterations Number of iterations to run
n_parallel Parallel evaluations
n_regions Total number of regions
n_sections Number of shooting sections for shooting or Poincaré methods
n_threads Number of CPU threads per worker (-1 = auto-detect)
n_trials Number of independent trials per grid point
n_vertices Total number of vertices
n_workers Number of parallel workers (maps to pmap devices in JAX, processes in multipr…
name
nativeUnit Add the native unit that is used for this common coordinate space version
network
nev Number of eigenvalues to compute
newton_max_iterations Maximum Newton corrector iterations per step
newton_tol Absolute tolerance for Newton corrector convergence
node_mapping HDF5 dataset path for node-to-parent mapping
nodes List of nodes with individual dynamics (optional, for heterogeneous networks)
noise
noise_type
non_negative All values >= 0
notes
number_of_elements Number of elements (triangles, quads, tetrahedra, etc
number_of_modes
number_of_nodes Number of nodes in the network (derived from nodes if not set)
number_of_stages
number_of_subjects Number of subjects in the tractography dataset
number_of_vertices Number of vertices in the mesh
objective What the algorithm optimizes for
observable Observable to compute at each point
observational_measures BEP017 measure names for observational targets (e
observations References to observations defined in the observations section
observed Observable functions computed from states, inputs, and parameters after simul…
ode_solver ODE solver for flow-based methods (shooting, poincaré)
on_region Mesh/atlas subset where BC applies
operator_type
operators
optimizations Parameter optimization configurations
optional
options Toolkit-specific string options (jacobian type, etc
originalLookupLabel Add the original label of this entity as defined in the parcellation terminol…
output Output variable names to include in simulation results
output_equation Output transformation equation (if equation-based)
outsym Output symbol names for the edge model
over Dimension to aggregate over (e
package Reference to the software package identity
parameters
parcellation Brain parcellation/atlas reference
parent_network Path/URI to parent (coarser) Network
parent_score If this score is a subscore of a broader composite
path
percent_change Percent change compared to preoperative baseline (positive = improvement)
period Sampling period for monitors (ms)
pipeline Ordered sequence of Functions
platform OS / architecture description (e
position Spatial coordinates (x, y, z) of the node
post_expression Post-processing expression applied after coupling
pre_expression Pre-processing expression applied before coupling
precision Floating point precision: ‘float32’ or ‘float64’
preconditioner
preprocessing Optional preprocessing to apply after loading
processing_pipeline Processing pipeline used to generate the tractography
protocols All DBS protocols assigned to this subject
provenance W3C PROV-O aligned provenance
pulse_width
pycode Python code for the equation
quantity_kind Scalar, vector, or tensor
random_seed Base random seed for reproducibility
random_state
recon_path
reconstruction BIDS rec- entity (e
reference DOI, PMID or persistent identifier
references
region Brain region or anatomical label
region_mapping For hierarchical coupling: vertex-to-region mapping for aggregation
regional_connectivity For hierarchical coupling: region-to-region connectivity with weights and del…
regions
rel_tol Relative tolerance for ODE integration
relatedUBERONTerm Add the related anatomical entity as defined by the UBERON ontology
reported_optimum
repository
requirements
requires Observables required by this update rule
righthandside
role
run_id BIDS run number
sample
sampling_period Time between samples (inverse of sampling_rate)
sampling_period_unit Unit of the sampling period (e
sampling_rate Sampling rate in Hz
scale The scale this score belongs to, if applicable
scipy_ode_base
score
seed Random seed for reproducible graph generation
segmentation BIDS seg- entity (e
session_id BIDS session identifier
settings
sex
shape Matrix dimensions [N, M]
simulation_experiments
simulation_period Duration of each simulation step (e
size
skip_t Number of samples to skip at the start (transient removal)
software
software_environment Software environment used to generate this data
solver ODE solver for time_integration method
source
source_branch Name of a previously computed branch (for from_branch method)
source_code
source_experiment Reference to the SimulationExperiment that generated this TimeSeries
source_observations One or more observations to derive from
source_point Which point on the source branch: ‘endpoint’, ‘hopf:1’, ‘fold:2’, a step numb…
source_url Canonical source or repository URL
source_var Output variable from source node to use (e
sources
sparse Whether the coupling uses sparse representations
stages Ordered list of optimization stages
state Per-node initial state variable values, keyed by state variable name
state_variables
state_wise_sigma
step Step size
step_size
steps
stimulation
stimulation_variable
stimulus
structural_measures BEP017 measure names for structural connectivity (e
subject_id BIDS subject identifier
subjects
symbol
symmetry Edge symmetry type for NetworkDynamics
system_type
tail
tail_samples Number of samples from the end to use
target Target node ID (set for explicit edges, absent for template edges)
target_component Component to attach this event to
target_data Reference to empirical data observation for matching objectives
target_network Path or name of the Network whose nodes define the columns of a non-square (p…
target_parameter The parameter to update (e
target_structure Anatomical target structure from a brain atlas
target_value Target value for activity objectives
target_var Input variable on target node to connect to (e
target_variable State variable for activity targets (e
targets State variables this noise applies to; if omitted, applies globally
task_name BIDS task name for the simulation (e
template BIDS tpl- entity (e
tensor_coefficient Optional anisotropic tensor (e
terminology Add the parcellation terminology version used for this brain atlas version
threshold_applied Threshold value applied to the E-field simulation
time
time_dependent
time_integrator e
time_post_surgery Timepoint of assessment in days or months after implantation
time_range Time range for generated TimeSeries (for kernel generators)
time_scale Time unit for the integration / simulation
time_unit Default time unit for the network
timepoint Timepoint of assessment (e
timing_info
title
tol_stability Tolerance on real part of eigenvalue for stability boundary
tolerances Abs/rel tolerances
tractogram Reference to tractography data
trajectory The planned trajectory for electrode implantation
transforms Ordered list of transforms applied to edge property matrices
transient_time
trigger_times Predetermined trigger times for preset_time events
type Graph family name
unit Physical unit of measurement
update_expression
update_rules How parameters are updated each iteration
url (Deprecated) Use source_url
valid_diagonal Self-connections are meaningful
value
values
variable_of_interest
version Version of the instrument (e
version_spec Version or constraint specifier (e
vertex_to_region Array mapping each vertex index to its parent region index
voi Variable of interest index (which state variable to monitor)
volume_data Reference to raw or thresholded volume
warmup Whether to apply learning rate warmup to this update rule
warmup_from Previous stage to initialize from
warmup_source Reference to transient simulation result for history initialization (e
weighted Matrix entries carry weights (not just 0/1)
weighting
window_size Number of samples for windowed aggregation
x X coordinate
y Y coordinate
year
z Z coordinate

Enumerations

Enumeration Description
AggregationType How to aggregate time series data
BoundaryConditionType
ContinuationAlgorithm Predictor-corrector algorithm for numerical continuation
DimensionType Dimensions along which operations can be applied
DiscretizationMethod
ElementType
EnvironmentType
EventType Type of event triggering mechanism
ImagingModality
InitialStateMethod Strategy for obtaining the starting equilibrium or periodic orbit
ModelType Coarse classification of a Dynamics model by its mathematical/biological orig…
NoiseType
NumericalDiscretizationMethod Numerical discretization method for boundary value problems (periodic orbits,…
OperatorType
PhysicalDimension Physical dimension categories for LEMS and dimensional analysis
ReductionType Operations for reducing/aggregating values across dimensions
RequirementRole
SamplingAxis Dimension along which a distribution is sampled
SparseFormat
StandardGraphType Well-known graph generator families with automatic backend mapping
SystemType
UnitEnum Physical units of measurement for model parameters, state variables, and inte…

Types

Type Description

Subsets

Subset Description