[RELEASE] 1.0.0

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,28 @@
+---
+name: Bug report
+about: Create a report to help us improve.
+title: "[BUG]"
+labels: bug
+---
+### Describe the bug
+A clear and concise description of what the bug is.
+
+### To Reproduce
+Steps to reproduce the behavior. If possible, add a simple sample code which reproduces the bug you are experiencing.
+
+### Expected behavior
+A clear and concise description of what you expected to happen.
+
+### Screenshots
+If applicable, add screenshots to help explain your problem.
+
+### Environment
+```
+- Go to your working directory
+- Activate your virtual environment
+- Use the command `shamo-report`
+- Paste the output of this command in place of this text.
+```
+
+### Additional context
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest an idea for this project.
+title: "[FEATURE]"
+labels: enhancement
+---
+### Is your feature request related to a problem? Please describe.
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+### Describe the solution you'd like
+A clear and concise description of what you want to happen.
+
+### Describe alternatives you've considered
+A clear and concise description of any alternative solutions or features you've considered.
+
+### Additional context
+Add any other context or screenshots about the feature request here.

.github/ISSUE_TEMPLATE/help.md

@@ -0,0 +1,11 @@
+---
+name: Help
+about: Ask for some help on how to use this project.
+title: "[Help]"
+labels: question
+---
+### What do you want help for?
+A quick description of what you want to achieve.
+
+### What have you tried?
+Show what you have tried already.

.github/workflows/pypi.yml

@@ -0,0 +1,46 @@
+name: Pypi package
+
+on:
+  push:
+    tags: [ '*' ]
+
+jobs:
+    build-and-publish:
+      name: Build and publish Test PyPI and PyPI package 🐍
+      runs-on: ubuntu-latest
+      steps:
+        - name: Checkout code
+          uses: actions/checkout@v2
+
+        - name: Set up Python 3.8
+          uses: actions/setup-python@v1
+          with:
+            python-version: 3.8
+
+        - name: Install pep517
+          run: >-
+            python -m
+            pip install
+            pep517
+            --user
+
+        - name: Build binary wheel and source tarball
+          run: >-
+            python -m
+            pep517.build
+            --source
+            --binary
+            --out-dir dist/
+            .
+
+        - name: Publish distribution to Test PyPI
+          uses: pypa/gh-action-pypi-publish@master
+          with:
+            password: ${{ secrets.TEST_PYPI_PASSWORD }}
+            repository_url: https://test.pypi.org/legacy/
+
+        - name: Publish distribution to PyPI
+          if: startsWith(github.ref, 'refs/tags')
+          uses: pypa/gh-action-pypi-publish@master
+          with:
+            password: ${{ secrets.PYPI_PASSWORD }}

.gitignore

@@ -0,0 +1,4 @@
+.venv
+.tox
+__pycache__
+*.egg-info

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "docs/src/quickstart/usage/tutorials"]
+	path = docs/src/quickstart/usage/tutorials
+	url = [email protected]:CyclotronResearchCentre/shamo-tutorials.git
+    branch = master

.pre-commit-config.yaml

@@ -0,0 +1,6 @@
+repos:
+  - repo: https://github.com/psf/black
+    rev: 19.10b0
+    hooks:
+      - id: black
+        language_version: python3

CHANGELOG.md

@@ -0,0 +1,25 @@
+# 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]
+
+## [1.0.0] - 20-12-16
+
+### Added
+
+- Added `ObjABC`, `ObjFile` and `ObjDir` classes to provide a base for any savable/loadable object.
+- Added `Group`, `Tissue`, `Field`, `Sensor`, `PointSensor` and `FEM` classes to provide a way to generate realistic finite element model based on labelled volumes.
+- Added `ProbABC`, `CompABC`, `CompFilePath`, `CompGridSampler`, `CompSensors`, `CompTissueProp`, `CompTissues` and `ProbGetDP` classes to define any problem.
+- Added `SolGetDP` class to store information about the solution of a `ProbGetDP` problem.
+- Added `DistABC`, `DistConstant`, `DistNormal`, `DistTruncNormal` and `DistUniform` to model random parameters for parametric problems.
+- Added `ProbParamABC`, `CompParamTissueProp`, `CompParamValue`, and `ProbParamGetDP` classes to define any parametric problem.
+- Added `SolParamABC` and `SolParamGetDP` classes to store information about the solution of a `ProbParamABC` problem.
+- Added `ProbEEGLeadfield` and `SolEEGLeadfield` classes to solve the EEG forward problem.
+- Added `ProbParamEEGLeadfield`, `SolParamEEGLeadfield` and `SurrEEGLeadfield` classes to solve the parametric EEG forward problem. Also added `SurrEEGLeadfieldToRef` class to evalaute the sensitivity of the EEG leadfield matrix.
+- Added `ProbHDTDCSSim` and `SolHDTDCSSim` classes to simulate a HD-tDCS.
+- Added `ProbParamHDTDCSSim` and `SolParamHDTDCSSim` classes to simulate a parametric HD-tDCS.
+- Added `SurrogateABC` class to define any surrogate model based on a `SolParamABC`.
+- Added `SurrScalar` class to define any surrogate model returning a scalar to perform sensitivity analysis.
+- Added `shamo-report` command to facilitate bug report.
+- Added automated full reference with sphinx autosummary.

CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing to shamo
+
+First, I would like to thank you for your interest in *shamo*. If you want to improve the tool, here are the ways you can help:
+- [Requesting new features](#requesting-new-features)
+- [Finding and reporting bugs](#finding-and-reporting-bugs)
+- [Enhancing documentation and examples](enhancing-documentation-and-examples)
+- [Developing shamo](#developing-shamo)
+    - [Enhancing existing features](#enhancing-existing-features-and-fixing-bugs)
+    - [Adding new features](#adding-new-features)
+
+## Requesting new features
+
+To request a new feature, head over to [this page](https://github.com/CyclotronResearchCentre/shamo/issues/new), pick the feature request template and describe as precisely as possible the feature you want to be added.
+
+## Finding and reporting bugs
+
+To report a bug, head over to [this page](https://github.com/CyclotronResearchCentre/shamo/issues/new), pick the bug report template and describe as precisely as possible the issue you are facing.
+
+## Enhancing documentation and examples
+
+If you want to only edit the documentation, make of fork of the project. Once it is done, clone the repository on your machine and start working on the documentation. If you want to edit the code, take a look at [developing shamo](#developing-shamo).
+
+## Developing shamo
+
+If you want to participate to the development of *shamo*, make of fork of the project. Once it is done, clone the repository on your machine and create a virtual environment in the project directory following these steps:
+
+```shell
+python3 -m venv --prompt shamo .venv
+.venv/bin/activate
+python3 -m pip install -r requirements.txt
+python3 -m pip install -r dev-requirements.txt
+python3 -m pip install -e .
+```
+
+Make sure you also have [Gmsh](https://gmsh.info/#Download), [GetDP](https://getdp.info/#Download) and [CGAL](https://www.cgal.org/download.html) installed on your computer.
+
+This project uses [black](https://black.readthedocs.io/en/stable/index.html) for its code formatting so make sure to either [integrate it to your code editor](https://black.readthedocs.io/en/stable/editor_integration.html) to apply the format directly in it or to [install a pre-commit hook](https://black.readthedocs.io/en/stable/version_control_integration.html).
+
+Once everything is properly setup, create a new branch called `feature/{feature_name}` and start writing code.
+
+When you are done working, create a [pull request](https://github.com/CyclotronResearchCentre/shamo/pulls). We'll review the modifications you did as soon as possible.
+
+### Enhancing existing features and fixing bugs
+
+<!-- TODO: Add documentation about how to propose bug fixes and features enhancements. -->
+
+### Adding new features
+
+Many features can be implemented in *shamo*. Here are the instructions to add some of them.
+
+Everything in *shamo* is defined as a pair of objects where the problem defines the computation and the solution stores the result.
+
+The structure of *shamo* is split into the `core` package which contains all the features shared by all or at least some of the problems/solutions and the modalities such as `eeg` or `hd_tdcs` containing the actual processes. Those packages are further split into sub-packages focused on a single process.
+```shell
+src/shamo/
+├── cli/                # Contain the command line interface.
+├── core/               # Contain the features shared by many objects.
+└── modality/           # Define a new modality with one or multiple processes.
+    └── process/        # Define a process with its problems and solutions.
+        ├── parametric/ # Define the parametric problem-solution pair of the process.
+        └── single/     # Define the single problem-solution pair of the process.
+```
+
+#### Add a new problem-solution pair
+
+To add a new modality called `new_modality`, add the sub-package in the `src/shamo` directory as:
+
+#### Add a new parametric problem-solution pair
+
+#### Add a new surrogate model

MANIFEST.in

@@ -0,0 +1,2 @@
+include *.md
+include templates/*

README.md

@@ -1 +1,59 @@
-shamo
+# shamo
+
+[![version](https://img.shields.io/pypi/v/shamo?color=black&logo=pypi&logoColor=white&style=flat-square)](https://pypi.org/project/shamo/)
+![Python](https://img.shields.io/pypi/pyversions/shamo?logo=python&logoColor=white&color=black&style=flat-square)
+[![codestyle](https://img.shields.io/badge/codestyle-black-black?style=flat-square)](https://github.com/psf/black)
+[![docstyle](https://img.shields.io/badge/docstyle-numpydoc-black?style=flat-square)](https://numpydoc.readthedocs.io/en/latest/)
+[![license](https://img.shields.io/pypi/l/shamo?color=black&style=flat-square)](https://github.com/CyclotronResearchCentre/shamo/blob/master/LICENSE.md)
+
+## 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.
+1. **Solution:** The object resulting from the resolution of a problem.
+1. **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](https://www.cgal.org/) and [Gmsh](https://gmsh.info/), the physical problem resolution is done with [GetDP](https://getdp.info/), the Gaussian processes are generated with [scikit-learn](https://scikit-learn.org/stable/) and the sensitivity analysis uses [SALib](https://salib.readthedocs.io/en/latest/).
+
+## Documentation
+
+The documentation of *shamo* is available [here](https://cyclotronresearchcentre.github.io/shamo/index.html) and tutorials are available in the form of jupyter notebooks in [this repository](https://github.com/CyclotronResearchCentre/shamo-tutorials).
+
+## FAQ
+
+### Where can you get help about *shamo*?
+
+If you need help with your project involving *shamo*, head over to [this page](https://github.com/CyclotronResearchCentre/shamo/issues/new) 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](CONTRIBUTING.md).
+
+## License
+
+Copyright (C) 2020 [GIGA CRC In-Vivo Imaging](https://www.giga.uliege.be/cms/c_5634375/fr/giga-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](LICENSE.md).

dev-requirements.txt

@@ -0,0 +1,11 @@
+black==19.10b0
+bump2version>=1.0.1
+nbsphinx>=0.8.0
+numpydoc>=1.1.0
+pre-commit>=2.8.2
+pytest>=6.1.1
+pytest-assume>=2.3.3
+Sphinx>=3.3.1
+sphinxcontrib-bibtex>=2.0.0
+sphinx-rtd-theme>=0.5.0
+tox>=3.20.1

docs/Makefile

@@ -0,0 +1,21 @@
+# 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
+	rm -rf src/reference/.autosummary

docs/src/.templates/custom-class-template.rst

@@ -0,0 +1,34 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :show-inheritance:
+   :inherited-members:
+   :special-members: __call__, __add__, __mul__
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :nosignatures:
+   {% for item in methods %}
+      {%- if not item.startswith('_') %}
+      ~{{ name }}.{{ item }}
+      {%- endif -%}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}