Skip to content

Instantly share code, notes, and snippets.

@yjmantilla

yjmantilla/work_product_gsoc2021_sovabids.md

Last active September 16, 2021 05:12
  • Star 1 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
Star You must be signed in to star a gist
Embed
What would you like to do?
Learn more about clone URLs
Download ZIP
work_product_gsoc2021_sovabids
Raw
work_product_gsoc2021_sovabids.md

GSoC sovabids work product

Description

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.

Given the goal, the developed package was named sovabids, which is under this github repository which is single-purpose for the GSoC. The documentation of the package is here.

The conversion was done through the power of the mne and mne-bids packages, which helped to infer eeg bids-relevant properties and execute the conversion respectively.

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:

arch

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:

Work Done

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

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

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

These commits:

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

This part was done with the help of Brayan Andrés Hoyos Madera who did 2PRs and their commits: here and here

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.

Usable Outcomes

Follow the advanced installation instructions here and then you can run any of the following examples:

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

Learnings

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.

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.

I also came to know about the minihack consortium through the OHBM hackathon, and as a result NeuroCo plans to participate in it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment