diff --git a/.gitignore b/.gitignore index b85fa319..5fe27778 100644 --- a/.gitignore +++ b/.gitignore @@ -79,4 +79,4 @@ target/ # doc _build/ auto_examples/ -modules/ + diff --git a/.travis.yml b/.travis.yml index a1d84d49..babd2810 100644 --- a/.travis.yml +++ b/.travis.yml @@ -13,13 +13,11 @@ install: - sudo apt-get update - pip install -r requirements.txt - pip install -e . - - pip install sphinx-gallery - - pip install numpydoc - - pip install sphinx_bootstrap_theme - pip install git+https://github.com/pymanopt/pymanopt script: - mkdir docs - cd doc + - pip install -r requirements.txt # - sphinx-autogen *.rst - make html - touch _build/html/.nojekyll diff --git a/README.md b/README.md index 27d6f260..162a0abd 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # MEEGkit [![unit-tests](https://github.com/nbara/python-meegkit/workflows/unit-tests/badge.svg?style=flat)](https://github.com/nbara/python-meegkit/actions?workflow=unit-tests) -[![Travis](https://img.shields.io/travis/nbara/python-meegkit.svg?label=documentation&logo=travis)](https://travis-ci.org/nbara/python-meegkit) +[![documentation](https://img.shields.io/travis/nbara/python-meegkit.svg?label=documentation&logo=travis)](https://travis-ci.org/nbara/python-meegkit) [![codecov](https://codecov.io/gh/nbara/python-meegkit/branch/master/graph/badge.svg)](https://codecov.io/gh/nbara/python-meegkit) [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/nbara/python-meegkit/master) [![twitter](https://img.shields.io/twitter/follow/lebababa?label=Twitter&style=flat&logo=Twitter)](https://twitter.com/intent/follow?screen_name=lebababa) diff --git a/doc/Makefile b/doc/Makefile index c86c2da4..1b22e89e 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -25,7 +25,6 @@ clean: -rm -rf _build/* -rm -rf _source/* -rm -rf generated - -rm -rf auto_examples/* -rm -rf *.stc -rm -rf *.fif -rm -rf *.nii.gz diff --git a/doc/conf.py b/doc/conf.py index 88691a47..ada6ab3c 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -12,10 +12,6 @@ # import os import sys -from numpydoc import docscrape # noqa -import sphinx_gallery # noqa -import sphinx_bootstrap_theme # noqa - import matplotlib matplotlib.use('agg') @@ -27,9 +23,10 @@ # -- Project information ----------------------------------------------------- -project = 'MEEGkit' -copyright = '2020, Nicolas Barascud' +project = f'MEEGkit v{meegkit.__version__}' +copyright = '2021, Nicolas Barascud' author = 'Nicolas Barascud' +release = meegkit.__version__ version = meegkit.__version__ # -- General configuration --------------------------------------------------- @@ -42,7 +39,9 @@ 'sphinx.ext.autosummary', 'sphinx.ext.napoleon', 'numpydoc', + 'jupyter_sphinx', 'sphinx_gallery.gen_gallery', + 'sphinxemoji.sphinxemoji', ] # Add any paths that contain templates here, relative to this directory. @@ -75,10 +74,8 @@ # -- Options for HTML output ------------------------------------------------- -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = 'bootstrap' +# The theme to use for HTML and HTML Help pages +html_theme = 'pydata_sphinx_theme' # 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, @@ -87,62 +84,33 @@ html_theme_options = { - # Tab name for entire site. (Default: "Site") - 'navbar_site_name': "MEEGkit documentation", - - # Render the next and previous page links in navbar. (Default: true) - 'navbar_sidebarrel': False, - - # Links in the navbar - 'navbar_links': [ - ("Examples", "auto_examples/index"), - ("GitHub", "https://github.com/nbara/python-meegkit", True) + "show_toc_level": 1, + "external_links": [ + { + "name": "GitHub", + "url": "https://github.com/nbara/python-meegkit", + } + ], + "icon_links": [ + { + "name": "GitHub", + "url": "https://github.com/nbara/python-meegkit", + "icon": "fab fa-github-square", + }, + { + "name": "Twitter", + "url": "https://twitter.com/lebababa", + "icon": "fab fa-twitter-square", + }, ], + "use_edit_page_button": True, +} - # Render the current pages TOC in the navbar. (Default: true) - 'navbar_pagenav': True, - - # Tab name for the current pages TOC. (Default: "Page") - 'navbar_pagenav_name': "Page", - - # Global TOC depth for "site" navbar tab. (Default: 1) - # Switching to -1 shows all levels. - 'globaltoc_depth': 2, - - # Include hidden TOCs in Site navbar? - # - # Note: If this is "false", you cannot have mixed ``:hidden:`` and - # non-hidden ``toctree`` directives in the same page, or else the build - # will break. - # - # Values: "true" (default) or "false" - 'globaltoc_includehidden': "true", - - # HTML navbar class (Default: "navbar") to attach to
element. - # For black navbar, do "navbar navbar-inverse" - 'navbar_class': "navbar navbar-inverse", - - # Fix navigation bar to top of page? - # Values: "true" (default) or "false" - 'navbar_fixed_top': "true", - - # Location of link to source. - # Options are "nav" (default), "footer" or anything else to exclude. - 'source_link_position': "nav", - - # Bootswatch (http://bootswatch.com/) theme. - # - # Options are nothing (default) or the name of a valid theme - # such as "cosmo" or "sandstone". - # - # Currently, the supported themes are: - # - Bootstrap 2: https://bootswatch.com/2 - # - Bootstrap 3: https://bootswatch.com/3 - 'bootswatch_theme': "united", - - # Choose Bootstrap version. - # Values: "3" (default) or "2" (in quotes) - 'bootstrap_version': "3", +html_context = { + "github_user": "nbara", + "github_repo": "python-meegkit", + "github_version": "master", + "doc_path": "doc", } # -- Options for Sphinx-gallery HTML ------------------------------------------ @@ -153,4 +121,5 @@ 'gallery_dirs': 'auto_examples', # path to where to save gallery generated output 'filename_pattern': '/example_', 'ignore_pattern': 'config.py', + 'run_stale_examples': False, } diff --git a/doc/index.rst b/doc/index.rst index e4a89444..2a588657 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,23 +1,37 @@ -.. MEEGkit documentation master file, created by +.. ``meegkit`` documentation master file, created by sphinx-quickstart on Fri Jan 10 12:31:49 2020. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to MEEGkit -================== +|:brain:| ``meegkit``: EEG and MEG denoising in Python +====================================================== -The code of the project is on Github: `MEEGkit `_ +Introduction +------------ +``meegkit`` is a collection of EEG and MEG denoising techniques for +**Python 3.6+**. Please feel free to contribute, or suggest new analyses. Keep +in mind that this is mostly development code, and as such is likely to change +without any notice. Also, while most of the methods have been fairly robustly +tested, bugs can (and should!) be expected. -Contents --------- +The source code of the project is hosted on Github at the following address: +https://github.com/nbara/python-meegkit -:py:mod:`meegkit`: +To get started, follow the installation instructions `in the README `_. + +Available modules +----------------- + +Here is a list of the methods and techniques available in ``meegkit``: .. currentmodule:: meegkit +.. toctree:: + :maxdepth: 1 + .. autosummary:: - :toctree: modules/ + :caption: meegkit ~meegkit.asr ~meegkit.cca @@ -30,16 +44,19 @@ Contents ~meegkit.tspca ~meegkit.utils + Examples gallery ---------------- -A gallery of examples is available at the following address: +A number of example scripts and notebooks are available: + .. toctree:: :maxdepth: 2 auto_examples/index + Indices and tables ------------------ diff --git a/doc/modules/meegkit.trca.rst b/doc/modules/meegkit.trca.rst new file mode 100644 index 00000000..42543526 --- /dev/null +++ b/doc/modules/meegkit.trca.rst @@ -0,0 +1,30 @@ +meegkit.trca +============ + +.. automodule:: meegkit.trca + + + + + + + + .. rubric:: Functions + + .. autosummary:: + + trca + TRCA + + + + + + + + + + + + + diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 00000000..6c33dbdb --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,9 @@ +sphinx +sphinx-copybutton +sphinxemoji +pydata-sphinx-theme +numpydoc +matplotlib +pillow +sphinx-gallery +jupyter-sphinx diff --git a/examples/README.rst b/examples/README.rst index 6e79c84e..6dc07724 100644 --- a/examples/README.rst +++ b/examples/README.rst @@ -1,4 +1,8 @@ -MEEGkit examples +Examples gallery ================ -Below is a gallery of examples +Below is a list of example scripts showing basic usage for most methods in +MEEGkit. + +The examples can be browsed directly on `Github `_. + diff --git a/meegkit/cca.py b/meegkit/cca.py index aaa747a6..3f03d8c9 100644 --- a/meegkit/cca.py +++ b/meegkit/cca.py @@ -1,4 +1,4 @@ -"""CCA functions.""" +"""Canonical Correlation Analysis.""" import numpy as np from scipy import linalg diff --git a/meegkit/ress.py b/meegkit/ress.py index 7bc854c1..5d9d916e 100644 --- a/meegkit/ress.py +++ b/meegkit/ress.py @@ -8,7 +8,9 @@ def RESS(X, sfreq: int, peak_freq: float, neig_freq: float = 1, peak_width: float = .5, neig_width: float = 1, n_keep: int = 1, return_maps: bool = False): - """Rhythmic entrainment source separation [1]_. + """Rhythmic Entrainment Source Separation. + + As described in [1]_. Parameters ---------- diff --git a/meegkit/trca.py b/meegkit/trca.py index 2f3c2e75..ae590dd0 100644 --- a/meegkit/trca.py +++ b/meegkit/trca.py @@ -1,4 +1,4 @@ -"""Task-Related Component Analysis (TRCA).""" +"""Task-Related Component Analysis.""" # Author: Giuseppe Ferraro import numpy as np import scipy.linalg as linalg @@ -8,7 +8,7 @@ def trca(X): - """Task-related component analysis (TRCA). + """Task-related component analysis. This function implements the method described in [1]_. diff --git a/meegkit/utils/stats.py b/meegkit/utils/stats.py index cc694857..ba9cdfad 100644 --- a/meegkit/utils/stats.py +++ b/meegkit/utils/stats.py @@ -225,8 +225,8 @@ def cronbach(epochs, K=None, n_bootstrap=2000, tmin=None, tmax=None): Internal reliability of the ERN and Pe as a function of increasing trial numbers can be quantified with Cronbach's alpha: - $$\alpha = \frac{K}{K-1} \left(1-\frac{\sum_{i=1}^K - \sigma^2_{Y_i}}{ \sigma^2_X}\right)$$ + $$\alpha = \frac{K}{K-1} \left(1-\frac{\sum_{i=1}^K + \sigma^2_{Y_i}}{ \sigma^2_X}\right)$$ Hinton, Brownlow, McMurray, and Cozens (2004) have suggested that Cronbach's alpha exceeding .90 indicates excellent internal reliability, @@ -284,6 +284,8 @@ def cronbach(epochs, K=None, n_bootstrap=2000, tmin=None, tmax=None): def snr_spectrum(X, freqs, n_avg=1, n_harm=1, skipbins=1): """Compute Signal-to-Noise-corrected spectrum. + The implementation tries to replicate examples in [1; 2; 3]_. + Parameters ---------- X : ndarray , shape=(n_freqs, n_chans,[ n_trials,]) diff --git a/meegkit/utils/trca.py b/meegkit/utils/trca.py index 3236a181..f716ded7 100644 --- a/meegkit/utils/trca.py +++ b/meegkit/utils/trca.py @@ -31,7 +31,7 @@ def normfit(data, ci=0.95): Parameters ---------- - data: array, shape=() + data : array, shape=() Input data. ci : float Confidence interval (default=0.95). @@ -61,8 +61,10 @@ def normfit(data, ci=0.95): def itr(n, p, t): """Compute information transfer rate (ITR). - Inputs - ------ + Definition in [1]_. + + Parameters + ---------- n : int Number of targets. p : float diff --git a/requirements.txt b/requirements.txt index 7d34f17a..622bffb6 100644 --- a/requirements.txt +++ b/requirements.txt @@ -3,11 +3,7 @@ scipy matplotlib scikit-learn pandas -sphinx -pillow -sphinx-gallery joblib -numpydoc flake8 pytest pytest-cov