bids
adapters.bids
BIDS BEP034 Export Module
This module provides utilities for exporting TVB simulation data to BIDS format following the BEP034 Computational Modeling Extension v1.0.0.
Uses: - Pydantic models from tvbo.datamodel.tvbopydantic for metadata serialization - pybids for BIDS-compliant filename generation - nibabel for CIFTI-2 ptseries files
Classes
| Name | Description |
|---|---|
| BEP034BaseModel | Base model for all BEP034 sidecar metadata. |
| BEP034PathBuilder | Build BIDS BEP034-compliant paths using pybids patterns. |
| CoordinateSidecar | Sidecar metadata for coordinate files (coord/). |
| DatasetDescription | BIDS dataset_description.json model. |
| EquationSidecar | Sidecar metadata for equation/model files (eq/). |
| GeneratedBy | GeneratedBy entry for dataset_description.json. |
| NetworkSidecar | Sidecar metadata for network files (net/). |
| SimulationProvenance | Provenance information for a simulation. |
| TimeSeriesHDF5Sidecar | Sidecar metadata for HDF5 time series files preserving full dimensionality. |
| TimeSeriesSidecar | Sidecar metadata for time series files (ts/). |
BEP034BaseModel
adapters.bids.BEP034BaseModel()Base model for all BEP034 sidecar metadata.
Methods
| Name | Description |
|---|---|
| to_dict | Export to dictionary, excluding None values. |
| to_json | Export to JSON string. |
to_dict
adapters.bids.BEP034BaseModel.to_dict()Export to dictionary, excluding None values.
to_json
adapters.bids.BEP034BaseModel.to_json(**kwargs)Export to JSON string.
BEP034PathBuilder
adapters.bids.BEP034PathBuilder()Build BIDS BEP034-compliant paths using pybids patterns.
If pybids is not available, falls back to manual path construction.
Methods
| Name | Description |
|---|---|
| build_coord_path | Build path for coordinate files. |
| build_eq_path | Build path for equation/model files. |
| build_net_path | Build path for network files (weights/distances). |
| build_path | Build a path from entities using BEP034 patterns. |
| build_ts_path | Build path for time series files. |
build_coord_path
adapters.bids.BEP034PathBuilder.build_coord_path(
subject,
coord_type,
id_hash,
desc=None,
session=None,
space=None,
extension='.tsv',
)Build path for coordinate files.
build_eq_path
adapters.bids.BEP034PathBuilder.build_eq_path(
eq_label,
id_hash,
desc=None,
subject=None,
session=None,
extension='.json',
)Build path for equation/model files.
build_net_path
adapters.bids.BEP034PathBuilder.build_net_path(
subject,
net_type,
id_hash,
desc=None,
session=None,
run=None,
extension='.tsv',
)Build path for network files (weights/distances).
build_path
adapters.bids.BEP034PathBuilder.build_path(entities, strict=False)Build a path from entities using BEP034 patterns.
Parameters
entities : dict Entity-value pairs (e.g., {‘subject’: ‘01’, ‘net’: ‘weights’, …}) strict : bool If True, all entities must match pattern
Returns
str or None Built path or None if no pattern matches
build_ts_path
adapters.bids.BEP034PathBuilder.build_ts_path(
subject,
ts_label,
suffix='State',
desc=None,
session=None,
run=None,
extension='.ptseries.nii',
)Build path for time series files.
Parameters
subject : str Subject identifier ts_label : str Time series entity label - the output name from the model. This can be: - A state variable name (e.g., ‘V’, ‘W’) - A derived output name (e.g., ‘Diff’ for V-W) - Any named output defined in the dynamics model suffix : str BIDS suffix indicating the observation/output type: - ‘State’: Raw neural state time series (default, 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) - ‘LFP’: Local field potential desc : str, optional Description label (e.g., model name) session : str, optional Session identifier run : int, optional Run number extension : str File extension (default: .ptseries.nii)
Returns
str BIDS-compliant file path
Examples
path_builder.build_ts_path(‘01’, ‘V’, ‘State’) # Raw state V ‘sub-01/ts/sub-01_ts-V_State.ptseries.nii’ path_builder.build_ts_path(‘01’, ‘V’, ‘BOLD’) # V convolved with HRF ‘sub-01/ts/sub-01_ts-V_BOLD.ptseries.nii’ path_builder.build_ts_path(‘01’, ‘Diff’, ‘BOLD’) # Derived output (V-W) as BOLD ‘sub-01/ts/sub-01_ts-Diff_BOLD.ptseries.nii’
CoordinateSidecar
adapters.bids.CoordinateSidecar()Sidecar metadata for coordinate files (coord/).
DatasetDescription
adapters.bids.DatasetDescription()BIDS dataset_description.json model.
EquationSidecar
adapters.bids.EquationSidecar()Sidecar metadata for equation/model files (eq/).
GeneratedBy
adapters.bids.GeneratedBy()GeneratedBy entry for dataset_description.json.
NetworkSidecar
adapters.bids.NetworkSidecar()Sidecar metadata for network files (net/).
SimulationProvenance
adapters.bids.SimulationProvenance()Provenance information for a simulation.
TimeSeriesHDF5Sidecar
adapters.bids.TimeSeriesHDF5Sidecar()Sidecar metadata for HDF5 time series files preserving full dimensionality.
TimeSeriesSidecar
adapters.bids.TimeSeriesSidecar()Sidecar metadata for time series files (ts/).
Functions
| Name | Description |
|---|---|
| compute_id | Compute ID as hash of JSON sidecar content. |
| create_cifti_ptseries | Create a CIFTI-2 ptseries (parcellated time series) image. |
| create_dataset_description | Create a dataset_description.json model. |
| create_multi_state_cifti | Create separate CIFTI-2 ptseries files for each state variable. |
| detect_timeseries_format | Detect the time series format in a BIDS ts/ directory. |
| find_bids_session_path | Find the path to a BIDS subject/session directory. |
| get_unique_entity_values | Get a set of all unique values for a given entity key from the BIDSLayout files. |
| ingest_bids_session | Ingest all data from a BIDS BEP034 session. |
| load_bep034_config | Load the BEP034 configuration file. |
| read_bids_coordinates | Read coordinates from a BIDS coord/ directory. |
| read_bids_equations | Read model equations from a BIDS eq/ directory. |
| read_bids_network | Read network connectivity from a BIDS net/ directory. |
| read_bids_sidecar | Read a BIDS JSON sidecar file. |
| read_bids_timeseries | Read time series data from a BIDS ts/ directory. |
| read_cifti_ptseries | Read a CIFTI-2 ptseries file. |
| read_hdf5_timeseries | Read time series data from HDF5 file. |
| to_float | Safely convert JAX arrays/tracers to Python floats. |
| write_cifti_ptseries | Write time series data to a CIFTI-2 ptseries.nii file. |
| write_hdf5_timeseries | Write time series data to HDF5 file preserving full dimensionality. |
| write_sidecar | Write a pydantic sidecar model to JSON file. |
| write_tsv | Write a DataFrame to TSV file. |
compute_id
adapters.bids.compute_id(sidecar_dict)Compute ID as hash of JSON sidecar content.
create_cifti_ptseries
adapters.bids.create_cifti_ptseries(
data,
region_labels,
sample_period,
sample_period_unit='ms',
state_variable_labels=None,
)Create a CIFTI-2 ptseries (parcellated time series) image.
This creates a valid CIFTI-2 file with: - ParcelsAxis: Named brain regions with proper structure - SeriesAxis: Time dimension with sampling info - ScalarAxis: State variable names (if multiple)
Parameters
data : np.ndarray Time series data with shape: - (time, regions) for single state variable - (time, state_variables, regions) for multiple state variables region_labels : list[str] Names for each brain region/parcel sample_period : float Sampling period (time between samples) sample_period_unit : str Unit for sample period (‘ms’, ‘s’, ‘sec’) state_variable_labels : list[str], optional Names for each state variable if data has 3 dimensions
Returns
cifti2.Cifti2Image CIFTI-2 image ready to be saved
Raises
ImportError If nibabel is not available ValueError If data dimensions don’t match provided labels
Examples
img = create_cifti_ptseries(data, region_labels, 1.0, ‘ms’) nib.save(img, ‘output.ptseries.nii’)
create_dataset_description
adapters.bids.create_dataset_description(
name='TVB Simulation Output',
bids_version='1.9.0',
software_name='tvbo',
software_version='0.1.0',
)Create a dataset_description.json model.
create_multi_state_cifti
adapters.bids.create_multi_state_cifti(
data,
region_labels,
state_variable_labels,
sample_period,
sample_period_unit='ms',
)Create separate CIFTI-2 ptseries files for each state variable.
This is the recommended approach for multi-state variable data, creating one ptseries file per state variable.
Parameters
data : np.ndarray Time series data with shape (time, state_variables, regions) region_labels : list[str] Names for each brain region state_variable_labels : list[str] Names for each state variable sample_period : float Sampling period sample_period_unit : str Unit for sample period
Returns
dict[str, Cifti2Image] Dictionary mapping state variable names to CIFTI images
detect_timeseries_format
adapters.bids.detect_timeseries_format(ts_dir)Detect the time series format in a BIDS ts/ directory.
Parameters
ts_dir : Path Path to the ts/ directory
Returns
str Format: ‘h5’, ‘cifti’, or ‘tsv’
find_bids_session_path
adapters.bids.find_bids_session_path(bids_dir, subject, session=None)Find the path to a BIDS subject/session directory.
Parameters
bids_dir : Path Root BIDS dataset directory subject : str Subject ID (with or without ‘sub-’ prefix) session : str, optional Session ID (with or without ‘ses-’ prefix)
Returns
Path Path to the subject/session directory
get_unique_entity_values
adapters.bids.get_unique_entity_values(bids_layout, key)Get a set of all unique values for a given entity key from the BIDSLayout files.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| bids_layout | BIDSLayout | The BIDSLayout object to extract entities from. | required |
| key | str | The entity key to extract values for (e.g., ‘atlas’, ‘space’). | required |
Returns
| Name | Type | Description |
|---|---|---|
| set | set | A set of unique values for the specified entity key. |
ingest_bids_session
adapters.bids.ingest_bids_session(bids_dir, subject, session=None)Ingest all data from a BIDS BEP034 session.
Parameters
bids_dir : str or Path Root BIDS dataset directory subject : str Subject ID session : str, optional Session ID
Returns
dict Complete ingested data with keys: - ‘timeseries’: time series data dict - ‘network’: network data dict - ‘equations’: model equations dict - ‘coordinates’: coordinates dict - ‘dataset_description’: dataset description dict - ‘session_path’: path to session directory
load_bep034_config
adapters.bids.load_bep034_config()Load the BEP034 configuration file.
read_bids_coordinates
adapters.bids.read_bids_coordinates(coord_dir)Read coordinates from a BIDS coord/ directory.
Parameters
coord_dir : Path Path to the coord/ directory
Returns
dict Dictionary with ‘centres’, ‘region_labels’, ‘coordinate_system’
read_bids_equations
adapters.bids.read_bids_equations(eq_dir)Read model equations from a BIDS eq/ directory.
Parameters
eq_dir : Path Path to the eq/ directory
Returns
dict Dictionary with model information
read_bids_network
adapters.bids.read_bids_network(net_dir)Read network connectivity from a BIDS net/ directory.
Parameters
net_dir : Path Path to the net/ directory
Returns
dict Dictionary with ‘weights’, ‘distances’, ‘region_labels’, ‘sidecars’
read_bids_sidecar
adapters.bids.read_bids_sidecar(json_path)Read a BIDS JSON sidecar file.
read_bids_timeseries
adapters.bids.read_bids_timeseries(ts_dir, format=None)Read time series data from a BIDS ts/ directory.
Automatically detects the format (h5, cifti, tsv) unless specified.
Parameters
ts_dir : Path Path to the ts/ directory format : str, optional Force a specific format (‘h5’, ‘cifti’, ‘tsv’)
Returns
dict Dictionary with: - ‘data’: numpy array (time, state_vars, regions, modes) - ‘time’: time array - ‘labels_dimensions’: dimension labels - ‘sample_period’: sampling period - ‘sample_period_unit’: unit string - ‘state_variables’: list of state variable names - ‘region_labels’: list of region names - ‘sidecars’: list of sidecar metadata dicts - ‘format’: detected format string
read_cifti_ptseries
adapters.bids.read_cifti_ptseries(path)Read a CIFTI-2 ptseries file.
Parameters
path : Path Path to the ptseries.nii file
Returns
tuple (data, region_labels, sample_period, sample_period_unit)
read_hdf5_timeseries
adapters.bids.read_hdf5_timeseries(path)Read time series data from HDF5 file.
Parameters
path : str or Path Path to HDF5 file
Returns
dict Dictionary with ‘data’, ‘time’, ‘labels_dimensions’, ‘dimensions’, ‘metadata’
to_float
adapters.bids.to_float(val)Safely convert JAX arrays/tracers to Python floats.
write_cifti_ptseries
adapters.bids.write_cifti_ptseries(
data,
region_labels,
path,
sample_period,
sample_period_unit='ms',
state_variable_labels=None,
)Write time series data to a CIFTI-2 ptseries.nii file.
Parameters
data : np.ndarray Time series data (time, regions) or (time, state_vars, regions) region_labels : list[str] Names for each brain region path : str or Path Output file path (should end with .ptseries.nii or .ptseries.nii.gz) sample_period : float Sampling period sample_period_unit : str Unit for sample period (‘ms’ or ‘s’) state_variable_labels : list[str], optional Names for state variables if data is 3D
Returns
Path Path to the created file
write_hdf5_timeseries
adapters.bids.write_hdf5_timeseries(
data,
time,
path,
labels_dimensions=None,
labels_ordering=None,
sample_period=None,
sample_period_unit='ms',
metadata=None,
compression='gzip',
compression_opts=4,
)Write time series data to HDF5 file preserving full dimensionality.
This format supports arbitrary dimensionality (e.g., parameter sweeps, multiple modes, etc.) without splitting by state variable.
Parameters
data : np.ndarray Time series data with any dimensionality (e.g., time, state, region, mode) or (param_sweep, time, state, region, mode) time : np.ndarray Time array path : str or Path Output file path (should end with .h5) labels_dimensions : dict, optional Labels for each dimension: {‘State Variable’: [‘V’, ‘W’], ‘Space’: [‘R1’, ‘R2’]} labels_ordering : tuple, optional Names of dimensions in order: (‘Time’, ‘State Variable’, ‘Space’, ‘Mode’) sample_period : float, optional Sampling period sample_period_unit : str Unit for sample period metadata : dict, optional Additional metadata to store compression : str HDF5 compression filter compression_opts : int Compression level
Returns
Path Path to the created file
write_sidecar
adapters.bids.write_sidecar(sidecar, path)Write a pydantic sidecar model to JSON file.
write_tsv
adapters.bids.write_tsv(df, path, include_index=True)Write a DataFrame to TSV file.