Merge pull request #213 from fkuehlein/master

Clean up tutorial notebooks and documentation

.gitignore

@@ -72,6 +72,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/source/tutorials/images/
 
 # PyBuilder
 .pybuilder/
@@ -164,5 +165,6 @@ cython_debug/
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
 
-# Calculation dumps
+# cached data
 *.data
+examples/tutorials/data

.travis.yml

@@ -1,6 +1,6 @@
 # This file is part of pyunicorn.
 # Copyright (C) 2008--2024 Jonathan F. Donges and pyunicorn authors
-# URL: <http://www.pik-potsdam.de/members/donges/software>
+# URL: <https://www.pik-potsdam.de/members/donges/software-2/software>
 # License: BSD (3-clause)
 
 
@@ -47,27 +47,29 @@ env:
 before_install: export ARCH=Linux-aarch64 SED=sed
 
 install:
-  - | # install Python via Miniconda
+  - | # install Miniconda
     travis_retry wget https://repo.anaconda.com/miniconda/Miniconda3-latest-${ARCH}.sh -O miniconda.sh
-    bash miniconda.sh -b -p $HOME/miniconda
-    export PATH="$HOME/miniconda/bin:$PATH"; hash -r
+    bash miniconda.sh -b -p ${HOME}/miniconda
+    export PATH="${HOME}/miniconda/bin:${PATH}"; hash -r
     conda config --set quiet yes --set always_yes yes --set changeps1 no
-  - |
     travis_retry conda update -n base -c defaults conda
     travis_retry conda update --all
     conda config --set solver libmamba
     conda info -a
     conda list
+  - | # install executables via Miniconda: Python, Pandoc, Codecov
     travis_retry conda create -n test-env
     eval "$(conda shell.bash hook)"
     conda activate test-env
-    travis_retry conda install -c conda-forge python=${PYTHON}
-
-  - | # install dependencies
-    travis_retry conda install -c conda-forge numpy scipy python-igraph h5netcdf tqdm
+    travis_retry conda install -c conda-forge python=${PYTHON} pandoc codecov
     travis_retry conda update  -c conda-forge --all
-    travis_retry conda install -c conda-forge tox flake8 pylint pytest-xdist pytest-cov codecov
-    travis_retry conda install -c conda-forge networkx matplotlib cartopy sphinx
+    conda info -a
+    conda list
+  - | # install Python libs via Miniconda
+    travis_retry conda install -c conda-forge \
+        numpy scipy python-igraph h5netcdf tqdm \
+        ipython networkx matplotlib cartopy sphinx nbsphinx nbsphinx-link \
+        tox flake8 pylint pytest-xdist pytest-cov
     conda info -a
     conda list
 
@@ -77,12 +79,10 @@ script:
     ${SED} -i '/-j ./      {s//-j 2/;      h}; ${x;/./{x;q0};x;q1}' setup.cfg
     ${SED} -i '/-n auto/   {s//-n 2/;      h}; ${x;/./{x;q0};x;q1}' pyproject.toml
     ${SED} -i '/jobs = ./  {s//jobs = 2/;  h}; ${x;/./{x;q0};x;q1}' pyproject.toml
-
-  # install self (and dependencies, if on Windows)
-  - travis_retry pip install -v -e ".[tests,docs]"
-
-  # run test suite
-  - tox -v
+  - | # install Python libs via Pip: self (+ dependencies, if on Windows)
+    travis_retry pip install -v -e .[tests,docs]
+  - | # run test suite
+    tox -v
 
 # report statistics
 after_success: codecov
@@ -99,15 +99,17 @@ jobs:
       language: shell
       before_install:
         - export ARCH=MacOSX-x86_64 SED=gsed
-        - export HOMEBREW_NO_AUTO_UPDATE=1 HOMEBREW_NO_INSTALL_CLEANUP=1
-        - travis_retry brew install gnu-sed
+        - | # install executables via Homebrew: GNU `sed`
+          export HOMEBREW_NO_AUTO_UPDATE=1 HOMEBREW_NO_INSTALL_CLEANUP=1
+          travis_retry brew install gnu-sed
 
     - os: windows
       language: shell
       before_install:
         - export ARCH=Windows-x86_64 SED=sed
         - export PATH=/c/Python${PYTHON/.}:/c/Python${PYTHON/.}/Scripts:${PATH}
       install:
-        - | # install Python via Chocolatey
+        - | # install executables via Chocolatey: Python, Pandoc, Codecov
           travis_retry choco install python --version ${PYTHON}
           travis_retry python -m pip install --upgrade pip
+          travis_retry choco install pandoc codecov

CONTRIBUTIONS.rst

@@ -12,13 +12,17 @@ BSD (3-clause)
 
 URL
 ---
-http://www.pik-potsdam.de/members/donges/software
+https://www.pik-potsdam.de/members/donges/software-2/software
 
 Mail
 ----
 Jonathan Donges, Potsdam Institute for Climate Impact Research,
 P.O. Box 60 12 03, D-14412 Potsdam, Germany
 
+Related publications
+--------------------
+See `Publications <docs/source/publications.rst>`_.
+
 Authors
 -------
 Written as part of a diploma/PhD thesis in physics by `Jonathan F. Donges
@@ -27,10 +31,6 @@ Institute for Climate Impact Research (PIK) and completed at the University of
 Potsdam, Germany. Substantially extended by `Jobst Heitzig
 <heitzig@pik-potsdam.de>`_.
 
-Related publications
---------------------
-See `Publications <docs/source/publications.rst>`_.
-
 Contributors
 ------------
 - Jakob Runge (extended ``core`` and ``climate``)

MANIFEST.in

@@ -4,6 +4,8 @@ recursive-include src/pyunicorn/*/_ext *.pxd *.pyx src_*.c
 
 include *.rst *.txt docs/Makefile
 graft docs/source
-recursive-include examples *.py
+recursive-include examples *.py *.ipynb *.png
+prune docs/source/tutorials/images
+prune **/.ipynb_checkpoints
 
 recursive-include tests *.py

README.rst

@@ -12,22 +12,27 @@ About
 =====
 ``pyunicorn`` (**Uni**\ fied **Co**\ mplex Network and **R**\ ecurre\ **N**\ ce
 analysis toolbox) is an object-oriented Python package for the advanced analysis
-and modeling of complex networks. Beyond the standard measures of complex
-network theory, such as degree, betweenness and clustering coefficients, it
-provides some uncommon but interesting statistics like Newman's random walk
-betweenness. ``pyunicorn`` also features novel *node-weighted (node splitting
-invariant)* network statistics as well as measures designed for analyzing
-*networks of interacting/interdependent networks*.
-
-Moreover, ``pyunicorn`` allows one to easily *construct networks from uni- and
-multivariate time series and event data* (functional (climate) networks and
-recurrence networks). This involves linear and nonlinear measures of time series
-analysis for constructing functional networks from multivariate data (e.g.,
-Pearson correlation, mutual information, event synchronization and event
-coincidence analysis). ``pyunicorn`` also features modern techniques of
-nonlinear analysis of single and pairs of time series, such as recurrence
-quantification analysis (RQA), recurrence network analysis and visibility
-graphs.
+and modeling of complex networks. Beyond the standard **measures of complex
+network theory** (such as *degree*, *betweenness* and *clustering coefficients*), it
+provides some uncommon but interesting statistics like *Newman's random walk
+betweenness*. ``pyunicorn`` also provides novel **node-weighted** *(node splitting invariant)*
+network statistics, measures for analyzing networks of **interacting/interdependent
+networks**, and special tools to model **spatially embedded** complex networks.
+
+Moreover, ``pyunicorn`` allows one to easily *construct networks* from uni- and
+multivariate time series and event data (**functional/climate networks** and
+**recurrence networks**). This involves linear and nonlinear measures of
+**time series analysis** for constructing functional networks from multivariate data
+(e.g., *Pearson correlation*, *mutual information*, *event synchronization* and *event
+coincidence analysis*). ``pyunicorn`` also features modern techniques of
+nonlinear analysis of time series (or pairs thereof), such as *recurrence
+quantification analysis* (RQA), *recurrence network analysis* and *visibility
+graphs*.
+
+``pyunicorn`` is **fast**, because all costly computations are performed in
+compiled C/C++ and Fortran code. It can handle **large networks** through the
+use of sparse data structures. The package can be used interactively, from any
+Python script, and even for parallel computations on large cluster architectures.
 
 License
 -------
@@ -69,8 +74,8 @@ Mailing list
 Not implemented yet.
 
 
-Usage
-=====
+Getting Started
+===============
 
 Installation
 ------------
@@ -103,8 +108,7 @@ Optional *(used only in certain classes and methods)*:
 
 To install these dependencies, please follow the instructions for your system's
 package manager or consult the libraries' homepages. An easy way to go may be a
-Python distribution like `Anaconda <https://www.anaconda.com/>`_
-that already includes many libraries.
+Python distribution like `Anaconda <https://www.anaconda.com/download>`_.
 
 Official releases
 .................
@@ -148,7 +152,7 @@ Test suite
 ----------
 Before committing changes or opening a pull request (PR) to the code base,
 please make sure that all tests pass. The test suite is managed by `tox
-<http://tox.readthedocs.io/>`_ and is configured to use system-wide packages
+<https://tox.wiki/>`_ and is configured to use system-wide packages
 when available. Install the test dependencies as follows::
 
     $> pip install .[tests]

docs/source/conf.py

@@ -38,7 +38,9 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
-    'sphinx.ext.githubpages'
+    'sphinx.ext.githubpages',
+    'nbsphinx',
+    'nbsphinx_link',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/contact.rst

@@ -4,8 +4,7 @@ Contact
 
 .. include:: ../../README.rst
     :start-after: (3 clause).
-    :end-before: Usage
+    :end-before: Getting Started
 
 .. include:: ../../CONTRIBUTIONS.rst
     :start-after: BSD (3-clause)
-    :end-before: Acknowledgements

docs/source/development.rst

@@ -1,3 +1,3 @@
 
-Development
-===========
+.. include:: ../../README.rst
+    :start-after: $> cd docs; make clean html latexpdf

docs/source/download.rst

@@ -1,11 +1,4 @@
 
-Download
-========
-
-.. include:: ../../README.rst
-    :start-after: ``pyunicorn`` is `BSD-licensed <LICENSE.txt>`_ (3 clause).
-    :end-before: Test suite
-
 .. include:: ../../README.rst
-    :start-after: graphs.
-    :end-before: License
+    :start-after: Not implemented yet.
+    :end-before: Development

docs/source/index.rst

@@ -1,21 +1,16 @@
 
+============
 Introduction
 ============
 
 .. include:: ../../README.rst
-    :start-after: =========
-    :end-before: Reference
-
-For example, to generate a recurrence network with 1000 nodes from a sinusoidal
-signal and compute its network transitivity you simply need to type
+    :start-after: :target: https://codecov.io/gh/pik-copan/pyunicorn
+    :end-before: License
 
-.. literalinclude:: ../../examples/modules/timeseries/recurrence_network.py
+Example
+=======
 
-The package provides special tools to analyze and model **spatially embedded**
-complex networks.
+To generate a recurrence network with 1000 nodes from a sinusoidal
+signal and to compute its network transitivity, you can simply run:
 
-``pyunicorn`` is **fast** because all costly computations are performed in
-compiled C, C++ and Fortran code. It can handle **large networks** through the
-use of sparse data structures. The package can be used interactively, from any
-Python script and even for parallel computations on large cluster
-architectures.
+.. literalinclude:: ../../examples/modules/timeseries/recurrence_network.py

docs/source/license.rst

@@ -2,9 +2,4 @@
 License
 =======
 
-.. include:: <isonum.txt>
-.. include:: ../../CONTRIBUTIONS.rst
-    :start-after: =============
-    :end-before: Mail
-
-.. literalinclude:: ../../LICENSE.txt
+.. literalinclude:: ../../LICENSE.txt

docs/source/methods.rst

@@ -1,6 +1,6 @@
 
-Methods
-=======
+Package Overview
+================
 
 A brief introduction to the methods, measures and algorithms provided by
 ``pyunicorn``.
@@ -21,15 +21,15 @@ possible.
 Spatially embedded networks
 ---------------------------
 ``pyunicorn`` includes measures and models specifically designed for spatially
-embedded networks (or simply spatial networks) via the GeoNetwork and Grid
+embedded networks (or simply spatial networks) via the ``GeoNetwork`` and ``Grid``
 classes.
 
 * :doc:`api/core/geo_network`
 * :doc:`api/core/grid`
 
-Interacting/interdependent/multiplex networks / networks of networks
---------------------------------------------------------------------
-The InteractingNetworks class provides a rich collection of network measures and models specifically designed for investigating the structure of networks of
+Interacting/multiplex networks (networks of networks)
+-----------------------------------------------------
+The ``InteractingNetworks`` class provides a rich collection of network measures and models specifically designed for investigating the structure of networks of
 networks (also called interacting networks, interdependent networks or
 multiplex networks in different contexts). Examples include the cross-link
 density of connections between different subnetworks or the cross-shortest
@@ -39,8 +39,8 @@ the degree of organization of the cross-connectivity between subnetworks.
 
 * :doc:`api/core/interacting_networks`
 
-Node-weighted network measures / node-splitting invariance
-----------------------------------------------------------
+Node-weighted (node-splitting invariant) network measures
+---------------------------------------------------------
 Node-weighted networks measures derived following the node-splitting invariance
 approach are useful for studying systems with nodes representing subsystems of
 heterogeneous size, weight, area, volume or importance, e.g., nodes
@@ -52,8 +52,8 @@ as well as interacting networks.
 * :doc:`api/core/network`
 * :doc:`api/core/interacting_networks`
 
-Climate networks / Coupled climate networks
--------------------------------------------
+(Coupled) Climate networks
+--------------------------
 ``pyunicorn`` provides classes for the easy construction and analysis of the
 statistical interdependency structure within and between fields of time series (functional networks) using various similarity measures such as Pearson and Spearman correlation, lagged linear correlation, mutual information and event
 synchronization. Climate networks allow the analysis of single fields of time series, whereas coupled climate networks focus on studying the
@@ -66,8 +66,8 @@ FMRI and EEG data) or financial data (e.g., stock market indices).
 * :doc:`api/climate/coupled_climate_network`
 * :doc:`api/climate/climate_data`
 
-Recurrence networks / recurrence quantification analysis / recurrence plots
----------------------------------------------------------------------------
+Recurrence quantification/network analysis
+------------------------------------------
 Recurrence analysis is a powerful method for studying nonlinear systems,
 particularly based on univariate and multivariate time series data. Recurrence
 quantification analysis (RQA) and recurrence network analysis (RNA) allow to