Export BOLD observation model output
types
data.types
Classes
| Name | Description |
|---|---|
| AlgorithmResult | Result of an iterative algorithm (FIC, EIB, etc.). |
| ExperimentResult | Result from a complete experiment run. |
| ExplorationResult | Result of parameter exploration (grid search). |
| InferenceResult | Result of Bayesian inference (MCMC posterior over parameters). |
| ObservationResult | Result from an observation pipeline with named outputs. |
| OptimizationResult | Result of gradient-based optimization. |
| SimulationResult | Output from a single simulation run with its computed observations. |
| SimulationState | |
| TimeSeries | Time-series dataType with JAX pytree support, domain-specific analysis, |
AlgorithmResult
data.types.AlgorithmResult(
name=None,
state=None,
history=None,
pre_tuning=None,
post_tuning=None,
post_tuning_observations=None,
n_iterations=None,
hyperparameters=None,
state_names=None,
**kwargs,
)Result of an iterative algorithm (FIC, EIB, etc.).
Provides structured access to algorithm outputs with consistent naming regardless of which algorithm was run.
Attributes
name : str Algorithm name state : Bunch Final state with tuned parameters history : Bunch Per-iteration tracking: parameters, observations, metrics pre_tuning : SimulationResult Simulation BEFORE algorithm (for comparison) post_tuning : SimulationResult Simulation AFTER algorithm with attached observations n_iterations : int Number of iterations run hyperparameters : Bunch Algorithm hyperparameters used (eta, window_size, etc.) convergence : Bunch Convergence metrics (final values, deltas, etc.)
Methods
| Name | Description |
|---|---|
| get | Dict-like get for backward compat with Bunch-based code. |
get
data.types.AlgorithmResult.get(key, default=None)Dict-like get for backward compat with Bunch-based code.
ExperimentResult
data.types.ExperimentResult(
integration=None,
explorations=None,
algorithms=None,
optimizations=None,
continuations=None,
data_sources=None,
name=None,
source=None,
**kwargs,
)Result from a complete experiment run.
Mirrors the SimulationExperiment schema structure: integration, algorithms, optimizations, explorations, continuations. Accepts both new-style explicit fields and old-style results=Bunch constructor for backward compatibility.
Attributes
integration : SimulationResult or None Primary simulation output with its observations and transient. algorithms : dict Algorithm results keyed by name. optimizations : dict Optimization results keyed by name. explorations : dict Exploration results keyed by name. continuations : dict Bifurcation/continuation results keyed by name. data_sources : dict External/empirical data (not from simulations). name : str or None Experiment name. source : SimulationExperiment or None Back-reference to input specification.
Methods
| Name | Description |
|---|---|
| export | Export results and metadata to a BIDS-compatible directory. |
| from_timeseries | Create an ExperimentResult from a TVBO TimeSeries. |
| from_tvb | Create an ExperimentResult from a TVB simulator and its run output. |
| plot | Dispatch plot to the most relevant sub-result. |
export
data.types.ExperimentResult.export(
output_dir,
subject='01',
session=None,
description='tvbsim',
)Export results and metadata to a BIDS-compatible directory.
Writes experiment specification as YAML and simulation data as netCDF/HDF5, following BEP034 directory conventions::
output_dir/
├── dataset_description.json
├── sub-{subject}/
│ ├── sub-{subject}_desc-{desc}_experiment.yaml
│ └── ts/
│ ├── sub-{subject}_desc-{desc}_ts-sim_State.nc
│ ├── sub-{subject}_desc-{desc}_ts-sim_State.json
│ └── sub-{subject}_desc-{desc}_ts-{obs}_BOLD.nc (per observation)Parameters
output_dir : str or Path Root output directory (created if it doesn’t exist). subject : str BIDS subject label (default "01"). session : str or None BIDS session label (optional). description : str BIDS desc- entity (default "tvbsim").
Returns
pathlib.Path Path to the output directory.
from_timeseries
data.types.ExperimentResult.from_timeseries(
ts,
source=None,
name=None,
**extras,
)Create an ExperimentResult from a TVBO TimeSeries.
Converts a raw TimeSeries (as returned by JAX, PyRates, NetworkDynamics, etc.) into the standard ExperimentResult wrapper.
Parameters
ts : TimeSeries Simulation output with .data, .time, .labels_dimensions. source : SimulationExperiment, optional Back-reference to the experiment that produced this result. name : str, optional Experiment label. **extras Additional attributes to store (e.g. sol, graph).
Returns
ExperimentResult
from_tvb
data.types.ExperimentResult.from_tvb(simulator, result=None)Create an ExperimentResult from a TVB simulator and its run output.
Wraps TVB simulation output into the standard TVBO result structure:
result.integration— primary monitor as SimulationResult (xr.DataArray)result.integration.observations['MonitorName']— one TimeSeries per additional monitor, keyed by the TVB monitor class name
Parameters
simulator : tvb.simulator.simulator.Simulator A configured TVB simulator. result : list of (time_array, data_array) tuples, optional Output of simulator.run(). If None, the simulator is run using its simulation_length.
Returns
ExperimentResult
plot
data.types.ExperimentResult.plot(**kwargs)Dispatch plot to the most relevant sub-result.
ExplorationResult
data.types.ExplorationResult(
name=None,
grid=None,
results=None,
axes=None,
observable=None,
dt=None,
output_names=None,
observations=None,
**kwargs,
)Result of parameter exploration (grid search).
A thin wrapper around tvboptim exploration outputs that provides: - Access to raw results (flat or grid-shaped) - Axis information for parameter values - Utility methods for finding optimal points and slicing - Time series plotting for parameter sweeps (when observable returns time series)
Designed to work with tvboptim’s Space and ParallelResult directly, while also supporting other exploration backends.
Supports two result types: - Scalar results: Each grid point produces a scalar (e.g., loss function). Stored flat, reshaped via as_grid(), with optimal point tracking. - Time series results: Each grid point produces a time series (e.g., model output). Stored as (n_grid, n_time, ...), with plot() support.
Attributes
name : str Exploration name grid : Space Parameter grid specification (tvboptim Space object) results : jnp.ndarray Observable values at each grid point (flat for scalars, multi-dim for time series) axes : list List of axis info (Bunch with name, lo, hi, n, values) observable : str Name of observable computed optimal : Bunch Best point found (parameters, value, index) — only for scalar results shape : tuple Grid shape derived from axes is_timeseries : bool True if results contain time series per grid point dt : float Time step for time series results (optional) output_names : list[str] Names of output variables (e.g., [‘v_pyr’]) for time series results
Methods
| Name | Description |
|---|---|
| as_grid | Reshape flat results to grid shape. |
| plot | Plot exploration results. |
| slice | Get a slice of results with some parameters fixed. |
as_grid
data.types.ExplorationResult.as_grid()Reshape flat results to grid shape.
Returns
jnp.ndarray Results reshaped to (n_axis1, n_axis2, …) matching axes order. For time series, returns (n_axis1, …, n_time, …) as-is.
plot
data.types.ExplorationResult.plot(
figsize=None,
sharex=True,
ax=None,
overlay=False,
**kwargs,
)Plot exploration results.
For time series results: subplots for each parameter value by default, or a single overlaid axis when overlay=True. For scalar results: line plot (1D) or filled-contour heatmap (2D), drawn into ax if given.
slice
data.types.ExplorationResult.slice(**fixed_params)Get a slice of results with some parameters fixed.
Example: result.slice(G=0.5) returns 1D slice at G=0.5
InferenceResult
data.types.InferenceResult(
name=None,
posterior=None,
diagnostics=None,
**kwargs,
)Result of Bayesian inference (MCMC posterior over parameters).
Attributes
name : str Inference name (the inferences: key). posterior : dict Posterior samples keyed by parameter dotted-name (the priors keys), each an array of length num_samples (× num_chains). diagnostics : dict Sampler diagnostics (per-parameter mean/std/r_hat/n_eff etc., as returned by numpyro.diagnostics.summary).
Methods
| Name | Description |
|---|---|
| mean | Posterior mean per parameter. |
| std | Posterior standard deviation per parameter. |
mean
data.types.InferenceResult.mean()Posterior mean per parameter.
std
data.types.InferenceResult.std()Posterior standard deviation per parameter.
ObservationResult
data.types.ObservationResult()Result from an observation pipeline with named outputs.
Exposes pipeline outputs as attributes (e.g., result.psd, result.frequencies) while maintaining NativeSolution-like interface (.data, .time, .dt).
Attributes
| Name | Description |
|---|---|
| data | Primary data output (alias for ys). |
| time | Time array (alias for ts). |
OptimizationResult
data.types.OptimizationResult(
name=None,
state=None,
history=None,
simulation=None,
n_steps=None,
hyperparameters=None,
**kwargs,
)Result of gradient-based optimization.
Provides structured access to optimization outputs including loss trajectory, parameter evolution, and final simulation.
Attributes
name : str Optimization/loss function name state : Bunch Final optimized state (alias: fitted_params) history : Bunch Per-step tracking: loss values, states, gradients simulation : SimulationResult Post-optimization simulation with attached observations loss_trajectory : jnp.ndarray Loss values at each step (convenience accessor) n_steps : int Number of optimization steps final_loss : float Final loss value hyperparameters : Bunch Optimizer settings (learning_rate, algorithm, etc.)
Methods
| Name | Description |
|---|---|
| plot | Plot optimization results. |
plot
data.types.OptimizationResult.plot(
type='summary',
ax=None,
figsize=None,
**kwargs,
)Plot optimization results.
Parameters
type : str 'summary' (default) – loss curve + parameter trajectories. 'loss' – loss curve only. 'parameters' – free-parameter evolution over steps. 'state' – final fitted parameter values (bar charts). ax : matplotlib.axes.Axes, optional Target axes (single-panel plots only, i.e. type=‘loss’). figsize : tuple, optional **kwargs Forwarded to matplotlib plot calls.
SimulationResult
data.types.SimulationResult(
data=None,
observations=None,
transient=None,
*,
result=None,
state_names=None,
nodes=None,
units=None,
**kwargs,
)Output from a single simulation run with its computed observations.
Stores simulation data as an xr.DataArray with named dimensions (time, variable, node[, mode][, trial]). Observations are bound to the simulation that produced them.
Accepts both new-style (data=xr.DataArray) and legacy (result=NativeSolution, state_names=[...]) constructor signatures for backward compatibility with generated template code.
Attributes
data : xr.DataArray or None Simulation data with named dims and coords. observations : dict Computed observations from this simulation (BOLD, FC, etc.). transient : SimulationResult or None Warm-up simulation result that preceded this one.
Attributes
| Name | Description |
|---|---|
| coords | Coordinates of the data array. |
| dims | Dimension names of the data array. |
| state_names | State variable names from data coordinates. |
| time | Time values as numpy array (backward compatible). |
| units | Unit mapping {variable_name: unit_string} for state/derived variables. |
Methods
| Name | Description |
|---|---|
| animate | Animate simulation results. |
| isel | Integer-based selection returning a new SimulationResult. |
| plot | Plot simulation results. |
| sel | Label-based selection returning a new SimulationResult. |
| to_timeseries | Convert to a full TimeSeries object for plotting and analysis. |
animate
data.types.SimulationResult.animate(type=None, **kwargs)Animate simulation results.
Parameters
type : str or list of str, optional Single panel type: ‘network’ — nodes colored by state on graph layout. ‘phase’ — trailing trajectory in phase space. ‘timeseries’ — evolving time-series traces. ‘pendulum’ — dual-panel: pendulum bob + timeseries. A state variable name — selects that variable, then animates. List of panel types for custom multi-panel layout: e.g. ['pendulum_bob', 'timeseries'], ['phase', 'timeseries'] If None, auto-selects based on available metadata. **kwargs Forwarded to the animation function.
Returns
matplotlib.animation.FuncAnimation
isel
data.types.SimulationResult.isel(**kw)Integer-based selection returning a new SimulationResult.
plot
data.types.SimulationResult.plot(ax=None, type='timeseries', **kwargs)Plot simulation results.
Parameters
ax : matplotlib.axes.Axes, optional Axes to plot on (single-panel plots only). type : str Plot type: ‘timeseries’ (default), ‘phase’/‘state-space’, ‘vector_field’, ‘eeg’, ‘power_spectrum’, ‘raster’. **kwargs Forwarded to the underlying plot function in tvbo.plot.
sel
data.types.SimulationResult.sel(**kw)Label-based selection returning a new SimulationResult.
to_timeseries
data.types.SimulationResult.to_timeseries()Convert to a full TimeSeries object for plotting and analysis.
Returns
TimeSeries 4D time series (Time, State Variable, Space, Mode)
SimulationState
data.types.SimulationState(
initial_conditions,
network,
dt,
noise,
parameters,
stimulus,
monitor_parameters,
nt,
)Attributes
| Name | Description |
|---|---|
| state_variables | Ergonomic proxy: state.state_variables.V.noise.sigma = 0.02 |
Methods
| Name | Description |
|---|---|
| convert_dtype | Convert the dtype of the parameter pytree. |
| set_sigma_many | Set multiple sigma values using a dict: { ‘V’: 0.02, ‘W’: 0.0 } |
convert_dtype
data.types.SimulationState.convert_dtype(target_dtype=jnp.float32)Convert the dtype of the parameter pytree.
Useful for converting between 32 and 64 bit types.
Parameters
pytree : pytree The parameter tree whose dtype needs to be converted. target_dtype : jnp.dtype, optional The target dtype to convert to. Defaults to jnp.float32.
Returns
converted_pytree : pytree The parameter tree with converted dtype.
Notes
This method recursively traverses the pytree structure and converts all leaf nodes to the specified target dtype. It preserves the overall structure of the pytree while changing the dtype of its elements.
set_sigma_many
data.types.SimulationState.set_sigma_many(mapping)Set multiple sigma values using a dict: { ‘V’: 0.02, ‘W’: 0.0 }
TimeSeries
data.types.TimeSeries(
time,
data,
network=None,
title='TimeSeries',
sample_period=None,
labels_dimensions={},
units=None,
)Time-series dataType with JAX pytree support, domain-specific analysis, and visualization methods.
Attributes
| Name | Description |
|---|---|
| sample_period_ms | :returns sample_period is ms |
| sample_rate | :returns samples per second [Hz] |
Methods
| Name | Description |
|---|---|
| animate | Animate timeseries on a graph layout. |
| calculate_frequency | Calculate the dominant frequency of the time series data using FFT. |
| compute_normalised_average_power | Compute normalized average power spectrum using FFT. |
| convert_units | Convert units for a specific dimension and return a new TimeSeries. |
| copy | Return a deep copy of the current instance. |
| duplicate | Fast shallow-copy-based duplication with attribute update. |
| plot_eeg | Plot each region as a separate channel stacked vertically on a single axes |
| plot_power_spectrum | Plot the power spectrum with normalized average power computed via FFT. |
| summary_info | Gather scientifically interesting summary information from an instance of this datatype. |
| to_bids | Export TimeSeries data to BIDS-compliant format (BEP034). |
animate
data.types.TimeSeries.animate(
state=0,
format='dots',
interval=50,
cmap='viridis',
node_size=120,
figsize=(10, 4),
)Animate timeseries on a graph layout.
Each node is a dot positioned by the graph layout; its color reflects the timeseries value of the selected state variable over time.
Parameters
state : int or str State variable index or name to animate. format : str Animation format. Currently only 'dots' is supported. interval : int Milliseconds between frames. cmap : str Matplotlib colormap name. node_size : int Scatter point size. figsize : tuple Figure size (width, height).
Returns
matplotlib.animation.FuncAnimation The animation object (render with HTML(ani.to_jshtml()) in Jupyter, or ani.save(...)).
calculate_frequency
data.types.TimeSeries.calculate_frequency(state_variable=None, region=0, mode=0)Calculate the dominant frequency of the time series data using FFT.
Returns
| Name | Type | Description |
|---|---|---|
| float | float | Dominant frequency in Hz. |
compute_normalised_average_power
data.types.TimeSeries.compute_normalised_average_power(VOI=None)Compute normalized average power spectrum using FFT.
Parameters
VOI : str, optional Variable of interest to analyze. Required if multiple state variables exist.
Returns
frequency : ndarray Frequency values in Hz power : ndarray Normalized average power values
convert_units
data.types.TimeSeries.convert_units(dimension, target_unit)Convert units for a specific dimension and return a new TimeSeries.
Parameters:
dimension : str Dimension to convert (‘time’, ‘state’, ‘region’, ‘mode’) target_unit : str Target unit to convert to
Returns:
TimeSeries New TimeSeries with converted values
copy
data.types.TimeSeries.copy()Return a deep copy of the current instance.
duplicate
data.types.TimeSeries.duplicate(**kwargs)Fast shallow-copy-based duplication with attribute update.
plot_eeg
data.types.TimeSeries.plot_eeg(
VOI=None,
mode=0,
spacing=None,
normalize=False,
channel_labels=True,
ax=None,
linewidth=0.5,
**kwargs,
)Plot each region as a separate channel stacked vertically on a single axes (EEG-like representation).
Parameters
VOI : str | None Variable of interest to plot. If None and multiple variables exist, the first one is used. mode : int Mode index to select. spacing : float | None Vertical spacing between channels. If None, computed from data (median std). normalize : bool If True, z-score each channel before plotting. channel_labels : bool If True, add region labels at the channel offsets on the y-axis. ax : matplotlib.axes.Axes | None Axes to plot on. If None, a new figure and axes are created. color : str Line color for all channels. linewidth : float Line width for plotted channels. **kwargs : dict Additional kwargs forwarded to matplotlib plot.
Returns
matplotlib.figure.Figure | None Returns a figure if it creates one; otherwise None.
plot_power_spectrum
data.types.TimeSeries.plot_power_spectrum(
VOI=None,
ROI='mean',
mode=0,
bands=None,
colors=None,
ax=None,
label='simulation',
**kwargs,
)Plot the power spectrum with normalized average power computed via FFT.
Parameters: - VOI: Variable of Interest, typically selecting subsets of data. - ROI: Region of Interest (“mean” or index). - mode: Mode index for selecting data. - bands: Dictionary of frequency bands to highlight. - colors: Custom colors for frequency bands. - ax: Matplotlib Axes object to plot on. - label: Label for the plot. - kwargs: Additional plotting arguments.
Returns: - Matplotlib figure if ax is None, otherwise None.
summary_info
data.types.TimeSeries.summary_info()Gather scientifically interesting summary information from an instance of this datatype.
to_bids
data.types.TimeSeries.to_bids(
output_dir,
subject='01',
session=None,
description=None,
run=None,
suffix='State',
experiment=None,
include_model=True,
include_connectivity=True,
timeseries_format='cifti',
)Export TimeSeries data to BIDS-compliant format (BEP034).
Creates a BIDS dataset structure following the Computational Model Specification (BEP034 v1.0.0) with: - net/: Network connectivity files (weights, distances) - ts/: Time series data files (CIFTI-2 ptseries or TSV) - eq/: Model equations (tvbo format) - coord/: Region coordinates (if available) - JSON sidecar files with metadata
Uses pydantic models for metadata serialization and pybids patterns for BIDS-compliant filename generation.
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, optional Description label for the output files. If not provided, uses the model name from experiment (e.g., ‘wilsoncowan’). run : int, optional Run number. suffix : str BIDS suffix indicating the observation/output type: - ‘State’ (default): Raw neural output (no observation model) - ‘BOLD’: fMRI BOLD signal (output convolved with HRF) - ‘EEG’: EEG signal (output with EEG forward model) - ‘MEG’: MEG signal (output with MEG forward model) The ts entity (ts-V, ts-W, ts-Diff) identifies which output variable, which can be a state variable or derived output (e.g., Diff: V-W). The suffix indicates the observation transformation applied. experiment : SimulationExperiment, optional The source simulation experiment for full provenance tracking. If not provided, uses self.source_experiment if available. include_model : bool Whether to export model equations. Default: True. include_connectivity : bool Whether to export connectivity data. Default: True. timeseries_format : str Format for time series output. Options: - ‘cifti’ (default): CIFTI-2 ptseries.nii files with named parcels. Splits data by state variable into separate files. - ‘tsv’: Tab-separated values files. Splits by state variable. - ‘h5’ or ‘hdf5’: HDF5 files preserving full dimensionality. Does NOT split by state variable - keeps all dimensions intact. Ideal for parameter sweeps (e.g., sweep, time, state, region, mode).
Returns
str Path to the created BIDS dataset root directory.
Examples
ts = experiment.run() ts.to_bids(“./derivatives/tvbo”, subject=“01”) ‘./derivatives/tvbo’
bold_ts.to_bids(“./derivatives/tvbo”, suffix=“BOLD”)
Export as TSV instead of CIFTI
ts.to_bids(“./derivatives/tvbo”, timeseries_format=“tsv”)
Export as HDF5 preserving all dimensions (no state variable split)
ts.to_bids(“./derivatives/tvbo”, timeseries_format=“h5”)
Notes
Follows BIDS BEP034 Computational Modeling extension v1.0.0. Uses pydantic for metadata serialization and pybids for filenames.