Merge branch 'release/0.1.0'

.dockerignore

@@ -0,0 +1,12 @@
+.git
+.venv
+**/.ipynb_checkpoints
+*.egg-info
+**/__pycache__
+docs
+examples
+tests
+.gitlab-ci.yml
+*.md
+!README*.md
+tox.ini

.gitignore

@@ -0,0 +1,5 @@
+.ipynb_checkpoints
+.venv
+*.egg-info
+__pycache__
+derivatives

.gitlab-ci.yml

@@ -0,0 +1,77 @@
+stages:
+    - docker-build
+    - static-test
+    - integrated-test
+
+# BUILD DOCKER TEST IMAGES ----------------------------------------------------
+.docker-build-test:
+    stage: docker-build
+    when: manual
+    image:
+        name: gcr.io/kaniko-project/executor:debug
+        entrypoint: [""]
+    script:
+        - echo "{\"auths\":{\"${DOCKER_HUB}\":{\"username\":\"${DOCKER_HUB_USER}\",\"password\":\"$DOCKER_HUB_PASSWORD\"}}}" > /kaniko/.docker/config.json
+        - cat /kaniko/.docker/config.json
+        - /kaniko/executor --cache=true --context dir:///tmp/workspace --dockerfile Dockerfile --destination ${DOCKER_HUB}/${DOCKER_HUB_USER}/shamo:test-${PY}
+
+# Python 3.5
+docker-build-test-3.5:
+    extends: .docker-build-test
+    variables:
+        PY: "3.5"
+
+# Python 3.6
+docker-build-test-3.6:
+    extends: .docker-build-test
+    variables:
+        PY: "3.6"
+
+# Python 3.7
+docker-build-test-3.7:
+    extends: .docker-build-test
+    variables:
+        PY: "3.7"
+
+# Python 3.8
+docker-build-test-3.8:
+    extends: .docker-build-test
+    variables:
+        PY: "3.8"
+# STATIC TESTS ----------------------------------------------------------------
+flake8:
+    stage: static-test
+    image: ${DOCKER_HUB_USER}/shamo:test-3.7
+    script:
+        - tox -e flake8
+
+# INTEGRATED TESTS ------------------------------------------------------------
+.test:
+    stage: integrated-test
+    image: ${DOCKER_HUB_USER}/shamo:test-${PY}
+    script:
+        - tox -e py${PY}
+
+# Python 3.5
+test-3.5:
+    extends: .test
+    variables:
+        PY: "3.5"
+
+# Python 3.6
+test-3.6:
+    extends: .test
+    variables:
+        PY: "3.6"
+
+# Python 3.7
+test-3.7:
+    extends: .test
+    variables:
+        PY: "3.7"
+
+# Python 3.8
+test-3.8:
+    extends: .test
+    variables:
+        PY: "3.8"

CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+
+
+## [0.1.0] - 2020-05-13
+
+### Added
+
+- Finite element model generation from labeled (segmented) images.
+- EEG forward problem resolution.
+- EEG parametric forward resolution and surrogate model generation.
+- EEG simulation.
+- Sphinx documentation.
+- Examples for finite element model generation, EEG forward problem resolution, EEG parametric forward problem resolution and EEG simulation.

Dockerfile

@@ -0,0 +1,71 @@
+ARG PY=3.7
+
+# SYSTEM DEPENDENCIES ---------------------------------------------------------
+# This stage installs all required system dependencies and makes sure to add
+# them to the path.
+FROM python:${PY}-buster AS sys-deps
+
+MAINTAINER "Martin Grignard, [email protected]"
+LABEL maintainer="Martin Grignard, [email protected]"
+LABEL affiliation="GIGA CRC In vivo imaging, University of Liège, Liège, Belgium"
+LABEL description="A tool for electromagnetic modelling of the head and sensitivity analysis."
+LABEL link="https://github.com/CyclotronResearchCentre/shamo"
+
+RUN apt-get update && \
+    apt-get install -y \
+        libglu1-mesa \
+        libxext-dev \
+        libxrender-dev \
+        libxtst-dev \
+        libxcursor-dev \
+        libxft2 \
+        libxinerama1 \
+        wget \
+        openmpi-bin \
+        libcgal-dev \
+        libeigen3-dev && \
+    rm -rf /var/lib/apt/lists/*
+
+# Install GetDP (http://getdp.info/)
+RUN wget -O /tmp/getdp.tgz http://getdp.info/bin/Linux/getdp-3.3.0-Linux64c.tgz && \
+    tar -zxvf /tmp/getdp.tgz -C /opt && \
+    rm /tmp/getdp* && \
+    mv /opt/getdp* /opt/getdp
+
+# Add Gmsh and GetDP to the path
+ENV PATH=${PATH}:/opt/gmsh/bin/:/opt/getdp/bin/ \
+    PYTHONPATH=${PYTHONPATH}:/opt/gmsh/lib/
+
+# PYTHON DEPENDENCIES ---------------------------------------------------------
+# Install python dependencies.
+FROM sys-deps AS py-deps
+
+COPY requirements.txt /tmp/
+
+RUN python -m pip install -r /tmp/requirements.txt
+
+# TEST ------------------------------------------------------------------------
+# Install dependencies for test stages and create a test user.
+FROM py-deps AS test
+
+RUN python -m pip install flake8 pytest tox
+
+RUN useradd --create-home test
+WORKDIR /home/test
+USER test
+
+# DEPLOY ----------------------------------------------------------------------
+# Create a usable docker with shamo installed.
+FROM py-deps AS deploy
+
+RUN useradd --create-home shamo
+USER shamo
+
+WORKDIR /tmp
+COPY . /tmp/
+RUN python setup.py install --user
+
+WORKDIR /home/shamo
+
+
+ENTRYPOINT ["python"]

MANIFEST.in

@@ -0,0 +1,2 @@
+include *.pro
+include *.template

README.md

@@ -1 +1,5 @@
-shamo
+# shamo
+
+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.
+
+For more information, see [the documentation](https://cyclotronresearchcentre.github.io/shamo/index.html).

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = src
+BUILDDIR      = ../../shamo-docs
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -T

docs/src/api/api.rst

@@ -0,0 +1,42 @@
+API reference
+=============
+
+The public API of :mod:`shamo` only provides a subset of the classes and methods defined in the package.
+Here is a quick description of the exposed classes.
+
+Finite element model
+--------------------
+
+- :class:`FEModel <shamo.model.fe_model.FEModel>`: The model itself which holds all the data and provides all the methods.
+- :class:`MeshConfig <shamo.model.mesh_config.MeshConfig>`: The parameters passed to the meshing algorithm.
+
+Problems
+--------
+
+EEG
+~~~
+- :class:`EEGForwardProblem <shamo.problems.forward.eeg.eeg_forward_problem.EEGForwardProblem>`: A problem used to generate a single leadfield matrix.
+- :class:`EEGParametricForwardProblem <shamo.problems.forward.eeg.eeg_parametric_forward_problem.EEGParametricForwardProblem>`: A problem used to generate a parametric leadfield matrix.
+- :class:`EEGSimulationProblem <shamo.problems.forward.eeg.eeg_simulation_problem.EEGSimulationProblem>`: A problem to simulate sources in the brain for EEG.
+
+Solutions
+---------
+
+EEG
+~~~
+- :class:`EEGForwardSolution <shamo.solutions.forward.eeg.eeg_forward_solution.EEGForwardSolution>`: A single leadfield matrix.
+- :class:`EEGParametricForwardSolution <shamo.solutions.forward.eeg.eeg_parametric_forward_solution.EEGParametricForwardSolution>`: A parametric leadfield matrix.
+- :class:`EEGSimulationSolution <shamo.solutions.forward.eeg.eeg_simulation_solution.EEGSimulationSolution>`: A simulation of sources in the brain for EEG.
+
+
+Sources
+-------
+
+- :class:`FESource <shamo.model.sources.fe_source.FESource>`: A source defined in a finite element model.
+- :class:`EEGSource <shamo.model.sources.eeg_source.EEGSource>`: A source defined in an EEG problem.
+
+Distributions
+-------------
+
+- :class:`ConstantDistribution <shamo.core.distribution.ConstantDistribution>`: For a property with a fixed value.
+- :class:`UniformDistribution <shamo.core.distribution.UniformDistribution>`: For a property with uniformly distributed values.

docs/src/conf.py

@@ -0,0 +1,77 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+import os
+import sys
+sys.path.insert(0, os.path.abspath("../.."))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "shamo"
+copyright = "2020, Martin Grignard"
+author = "Martin Grignard"
+
+# The full version, including alpha/beta/rc tags
+release = "0.1.0"
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named "sphinx.ext.*") or your custom
+# ones.
+extensions = [
+    "numpydoc",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.inheritance_diagram",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.viewcode"
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = [
+    "test"
+]
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+# -- Option for intersphinx --------------------------------------------------
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://docs.scipy.org/doc/numpy", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/reference", None),
+    "matplotlib": ("https://matplotlib.org", None),
+    "chaospy": ("https://chaospy.readthedocs.io/en/master", None)
+}
+
+# -- Options for numpydoc ----------------------------------------------------
+
+numpydoc_use_plots = True
+numpydoc_show_class_members = False
+numpydoc_attributes_as_param_list = False
+numpydoc_xref_param_type = True
+
+# -- Options for read the docs theme -----------------------------------------
+
+html_theme = "sphinx_rtd_theme"
+html_theme_path = ["_themes"]
+html_theme_options = {
+    "collapse_navigation": False
+}

docs/src/core/core.rst

@@ -0,0 +1,10 @@
+shamo.core
+==========
+
+.. toctree::
+   :maxdepth: 2
+
+   distribution
+   objects
+   problem
+   solution

docs/src/core/distribution.rst

@@ -0,0 +1,23 @@
+shamo.core.distribution
+=======================
+
+shamo.core.distribution.Distribution
+------------------------------------
+
+.. autoclass:: shamo.core.distribution.Distribution
+    :members:
+    :undoc-members:
+
+shamo.core.distribution.ConstantDistribution
+--------------------------------------------
+
+.. autoclass:: shamo.core.distribution.ConstantDistribution
+    :members:
+    :undoc-members:
+
+shamo.core.distribution.UniformDistribution
+-------------------------------------------
+
+.. autoclass:: shamo.core.distribution.UniformDistribution
+    :members:
+    :undoc-members: