New documentation style, guidelines and refactoring (NeuralEnsemble#294)

* Fixed outdated install.rst and developer_guide.rst docs * Added autosummary * Abbreviated member list tested for statistics module doc * Added sections in function overview * Further structured module level docs * Moved overview * Add first version of statistics tutorial notebook * Set ipynb tutorial to unexecuted state * On this branch we will fix issues with function docstrings * cleaned the docs formatting * moved alias info to notes * refactored docs of unitary event analysis * corrected formatting of examples to display nicely * statistics.py: changes in docstring formatting * statistics.py: changes in docstring formatting * Changes in docstring formatting * started restructuring the docstrings * finished unitary event analysis * fixed function docstrings * Fix typos in tutorial notebook * Final revision of docstrings in statistics.py * Final revision of docstrings in kernels.py * corrected a few more upper-lower case typos * Fix errors in visualization of formulas, and general visualization issues in statistics.py and kernels.py * Some more doc * Integrate first tutorial into sphinx documentation * Added requirements for tutorials * corrected docstrings of old surrogates (no jointISI) * Added postBuild file for mybinder * Added more nbsphinx options explicitely * Manually added elephant directory for doc build (quick fix) * More debug info on packages and pythons paths * Made sure project itself is installed for doc build * Remove debug info from notebook * Try more elegant way to install for mybinder * Add inline statement for matplotlib * Changed Default statements in docstrings, to use : instead of is * Finished revision of phase_analysis.py * Added bibtex to docs, and added UE notebook * Added h5py requirement * Added requirements and bib file for docs to build * Typo * Added new bibstyle refs to functions * one more minor change * started refactoring jointISI docstring * Updated docstrings on signal_processing and spectral modules * style_guide based on example generated during the hackathon * First draft of style guide in rst format * First draft of style guide in rst format * First draft of style guide in rst format * Correcting typos * added from __future__ import... statement * Inserted section in the style_guide.rst describing mandatory imports * Minor fixes in style guide. * Added naming of signal/signals. * Removed extra line * first finish of function doc refactoring * Added first paragraphs of documentation guide, restructure toctree * added imports from future to all modules * Switch to modified bootstrap theme * Reordered requirements * Updated authors.rst * Added more text to doc guide * the beginning of function doc refactoring * corrected formatting of function doc again (?) * Finished revision of signal_processing docstrings. * Finished revision of spectral docstrings. Minor fixes in signal_processing docstrings. * Minor fix in kernels docstrings. * fixed a few typos * Minor fix in phase_analysis docstsring * fixed latex error in cross_corr_func * pep8 * removed scipy.stats.variation wrapper back to 'cv' alias * gitignore html build related files * fixed codefactor * sphnix 1.6.5 automatically inherits class method's docstring from a parent class, if not overridden. see readthedocs/readthedocs.org#3942 * pep8 * grepped 'Parameters:' and 'Returns:' * py2.7 string formatting * don't compare strings with 'str1 is str2' * fixed tests * do not import unicode_literals: quantities rescale does not work with unicodes * Noted that spectral module function welch_cohere is actually using the helper function _welch * changed titles so that "Guide" always starts with a capital letter * changed hand-written ref in a doc string to interactive one * added phase_analysis to be displayed in the Function Reference by Module * added module-specific tutorials to be listed at the beginning of tutorials.rst * Fix on cell_assembly_detection docstring * corrected a name in a list of functions * fixed "Buf fixes" in two headers * Fix on signal_processing and change_point_detection * added change_point_detection to reference module list * Fix on neo_tools docstring * Fix on signal_processing docstrings * install extras packages to build docs and run examples * conda environment.yml for reqdthedocs to avoid apt-get install openmpi * travis: fixed conda 2.7 becomes 3.7 * Updated kernels docstring and generated rst files to display the documentation of the module as a table of contents * install.rst sphinx-tabs * sphinx_rtd_theme (our custom yellowish theme renders tabs ungly * removed overview.rst with outdated image and put some of its content in index.rst * removed References section in index.rst * readme badges * custom.css fix for sphinx_rtd_theme 'x : type' docstring * complete rewrite of all .rst docs * moved text in tutorial.rst to statistics tutorial * simplified reference names * removed not necessary xxx-overview.rst * last refactor? * fixed travis * fixed travis and readthedocs * Updated kernels docstring * Testing for Alabaster theme * deleted not used (and completely wrong) elephant_structure.png * fixed UE docs * added gitter chat badge in readme * alabaster increased page and slider width * Fix in sskernel docstring * Fixes in raised exceptions list appearance * exclude maintainers_guide.rst from sphinx build * Fix in raised exceptions list appearance, and periods in default values. * added myself to authors * fix alabaster citation reference no space before text * dummy commit to trigger readthedocs * cleared tutorial cells output; moved tutorials on top * Updated bibliography * upd url path enh/module_doc to master Co-authored-by: Michael Denker <[email protected]> Co-authored-by: Julia Sprenger <[email protected]> Co-authored-by: PaulinaDabrowska <[email protected]>
INM-6 · Mar 2, 2020 · c3fd35d · c3fd35d
1 parent e340ff9
commit c3fd35d
Show file tree

Hide file tree

Showing 85 changed files with 5,026 additions and 2,720 deletions.
diff --git a/.gitignore b/.gitignore
@@ -44,6 +44,9 @@ lib
 lib64
 # sphinx build directory
 doc/_build
+doc/reference/statistics/
+doc/reference/unitary_event_analysis/
+*.h5
 # setup.py dist directory
 dist
 sdist

diff --git a/.travis.yml b/.travis.yml
@@ -25,7 +25,7 @@ matrix:
       python: 3.6
       env: DISTRIB="pip"
       before_install: sudo apt install -y libopenmpi-dev openmpi-bin
-      before_script: pip install -r requirements-extras.txt
+      before_script: pip install -r requirements/requirements-extras.txt
       script: mpiexec -n 1 nosetests --with-coverage --cover-package=elephant
       after_success: coveralls || echo "coveralls failed"
 
@@ -41,37 +41,20 @@ matrix:
       python: 3.8
       env: DISTRIB="pip"
 
-  exclude:
-    - name: "pip 3.6 requirements-extras min version"
-      # excluded due to unrelated unittest assertWarn bug error
-      python: 3.6
-      env: DISTRIB="pip"
-      before_install:
-        - sudo apt install -y libopenmpi-dev openmpi-bin
-        - sudo apt install -y libblas-dev liblapack-dev libatlas-base-dev gfortran
-        - sed -i 's/>=/==/g' requirements*.txt
-      before_script: pip install -r requirements-extras.txt
-
-
 install:
   - if [[ "${DISTRIB}" == "conda" ]];
     then
-      export MINICONDA_PATH=${HOME}/miniconda;
-      export PATH=${MINICONDA_PATH}/bin:${PATH};
-      wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh;
-      bash miniconda.sh -b -p ${MINICONDA_PATH};
+      py_major=${TRAVIS_PYTHON_VERSION:0:1};
+      wget https://repo.continuum.io/miniconda/Miniconda${py_major}-latest-Linux-x86_64.sh -O miniconda.sh;
+      bash miniconda.sh -b -p $HOME/miniconda;
+      source "$HOME/miniconda/etc/profile.d/conda.sh";
       conda config --set always_yes yes;
       conda update conda;
-      conda create --name elephant_env python=${TRAVIS_PYTHON_VERSION};
-      source activate elephant_env;
-      conda install mkl;
-      conda config --append channels conda-forge;
-      sed '/^neo/d' requirements.txt > requirements-conda.txt;
-      conda install --file requirements-conda.txt;
-      echo "'neo' will be installed by pip from requirements.txt later on";
+      conda env create -f requirements/environment.yml;
+      conda activate elephant;
       pip list;
     else
-      pip install -r requirements.txt;
+      pip install -r requirements/requirements.txt;
     fi
 
   - pip -V

diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1,5 +1,5 @@
 recursive-include elephant *.py
-include requirements*.txt
+include requirements/*
 include README.md
 include LICENSE.txt
 include elephant/VERSION

diff --git a/README.md b/README.md
@@ -1,22 +1,30 @@
 # Elephant - Electrophysiology Analysis Toolkit
 
-Elephant is a package for the analysis of neurophysiological data, based on Neo.
-
-## Code status
-
 ![](https://travis-ci.org/NeuralEnsemble/elephant.png?branch=master "Unit Test Status")
 ![](https://coveralls.io/repos/NeuralEnsemble/elephant/badge.png "Unit Test Coverage")
-![](https://requires.io/github/NeuralEnsemble/elephant/requirements.png?branch=master "Requirements Status")
 ![](https://readthedocs.org/projects/elephant/badge/?version=latest "Documentation Status")
+![](https://img.shields.io/pypi/v/elephant)
+![](https://img.shields.io/pypi/dd/elephant)
+[![Gitter](https://badges.gitter.im/python-elephant/community.svg)](https://gitter.im/python-elephant/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
 
-#### Copyright
+*Elephant* package analyses all sorts of neurophysiological data:
+spike trains, LFP, analog signals. The input-output data format is either
+[Neo](https://github.com/NeuralEnsemble/python-neo), Quantity or Numpy array.
 
-:copyright: 2014-2019 by the [Elephant team](doc/authors.rst).
+### More Information
+
+* Documentation: https://elephant.readthedocs.io/en/latest/
+* Mailing list: https://groups.google.com/group/neuralensemble
 
-#### License
 
+#### License
+
 Modified BSD License, see [LICENSE.txt](LICENSE.txt) for details.
 
+#### Copyright
+
+:copyright: 2014-2020 by the [Elephant team](doc/authors.rst).
+
 #### Acknowledgments
 
 See [acknowledgments](doc/acknowledgments.rst).
diff --git a/doc/authors.rst b/doc/authors.rst
@@ -39,9 +39,11 @@ contribution, and may not be the current affiliation of a contributor.
 * Peter Bouss [1]
 * Alexander van Meegen [1]
 * Aitor Morales-Gregorio [1]
-* Paulina Dabrowska [1]
+* Cristiano Köhler [1]
+* Paulina Dąbrowska [1]
 * Jan Lewen [1]
 * Alexander Kleinjohann [1]
+* Danylo Ulianych [1]
 
 1. Institute of Neuroscience and Medicine (INM-6), Computational and Systems Neuroscience & Institute for Advanced Simulation (IAS-6), Theoretical Neuroscience, Jülich Research Centre and JARA, Jülich, Germany
 2. Unité de Neurosciences, Information et Complexité, CNRS UPR 3293, Gif-sur-Yvette, France

diff --git a/doc/bib/elephant.bib b/doc/bib/elephant.bib
@@ -0,0 +1,65 @@
+@article{Gruen02_43, 
+  title = {Unitary events in multiple single-neuron spiking activity: I. Detection and significance},
+  author = {Gr{\"u}n, S. and Diesmann, M. and Aertsen, A.},
+  year = {2002},
+  journal = {Neural Comp.},
+  volume = {14},
+  number = {1},
+  pages = {43--80},
+  doi = {10.1162/089976602753284455}
+}
+        
+@article{Gruen02_81, 
+  title = {Unitary events in multiple single-neuron spiking activity: II. Nonstationary data},
+  author = {Gr{\"u}n, S. and Diesmann, M. and Aertsen, A.},
+  year = {2002},
+  journal = {Neural Comp.},
+  volume = {14},
+  number = {1},
+  pages = {81--119},
+  doi = {10.1162/089976602753284464}
+}
+
+@article{Gruen03, 
+  title = {Effects across trial non-stationarity on joint-spike events},
+  author = {Gr\"{u}n, S. and Riehle, A. and Diesmann, M.},
+  year = {2003},
+  journal = {Biol. Cyb.},
+  volume = {88},
+  number = {5},
+  pages = {335--51},
+  doi = {10.1007/s00422-002-0386-2}
+}
+
+@article{Gruen09_1126, 
+  title = {Data-driven significance estimation of precise spike correlation},
+  author = {Gr\"{u}n, S.},
+  year = {2009},
+  journal = {J. Neurophysiol.},
+  number = {101},
+  pages = {1126--1140},
+  doi = {10.1152/jn.00093.2008}
+}
+
+@article{Gruen99_67, 
+  title = {Detecting unitary events without discretization of time},
+  author = {Gr{\"u}n, S. and Diesmann, M. and Grammont, F. and Riehle, A. and Aertsen, A.},
+  journal = {J.  Neurosci. Meth.},
+  year = {1999},
+  volume = {94},
+  number = {1},
+  pages = {67--79},
+  doi = {10.1016/s0165-0270(99)00126-0}
+
+}
+
+@article{Riehle97_1950,
+  title = {Spike synchronization and rate modulation differentially involved in motor cortical function},
+  author = {Riehle, A. and Gr{\"u}n, S. and Diesmann, M. and Aertsen, A.},
+  year = {1997},
+  journal = {Science},
+  volume = {278},
+  number = {5345},
+  pages = {1950--1953},
+  doi = {10.1126/science.278.5345.1950}
+}
diff --git a/doc/conf.py b/doc/conf.py
@@ -11,8 +11,9 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
 import os
+import sys
+from datetime import date
 
 # 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
@@ -28,12 +29,19 @@
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
     'sphinx.ext.imgmath',
     'sphinx.ext.viewcode',
-    'numpydoc']
+    'sphinx.ext.mathjax',
+    'sphinxcontrib.bibtex',
+    'matplotlib.sphinxext.plot_directive',
+    'numpydoc',
+    'nbsphinx',
+    'sphinx_tabs.tabs',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -50,7 +58,8 @@
 # General information about the project.
 project = u'Elephant'
 authors = u'Elephant authors and contributors'
-copyright = u'2014-2019, ' + authors
+copyright = u"2014-{this_year}, {authors}".format(this_year=date.today().year,
+                                                  authors=authors)
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -77,7 +86,11 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build']
+exclude_patterns = [
+    '_build',
+    '**.ipynb_checkpoints',
+    'maintainers_guide.rst',  # should not be visible for users
+]
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None
@@ -99,12 +112,27 @@
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 
+# Only execute Jupyter notebooks that have no evaluated cells
+nbsphinx_execute = 'auto'
+# Kernel to use for execution
+nbsphinx_kernel_name = 'python3'
+# Cancel compile on errors in notebooks
+nbsphinx_allow_errors = False
+
+# Required to automatically create a summary page for each function listed in
+# the autosummary fields of each module.
+autosummary_generate = True
 
 # -- 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 = 'sphinxdoc'
+html_theme = 'alabaster'
+html_theme_options = {
+    'font_family': 'Arial',
+    'page_width': '1200px',  # default is 940
+    'sidebar_width': '280px',  # default is 220
+}
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -163,10 +191,10 @@
 #html_show_sourcelink = True
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#html_show_sphinx = True
+html_show_sphinx = False
 
 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
+html_show_copyright = True
 
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
@@ -183,17 +211,23 @@
 # see here https://github.com/phn/pytpm/issues/3#issuecomment-12133978
 numpydoc_show_class_members = False
 
+# A fix for Alabaster theme for no space between a citation reference
+# and citation text
+# https://github.com/sphinx-doc/sphinx/issues/6705#issuecomment-536197438
+html4_writer = True
+
+
 # -- Options for LaTeX output --------------------------------------------
 
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
-    #'papersize': 'letterpaper',
+    # 'papersize': 'letterpaper',
 
     # The font size ('10pt', '11pt' or '12pt').
-    #'pointsize': '10pt',
+    # 'pointsize': '10pt',
 
     # Additional stuff for the LaTeX preamble.
-    #'preamble': '',
+    # 'preamble': '',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples