pyunicorn

An object-oriented Python package for advanced analysis and modelling of complex networks such as climate networks, a way of applying complex network theory to the climate system by assuming that each node represents a varying dynamical system.
https://github.com/pik-copan/pyunicorn

Category: Climate Change
Sub Category: Earth and Climate Modeling

Keywords from Contributors

earth-science agent-based-framework agent-based-modeling earth-system-model networks sustainability

Last synced: about 2 hours ago
JSON representation

Repository metadata

Unified Complex Network and Recurrence Analysis Toolbox

• Host: GitHub
• URL: https://github.com/pik-copan/pyunicorn
• Owner: pik-copan
• License: other
• Created: 2015-04-10T09:25:13.000Z (about 10 years ago)
• Default Branch: master
• Last Pushed: 2025-03-03T17:56:16.000Z (about 2 months ago)
• Last Synced: 2025-04-19T15:56:39.427Z (8 days ago)
• Language: Python
• Homepage: http://pik-potsdam.de/~donges/pyunicorn/
• Size: 34.4 MB
• Stars: 209
• Watchers: 15
• Forks: 87
• Open Issues: 36
• Releases: 9
• Metadata Files:
  • Readme: README.rst
  • Changelog: CHANGELOG.rst
  • License: LICENSE.txt
  • Citation: CITATION.cff

README.rst

          =========
pyunicorn
=========

.. image:: https://app.travis-ci.com/pik-copan/pyunicorn.svg?branch=master
  :target: https://app.travis-ci.com/github/pik-copan/pyunicorn

.. image:: https://codecov.io/gh/pik-copan/pyunicorn/branch/master/graph/badge.svg
  :target: https://codecov.io/gh/pik-copan/pyunicorn

.. image:: https://img.shields.io/pypi/v/pyunicorn
  :target: https://pypi.org/project/pyunicorn/

.. image:: https://img.shields.io/pypi/pyversions/pyunicorn
  :target: https://pypi.org/project/pyunicorn/

.. image:: https://zenodo.org/badge/33720178.svg
  :target: https://zenodo.org/badge/latestdoi/33720178

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 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 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.
For information about individual releases,
see our `CHANGELOG `_ and `CONTRIBUTIONS `_.


License
-------
``pyunicorn`` is `BSD-licensed `_ (3 clause).

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.

Getting Started
===============

Installation
------------
Official releases
.................
`Stable releases `_ can be
installed directly from the `Python Package Index (PyPI)
`_::

    $> pip install pyunicorn

Alternatively, source distributions can be downloaded from the
`GitHub Releases `_.

On **Windows**, please *first* install the latest version of the `Microsoft C++ Build
Tools `_, which is required for
compiling Cython modules.

Current development version
...........................
In order to use a `newer version `_,
please follow the ``pip`` instructions for installing from `version control
`_
or from a `local source tree
`_.

Dependencies
............
``pyunicorn`` is implemented in `Python 3 `_ /
`Cython 3 `_, is `tested
`_ on *Linux*, *macOS*
and *Windows*, and relies on the following packages:

- Required:

  - `numpy `_, `scipy `_
  - `python-igraph `_ (for ``Network``)
  - `h5netcdf `_ (for ``Data``, ``NetCDFDictionary``)
  - `tqdm `_ (for progress bars)

- Optional:

  - `Matplotlib `_,
    `Cartopy `_
    (for plotting features)
  - `mpi4py `_
    (for parallelizing costly computations)
  - `Sphinx `_
    (for generating documentation)
  - `Jupyter Notebook `_
    (for tutorial notebooks)


Documentation
-------------
For extensive HTML documentation, jump right to the `homepage
`_. In a local source tree,
HTML and PDF documentation can be generated using ``Sphinx``::

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

Tuturials
---------

For some example applications look into the
`tutorials `_ provided with the documentation.
They are designed to be self-explanatory, and are set up as Jupyter notebooks.

Development
===========

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

    $> pip install -e .[tests]

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/test_network.py   # unit tests

        

Citation (CITATION.cff)

cff-version: 1.2.0
message: If you use this software, please cite it using the metadata provided below.
type: software
title: 'Pyunicorn: Unified Complex Network and Recurrence Analysis Toolbox'
abstract: pyunicorn (Unified Complex Network and RecurreNce 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 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 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.
authors:
- family-names: Donges
  given-names: Jonathan
  email: [email protected]
  orcid: https://orcid.org/0000-0001-5233-7703
- family-names: Heitzig
  given-names: Jobst
  email: [email protected]
  orcid: https://orcid.org/0000-0002-0442-8077
- family-names: Beronov
  given-names: Boyan
  email: [email protected]
  orcid: https://orcid.org/0000-0002-0900-752X
- family-names: Kühlein
  given-names: Fritz
  email: [email protected]
- family-names: Bechthold
  given-names: Max
  email: [email protected]
  orcid: https://orcid.org/0009-0007-7113-4814
- family-names: Kroenke
  given-names: Jonathan
  email: [email protected]
- family-names: Barfuss
  given-names: Wolfram
  email: [email protected]
  orcid: https://orcid.org/0000-0002-9077-5242
- family-names: Harmening
  given-names: Nils
- family-names: Nascimento Silva
  given-names: Filipi
- family-names: Kassel
  given-names: Johannes
- family-names: Ziehbarth
  given-names: Malte
- family-names: Odenweller
  given-names: Adrian
- family-names: Tzinis
  given-names: Efthymios
- family-names: Hotz
  given-names: Ronja

license: GPL-3.0
repository-code: https://github.com/pik-copan/pyunicorn

preferred-citation:
  type: article
  title: 'Unified functional network and nonlinear time series analysis for complex
    systems science: The pyunicorn package'
  authors:
  - family-names: Donges
    given-names: Jonathan
    email: [email protected]
    orcid: https://orcid.org/0000-0001-5233-7703
  - family-names: Heitzig
    given-names: Jobst
    email: [email protected]
    orcid: https://orcid.org/0000-0002-0442-8077
  - family-names: Beronov
    given-names: Boyan
    email: [email protected]
    orcid: https://orcid.org/0000-0002-0900-752X
  - family-names: Wiedermann
    given-names: Marc
    orcid: https://orcid.org/0000-0001-9869-3789
  - family-names: Runge
    given-names: Jakob
  - family-names: Feng
    given-names: Quing Yi
  - family-names: Tupikina
    given-names: Liubov
  - family-names: Stolbova
    given-names: Veronika
  - family-names: Donner
    given-names: Reik V.
    email: [email protected]
    orcid: https://orcid.org/0000-0001-7023-6375
  - family-names: Marwan
    given-names: Norbert
    email: [email protected]
    orcid: https://orcid.org/0000-0003-1437-7039
  - family-names: Dijkstra
    given-names: Henk A.
  - family-names: Kurths
    given-names: Jürgen
    email: [email protected]
    orcid: https://orcid.org/0000-0002-5926-4276
  abstract: We introduce the pyunicorn (Pythonic unified complex network and recurrence analysis
    toolbox) open source software package for applying and combining modern methods of data
    analysis and modeling from complex network theory and nonlinear time series analysis. pyunicorn
    is a fully object-oriented and easily parallelizable package written in the language Python. It
    allows for the construction of functional networks such as climate networks in climatology or
    functional brain networks in neuroscience representing the structure of statistical
    interrelationships in large data sets of time series and, subsequently, investigating this
    structure using advanced methods of complex network theory such as measures and models for
    spatial networks, networks of interacting networks, node-weighted statistics, or network
    surrogates. Additionally, pyunicorn provides insights into the nonlinear dynamics of complex
    systems as recorded in uni- and multivariate time series from a non-traditional perspective by
    means of recurrence quantification analysis, recurrence networks, visibility graphs, and
    construction of surrogate time series. The range of possible applications of the library is
    outlined, drawing on several examples mainly from the field of climatology.
  doi: 10.1063/1.4934554
  journal: Chaos
  month: 11
  issue: 11
  volume: 25
  year: 2015

---

Owner metadata

• Name: copan
• Login: pik-copan
• Email: [email protected]
• Kind: organization
• Description: Coevolutionary Pathways – collaboration at Potsdam Institute for Climate Impact Research (PIK)
• Website: https://www.pik-potsdam.de/copan
• Location: Potsdam (Germany)
• Twitter: pik_copan
• Company:
• Icon url: https://avatars.githubusercontent.com/u/11884394?v=4
• Repositories: 6
• Last ynced at: 2023-03-01T06:50:17.483Z
• Profile URL: https://github.com/pik-copan

---

GitHub Events

Total

• Create event: 2
• Release event: 1
• Issues event: 6
• Watch event: 14
• Delete event: 1
• Issue comment event: 3
• Push event: 16
• Pull request event: 2
• Fork event: 1

Last Year

• Create event: 2
• Release event: 1
• Issues event: 6
• Watch event: 14
• Delete event: 1
• Issue comment event: 3
• Push event: 16
• Pull request event: 2
• Fork event: 1

---

Committers metadata

Last synced: 7 days ago

Name	Email	Commits
fkuehlein	f****n@s****e	161
ntfrgl	n****l@g****m	141
harmening	n****g@f****e	81
Jonathan Krönke	k****e@p****e	61
MaxBechthold	b****o@g****m	59
harmening	n****g@m****e	32
Jonathan Donges	d****s@p****e	27
lschmidt	8****5	18
wbarfuss	w****s@g****e	16
wbarfuss	w****s@p****e	16
wbarfuss	b****s@p****e	11
Filipi Nascimento Silva	f****o@g****m	9
Jobst Heitzig	h****g@p****e	4
Malte J. Ziebarth	m****h@f****e	4
jakassel	j****l@p****e	4
nils	p****e@g****e	3
Adrian Odenweller	a****r@p****e	2
Efthymios Tzinis	e****s@g****m	1
lenaschmidt	l****t@t****e	1
RonjaHo	1****o	1

Committer domains:

• pik-potsdam.de: 6
• gmx.de: 2
• tu-berlin.de: 1
• pks.mpg.de: 1
• fmvkb.de: 1
• mail.de: 1
• fu-berlin.de: 1
• student.uni-halle.de: 1

---

Issue and Pull Request metadata

Last synced: 1 day ago

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/pik-copan/pyunicorn

---

---

---

Package metadata

• Total packages: 1
• Total downloads:
  • pypi: 10,467 last-month
• Total dependent packages: 0
• Total dependent repositories: 4
• Total versions: 9
• Total maintainers: 2

---

Dependencies

Score: 17.753546279871863