types
data.types
Runtime data types for TVBO simulations.
Provides TimeSeries, a JAX-pytree-aware, xarray-backed time-series container with domain-specific analysis and visualization helpers, and SimulationState, the bundled simulation state (initial conditions, network, noise, parameters, stimulus, and monitor settings) handed to the integration backends.
Attributes
| Name | Description |
|---|---|
| logger |
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 | Bundled state passed to the integration backends for one simulation. |
| TimeSeries | Time-series dataType with JAX pytree support, domain-specific analysis, and visualization methods. |
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,
inferences=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. |
| save | Persist the run as one keyed HDF5 result plus a YAML provenance sidecar. |
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, transient_time=0.0)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. transient_time : float Length of the leading settle inside the run, in the simulator’s time unit. TVB integrates it as part of one simulation; it is marked here so the result cuts it at t=0 exactly as every other backend does.
Returns:
ExperimentResult
plot
data.types.ExperimentResult.plot(**kwargs)Dispatch plot to the most relevant sub-result.
save
data.types.ExperimentResult.save(out_dir, compress=True, record_only=True)Persist the run as one keyed HDF5 result plus a YAML provenance sidecar.
Writes <prefix>_result.h5 — a single xarray Dataset where every output is a data-variable and the sweep parameters are shared coordinates (a full run is gridded; a sharded run keeps the flat, self-describing point dim that reassembles by value) — and <prefix>_result.yaml, the frozen experiment spec. <prefix> is the experiment’s BIDS-style key-value name (ses-<id>_desc-<label>). The same artifact is produced by a local run and by the HPC gather pass, so they are interchangeable. Returns the written paths.
The sidecar carries the frozen spec plus a connectome companion (<stem>_network.h5), so the result reloads without its original data sources. Writing it is not guarded: it is half of what this method promises, and a swallowed failure returned an .h5 with no .yaml, which the caller met much later as an unrelated error.
An on-device cohort run fans here into one per-subject result (see :meth:_save_per_subject), mirroring the per-subject workflow fan-out.
ExplorationResult
data.types.ExplorationResult(
name=None,
grid=None,
results=None,
axes=None,
observable=None,
dt=None,
transient_time=0.0,
output_names=None,
observations=None,
cell_coords=None,
is_shard=None,
axis_points=None,
**kwargs,
)Result of parameter exploration (grid search).
A thin wrapper around tvboptim exploration outputs that provides: - Access to labelled 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 : xr.DataArray Observable values at each grid point (flat for scalars, multi-dim for time series), carrying named dims: the leading run axis (the swept parameter, trial, or point) followed by the intrinsic dims (time, variable, node, mode). The payload stays JAX-native — only the labels are materialised — and the shape is unchanged from what the backend emitted, so it is addressed by key rather than by position. as_grid() reshapes the flat run axis into one dim per exploration axis. 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) transient_time : float Length of the settle at the head of each cell’s recorded trajectory. A sweep records the window it integrated, so results spans the settle too — the analogue of SimulationResult.full — and this puts its time axis on the measurement clock, where the settle carries non-positive timestamps. results.sel(time=slice(dt, None)) is the measured window that SimulationResult.data reports. output_names : list[str] Names of output variables (e.g., [‘v_pyr’]) for time series results
Methods
| Name | Description |
|---|---|
| as_grid | Reshape the flat results into a grid labeled by parameter name. |
| plot | Plot exploration results. |
| slice | Get a slice of results with some parameters fixed. |
as_grid
data.types.ExplorationResult.as_grid()Reshape the flat results into a grid labeled by parameter name.
Returns an xr.DataArray with one dimension per exploration axis — named by the swept parameter, coordinates set to the swept values — so grid results are addressed by name (g.sel(**{"ReducedWongWang.w": 0.5})) and are independent of axis order. The data stays a JAX array (the DataArray is a registered JAX pytree); only the coordinate labels are materialised. A time-series observable keeps its intrinsic dims (time, variable, node, mode) after the grid dims. None when empty; otherwise always labelled — a payload that cannot be reshaped into the grid is returned with the dim names it already carries (see :meth:_label_payload) rather than as a bare array, so no consumer is handed positional data. A set cell_coords selects the keyed path below, which every sweep takes because every sweep sets it; :func:_stacked_to_dataarray then decides the shape from whether the cells fill the Cartesian product. A full product is placed into the rectangular grid BY VALUE, so sel by parameter works as usual. A subset — an HPC array task’s slice, or a branch restart — gets a single point dim carrying each axis’s value, so it reassembles across shards by parameter value.
Do not read a set cell_coords as “this is a shard”. _is_partial_shard answers that separate question, for provenance rather than labelling, and prefers the producer’s declared is_shard.
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,
observation_dims=None,
observation_times=None,
units=None,
n_transient=0,
**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 The run’s own settling window, as a view on the same buffer — never a second run.
Attributes
| Name | Description |
|---|---|
| coords | Coordinates of the data array. |
| dims | Dimension names of the data array. |
| full | The whole integrated window, settle included, on the measurement clock (t <= 0 is the settle). |
| state_names | State variable names from data coordinates. |
| time | Time values as numpy array (backward compatible). |
| transient | This run’s settling window, or None when none was declared. |
| 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,
)Bundled state passed to the integration backends for one simulation.
Groups everything a backend needs to advance a run: the initial conditions, the Network, the integration step, the noise configuration, model parameters, stimulus, monitor settings, and the number of time steps. Registered as a JAX pytree so it can flow through jit/vmap; nt is kept static while the remaining fields are dynamic children.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| initial_conditions | TimeSeries | Initial state as a TimeSeries (history buffer). |
required |
| network | Network | The Network (connectivity and coupling) to simulate. |
required |
| dt | Integration time step. | required | |
| noise | Noise configuration, including per-state-variable sigma. | required | |
| parameters | Model parameter pytree. | required | |
| stimulus | Stimulus specification applied during integration. | required | |
| monitor_parameters | Settings controlling recorded outputs. | required | |
| nt | Number of integration steps to run. | required |
Attributes
| Name | Description |
|---|---|
| n_state_variables | Number of state variables inferred from the initial conditions. |
| state_variable_names | State-variable names, falling back to positional indices as strings. |
| state_variables | Ergonomic proxy: state.state_variables.V.noise.sigma = 0.02. |
Methods
| Name | Description |
|---|---|
| convert_dtype | Convert the dtype of the parameter pytree. |
| get_state_variable_index | Resolve a state variable to its integer index. |
| set_sigma_for | Set the noise sigma for one state variable (or all at once). |
| set_sigma_many | Set multiple sigma values using a dict: { ‘V’: 0.02, ‘W’: 0.0 }. |
| tree_flatten | Flatten into JAX pytree (children, aux_data). |
| tree_unflatten | Reconstruct a SimulationState from JAX pytree children and aux_data. |
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.
get_state_variable_index
data.types.SimulationState.get_state_variable_index(name_or_index)Resolve a state variable to its integer index.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| name_or_index | A state-variable name or an integer index. Integers are returned unchanged; unknown names fall back to 0. |
required |
Returns
| Name | Type | Description |
|---|---|---|
| int | The integer index of the state variable. |
set_sigma_for
data.types.SimulationState.set_sigma_for(name_or_index, value)Set the noise sigma for one state variable (or all at once).
Rebuilds noise.sigma_vec rather than mutating it in place, so it is safe to call before jit/vmap.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| name_or_index | The state variable to target, by name or index. | required | |
| value | A scalar sigma for the selected variable, or a list/tuple giving sigma for every state variable at once. | required |
Returns
| Name | Type | Description |
|---|---|---|
self, to allow method chaining. |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If a list/tuple value does not match the number of state variables. |
set_sigma_many
data.types.SimulationState.set_sigma_many(mapping)Set multiple sigma values using a dict: { ‘V’: 0.02, ‘W’: 0.0 }.
tree_flatten
data.types.SimulationState.tree_flatten()Flatten into JAX pytree (children, aux_data).
nt is kept as static aux_data so it stays concrete in shape/length contexts under jit/vmap.
tree_unflatten
data.types.SimulationState.tree_unflatten(aux_data, children)Reconstruct a SimulationState from JAX pytree children and aux_data.
TimeSeries
data.types.TimeSeries(
time,
data,
network=None,
title='TimeSeries',
sample_period=None,
labels_dimensions=None,
units=None,
)Time-series dataType with JAX pytree support, domain-specific analysis, and visualization methods.
Attributes
| Name | Description |
|---|---|
| ndim | Number of dimensions of the underlying data array. |
| sample_period_ms | :returns sample_period is ms |
| sample_rate | :returns samples per second [Hz] |
| shape | Shape of the underlying data array. |
| space_labels | Labels for the spatial (region) axis as a NumPy array. |
| time_unit | Unit of the sample period (e.g. "ms"). |
| variables_labels | Labels for the state-variable axis as a NumPy array. |
Methods
| Name | Description |
|---|---|
| animate | Animate timeseries on a graph layout. |
| calculate_frequency | Calculate the dominant frequency of the time series data using FFT. |
| check_identity | Test whether this series’ data matches another array or time series. |
| compute_dt | Recompute sample_period from the mean spacing of the time axis. |
| 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. |
| cut_transient | Drop the initial transient before a given time. |
| duplicate | Fast shallow-copy-based duplication with attribute update. |
| exclude_region | Return a copy with one region removed. |
| get_dt | Return the sampling interval. |
| get_region | Extract a single region by label. |
| get_region_index | Return the spatial-axis index of a region given its label. |
| get_state | Extract one or more state variables by label. |
| get_state_variable | Evaluate a state variable or a symbolic expression of state variables. |
| get_subspace_by_index | Extract a spatial subset by region index. |
| get_subspace_by_labels | Extract a spatial subset by region label. |
| plot | Plot the time series, or a state-space trajectory of its variables. |
| plot_eeg | Plot each region as a separate channel stacked vertically on a single axes (EEG-like representation). |
| plot_power_spectrum | Plot the power spectrum with normalized average power computed via FFT. |
| subset | Restrict the time series to a [start, end] time window. |
| summary_info | Gather scientifically interesting summary information from an instance of this datatype. |
| tree_flatten | Flatten into JAX pytree (children, aux_data). |
| tree_unflatten | Reconstruct a TimeSeries from JAX pytree children and aux_data. |
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. |
check_identity
data.types.TimeSeries.check_identity(other, select_state_variable=None)Test whether this series’ data matches another array or time series.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| other | A NumPy array or another TimeSeries to compare against. |
required | |
| select_state_variable | Optional state-variable label (or expression) to compare instead of the full data array. | None |
Returns
| Name | Type | Description |
|---|---|---|
True if the flattened values are element-wise close (atol=1e-8), |
||
else False. |
compute_dt
data.types.TimeSeries.compute_dt()Recompute sample_period from the mean spacing of the time axis.
Prints a warning and updates sample_period in place when it disagrees with the mean of diff(time).
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.
cut_transient
data.types.TimeSeries.cut_transient(start_time)Drop the initial transient before a given time.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| start_time | Time value; all samples strictly before it are removed. | required |
Returns
| Name | Type | Description |
|---|---|---|
A new TimeSeries starting at the first sample at or after |
||
start_time. |
duplicate
data.types.TimeSeries.duplicate(**kwargs)Fast shallow-copy-based duplication with attribute update.
exclude_region
data.types.TimeSeries.exclude_region(region)Return a copy with one region removed.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| region | The region to drop, given either as an integer index along the spatial axis or as a region label. | required |
Returns
| Name | Type | Description |
|---|---|---|
A new TimeSeries without the specified region. |
get_dt
data.types.TimeSeries.get_dt()Return the sampling interval.
Returns
| Name | Type | Description |
|---|---|---|
The stored dt when available, otherwise the mean spacing between |
||
| successive time points. |
get_region
data.types.TimeSeries.get_region(region_label)Extract a single region by label.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| region_label | The label of the region to keep. | required |
Returns
| Name | Type | Description |
|---|---|---|
A new TimeSeries containing only the selected region. |
get_region_index
data.types.TimeSeries.get_region_index(region_label)Return the spatial-axis index of a region given its label.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| region_label | The region label to look up. | required |
Returns
| Name | Type | Description |
|---|---|---|
The integer index of the region within the "Region" labels. |
get_state
data.types.TimeSeries.get_state(sv_label)Extract one or more state variables by label.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| sv_label | A single state-variable label, or a list/tuple/array of labels to select several at once. | required |
Returns
| Name | Type | Description |
|---|---|---|
A new TimeSeries restricted to the selected state variable(s), with |
||
| its state-variable labels updated accordingly. |
get_state_variable
data.types.TimeSeries.get_state_variable(sv_label)Evaluate a state variable or a symbolic expression of state variables.
When sv_label is a list/tuple/array it behaves like get_state. When it is a string it is parsed as a symbolic expression whose free symbols are matched against existing state variables, allowing derived quantities such as "E - I" to be computed.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| sv_label | A state-variable label, a collection of labels, or a symbolic expression string combining state-variable names. | required |
Returns
| Name | Type | Description |
|---|---|---|
A new TimeSeries holding the evaluated state variable or |
||
expression, labelled with sv_label. |
get_subspace_by_index
data.types.TimeSeries.get_subspace_by_index(list_of_index, **kwargs)Extract a spatial subset by region index.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| list_of_index | Indices along the spatial (region) axis to keep. | required | |
| **kwargs | Additional keyword arguments forwarded to duplicate. |
{} |
Returns
| Name | Type | Description |
|---|---|---|
A new TimeSeries containing only the selected regions, with its |
||
| spatial labels updated accordingly. |
Raises
| Name | Type | Description |
|---|---|---|
| IndexError | If any index is outside the valid region range. |
get_subspace_by_labels
data.types.TimeSeries.get_subspace_by_labels(list_of_labels)Extract a spatial subset by region label.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| list_of_labels | Region labels to keep. | required |
Returns
| Name | Type | Description |
|---|---|---|
A new TimeSeries containing only the regions matching the given |
||
| labels. |
plot
data.types.TimeSeries.plot(
ax=None,
axis_labels=False,
legend=True,
title=None,
**kwargs,
)Plot the time series, or a state-space trajectory of its variables.
By default each state variable is drawn against time. Passing type="statespace" (or an equivalent alias such as "phase" or "trajectory") instead plots one state variable against another for a chosen region and mode.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| ax | Existing Matplotlib axes to draw on. When omitted, a new figure and axes are created and the figure is returned. | None |
|
| axis_labels | Whether to label the x-axis with the time unit. | False |
|
| legend | Whether to draw a legend (ignored for single-variable plots). | True |
|
| title | Optional axes title. | None |
|
| **kwargs | Additional options forwarded to Matplotlib’s plot, plus recognised keys such as type, region, mode, state_variables, labels, and label. |
{} |
Returns
| Name | Type | Description |
|---|---|---|
The created Matplotlib figure when ax was not supplied, otherwise |
||
None. |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If a state-space plot is requested with fewer than two state variables, or the data shape is unsupported. |
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.
subset
data.types.TimeSeries.subset(start, end)Restrict the time series to a [start, end] time window.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| start | Start time of the window (inclusive). | required | |
| end | End time of the window (inclusive). | required |
Returns
| Name | Type | Description |
|---|---|---|
A new TimeSeries covering only samples within the window. |
summary_info
data.types.TimeSeries.summary_info()Gather scientifically interesting summary information from an instance of this datatype.
tree_flatten
data.types.TimeSeries.tree_flatten()Flatten into JAX pytree (children, aux_data).
sample_period is a child (not aux) because it may hold a JAX tracer such as state.dt inside jit.
tree_unflatten
data.types.TimeSeries.tree_unflatten(aux_data, children)Reconstruct a TimeSeries from JAX pytree children and aux_data.
Functions
| Name | Description |
|---|---|
| reassemble_experiment_results | Gather an HPC run’s shard outputs into one keyed ExperimentResult artifact. |
| reassemble_shards | Concatenate sharded exploration outputs into the full sweep result. |
reassemble_experiment_results
data.types.reassemble_experiment_results(
shards_root,
out_dir,
pattern='**/*_result.h5',
point_dim='point',
stem='result',
sidecar=None,
compress=True,
)Gather an HPC run’s shard outputs into one keyed ExperimentResult artifact.
Follows the same on-disk shape as a :class:~tvbo.classes.network.Network: one HDF5 file (<stem>.h5) holding the data, plus a YAML sidecar (<stem>.yaml) carrying the frozen, fully-overridden experiment spec — so the result is self-describing, provenance-complete and reproducible without any extra flags, and identical to what a local run writes.
Each array task wrote a shard as the same <prefix>_result.h5 Dataset with a flat, self-describing point dimension (see :meth:ExperimentResult.save). This concatenates them along point and pivots by parameter value into the full rectangular grid, giving one standard xarray Dataset that opens with a plain xarray.open_dataset("<stem>.h5") — no TVBO-specific reader. axis_points__* variables — one sweep-wide axis table, required identical in every shard — are carried past the concat and re-attached to the grid, so the gathered artifact stays as self-describing as a local run’s.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| shards_root | directory holding the shard .h5 files (scanned recursively). |
required | |
| out_dir | where the <stem>.h5 (+ <stem>.yaml) is written. |
required | |
| pattern | glob for shard files. | '**/*_result.h5' |
|
| point_dim | the flat cell dimension the shards wrote. | 'point' |
|
| stem | basename of the result artifact (default result). |
'result' |
|
| sidecar | path to the frozen spec YAML to copy as <stem>.yaml (typically the kit’s spec/<name>.yaml). Omit to skip the sidecar. |
None |
|
| compress | bool | whether the reassembled artifact is written compressed. A gathered sweep is the archival copy of a run that will not be repeated, so it is worth the write time by default. | True |
Returns
| Name | Type | Description |
|---|---|---|
List of written paths (<stem>.h5 first, then <stem>.yaml). |
reassemble_shards
data.types.reassemble_shards(
source,
pattern='*__results.nc',
to_grid=False,
point_dim='point',
)Concatenate sharded exploration outputs into the full sweep result.
Each HPC array task writes its slice of the sweep as a flat point-dim DataArray whose per-cell parameter values are coordinates (see :meth:ExperimentResult.save). This is the analysis-pass side of the two-stage HPC pattern: it reads every shard file, concatenates them along point, and — with to_grid=True — pivots point into one dimension per swept parameter, giving the full rectangular grid addressed by value (order-independent, so it is robust to how tasks were sharded).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| source | a directory to scan with pattern, or an explicit list of paths. | required | |
| pattern | glob for shard files when source is a directory. | '*__results.nc' |
|
| to_grid | pivot the flat point dim into one dim per parameter. |
False |
|
| point_dim | name of the flat cell dimension written by the shards. | 'point' |
Returns
| Name | Type | Description |
|---|---|---|
The concatenated DataArray (flat point dim), or the gridded one |
||
when to_grid is set. |