Skip to content

Usage

How to run the software?¤

Step 1: Clone the repository¤

git clone https://github.com/s-ccs/LSLAutoBIDS.git

Step 2: Install the package¤

Go to the cloned directory and install the package using pip. 

cd LSLAutoBIDS
pip3 install lslautobids
It is advised to install the package in a separate environment (e.g. using conda or virtualenv).

Note

If you are using conda, you can create a new conda environment using the following command and activate it.

conda create -n <ENV_NAME> python=3.11
conda activate <ENV_NAME>

Step 3: Data Organization¤

The package requires the recorded XDF data to be organized in a specific directory structure following the BIDS (Brain Imaging Data Structure) naming convention. This is the default output of the popular labrecorder. The BIDS format is a standard for organizing and describing neuroimaging data, making it easier to share and analyze.

  • The projects root location is the root directory where all the eeg raw recordings (say .xdf files) are stored e.g. projects/sub-A/ses-001/eeg/sub-A_ses-001_task-foo.xdf.
  • The (optional) project_other root location is the directory where the experiments (e.g .py, .oxexp) and behavioral files (e.g. eye-tracking recordings, labnotebook, participant forms, etc ) are stored.
  • The bids root location is the directory where the converted BIDS data is stored, along with source data and code files which we want to version control using Datalad.

Important

The package is looking in these paths, and extracts some metadata from the BIDS-like names. You can change the location of the root directories according to your preference. You must also strictly follow the naming convention for the project and subject subdirectories.

Here you will find the recommended directory structure for storing the project data (recorded, other and converted data) in the data_organization file.

Step 4: Generate the configuration files¤

This configuration is required to run for running the automation pipeline of lslautobids.

  1. AutoBIDS and Dataverse Configuration :
  2. Run the command below to create a configuration file template in folder ~/.config/lslautobids/ folder. This will create a config file with the dataverse details and the root directories for the projects. 

lslautobids gen-dv-config
- Edit the file e.g. via nano ~/.config/lslautobids/autobids_config.yaml to add the dataverse and project root details.

This will be mostly same for all the projects, thus running this command is only recommended once per system.

  1. Project Configuration : This is to be done once for each new project. This store the project details like project name, project id, project description etc. and is saved in a projects/<PROJECT_NAME>/project_<PROJECT_NAME>.toml file
  2. Run the command below to create a configuration file template in projects/<PROJECT_NAME>/ folder (according to the selected root directories).
lslautobids gen-proj-config -p <projectname>

Step 6: Run the conversion scripts¤

Run the conversion scripts to convert the xdf files to BIDS format and upload the data to the dataverse. 

lslautobids run -p TestData2025

Note

You can run the --help for all the commands to get more information about the available options and directly lsl-autobids help to get the list of available commands.