GSoC sovabids work product
BIDS is a standard for neuroimaging datasets that helps with data sharing and reusability; as a result it has been widely adopted by the community. Although developed for MRI originally, it has gained popularity within the EEG realm. Converting raw data to the BIDS standard is not difficult but requires a lot of time if done by hand. Currently software like mne-bids, eeg2bids, data2bids are available to assist and facilitate this conversion but there is still no automated way to produce a valid BIDS dataset for the EEG use-case.
The goal of this GSoC 2021 project was a python package that provided a backend for a more automated eeg-to-bids conversion that was set up by simple configuration files.
Initially the proposal of my mentors Aswin Narayanan, Oren Civier, Steffen Bollmann, and Tom Johnstone was to develop or enhance an already existing GUI to provide an user-friendly procedure for MEG and EEG to-bids conversion. Nevertheless, through some early discussions we arrived at the conclusion of making a backend for the conversion rather than focusing on the GUI; this since GUI is harder to maintain and since the proliferation of web applications motivate the implementation of an API that could be consumed by any particular web application providing a GUI. Likewise, given my eeg background the GSoC project was constrained to eeg conversion. The proposal presented to the GSoC can be found here.
Two set up files for the conversion process were designed: one from the general (dataset-wise) point of view and one from the individual (eeg-file-wise) points-of-view. These files are two yaml files known as the 'rules file' and the 'mappings file' respectively.
The package has the following architecture:
Given this architecture, the main development milestones were:
- Develop heuristics and functions to infer information from the path of the source files
- Develop a schema for the 'Rules File' which holds the set up for conversion from a general (or dataset-wise) point of view
- Develop a schema for the 'Mappings File' which holds the set up for conversion from an individual (eeg-file-wise) point of view
- Develop an 'Apply Rules' module that interprets the 'Rules File' and ouputs a 'Mappings File'
- Develop a 'Convert Them' module that interprets the 'Mappings File' and performs the conversion
- Develop a plugin for bidscoin which would be one example use-case of the python API of sovabids being consumed by a third-party GUI
- Develop a CLI tool to use sovabids in a stand-alone manner
- Develop a WEB API to use sovabids in a web-application context
- Develop a minimal web-app that would illustrate the comsumption of the WEB API of the package
- Implement testing and code-coverage
- Implement CI to improve the maintainability of the project
- Implement an auto-generated documentation for the package and its hosting at readthedocs
- Make example use-case tutorials
- Implement software versioning using semantic versioning and versioneer
The chronology of how these milestones advanced week-by-week is kept here.
Since the development was done on a single-purpose github repository for the GSoC, all of these developments were merged into main. Almost all of the code for these milestones was written by me through these commits during the GSoC. Nevertheless, for each of these milestones I will list the main associated commits, discussions and issues:
Develop heuristics and functions to infer information from the path of the source files
Develop a schema for the 'Rules File' which holds the set up for conversion from a general (or dataset-wise) point of view
Develop a schema for the 'Mappings File' which holds the set up for conversion from an individual (eeg-file-wise) point of view
Develop an 'Apply Rules' module that interprets the 'Rules File' and ouputs a 'Mappings File'
- Commits listed here
Develop a 'Convert Them' module that interprets the 'Mappings File' and performs the conversion
- Commits listed here
bidscoin which would be one example use-case of the python API of sovabids being consumed by a third-party GUIDevelop a plugin for
The work of this milestone was mainly accomplish by my interaction with the bidscoin developer at the OHBM brainhack 2021
Develop a CLI tool to use sovabids in a stand-alone manner
Develop a WEB API to use sovabids in a web-application context
Develop a minimal web-app that would illustrate the comsumption of the WEB API of the package
My work on the web-app builts upon the core flask-app he did by adding more functionalities and interconecting the app to sovabids through the WEB API.
My commits are the ones listed here minus the 2 commits done by Brayan (leoBAHM).
Implement testing and code-coverage
Implement CI to improve the maintainability of the project
Implement an auto-generated documentation for the package and its hosting at readthedocs
Make example use-case tutorials
- Commits listed here
Implement software versioning using semantic versioning and versioneer
Current state of the project
The project is usable but it is at an alpha state of development, so its design or API may change.
Follow the advanced installation instructions here and then you can run any of the following examples:
- Example of sovabids usage through the python API and CLI
- Example of sovabids usage through bidscoin
- Example of sovabids usage through the WEB API
- Example of sovabids usage through the minimal web-app developed
Work left to do
I plan to continue maintaining sovabids since my participation in GRUNECO involves eeg data management so it is directly usable for me.
The current main issues that need work are:
- Deal with the use-case of incremental conversion (here)
- Redesign of the rules file for more extensibility, more powerful heuristics and better usage of metadata files (here)
- Develop heuristics for metadata files (here)
- Implement a way to conserve the where a piece of information came from (here)
- Solve some front-end bugs (here and here)
- Design how sovabids will deal with datasets with inconsistent path pattern (here)
- Implement a form-based way of producing the rules file for non-technical users
- Once the final format of the rules file is stable, implement a validator for it (here)
- I'm no expert on logging and error handling so both of this need to be improved (here)
- More testing on non-brainvision files
- Extension to MEG use-case
Through this project the main learning were:
- Software design
This project required a lot of design since it was developed from the scratch. A lot of proposals were made and a lot of discussions were and are still being done with the mentors regarding the designing of the package.
- CLI development in python
I was inspired by the source code of bidscoin.
- Logging functionality in python
Again, I was inspired by the source code of bidscoin.
- Software Versioning
I learned how to do this in a more consistent way through the ideas of semantic versioning (which the mentors guided me to) and the workflow of versioneer. I was inspired by the source code of pyprep for the versioneer implementation.
- Implementing CI in github
I was inspired by the source code of pyprep
- Implementing code-coverage
Again, I was inspired by the source code of pyprep
- Software documentation through sphinx
Through this GSoC project I wanted to document with an as-you-go philosophy, so I implemented docstrings as soon as I finished the functions.
This paired nicely with learning sphinx because I was then able to produce automatic documentation from the docstring I made.
I also learned to implement documented examples with code through sphinx, which was crucial for the testing of the code by the mentors.
- RPC API development through fastapi-jsonrpc
Thanks to my mentors since I was pretty clueless on how to do this, but their guidance helped me accomplish it.
- Flask web-app development
Thanks to Brayan Andrés Hoyos Madera as his core flask web-app served as an example that I was able to reverse-engineer and improve.
- Improvement of my regex abilities
Thanks to Marcel from bidscoin
- Some bash tricks
My mentors were able to help me with some problems for the CI testing using bash. I feel I understand it better now.
- Hackathons planning
Through the OHBM hackathon I learned some ideas regarding their logistics which hopefully will help me implement a low-scale version of them at NeuroCo which is an student group of my university.