pyunicorn

pyunicorn (Unified Complex Network and RecurreNce analysis toolbox) is a fully object-oriented Python package for the advanced analysis and modeling of complex networks. Above the standard measures of complex network theory such as degree, betweenness and clustering coefficient it provides some uncommon but interesting statistics like Newman's random walk betweenness. pyunicorn features novel node-weighted (node splitting invariant) network statistics as well as measures designed for analyzing networks of interacting/interdependent networks.

Moreover, pyunicorn allows 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.

Reference

Please acknowledge and cite the use of this software and its authors when results are used in publications or published elsewhere. You can use the following reference:

J.F. Donges, J. Heitzig, B. Beronov, M. Wiedermann, J. Runge, Q.-Y. Feng, L. Tupikina, V. Stolbova, R.V. Donner, N. Marwan, H.A. Dijkstra, and J. Kurths, Unified functional network and nonlinear time series analysis for complex systems science: The pyunicorn package, Chaos 25, 113101 (2015), doi:10.1063/1.4934554, Preprint: arxiv.org:1507.01571 [physics.data-an].

Funding

The development of pyunicorn has been supported by various funding sources, notably the German Federal Ministry for Education and Research (projects GOTHAM and CoSy-CC2), the Leibniz Association (projects ECONS and DominoES), the German National Academic Foundation, and the Stordalen Foundation via the Planetary Boundary Research Network (PB.net) among others.

License

pyunicorn is BSD-licensed (3 clause).

Code

Stable releases, Development version

Changelog, Contributions

Documentation

For extensive HTML documentation, jump right to the pyunicorn homepage. Recent PDF versions are also available.

On a local development version, HTML and PDF documentation can be generated using Sphinx:

$> pip install --user .[docs]
$> cd docs; make clean html latexpdf

Dependencies

pyunicorn is implemented in Python 3 and Cython 3. The software is written and tested on Linux and macOS, but it is also in active use on Windows. pyunicorn relies on the following open source or freely available packages, which need to be installed on your machine. For exact dependency information, see setup.cfg.

Required at runtime:

• Numpy
• Scipy
• python-igraph
• h5netcdf or netcdf4-python (for Data and NetCDFDictionary)

Optional (used only in certain classes and methods):

• PyNGL (for NetCDFDictionary)
• Matplotlib
• Matplotlib Basemap Toolkit (for drawing maps)
• Cartopy (for some plotting features)
• mpi4py (for parallelizing costly computations)
• Sphinx (for generating documentation)

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 that already includes many libraries.

Installation

Before installing pyunicorn itself, we recommend to make sure that the required dependencies are installed using your preferred installation method for Python libraries. Afterwards, the package can be installed in the standard way from the Python Package Index (PyPI).

Linux, macOS

With the pip package manager:

$> pip install pyunicorn

On Fedora OS, use:

$> dnf install python3-pyunicorn

Windows

First follow the instructions for installing the latest version of the Microsoft C++ Build Tools in order to be able to compile the Cython modules, and then:

$> pip install pyunicorn

Development version

To use a newer version of pyunicorn than the latest official release on PyPI, download the source code from the Github repository and, instead of the above, execute:

$> pip install -e .

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 and configured to use system-wide packages when available. Install the test dependencies as follows:

$> pip install .[testing]

The test suite can be run from anywhere in the project tree by issuing:

$> tox

To display the defined test environments and target them individually:

$> tox -l
$> tox -e style,lint,test,docs

To test individual files:

$> flake8 src/pyunicorn/core/network.py     # style check
$> pylint src/pyunicorn/core/network.py     # static code analysis
$> pytest tests/test_core/TestNetwork.py    # unit tests

Mailing list

Not implemented yet.