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
BoundaryCondition
BrainRegionSeries A series whose values represent latitude
Callable
        ClassReference Reference to a class that can be instantiated and called
Case
ConditionalBlock A single condition and its corresponding equation segment
Coupling
CouplingInput Specification of a coupling input channel for multi-coupling dynamics
DataSource Specification for loading external/empirical data
DerivedVariable
DifferentialOperator
Distribution
Dynamics
Edge A directed edge in a network with coupling and connectivity properties
Equation
        TemporalApplicableEquation
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
Integrator
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
Parameter
        DerivedParameter
Parcellation
PDE Partial differential equation problem definition
PDESolver
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
SpatialDomain
SpatialField
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
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
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
axesOrigin Enter the origin (central point where all axes intersect)
baseline_value Preoperative baseline value of the score
batch_size Batch size for vectorized operations (None = auto)
bc_type
bids_dir Path to BEP017-compliant BIDS directory for loading connectivity matrices
boundaries
boundary_conditions
bounds Constraints on parameter values after update
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
center_coordinates
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
color Add the color code used for visual representation of this entity
comment
condition The condition for this block (e
conditional
conditionals Conditional logic for piecewise equations
conduction_speed Conduction speed for computing delays from distances
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
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
data
data_source
dataLocation
dataset_id
default
defaultImage Add all image files used as visual representation of this common coordinate s…
definition
delayed
dependencies
depends_on Algorithm to use as starting point for optimization
derived_from
derived_from_model
derived_observations Observations derived from combining other observations
derived_parameters
derived_variables
description
diagnosis
dimension Dimensionality of the coupling input (number of coupled values)
directed Whether the edge is directed
discretization
distance_unit Unit for distances/lengths in the network (e
distribution For hierarchical coupling: distribution method (‘broadcast’, ‘weighted’) or c…
doi
domain
downsample_period Intermediate downsampling period (ms)
dt Time step (s)
dtype
duration
dynamics Dynamics model governing this node’s behavior
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_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
evaluator Who performed the rating (e
execution Per-optimization execution configuration (overrides experiment-level defaults…
explorations Parameter exploration/grid search specifications
explored_values
expression The equation to apply when the condition is met
extension
field Primary field being solved for (deprecated; use state_variables)
field_dynamics
file
format Data format: ‘npy’, ‘mat’, ‘csv’, ‘nifti’, etc
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 Reference to a defined Function (by name)
functions
gaussian Indicates whether the noise is Gaussian
generated_at Timestamp when this TimeSeries was generated
geometry Optional file for geometry/ROI mask (e
global_coupling_strength Global scaling factor for all coupling weights
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 Initial values for state variables
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
lo Lower bound or starting value
loader Callable that loads the data (e
local_coupling_term
local_dynamics Default dynamics model for all nodes (used when node
local_states References to state variables from local node (target)
log_scale Whether to use logarithmic spacing
loss Loss function call
manufacturer
max_iterations
mesh
method Integration method (euler, heun, rk4, etc
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
modes
modified
module
modules (Deprecated) Former ad-hoc list; use environment
n Number of points (alternative to step for grid exploration)
n_iterations Number of iterations to run
n_parallel Parallel evaluations
n_regions Total number of regions
n_threads Number of CPU threads per worker (-1 = auto-detect)
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
nodes List of nodes with individual dynamics (optional, for heterogeneous networks)
noise
noise_type
normalization Normalization equation for connectivity weights
notes
number_of_modes
number_of_nodes Number of nodes in the network (derived from nodes if not set)
number_of_regions Number of regions (derived from nodes if not set)
number_of_stages
number_of_subjects Number of subjects in the tractography dataset
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
on_region Mesh/atlas subset where BC applies
operator_type
operators
optimization Parameter optimization configurations
optional
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)
over Dimension to aggregate over (e
package Reference to the software package identity
parameters
parcellation Brain parcellation/atlas reference
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
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
reference DOI, PMID or persistent identifier
references
region Brain region or anatomical label
region_labels
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
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
session_id BIDS session identifier
settings
sex
shape
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
source
source_code
source_experiment Reference to the SimulationExperiment that generated this TimeSeries
source_observations One or more observations to derive from
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_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
system_type
tail
tail_samples Number of samples from the end to use
target Target node ID
target_data Reference to empirical data observation for matching objectives
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
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 Default time unit for the network (e
timepoint Timepoint of assessment (e
timing_info
title
tolerances Abs/rel tolerances
tractogram Reference to tractography data
trajectory The planned trajectory for electrode implantation
transient_time
type
unit
update_expression
update_rules How parameters are updated each iteration
url (Deprecated) Use source_url
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
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
DimensionType Dimensions along which operations can be applied
DiscretizationMethod
ElementType
EnvironmentType
ImagingModality
NoiseType
OperatorType
ReductionType Operations for reducing/aggregating values across dimensions
RequirementRole
SystemType

Types

Type Description

Subsets

Subset Description