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 -e .
$> cd docs; make clean html latexpdf

Dependencies

pyunicorn is written in Python 3.7. The software is written and tested on Linux. It should work on other systems but installation might be more complicated (see instructions below). pyunicorn relies on the following open source or freely available packages which have to be installed on your machine.

Required:

Optional (used only in certain classes and methods):

PyNGL (for class NetCDFDictionary)
netcdf4-python (for classes Data and NetCDFDictionary)
Matplotlib 2.0+
Matplotlib Basemap Toolkit (for drawing maps)
mpi4py (for parallelizing costly computations)
Sphinx (for generating documentation)
Cython 0.27+ (for compiling code during development)

Numpy, Scipy, Matplotlib, igraph and other packages should be available via a package management system on Linux or MacOSX. All packages can be downloaded, compiled and installed following the instructions on their homepages.

An easy way to go may be a Python distribution like Anaconda that already includes many libraries.

Installation

Before the installation of pyunicorn we recommend that you make sure that the required dependencies are installed. Afterwards, the package can be installed following the instructions below.

Linux

On Linux pyunicorn can simply be installed via the Python Package Index:

$> pip install pyunicorn

MacOSX

We did not test the current version of pyunicorn with MacOSX. However, we would expect that the same installation procedure as for Linux systems might work as MacOSX is also UNIX based.

Windows

Unfortunately,``pyunicorn`` does not work with the Microsoft Visual Studio C-Compiler but only with the GNU Compiler gcc. The following installation procedure using Anaconda was found to work on a Windows 10 machine: Open an Anaconda prompt and install the Minimalist GNU Compiler Toolchain by typing:

$> conda install libpython m2w64-toolchain -c msys2

Download the zip-files of pyunicorn from the repository. Open the file pyunicorn/core/_ext/numerics.pyx and exchange "srand48()" with "srand()" and "drand48()" with "rand()". Finally, install pyunicorn with:

$> python setup.py install

Test suite

Before committing changes 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. Thus to avoid frequent waiting, we recommend you to install the current versions of the following packages:

$> pip install networkx matplotlib basemap Sphinx
$> pip install tox pylint pytest pytest-xdist pytest-flake8

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

$> tox

To expose the defined test environments and target them independently:

$> tox -l
$> tox -e units,style

To test individual files:

$> py.test                   tests/test_core/TestNetwork.py  # unit tests
$> py.test --doctest-modules pyunicorn/core/network.py       # doctests
$> py.test --flake8          pyunicorn/core/network.py       # style
$> pylint                    pyunicorn/core/network.py       # code analysis

Mailing list

Not implemented yet.

asrvsn/pyunicorn