tvbo_datamodel

datamodel.tvbo_datamodel

Classes

Name	Description
Aggregation	Specifies how to aggregate values across a dimension. Used for loss functions to define per-element loss with
AggregationType	How to aggregate time series data
Algorithm	A complete specification of an iterative parameter tuning algorithm. Combines update rules, objectives,
AlgorithmInclude	Reference to an included algorithm with optional argument overrides. Allows combining algorithms with different
Argument	A function argument with explicit value specification. Value can be: literal (number/string), reference to input
BrainAtlas	A schema for representing a version of a brain atlas.
BrainRegionSeries	A series whose values represent latitude
ClassReference	Reference to a class that can be instantiated and called. Used for external library classes (e.g., tvboptim.Bold,
ClinicalImprovement	Relative improvement on a defined clinical score.
ClinicalScale	A clinical assessment inventory or structured scale composed of multiple scores or items.
ClinicalScore	Metadata about a clinical score or scale.
CommonCoordinateSpace	A schema for representing a version of a common coordinate space.
ConditionalBlock	A single condition and its corresponding equation segment.
Contact	Individual contact on a DBS electrode.
Coordinate	A 3D coordinate with X, Y, Z values.
CouplingInput	Specification of a coupling input channel for multi-coupling dynamics
DBSProtocol	A protocol describing DBS therapy, potentially bilateral or multi-lead.
DataSource	Specification for loading external/empirical data.
Dataset	Collection of data related to a specific DBS study.
DerivedObservation	Observation derived from one or more other observations. Examples: - fc (from bold) - single source transformation
DimensionType	Dimensions along which operations can be applied
EField	Simulated electric field from DBS modeling.
Edge	A directed edge in a network with coupling and connectivity properties. Edge properties (weight, delay, distance)
Electrode	Implanted DBS electrode and contact geometry.
ExecutionConfig	Configuration for computational execution (parallelization, precision, hardware).
Exploration	Parameter space exploration (grid search, sweep).
Function	A function with explicit input → transformation → output flow. Can be equation-based (symbolic) or software-based
FunctionCall	Invocation of a function in a pipeline. Can reference a defined Function by name, OR inline a callable directly
LossFunction	A loss function for optimization with optional aggregation. Extends Function with aggregation specification for
Matrix	Adjacency matrix of a network.
Network	Network specification with nodes, edges, and reusable coupling configurations. Supports both explicit node/edge
Node	A node in a network with its own dynamics and properties
Observation	Unified class for all observation/measurement specifications. Covers monitors (BOLD, EEG), tuning observables, and
Optimization	Configuration for parameter optimization. Inherits single-stage fields from OptimizationStage. For multi-stage
OptimizationStage	A single stage in a multi-stage optimization workflow. Stages run sequentially, with each stage potentially using
PDE	Partial differential equation problem definition.
ParcellationEntity	A schema for representing a parcellation entity, which is an anatomical location or study target.
ParcellationTerminology	A schema for representing a parcellation terminology, which consists of parcellation entities.
Range	Specifies a range for array generation, parameter bounds, or grid exploration.
ReductionType	Operations for reducing/aggregating values across dimensions
RegionMapping	Maps vertices to parent regions for hierarchical/aggregated coupling
SoftwarePackage	Identity information about a software package independent of a specific version requirement.
SpecimenEnum	A set of permissible types for specimens used in brain atlas creation.
StimulationSetting	DBS parameters for a specific session.
Subject	Human or animal subject receiving DBS.
TimeSeries	Time series data from simulations or measurements. Supports BIDS-compatible export for computational modeling
Tractogram	Reference to tractography/diffusion MRI data used to derive structural connectivity
TuningObjective	Defines what the tuning algorithm optimizes for. Can be an activity target (FIC) or a connectivity target (EIB).
UpdateRule	Defines how a parameter is updated based on observables. Represents iterative learning rules like FIC or EIB

Aggregation

datamodel.tvbo_datamodel.Aggregation(over=None, type='mean')

Specifies how to aggregate values across a dimension. Used for loss functions to define per-element loss with reduction.

AggregationType

datamodel.tvbo_datamodel.AggregationType()

How to aggregate time series data

Algorithm

datamodel.tvbo_datamodel.Algorithm(
    name=None,
    description=None,
    execution=None,
    type=None,
    includes=empty_list(),
    objective=None,
    observations=empty_list(),
    update_rules=empty_dict(),
    hyperparameters=empty_dict(),
    learning_rate=None,
    learning_rate_warmup=False,
    n_iterations=None,
    learning_rate_schedule=None,
    simulation_period=None,
    apply_every=1,
    functions=empty_list(),
    depends_on=empty_list(),
)

A complete specification of an iterative parameter tuning algorithm. Combines update rules, objectives, observations, and hyperparameters.

AlgorithmInclude

datamodel.tvbo_datamodel.AlgorithmInclude(
    algorithm=None,
    arguments=empty_dict(),
)

Reference to an included algorithm with optional argument overrides. Allows combining algorithms with different hyperparameter values.

Argument

datamodel.tvbo_datamodel.Argument(
    name=None,
    description=None,
    value=None,
    unit=None,
)

A function argument with explicit value specification. Value can be: literal (number/string), reference to input (input.key), or cross-observation reference (observation_name.output_key).

BrainAtlas

datamodel.tvbo_datamodel.BrainAtlas(
    name=None,
    coordinateSpace=None,
    abbreviation=None,
    author=empty_list(),
    isVersionOf=None,
    versionIdentifier=None,
    terminology=None,
)

A schema for representing a version of a brain atlas.

BrainRegionSeries

datamodel.tvbo_datamodel.BrainRegionSeries(values=empty_list())

A series whose values represent latitude

ClassReference

datamodel.tvbo_datamodel.ClassReference(
    name=None,
    description=None,
    module=None,
    software=None,
    constructor_args=empty_dict(),
    call_args=empty_dict(),
    warmup_source=None,
)

Reference to a class that can be instantiated and called. Used for external library classes (e.g., tvboptim.Bold, custom monitors). The class is instantiated with constructor_args, then called with call_args. Generalizable pattern: works for tvboptim, TVB, or any Python class.

ClinicalImprovement

datamodel.tvbo_datamodel.ClinicalImprovement(
    score=None,
    baseline_value=None,
    absolute_value=None,
    percent_change=None,
    time_post_surgery=None,
    evaluator=None,
    timepoint=None,
)

Relative improvement on a defined clinical score.

ClinicalScale

datamodel.tvbo_datamodel.ClinicalScale(
    acronym=None,
    name=None,
    version=None,
    domain=None,
    reference=None,
)

A clinical assessment inventory or structured scale composed of multiple scores or items.

ClinicalScore

datamodel.tvbo_datamodel.ClinicalScore(
    acronym=None,
    name=None,
    description=None,
    domain=None,
    reference=None,
    scale=None,
    parent_score=None,
)

Metadata about a clinical score or scale.

CommonCoordinateSpace

datamodel.tvbo_datamodel.CommonCoordinateSpace(
    name=None,
    abbreviation=None,
    unit=None,
    license=None,
    anatomicalAxesOrientation=None,
    axesOrigin=None,
    nativeUnit=None,
    defaultImage=empty_list(),
)

A schema for representing a version of a common coordinate space.

ConditionalBlock

datamodel.tvbo_datamodel.ConditionalBlock(condition=None, expression=None)

A single condition and its corresponding equation segment.

Contact

datamodel.tvbo_datamodel.Contact(contact_id=None, coordinate=None, label=None)

Individual contact on a DBS electrode.

Coordinate

datamodel.tvbo_datamodel.Coordinate(
    coordinateSpace=None,
    x=None,
    y=None,
    z=None,
)

A 3D coordinate with X, Y, Z values.

CouplingInput

datamodel.tvbo_datamodel.CouplingInput(
    name=None,
    description=None,
    dimension=1,
    keys=empty_list(),
)

Specification of a coupling input channel for multi-coupling dynamics

DBSProtocol

datamodel.tvbo_datamodel.DBSProtocol(
    name=None,
    electrodes=empty_list(),
    settings=empty_list(),
    timing_info=None,
    notes=None,
    clinical_improvement=empty_list(),
)

A protocol describing DBS therapy, potentially bilateral or multi-lead.

DataSource

datamodel.tvbo_datamodel.DataSource(
    name=None,
    label=None,
    description=None,
    path=None,
    loader=None,
    format=None,
    key=None,
    preprocessing=None,
)

Specification for loading external/empirical data.

Dataset

datamodel.tvbo_datamodel.Dataset(
    label=None,
    dataset_id=None,
    subjects=empty_dict(),
    clinical_scores=empty_list(),
    coordinate_space=None,
)

Collection of data related to a specific DBS study.

DerivedObservation

datamodel.tvbo_datamodel.DerivedObservation(
    name=None,
    acronym=None,
    label=None,
    description=None,
    equation=None,
    parameters=empty_dict(),
    environment=None,
    time_scale='ms',
    source=None,
    period=None,
    downsample_period=None,
    voi=None,
    imaging_modality=None,
    warmup_source=None,
    data_source=None,
    skip_t=None,
    tail_samples=None,
    aggregation=None,
    window_size=None,
    pipeline=empty_list(),
    class_reference=None,
    source_observations=None,
)

Observation derived from one or more other observations. Examples: - fc (from bold) - single source transformation - fc_corr (from fc and fc_target) - multi-source comparison Unlike regular Observations, these don’t generate monitor classes but are computed from existing observation values.

DimensionType

datamodel.tvbo_datamodel.DimensionType()

Dimensions along which operations can be applied

EField

datamodel.tvbo_datamodel.EField(
    volume_data=None,
    coordinate_space=None,
    threshold_applied=None,
)

Simulated electric field from DBS modeling.

Edge

datamodel.tvbo_datamodel.Edge(
    source=None,
    target=None,
    label=None,
    description=None,
    parameters=empty_dict(),
    source_var=None,
    target_var=None,
    coupling=None,
    directed=False,
)

A directed edge in a network with coupling and connectivity properties. Edge properties (weight, delay, distance) are stored in the parameters slot with optional units.

Electrode

datamodel.tvbo_datamodel.Electrode(
    electrode_id=None,
    manufacturer=None,
    model=None,
    hemisphere='left',
    contacts=empty_list(),
    head=None,
    tail=None,
    trajectory=empty_list(),
    target_structure=None,
    coordinate_space=None,
    recon_path=None,
)

Implanted DBS electrode and contact geometry.

ExecutionConfig

datamodel.tvbo_datamodel.ExecutionConfig(
    n_workers=1,
    n_threads=-1,
    precision='float64',
    accelerator='cpu',
    batch_size=None,
    random_seed=42,
)

Configuration for computational execution (parallelization, precision, hardware).

Exploration

datamodel.tvbo_datamodel.Exploration(
    name=None,
    parameters=empty_dict(),
    label=None,
    description=None,
    execution=None,
    mode='product',
    observable=None,
    n_parallel=1,
)

Parameter space exploration (grid search, sweep).

Function

datamodel.tvbo_datamodel.Function(
    name=None,
    acronym=None,
    label=None,
    equation=None,
    definition=None,
    description=None,
    requirements=empty_list(),
    input=None,
    output=None,
    iri=None,
    arguments=empty_dict(),
    output_equation=None,
    source_code=None,
    callable=None,
    apply_on_dimension=None,
    aggregate=None,
    time_range=None,
)

A function with explicit input → transformation → output flow. Can be equation-based (symbolic) or software-based (callable). In a pipeline, functions are chained: output of one becomes input of next.

FunctionCall

datamodel.tvbo_datamodel.FunctionCall(
    function=None,
    callable=None,
    class_call=None,
    output=None,
    apply_on_dimension=None,
    aggregate=None,
    arguments=empty_dict(),
)

Invocation of a function in a pipeline. Can reference a defined Function by name, OR inline a callable directly for external library functions. OR inline a class_call for classes that need instantiation then calling. Use arguments to specify inputs by name (referencing previous outputs or values).

LossFunction

datamodel.tvbo_datamodel.LossFunction(
    name=None,
    acronym=None,
    label=None,
    equation=None,
    definition=None,
    description=None,
    requirements=empty_list(),
    input=None,
    output=None,
    iri=None,
    arguments=empty_dict(),
    output_equation=None,
    source_code=None,
    callable=None,
    apply_on_dimension=None,
    aggregate=None,
    time_range=None,
)

A loss function for optimization with optional aggregation. Extends Function with aggregation specification for per-element losses.

Matrix

datamodel.tvbo_datamodel.Matrix(
    label=None,
    description=None,
    dataLocation=None,
    x=None,
    y=None,
    values=empty_list(),
)

Adjacency matrix of a network.

Network

datamodel.tvbo_datamodel.Network(
    label=None,
    description=None,
    nodes=empty_list(),
    edges=empty_list(),
    coupling=empty_dict(),
    number_of_regions=1,
    number_of_nodes=1,
    parcellation=None,
    tractogram=None,
    normalization=None,
    global_coupling_strength=None,
    conduction_speed=None,
    bids_dir=None,
    structural_measures=empty_list(),
    observational_measures=empty_list(),
    distance_unit='mm',
    time_unit='ms',
    edge_matrix_files=empty_list(),
)

Network specification with nodes, edges, and reusable coupling configurations. Supports both explicit node/edge representation and matrix-based connectivity (Connectome compatibility).

Node

datamodel.tvbo_datamodel.Node(
    id=None,
    label=None,
    description=None,
    dynamics=None,
    position=None,
    region=None,
    parameters=empty_list(),
    initial_state=empty_list(),
)

A node in a network with its own dynamics and properties

Observation

datamodel.tvbo_datamodel.Observation(
    name=None,
    acronym=None,
    label=None,
    description=None,
    equation=None,
    parameters=empty_dict(),
    environment=None,
    time_scale='ms',
    source=None,
    period=None,
    downsample_period=None,
    voi=None,
    imaging_modality=None,
    warmup_source=None,
    data_source=None,
    skip_t=None,
    tail_samples=None,
    aggregation=None,
    window_size=None,
    pipeline=empty_list(),
    class_reference=None,
)

Unified class for all observation/measurement specifications. Covers monitors (BOLD, EEG), tuning observables, and derived quantities. Pipeline is a sequence of Functions with input → output flow.

Optimization

datamodel.tvbo_datamodel.Optimization(
    name=None,
    label=None,
    description=None,
    free_parameters=empty_list(),
    algorithm='adam',
    learning_rate=0.001,
    max_iterations=100,
    hyperparameters=empty_dict(),
    freeze_parameters=empty_list(),
    warmup_from=None,
    execution=None,
    integration=None,
    loss=None,
    stages=empty_dict(),
    depends_on=None,
)

Configuration for parameter optimization. Inherits single-stage fields from OptimizationStage. For multi-stage workflows, use ‘stages’ (ignores inherited single-stage fields). Loss equation references observations directly by name.

OptimizationStage

datamodel.tvbo_datamodel.OptimizationStage(
    name=None,
    label=None,
    description=None,
    free_parameters=empty_list(),
    algorithm='adam',
    learning_rate=0.001,
    max_iterations=100,
    hyperparameters=empty_dict(),
    freeze_parameters=empty_list(),
    warmup_from=None,
)

A single stage in a multi-stage optimization workflow. Stages run sequentially, with each stage potentially using different parameters, shapes, learning rates, and algorithms.

PDE

datamodel.tvbo_datamodel.PDE(
    label=None,
    description=None,
    parameters=empty_dict(),
    domain=None,
    mesh=None,
    state_variables=empty_list(),
    field=None,
    operators=empty_list(),
    sources=empty_list(),
    boundary_conditions=empty_list(),
    solver=None,
    derived_parameters=empty_list(),
    derived_variables=empty_list(),
    functions=empty_list(),
)

Partial differential equation problem definition.

ParcellationEntity

datamodel.tvbo_datamodel.ParcellationEntity(
    name=None,
    abbreviation=None,
    alternateName=empty_list(),
    lookupLabel=None,
    hasParent=empty_list(),
    ontologyIdentifier=empty_list(),
    versionIdentifier=None,
    relatedUBERONTerm=None,
    originalLookupLabel=None,
    hemisphere=None,
    center=None,
    color=None,
)

A schema for representing a parcellation entity, which is an anatomical location or study target.

ParcellationTerminology

datamodel.tvbo_datamodel.ParcellationTerminology(
    label=None,
    dataLocation=None,
    ontologyIdentifier=empty_list(),
    versionIdentifier=None,
    entities=empty_list(),
)

A schema for representing a parcellation terminology, which consists of parcellation entities.

Range

datamodel.tvbo_datamodel.Range(
    lo='0',
    hi=None,
    step=None,
    n=None,
    log_scale=False,
)

Specifies a range for array generation, parameter bounds, or grid exploration.

ReductionType

datamodel.tvbo_datamodel.ReductionType()

Operations for reducing/aggregating values across dimensions

RegionMapping

datamodel.tvbo_datamodel.RegionMapping(
    label=None,
    description=None,
    dataLocation=None,
    vertex_to_region=empty_list(),
    n_vertices=None,
    n_regions=None,
)

Maps vertices to parent regions for hierarchical/aggregated coupling

SoftwarePackage

datamodel.tvbo_datamodel.SoftwarePackage(
    name=None,
    description=None,
    homepage=None,
    license=None,
    repository=None,
    doi=None,
    ecosystem=None,
)

Identity information about a software package independent of a specific version requirement.

SpecimenEnum

datamodel.tvbo_datamodel.SpecimenEnum()

A set of permissible types for specimens used in brain atlas creation.

StimulationSetting

datamodel.tvbo_datamodel.StimulationSetting(
    electrode_reference=None,
    amplitude=None,
    frequency=None,
    pulse_width=None,
    mode=None,
    active_contacts=empty_list(),
    efield=None,
)

DBS parameters for a specific session.

Subject

datamodel.tvbo_datamodel.Subject(
    subject_id=None,
    age=None,
    sex=None,
    diagnosis=None,
    handedness=None,
    protocols=empty_list(),
    coordinate_space=None,
)

Human or animal subject receiving DBS.

TimeSeries

datamodel.tvbo_datamodel.TimeSeries(
    label=None,
    description=None,
    dataLocation=None,
    data=None,
    time=None,
    sampling_rate=None,
    sampling_period=None,
    sampling_period_unit='ms',
    unit=None,
    labels_ordering=empty_list(),
    labels_dimensions=None,
    source_experiment=None,
    generated_at=None,
    software_environment=None,
    task_name=None,
    subject_id=None,
    session_id=None,
    run_id=None,
    modality=None,
    model_equation_ref=None,
    model_param_ref=None,
    connectivity_ref=None,
)

Time series data from simulations or measurements. Supports BIDS-compatible export for computational modeling (BEP034).

Tractogram

datamodel.tvbo_datamodel.Tractogram(
    name=None,
    label=None,
    description=None,
    data_source=None,
    number_of_subjects=None,
    acquisition=None,
    processing_pipeline=None,
    reference=None,
)

Reference to tractography/diffusion MRI data used to derive structural connectivity

TuningObjective

datamodel.tvbo_datamodel.TuningObjective(
    label=None,
    description=None,
    type=None,
    target_variable=None,
    target_value=None,
    target_data=None,
    metric=None,
)

Defines what the tuning algorithm optimizes for. Can be an activity target (FIC) or a connectivity target (EIB).

UpdateRule

datamodel.tvbo_datamodel.UpdateRule(
    name=None,
    target_parameter=None,
    equation=None,
    description=None,
    bounds=None,
    warmup=None,
    requires=empty_list(),
)

Defines how a parameter is updated based on observables. Represents iterative learning rules like FIC or EIB updates. Functions from experiment.functions are available in the equation.