Load from BIDS

experiment

classes.experiment

Attributes

Name	Description
sessionid

Classes

Name	Description
SimulationExperiment	The central runnable object in TVBO: a complete brain-network simulation spec.

SimulationExperiment

classes.experiment.SimulationExperiment(**kwargs)

The central runnable object in TVBO: a complete brain-network simulation spec.

Bundles dynamics, coupling, network, integration, observations, and any analysis layers (stimulation, algorithms, explorations, …) into one declarative specification. The same instance can be:

executed in any registered backend (run("jax"), run("tvb"), …)
serialized to YAML, BIDS, openMINDS, or LEMS
rendered as code for inspection or external use (render_code(...))
reported as Markdown or HTML (report(...))

Construct via direct kwargs, from a Dynamics instance, by name from the curated database (from_db), or by loading a YAML / BIDS export.

Examples

from tvbo import Dynamics, SimulationExperiment

exp = SimulationExperiment(dynamics=Dynamics.from_db("Generic2dOscillator"))
result = exp.run("jax", duration=5_000)

# Or fully declarative
exp = SimulationExperiment(
    dynamics={"iri": "tvbo:ReducedWongWangExcInh"},
    coupling={"iri": "tvbo:Linear"},
    network={"parcellation": {"atlas": {"iri": "tvbo:DesikanKilliany"}},
             "tractogram":   {"iri": "tvbo:dTOR"}},
    integration={"method": "Heun", "duration": 10_000, "noise": None},
)

See the Usage / Simulation Experiments page for the full constructor surface and the running-simulations skill for backend choices.

Attributes

Name	Description
horizon	Number of history steps needed given delays and dt, like the old `horizon` attribute.
max_delay	Compute the maximum delay (ms) from the current network/connectome.
network_observation_measures	Map each network-sourced observation to its network measure.
noise_sigma_array	Per-state-variable noise sigma values.

Methods

Name	Description
copy	Return a deep copy of this experiment.
from_bids	Load a SimulationExperiment and TimeSeries from a BIDS BEP034 dataset.
from_datamodel	Create from a datamodel instance by copying its already-normalized
from_db	Load a SimulationExperiment by name from the tvbo database.
from_openminds	Create a SimulationExperiment from openMINDS JSON-LD.
from_platform	Load a simulation experiment from the tvbo platform API.
from_pydantic	Create a SimulationExperiment from a Pydantic model instance.
from_pyrates	Load a SimulationExperiment from a PyRates YAML template file.
from_string	Create a SimulationExperiment from a YAML string.
generate_report	Backward-compatible alias for :meth:`report`.
list_db	List available experiments in the tvbo database.
list_platform_experiments	List available experiments on the tvbo platform.
plot	Plot experiment outputs directly or compose multi-panel layouts.
render	Unified entry point for rendering the experiment in any output format.
render_code	Render generated code in format (back-compat shim around the registry).
render_yaml	Deprecated Render the YAML representation as a string.
report	Render a human-readable report for this experiment.
resolve_network_observations	Resolve network-sourced observations to their matrices.
save	Render via :meth:`render` and persist to disk.
save_model_specification	Save the LEMS simulation file to dir.
setup_monitors	Populate monitors in metadata from simple inputs or runtime wrappers.
supported_export_formats	Return metadata for API/UI export format dropdowns.
symbolic	Symbolic representation of the full experiment equations.
to_bids	Export simulation experiment and results to BIDS-compliant format (BEP034 v1.0.0).
to_lems	Export this experiment as a LEMS Model object.
to_openminds	Export experiment to openMINDS JSON-LD format.
to_yaml	Export the experiment to YAML format.

copy

classes.experiment.SimulationExperiment.copy(**overrides)

Return a deep copy of this experiment.

Use keyword overrides to set attributes on the returned copy.

Errors are not swallowed; if a field can’t be copied, an exception is raised.

from_bids

classes.experiment.SimulationExperiment.from_bids(
    bids_dir,
    subject='01',
    session=None,
    run_to_verify=False,
)

Load a SimulationExperiment and TimeSeries from a BIDS BEP034 dataset.

This method ingests data exported via to_bids() and reconstructs: - The SimulationExperiment with model, network, and integration settings - The TimeSeries data (with 100% fidelity for HDF5 format)

Automatically detects the time series format (HDF5, CIFTI, or TSV).

Parameters

bids_dir : str Path to the root BIDS dataset directory (e.g., ‘./derivatives/tvbo’) subject : str Subject identifier (with or without ‘sub-’ prefix). Default: ‘01’ session : str, optional Session identifier (with or without ‘ses-’ prefix). If not specified and sessions exist, uses the first one. run_to_verify : bool If True, re-run the simulation and compare with loaded TimeSeries. Useful for verifying reproducibility. Default: False.

Returns

tuple[SimulationExperiment, TimeSeries] The reconstructed experiment and time series data.

Examples

exp, ts = SimulationExperiment.from_bids(“./derivatives/tvbo”, subject=“01”) print(ts.shape) (1000, 2, 68, 1)

Verify reproducibility

exp, ts = SimulationExperiment.from_bids( … “./derivatives/tvbo”, … subject=“01”, … run_to_verify=True … )

Access the experiment settings

print(exp.dynamics.name) ‘Generic2dOscillator’

Notes

HDF5 format preserves full dimensionality with 100% fidelity
CIFTI/TSV formats reconstruct from per-state-variable files
Model parameters are restored from eq/ sidecar if available
Network connectivity is restored from net/ directory

from_datamodel

classes.experiment.SimulationExperiment.from_datamodel(dm)

Create from a datamodel instance by copying its already-normalized state.

This avoids the _as_dict → re-init round-trip which breaks on inlined_as_dict fields (the keyed dict is not valid **kwargs for the inner class constructor). Instead we directly copy the __dict__ from the fully-normalised LinkML object and then set the convenience aliases that __init__ would normally provide.

from_db

classes.experiment.SimulationExperiment.from_db(name)

Load a SimulationExperiment by name from the tvbo database.

from_openminds

classes.experiment.SimulationExperiment.from_openminds(source)

Create a SimulationExperiment from openMINDS JSON-LD.

Parameters

source : str or dict Either a file path to a JSON-LD file, or a dict containing JSON-LD data.

Returns

SimulationExperiment New instance constructed from the openMINDS data.

Example

exp = SimulationExperiment.from_openminds(“experiment.jsonld”) exp = SimulationExperiment.from_openminds({“type?”: “tvbo:SimulationExperiment”, …})

from_platform

classes.experiment.SimulationExperiment.from_platform(
    name,
    base_url=TVBO_PLATFORM_URL,
)

Load a simulation experiment from the tvbo platform API.

Fetches the full LinkML-valid YAML definition from the platform.

Parameters

name : str Experiment label/ID (e.g., “RWW_BOLD_FC_Optimization”). base_url : str Platform base URL.

Returns

SimulationExperiment Experiment loaded from the platform.

from_pydantic

classes.experiment.SimulationExperiment.from_pydantic(pyd_obj)

Create a SimulationExperiment from a Pydantic model instance.

Parameters

Name	Type	Description	Default
pyd_obj	Any	A Pydantic BaseModel instance (e.g., from tvbo.datamodel.tvbopydantic)	required

Returns

Name	Type	Description
	SimulationExperiment	SimulationExperiment instance

from_pyrates

classes.experiment.SimulationExperiment.from_pyrates(filepath)

Load a SimulationExperiment from a PyRates YAML template file.

Parses all OperatorTemplates in the file and creates a keyed dict of Dynamics objects.

Parameters

filepath : str Path to PyRates YAML file.

Returns

SimulationExperiment New instance with primary dynamics and network.dynamics for multi-operator files.

Example

exp = SimulationExperiment.from_pyrates(“synaptic_plasticity.yaml”) print(exp.dynamics.name) # ‘tsodyks’ print(list(exp.network.dynamics.keys())) # [‘tsodyks’, ‘depression’, ‘facilitation’]

from_string

classes.experiment.SimulationExperiment.from_string(yaml_string)

Create a SimulationExperiment from a YAML string.

This is useful for defining experiments inline in notebooks or scripts using human-readable YAML syntax.

Parameters

yaml_string : str YAML-formatted string defining the experiment.

Returns

SimulationExperiment New instance populated from the YAML definition.

Example

exp = SimulationExperiment.from_string(’’’ … id: 1 … label: My Experiment … dynamics: … name: JansenRit … parameters: … A: {value: 3.25} … ’’’)

generate_report

classes.experiment.SimulationExperiment.generate_report(
    format='markdown',
    template_name='tvbo-report-experiment',
    outputfile=None,
    derivative_notation='dot',
)

Backward-compatible alias for :meth:report.

list_db

classes.experiment.SimulationExperiment.list_db()

List available experiments in the tvbo database.

list_platform_experiments

classes.experiment.SimulationExperiment.list_platform_experiments(
    base_url=TVBO_PLATFORM_URL,
)

List available experiments on the tvbo platform.

Parameters

base_url : str Platform base URL.

Returns

list[dict] List of experiment summaries.

plot

classes.experiment.SimulationExperiment.plot(
    layout=None,
    panels=None,
    run_kwargs=None,
    auto=True,
    **kwargs,
)

Plot experiment outputs directly or compose multi-panel layouts.

By default (auto=True), this runs the experiment once, infers task-aware panels, and renders a flexible subplot_mosaic layout.

render

classes.experiment.SimulationExperiment.render(format='yaml', **kwargs)

Unified entry point for rendering the experiment in any output format.

Dispatches via the :mod:tvbo.export.registry. All supported formats (YAML, openMINDS, markdown/PDF report, TVB, JAX, tvboptim, Julia, NeuroML/LEMS, …) are looked up by canonical key or alias.

Parameters

format : str Target output format. See :func:tvbo.export.list_formats for the current set. **kwargs Forwarded to the underlying renderer.

Returns

str

render_code

classes.experiment.SimulationExperiment.render_code(format='tvb', **kwargs)

Render generated code in format (back-compat shim around the registry).

render_yaml

classes.experiment.SimulationExperiment.render_yaml()

Deprecated Render the YAML representation as a string. Use to_yaml(filepath=None) instead.

report

classes.experiment.SimulationExperiment.report(
    format='markdown',
    template_name='tvbo-report-experiment',
    outputfile=None,
    derivative_notation='dot',
)

Render a human-readable report for this experiment.

Reuses the model/dynamics report template via Mako include to avoid redundancy.
Summarizes integration, network/connectome, coupling, monitors, stimulation, and software info.

Parameters - format: optional explicit fallback format (‘markdown’ or ‘pdf’) - template_name: base name of the template without extension - outputfile: optional path to write the rendered report; when provided, extension defines output format (.md or .pdf)

resolve_network_observations

classes.experiment.SimulationExperiment.resolve_network_observations()

Resolve network-sourced observations to their matrices.

Pairs :attr:network_observation_measures with the data the network carries (:attr:Network.observations), yielding {obs_name: matrix} ready to pass into the generated run_experiment(network_observations=...). Raises a clear error if a declared measure’s data is absent.

save

classes.experiment.SimulationExperiment.save(
    path,
    format=None,
    metadata_only=True,
    **kwargs,
)

Render via :meth:render and persist to disk.

Parameters

path : str or Path Output file path or directory. When a directory is given the filename is derived from :meth:get_experiment_file_prefix and the correct extension for format (BIDS-style). format : str, optional Export format key (e.g. 'yaml', 'tvb', 'neuroml'). When omitted, inferred from path suffix. metadata_only : bool When True (default) only the textual/metadata artefact is written. When False and the experiment has a network, the network arrays are also saved as an HDF5 sidecar file next to path.

save_model_specification

classes.experiment.SimulationExperiment.save_model_specification(dir)

Save the LEMS simulation file to dir.

.. deprecated:: Use NeuroMLAdapter(experiment).export(dir) from tvbo.adapters.neuroml instead.

setup_monitors

classes.experiment.SimulationExperiment.setup_monitors(**kwargs)

Populate monitors in metadata from simple inputs or runtime wrappers.

supported_export_formats

classes.experiment.SimulationExperiment.supported_export_formats()

Return metadata for API/UI export format dropdowns.

symbolic

classes.experiment.SimulationExperiment.symbolic(
    integrate=False,
    indexed=False,
    delays=False,
)

Symbolic representation of the full experiment equations.

Produces different styles of mathematical output depending on the combination of flags:

integrate	indexed	delays	Description
False	False	False	Dynamics separated, coupling terms as free symbols. Coupling equations shown in `'coupling'` dict.
True	False	False	Coupling substituted into dynamics. State vars remain `y0(t)`.
False	True	False	State vars indexed `y0_i(t)`. \| Coupling shown separately with `[i],[j]`.
True	True	False	Fully integrated with node indices. Ready for network presentation.
	(True)	True	Like above but incoming states carry `y1[j, t - tau[i,j]]` time delay. `delays=True` implies `indexed=True`.

Parameters

integrate : bool Substitute coupling expressions into state equations. indexed : bool Add node index _i to state / derived variables. delays : bool Show time delays on incoming coupling states. Implies indexed=True.

Returns

dict Keys: 'state', 'coupling', 'functions', 'derived_parameters', 'derived', 'parameters'.

to_bids

classes.experiment.SimulationExperiment.to_bids(
    output_dir,
    subject='01',
    session=None,
    description='tvbsim',
    run=None,
    ts_label='sim',
    timeseries=None,
    run_simulation=True,
    **run_kwargs,
)

Export simulation experiment and results to BIDS-compliant format (BEP034 v1.0.0).

This method creates a complete BIDS dataset containing: - Time series data in ts/ directory - Network connectivity in net/ directory - Model equations in eq/ directory - Coordinates in coord/ directory (if available) - JSON sidecar files with full metadata

Parameters

output_dir : str Root directory for the BIDS dataset. subject : str Subject identifier (without ‘sub-’ prefix). Default: ‘01’. session : str, optional Session identifier (without ‘ses-’ prefix). description : str Description label for the output files. Default: ‘tvbsim’. run : int, optional Run number. ts_label : str Time series label (e.g., ‘sim’, ‘bold’, ‘eeg’). Default: ‘sim’. timeseries : TimeSeries, optional Pre-computed TimeSeries. If not provided and run_simulation=True, the simulation will be executed. run_simulation : bool If True and no timeseries provided, run the simulation. Default: True. **run_kwargs Additional arguments passed to the run() method.

Returns

str Path to the created BIDS dataset root directory.

Examples

experiment = SimulationExperiment(…) experiment.to_bids(“./derivatives/tvbo”, subject=“01”, description=“rest”) ‘./derivatives/tvbo’

Or with pre-computed timeseries

ts = experiment.run() experiment.to_bids(“./derivatives/tvbo”, timeseries=ts) ‘./derivatives/tvbo’

Notes

Follows BIDS BEP034 Computational Modeling extension v1.0.0. Uses tvbo format for model equations.

to_lems

classes.experiment.SimulationExperiment.to_lems(
    initial_conditions=1,
    out_path=None,
    out_file=None,
)

Export this experiment as a LEMS Model object.

.. deprecated:: Use NeuroMLAdapter(experiment).render_code() from tvbo.adapters.neuroml instead. This method returns a lems.Model object; the adapter produces a validated XML string that covers all LEMS constructs including ConditionalDerivedVariable and Coupling.

to_openminds

classes.experiment.SimulationExperiment.to_openminds(
    filepath=None,
    base_id=None,
    include_context=True,
)

Export experiment to openMINDS JSON-LD format.

Parameters

filepath : str, optional If provided, write JSON-LD to this file path. base_id : str, optional Base URI for generating id? values (e.g., “https://example.org/simulations”). include_context : bool Whether to include the context? in the output. Default True.

Returns

dict OpenMINDS-compatible JSON-LD dictionary.

Example

exp = SimulationExperiment(…) jsonld = exp.to_openminds() exp.to_openminds(“output.jsonld”, base_id=“https://example.org”)

to_yaml

classes.experiment.SimulationExperiment.to_yaml(filepath=None, format='tvbo')

Export the experiment to YAML format.

Parameters

filepath : str, optional Path to write the YAML file. If None, returns the YAML string. format : str Output format: “tvbo” (default) or “pyrates”.

Returns

str YAML string or filepath if written to file.

experiment

Attributes

Classes

SimulationExperiment

Examples

Attributes

Methods

copy

from_bids

Parameters

Returns

Examples

Verify reproducibility

Access the experiment settings

Notes

See Also

from_datamodel

from_db

from_openminds

Parameters

Returns

Example

from_platform

Parameters

Returns

from_pydantic

Parameters

Returns

from_pyrates

Parameters

Returns

Example

from_string

Parameters

Returns

Example

generate_report

list_db

list_platform_experiments

Parameters

Returns

plot

render

Parameters

Returns

render_code

render_yaml

report

resolve_network_observations

save

Parameters

save_model_specification

setup_monitors

supported_export_formats

symbolic

Parameters

Returns

to_bids

Parameters

Returns

Examples

Or with pre-computed timeseries

Notes

to_lems

to_openminds

Parameters

Returns

Example

to_yaml

Parameters

Returns