From 1a56dc3f1205823c6035a9410cf2a6e7e65e0f44 Mon Sep 17 00:00:00 2001 From: nbara <10333715+nbara@users.noreply.github.com> Date: Wed, 7 Apr 2021 20:44:25 +0200 Subject: [PATCH 1/3] [DOC] Fix doc --- .gitignore | 2 +- doc/modules/meegkit.trca.rst | 30 ++++++++++++++++++++++++++++++ meegkit/utils/stats.py | 2 ++ 3 files changed, 33 insertions(+), 1 deletion(-) create mode 100644 doc/modules/meegkit.trca.rst 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/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/meegkit/utils/stats.py b/meegkit/utils/stats.py index cc694857..dc8b3f9f 100644 --- a/meegkit/utils/stats.py +++ b/meegkit/utils/stats.py @@ -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,]) From c97e3d223391d9b9d0f81a5461e8da0f3ce0e391 Mon Sep 17 00:00:00 2001 From: nbara <10333715+nbara@users.noreply.github.com> Date: Wed, 7 Apr 2021 23:13:12 +0200 Subject: [PATCH 2/3] switch to pydata sphinx --- .travis.yml | 4 +- README.md | 2 +- doc/conf.py | 94 ++++++++++++++---------------------------- doc/examples.rst | 7 ++++ doc/index.rst | 19 +++++---- doc/requirements.txt | 8 ++++ meegkit/cca.py | 2 +- meegkit/ress.py | 4 +- meegkit/trca.py | 4 +- meegkit/utils/stats.py | 4 +- meegkit/utils/trca.py | 8 ++-- requirements.txt | 4 -- 12 files changed, 71 insertions(+), 89 deletions(-) create mode 100644 doc/examples.rst create mode 100644 doc/requirements.txt 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/conf.py b/doc/conf.py index 88691a47..a309f26b 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,10 +23,10 @@ # -- Project information ----------------------------------------------------- -project = 'MEEGkit' +project = f'MEEGkit v{meegkit.__version__}' copyright = '2020, Nicolas Barascud' author = 'Nicolas Barascud' -version = meegkit.__version__ +release = meegkit.__version__ # -- General configuration --------------------------------------------------- @@ -42,6 +38,7 @@ 'sphinx.ext.autosummary', 'sphinx.ext.napoleon', 'numpydoc', + 'jupyter_sphinx', 'sphinx_gallery.gen_gallery', ] @@ -75,10 +72,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 +82,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) + "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, + "show_toc_level": 1, +} - # 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 ------------------------------------------ diff --git a/doc/examples.rst b/doc/examples.rst new file mode 100644 index 00000000..276afa21 --- /dev/null +++ b/doc/examples.rst @@ -0,0 +1,7 @@ + +Examples gallery +~~~~~~~~~~~~~~~~ + +.. include:: auto_examples/index.rst + :start-after: Below is a gallery of examples + :end-line: -11 diff --git a/doc/index.rst b/doc/index.rst index e4a89444..93d0579f 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -6,18 +6,17 @@ Welcome to MEEGkit ================== -The code of the project is on Github: `MEEGkit `_ +The source code of the project is available on Github: `MEEGkit `_ - -Contents --------- +Available modules +----------------- :py:mod:`meegkit`: .. currentmodule:: meegkit .. autosummary:: - :toctree: modules/ + :caption: meegkit ~meegkit.asr ~meegkit.cca @@ -33,12 +32,16 @@ Contents Examples gallery ---------------- -A gallery of examples is available at the following address: +A gallery of examples is available: .. toctree:: - :maxdepth: 2 + :maxdepth: 0 + :hidden: + +.. include:: auto_examples/index.rst + :start-after: Below is a gallery of examples + :end-line: -11 - auto_examples/index Indices and tables ------------------ diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 00000000..a15dd634 --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,8 @@ +sphinx +sphinx-copybutton +pydata-sphinx-theme +numpydoc +matplotlib +pillow +sphinx-gallery +jupyter-sphinx 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 dc8b3f9f..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, 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 From 07d1b33fa832af827807c1182a960a7073d0dcc2 Mon Sep 17 00:00:00 2001 From: nbara <10333715+nbara@users.noreply.github.com> Date: Thu, 8 Apr 2021 14:06:44 +0200 Subject: [PATCH 3/3] improvements --- doc/Makefile | 1 - doc/conf.py | 7 +++++-- doc/examples.rst | 7 ------- doc/index.rst | 36 +++++++++++++++++++++++++----------- doc/requirements.txt | 1 + examples/README.rst | 8 ++++++-- 6 files changed, 37 insertions(+), 23 deletions(-) delete mode 100644 doc/examples.rst 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 a309f26b..ada6ab3c 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -24,9 +24,10 @@ # -- Project information ----------------------------------------------------- project = f'MEEGkit v{meegkit.__version__}' -copyright = '2020, Nicolas Barascud' +copyright = '2021, Nicolas Barascud' author = 'Nicolas Barascud' release = meegkit.__version__ +version = meegkit.__version__ # -- General configuration --------------------------------------------------- @@ -40,6 +41,7 @@ 'numpydoc', 'jupyter_sphinx', 'sphinx_gallery.gen_gallery', + 'sphinxemoji.sphinxemoji', ] # Add any paths that contain templates here, relative to this directory. @@ -82,6 +84,7 @@ html_theme_options = { + "show_toc_level": 1, "external_links": [ { "name": "GitHub", @@ -101,7 +104,6 @@ }, ], "use_edit_page_button": True, - "show_toc_level": 1, } html_context = { @@ -119,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/examples.rst b/doc/examples.rst deleted file mode 100644 index 276afa21..00000000 --- a/doc/examples.rst +++ /dev/null @@ -1,7 +0,0 @@ - -Examples gallery -~~~~~~~~~~~~~~~~ - -.. include:: auto_examples/index.rst - :start-after: Below is a gallery of examples - :end-line: -11 diff --git a/doc/index.rst b/doc/index.rst index 93d0579f..2a588657 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,20 +1,35 @@ -.. 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 source code of the project is available 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. + +The source code of the project is hosted on Github at the following address: +https://github.com/nbara/python-meegkit + +To get started, follow the installation instructions `in the README `_. Available modules ----------------- -:py:mod:`meegkit`: +Here is a list of the methods and techniques available in ``meegkit``: .. currentmodule:: meegkit +.. toctree:: + :maxdepth: 1 + .. autosummary:: :caption: meegkit @@ -29,18 +44,17 @@ Available modules ~meegkit.tspca ~meegkit.utils + Examples gallery ---------------- -A gallery of examples is available: +A number of example scripts and notebooks are available: + .. toctree:: - :maxdepth: 0 - :hidden: + :maxdepth: 2 -.. include:: auto_examples/index.rst - :start-after: Below is a gallery of examples - :end-line: -11 + auto_examples/index Indices and tables diff --git a/doc/requirements.txt b/doc/requirements.txt index a15dd634..6c33dbdb 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,5 +1,6 @@ sphinx sphinx-copybutton +sphinxemoji pydata-sphinx-theme numpydoc matplotlib 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 `_. +