shamo

Introduction

Constructing accurate subject specific head model is of main interest in the fields of source imaging (EEG/MEG) and brain stimulation (tDCS/tMS). shamo is an open source python package to calculate EEG leadfields, current flows, and electric potential distribution in the head. From a labelled 3D image of the head, the whole process is fully automatized, relying only on a few parameter files, e.g. conductivities (including white matter anisotropy) plus source and electrode locations. Since there is no non-invasive method to measure the electromagnetic (EM) properties of the head tissues, shamo can also be used to assess the sensitivity of the EM head model to these parameters.

Philosophy

The idea leading the development of shamo is to provide a versatile, intuitive and extendable toolbox for electromagnetic modelling of the head. Every object is though to be savable/loadable as a dictionary and stored as a JSON file on disk. shamo is built around three main concepts:

1. Problem: The definition of a task to perform. Computing the EEG leadfield or simulating tDCS for examples.
2. Solution: The object resulting from the resolution of a problem.
3. Surrogate: If the problem-solution pair is parametric, e.g. some parameters are random variables, surrogate can be used to produce parametric models.

One of the leading rules while working on shamo was to use already existing quality tools to perform key steps. Thus, the finite element generation is achieved by interfacing with CGAL and Gmsh, the physical problem resolution is done with GetDP, the Gaussian processes are generated with scikit-learn and the sensitivity analysis uses SALib.

Documentation

The documentation of shamo is available here and tutorials are available in the form of jupyter notebooks in this repository.

FAQ

Where can you get help about shamo?

If you need help with your project involving shamo, head over to this page and pick up the help template. Make sure your question does not already exist fy searching the issues.

We'll be happy to give you some help!

Where does the name "shamo" come from?

The name "shamo", pronounced [ʃɑ:mɔ:], stands for "Stochastic HeAd MOdelling".

In french, it sounds like the word "chameau" which is the translation for "camel". This is a reference to the bematists, those ancient greek and egyptians who were able to measure distances with a high accuracy by counting the steps of a camel. They were involved in the accurate calculation of the circumference of the Earth by limiting distance measurement errors.

As did the old bematists, this tool aims at raising the accuracy in outcome of neuro- studies by providing more insights on the errors involved.

How to contribute?

You can contribute to shamo in several ways like adding new features, fixing bugs or improving documentation and examples.

For more information, refer to this document.

How to cite?

If you use shamo in your work, please cite this paper (Available in open access on both Orbi and Arxiv):

@article{grignard_shamo_2022,
	title = {Shamo: A Tool for Electromagnetic Modeling, Simulation and Sensitivity} {Analysis of the Head},
	issn = {1559-0089},
	shorttitle = {Shamo},
	doi = {10.1007/s12021-022-09574-7},
	language = {en},
	journal = {Neuroinformatics},
	author = {Grignard, Martin and Geuzaine, Christophe and Phillips, Christophe},
	month = mar,
	year = {2022},
}

License

Copyright (C) 2020 GIGA CRC In-Vivo Imaging, Liège, Belgium

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

For more information, refer to the full license.