tvbids

export.tvbids

Brain Imaging Data Structure (BIDS) Export for TVB-O

This module provides functionality to export data and metadata from TVB simulations into a format that is compliant with the Brain Imaging Data Structure (BIDS) Extension for Computational Models (BEP034). BIDS is a standard for organizing and describing neuroimaging and associated data that TVB-O supports to facilitate the interchange of data within the research community.

The integration with BIDS enables users to structure their simulation output data and associated metadata in a way that enhances interoperability and reusability. This can be particularly advantageous for users aiming to share their simulation results with the wider neuroscience community, or for those who wish to integrate TVB-O outputs with other BIDS-compliant datasets for combined analyses.

By adhering to the BIDS Computational Model Specification (BEP034) <https://docs.google.com/document/d/1NT1ERdL41oz3NibIFRyVQ2iR8xH-dKY-lRCB4eyVeRo/edit>_, TVB-O ensures consistency in data formatting, which is crucial for collaborative research, data sharing, and the replicability of computational studies.

Features ——– - BIDS Compatibility: Seamlessly export simulation configurations, connectivity data, and time series outputs in BIDS-compliant format. - Metadata Organization: Automatic generation of BIDS metadata files to describe the simulations, including model specifications and integration details. - Visualization Support: Functions to visualize the BIDS directory structure, aiding in the verification and presentation of the export process.

Components

The module comprises functions that handle various aspects of the BIDS export process:

  • Conversion of time series data to BIDS-compliant time series files (TSV).
  • Generation of model description files in JSON format that align with BIDS specifications.
  • Organization of connectivity data in accordance with BIDS modality-specific extensions.
  • Utility functions for directory listing and visualization, enhancing user interaction with the file system.

See Also

For more information on BIDS and BEP034, visit the official BIDS website: https://bids.neuroimaging.io/ For comprehensive details on BEP034, refer to the BIDS Computational Model Specification document <https://docs.google.com/document/d/1NT1ERdL41oz3NibIFRyVQ2iR8xH-dKY-lRCB4eyVeRo/edit>_.

Functions

Name Description
connectivity2bids Export connectivity data to BIDS-compliant files.
generate_bids_path Generate a BIDS-compliant path for different modalities based on provided entities.
generate_json_sidecar Generate a JSON sidecar file for a dataset with provided metadata and entities.
getImage Load and return an OffsetImage object from the given image file path.
list_files Visualize the file hierarchy of a given directory with options to render images.
model2bids Export a computational model in TVB format to BIDS-compliant structure.
save_sim2bids Save simulation outputs in a BIDS-compatible format.
timeseries2bids Converts time series data from simulations to BIDS-compliant format.
ts_metadata Generate metadata for time series data based on a computational model and optional parameter configuration.

connectivity2bids

export.tvbids.connectivity2bids(
    dataset,
    connectivity,
    subject='1',
    compression='gzip',
    **entities,
)

Export connectivity data to BIDS-compliant files.

Parameters

dataset : str Path to the BIDS dataset directory where connectivity files will be stored. connectivity : Connectivity class instance The Connectivity instance containing data to be exported. subject : str, optional The subject identifier. compression : str, optional Compression method for the output files. **entities : dict Additional BIDS entities for file naming.

Returns

list of str Paths to the created BIDS-compliant connectivity files.

Examples

connectivity2bids(‘path/to/bids/dataset’, conn_instance, subject=‘02’) [‘path/to/bids/dataset/sub-02/net/sub-02_weights.tsv.gz’, ‘path/to/bids/dataset/sub-02/net/sub-02_tracts.tsv.gz’]

generate_bids_path

export.tvbids.generate_bids_path(**entities)

Generate a BIDS-compliant path for different modalities based on provided entities.

Parameters

**entities : dict Arbitrary keyword arguments that represent BIDS entities (e.g., subject, session, modality, suffix, extension).

Returns

tuple of (str, dict) A tuple containing the BIDS-compliant file path and the entities used for generating it.

Raises

ValueError If any required entities are missing from the keyword arguments or no valid path could be built from the provided entities.

Examples

generate_bids_path(subject=‘01’, session=‘01’, modality=‘anat’, suffix=‘T1w’, extension=‘nii.gz’) (‘sub-01/ses-01/anat/sub-01_ses-01_T1w.nii.gz’, {‘subject’: ‘01’, ‘session’: ‘01’, ‘modality’: ‘anat’, ‘suffix’: ‘T1w’, ‘extension’: ‘nii.gz’})

generate_json_sidecar

export.tvbids.generate_json_sidecar(dataset, metadata, **entities)

Generate a JSON sidecar file for a dataset with provided metadata and entities.

Parameters

dataset : str The path to the dataset directory where the JSON sidecar will be created. metadata : dict A dictionary containing metadata to be written into the JSON sidecar file. **entities : dict Arbitrary keyword arguments that represent BIDS entities for file naming.

Returns

dict The metadata dictionary that was written to the JSON sidecar.

Examples

generate_json_sidecar(‘path/to/dataset’, {‘Author’: ‘Leon K. Martin’}, subject=‘01’, modality=‘anat’) {‘Author’: ‘Leon K. Martin’}

getImage

export.tvbids.getImage(path)

Load and return an OffsetImage object from the given image file path.

Parameters: path (str): The file path of the image.

Returns: OffsetImage: An OffsetImage object representing the loaded image.

list_files

export.tvbids.list_files(startpath, render_image=False)

Visualize the file hierarchy of a given directory with options to render images.

Parameters

startpath : str The root directory from which the file hierarchy is generated. render_image : bool, optional If True, renders the file hierarchy as images using matplotlib. If False, prints the hierarchy to the console with emojis.

Raises

FileNotFoundError If the specified startpath does not exist.

Notes

When render_image is True, the function uses matplotlib to create a visual representation of the file structure with icons representing different file types. This is particularly useful for presentations or documentation purposes.

model2bids

export.tvbids.model2bids(
    dataset,
    model,
    subject='1',
    param_config=None,
    **entities,
)

Export a computational model in TVB format to BIDS-compliant structure.

Parameters

dataset : str Path to the BIDS dataset directory where model files will be stored. model : str Name of the model to be exported. subject : str, optional The subject identifier. param_config : str or dict, optional The parameter configuration for the model to be exported. **entities : dict Additional BIDS entities for file naming.

Returns

str Path to the exported XML LEMS model file.

Examples

model2bids(‘path/to/bids/dataset’, ‘JansenRit’, subject=‘02’, description=‘ExcitatoryInhibitory’) ‘path/to/bids/dataset/sub-02/eq/sub-02_excitatoryinhibitory_lems.xml’

save_sim2bids

export.tvbids.save_sim2bids(
    sim,
    time,
    data,
    dataset,
    subject,
    model_file=None,
    **entities,
)

Save simulation outputs in a BIDS-compatible format.

Parameters

sim : Simulator object The simulation object containing the model and connectivity data. time : ndarray A 1D array containing the time points at which the simulation was sampled. data : ndarray A 2D array (time points x variables) of data from the simulation. dataset : str The path to the BIDS dataset directory. subject : str The subject identifier to be used in the BIDS dataset. model_file : str, optional The path to the JSON file containing the model description. If not provided, it will be generated from the simulation object. **entities : dict, optional Additional BIDS entities to include in the filenames.

See Also

timeseries2bids : Function to convert time series data to BIDS format. connectivity2bids : Function to convert connectivity data to BIDS format.

Notes

This function acts as a high-level interface to convert and save all necessary components of a simulation into the BIDS format. It organizes metadata, models, and time series data according to BIDS specifications.

timeseries2bids

export.tvbids.timeseries2bids(
    dataset,
    sim,
    time,
    data,
    model_file,
    network_file,
    subject='1',
    compression='gzip',
    **entities,
)

Converts time series data from simulations to BIDS-compliant format.

Parameters

dataset : str Path to the BIDS dataset directory where the time series files will be stored. sim : Simulator object The simulator object that contains the model and connectivity information. time : array_like The time points for which the data is available. data : ndarray The time series data to be exported. model_file : str The filename where the model description is stored. network_file : str The filename where the network description is stored. subject : str, optional The subject identifier. Defaults to “1”. compression : str, optional Compression method for storage. Defaults to “gzip”. **entities : dict, optional Additional BIDS entities to be included.

Raises

ValueError If the number of variables in data does not match the number of variables of interest.

See Also

generate_bids_path : Helper function to generate BIDS-compliant paths.

Notes

This function assumes that the simulation data is organized with time as the last dimension.

Examples

timeseries2bids(‘path/to/bids_dataset’, sim_object, np.linspace(0, 1000, 1001), sim_data, ‘model.json’, ‘network.json’)

ts_metadata

export.tvbids.ts_metadata(model, param_config=None)

Generate metadata for time series data based on a computational model and optional parameter configuration.

Parameters

model : str or owl.ThingClass The model identifier or an instance from the ontology to create metadata for. param_config : str or dict, optional The parameter configuration identifier or a dictionary of the parameter settings.

Returns

dict A dictionary containing the metadata for the time series based on the model.

Raises

ValueError If the provided model is not found in the ontology or is not a recognized type.

Examples

ts_metadata(‘JansenRit’) {‘Model’: {‘ModelName’: ‘Jansen-Rit Model’, ‘ModelID’: ‘TVBO:001’, …}}