Intro to sovabids¶
sovabids is a python package for automating EEG to BIDS conversion (experimental MEG support).
New to sovabids? Start with the Quickstart guide.
- sovabids can be used through (click to see the examples):
Note
The advantage of the JSON-RPC way is that it can be used from other programming languages.
Limitation:
Do notice that at the moment the files have to be on the same computer that runs the server.
Warning
MEG support is experimental. sovabids correctly routes MEG data to the meg BIDS datatype,
but does not expose MEG-specific metadata requirements such as empty-room recordings,
manufacturer calibration files, or digitization coordinate systems. For complex MEG datasets
(Elekta/Neuromag, CTF, KIT) those steps must be handled manually after conversion using
MNE-BIDS directly — see the MNE-BIDS MEG conversion guide.
The output format is automatically set to FIF for MEG data; you do not need to set
non-bids.output_format manually (but you may still override it if needed).
Supported Formats¶
sovabids reads EEG files via MNE-Python’s read_raw, which supports a wide range of formats including BrainVision, EDF/BDF, EEGLAB, FIF, CNT, KIT/SQD, CTF, and more. See the full list in the MNE documentation.
Output is always written as a valid BIDS dataset. The table below lists formats that can also be exported natively (i.e., the BIDS data files stay in that format rather than being converted to BrainVision):
Format |
Extension |
Extra needed |
Notes |
|---|---|---|---|
BrainVision |
|
(core) |
Default output format; |
EDF |
|
|
Requires |
EEGLAB |
|
|
Requires |
FIF |
|
(core) |
MNE native format; use for MEG data (experimental — see warning above) |
Install export support for EDF and EEGLAB:
pip install "sovabids[formats]"
For all other readable formats, sovabids converts the data to BrainVision on output (the default mne-bids behaviour).
Tip
sovabids supports incremental conversion: files whose BIDS output already exists are skipped
automatically, so you can safely re-run after adding new participants without re-converting
the whole dataset. To force a full re-conversion, delete the output folder and start over.
The Python API returns {'succeeded': [...], 'skipped': [...], 'failed': [...]} so you
can distinguish newly converted files, skipped files, and failures. Skips are also logged
at WARNING level so they appear in CLI output without -v.
Architecture¶
- The main elements of sovabids are:
A source path with the original dataset.
A bids path that will be the output path of the conversion.
A rules file that configures how the conversion is done from the general perspective.
A mapping file that encodes how the conversion is performed to each individual file of the dataset.
Internally sovabids uses MNE-Python and MNE-BIDS to perform the conversion. In a sense is a wrapper that allows to do conversions from the command line.
Basic Usage¶
Terminal User Interface (sovatui)¶
The easiest way to use sovabids is through its terminal user interface (TUI) called sovatui. This will allow you to do the conversion without having to write any command line code, and also to have a more visual experience of the conversion process. The TUI guides you through the full conversion workflow in four tabs: Setup, Rules, Mappings, and Convert.
Installation for TUI usage¶
This will install sovabids with the terminal user interface dependencies.
pip install "sovabids[tui]"
Running the TUI¶
sovatui
See the TUI tutorial video for a walkthrough and its example.
Command Line Interface (CLI) entry-points¶
Use sovabids through its CLI entry-points as follows:
Installation¶
pip install sovabids
sovapply¶
Use the sovapply entry-point to produce a mapping file from a source path, an output bids root path and a rules filepath.
sovapply source_path bids_path rules_path
By default the mapping file made will have the following filepath:
bids_path/code/sovabids/mappings.yml
sovaconvert¶
Use the sovaconvert entry-point to convert the dataset given its mapping file.
sovaconvert mapping_file
Using the experimental web GUI¶
Installation for WEB GUI usage¶
This will install sovabids for usage with an experimental web gui.
pip install "sovabids[gui]"
See the WEB GUI tutorial video for a walkthrough and its example.
Using the experimental bidscoin plugin¶
For the experimental bidscoin plugin, install the sovabids fork of bidscoin manually:
pip install "git+https://github.com/yjmantilla/bidscoin.git@sovabids"
Follow the example at https://sovabids.readthedocs.io/en/latest/auto_examples/bidscoin_example.html to see how to use the plugin.
Installation for developers¶
Fork this repo and run:
git clone https://github.com/<gh-username>/sovabids.git
cd sovabids
pip install -e ".[dev]"
Funding¶
Acknowledgments¶
sovabids is developed with the help of the following entities:
Academic Works¶
What does sova means?¶
sova is a contraction of ‘eso va’ which mean ‘that goes’ in spanish.
Nevertheless the real usage by the original developers is just to convey the idea of :
we will make it happen, we dont know how, but we will