TUI example with LEMON dataset

This example illustrates the use of sovabids on the LEMON dataset using the terminal user interface (TUI).

A full video walkthrough is available at https://youtu.be/dOWiMTuGvAA (the layout changed a little since the video: the load existing rules file option now lives at the top of the Rules tab instead of on Setup).

Install sovabids in TUI mode

(see here)

pip install "sovabids[tui]"

Download the LEMON dataset

(if you have not already done so)

python -c 'from sovabids.datasets import lemon_prepare; lemon_prepare()'

This downloads the dataset to a _data subfolder inside the installed packages folder.

Launch the TUI

sovatui

The TUI opens in your terminal with four tabs: Setup, Rules, Mappings, and Convert.

Tab 1 — Setup

Fill in:

• Source directory — path to the raw EEG files (browse with the Browse… button or type directly).

• BIDS output directory — where the converted dataset will be written (the Browse… dialog can create a new folder for it).

For the LEMON example the source path is the lemon subfolder inside _data and the BIDS path can be any empty directory you choose.

Tab 2 — Rules

This tab is where you define the conversion rules. You have two options:

• Load an existing rules file (optional) — at the top of the tab, point the Browse… field at an existing rules.yml (for LEMON, examples/lemon_example_rules.yml). Loading a file locks the builder below, since those rules come from the file; clear the field to build rules by hand again.

• Or build the rules yourself with the fields below:

  • EEG file extension — select .vhdr for LEMON. A couple of example source paths from your source directory are listed to help you read off the pattern.

  • Pattern mode — choose Placeholder, Regex, or File example.

  • Path pattern — e.g. %subject%_%task%.vhdr for placeholder mode.

  • Sidecar fields — set power line frequency, EEG reference, etc.

  • Dataset description — dataset name and authors.

The live preview shows how many files match the current pattern. Use Show all to inspect individual files and the fields extracted from each path. Use Channel Names or Power Spectrum to inspect the first matched file.

Tab 3 — Mappings

Click Generate Mappings to get the mappings with your current setup and rules. The table shows each source file paired with its target BIDS path.

Click Save Mappings YAML… to persist the mappings file to <bids_path>/code/sovabids/mappings.yml.

Tab 4 — Convert

Click Convert to run the conversion based on the generated mappings. Progress and log messages stream into the log panel in real time. Errors are shown in red, warnings in yellow.

Press Ctrl+S at any time to save the current rules to <bids_path>/code/sovabids/rules.yml. Press Q to quit.