Source-linked AI summary
Unified functional network and nonlinear time series analysis for complex systems science: The pyunicorn package
Jonathan F. Donges, Jobst Heitzig, Boyan Beronov, Marc Wiedermann, Jakob Runge, Qing Yi Feng, Liubov Tupikina, Veronika Stolbova, Reik V. Donner, Norbert Marwan, Henk A. Dijkstra, Jürgen Kurths
TL;DR
Studying complex systems involves both network structure and nonlinear time-series dynamics, and the paper introduces pyunicorn to combine methods from these perspectives. The package covers functional networks and network-based time-series analysis; its authors describe it as a modular tool for large data sets, while noting that similarity networks reconstructed from bivariate measures are not causal.
Problem
Methods for studying complex-system structure and dynamics have developed from complementary network-theory and nonlinear time-series perspectives.
Source: §I · p. 2, §VI · p. 24Method
pyunicorn combines complex-network and nonlinear time-series methods, including functional networks, recurrence analysis, recurrence networks, visibility graphs, and surrogate time series.
Source: §I · p. 2, §1 · p. 19, §3 · p. 20Results
The authors describe pyunicorn as a modular, object-oriented Python package for analyzing complex networks and time series, with compiled implementations and sparse data structures supporting large data sets.
Source: §VI · p. 24Takeaways & Limitations
The package is applicable across fields including neuroscience, infrastructure, and climatology, and supports analysis of nonlinear dynamics and functional-network structure.
Source: §I · p. 2, §VI · p. 24Networks reconstructed from bivariate similarity measures describe statistical associations and cannot be interpreted causally.
Source: §3 · p. 12
Abstract
from arXiv · showhide
We introduce the \texttt{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. \texttt{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, \texttt{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 (RQA), 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.
I. INTRODUCTION
pyunicorn brings complex network theory and nonlinear time series analysis into one software framework for studying complex systems. Its object-oriented Python design organizes the methods into subpackages and supports combining them across functional-network and time-series analyses.
I. INTRODUCTION
- Network theory and nonlinear time series analysis offer complementary perspectives, and pyunicorn brings them together for functional-network and network-based time-series analysis.Functional networks represent statistical interrelationships among time series; recurrence networks, transition networks, and visibility graphs analyze time-series dynamics using network methods.Source: §I · pp. 1–2
A. Implementation philosophy
- The object-oriented Python library is intended as shared infrastructure for related methods and has been released under the BSD 3-Clause license.Its class hierarchy reflects relationships among methods; its design supports use from interactive sessions to cluster computations.Source: A. Implementation philosophy · pp. 2–3
B. Software structure
- Five subpackages organize general network analysis, spatial and interacting networks, functional networks, climate networks, and nonlinear time-series methods.The core package includes network measures and models; other subpackages provide functional- and climate-network construction, recurrence-based methods, visibility graphs, and surrogate time series.Source: B. Software structure · p. 3
C. General computational issues
The section describes pyunicorn’s computational approach and general network-analysis capabilities. It reports quadratic scaling for straightforward recurrence-network construction and notes memory and directedness constraints on the available methods.
C. General computational issues
- Available RAM limits network size until streaming algorithms are implemented for all measures, and many advanced methods currently apply only to undirected networks.Most measures aggregate local information from topology, node weights, and link attributes.Source: C. General computational issues · p. 4
- Most costly computations are delegated to compiled libraries or code, while an MPI helper supports parallel repetitive tasks; a typical recurrence network example takes about 0.03 seconds to compute.The example uses a dual-core Intel Core i5 CPU at 2.4 GHz running Mac OS X.Source: C. General computational issues · p. 4
- For larger N, recurrence-network construction time is proportional to N^2 when using the straightforward algorithm to calculate the N × N recurrence matrix.Fast neighbor-search algorithms that could reduce computation to O(N log N) or O(N) under certain conditions are not implemented in pyunicorn.Source: Figure 2 · p. 4
A. General complex networks
- The Network class supports directed and undirected graphs initialized from dense or sparse matrices or link lists, with node and link attributes for weights.Its measures include centralities, clustering, transitivity, community detection, and common random-network models; several measures support directed links and weights.Source: A. General complex networks · p. 5
- The package also supports less common random-walk betweenness measures and reading and saving data in formats such as GraphML.These formats support storage and exchange with other network-analysis and visualization software.Source: A. General complex networks · p. 5
B. Spatially embedded networks
pyunicorn provides measures and surrogate models for spatially embedded networks and networks of interacting subnetworks. Its US interstate example shows that preserving local link-length distributions and node degrees improves surrogate reproduction of observed links.
1. Measures and models for spatial networks
- GeoNetwork evaluates spatial distances, area-weighted network measures, and link-length statistics to analyze spatial embedding and long-range connections.Its spatially constrained surrogate models include distance-dependent link probabilities and rewiring models that preserve different network properties.Source: B. Spatially embedded networks · p. 5, §1 · p. 6
2. Use case: US interstate network
- With GeoModel2, most US interstate links appear in surrogate networks with high probability, improving on GeoModel1, which already reproduces many links.GeoModel1 preserves global link-length distribution and link density; GeoModel2 additionally preserves local link-length distributions and node degrees.Source: §2 · p. 6
C. Networks of interacting networks
- A network of networks divides nodes into disjoint subnetworks, with internal links within each subnetwork and cross-links between them; the partition may be specified or community-detected.The class InteractingNetworks provides measures including cross-link density, cross-degree, and cross-shortest-path betweenness to characterize connections between subnetworks.Source: C. Networks of interacting networks · pp. 6–7, §1 · p. 7
1. Measures and models for networks of networks
- InteractingNetworks provides surrogate models that preserve either cross-link density or cross-degree sequences between subnetworks.These models support assessment of how cross-connectivity relates to clustering, transitivity, path lengths, and betweenness.Source: §1 · p. 7
- Coupled climate networks and inter-system recurrence networks apply the interacting-network representation to relationships between climate fields and between dynamical systems.The paper identifies these as applications of the representation in time-series analysis.Source: §1 · p. 7
2. Use case: Zachary karate club network
In the karate club network, cross-group measures distinguish the groups’ connectivity and identify important connectors and leadership roles. The paper also motivates node-weighted analysis for networks whose nodes represent different-sized shares of a system.
2. Use case: Zachary karate club network
- The cross-link density between the karate club groups is about 0.04, versus internal densities of about 0.26 and 0.24, paralleling modularity measures.The comparison concerns cross-group density and the internal densities of groups G1 and G2.Source: §2 · pp. 7–8
- Interface members 2, 8, and 30 tend to have high cross-degree and cross-betweenness because they connect the groups.The paper also reports comparable first and second largest cross-betweenness values for the two group leaders, and regards cross-betweenness as a more reliable leadership indicator in this case.Source: §2 · p. 8
D. Node-weighted networks and node-splitting invariance
- Node-weighted analysis is appropriate when nodes represent different-sized shares or have different relevance, and its results should be consistent across scales.pyunicorn provides node-weighted variants of many standard and non-standard measures for ordinary and interacting networks.Source: D. Node-weighted networks and… · p. 8
1. Measures for node-weighted networks
pyunicorn provides node-splitting-invariant network measures that account for node weights, including an application to surface-temperature climate networks. Its functional-network tools also cover interdependencies within and between time-series fields.
1. Measures for node-weighted networks
- When a node is split into interlinked nodes with weights summing to the original weight and the same neighbors, other nodes’ n.s.i. measures remain unchanged.This scale consistency comes with a trade-off: when all weights equal one, n.s.i. measures do not simply reduce to unweighted measures; corrected variants can recover unweighted values when all weights equal a typical weight.Source: §1 · p. 8
2. Use case: spatial network structures in polar region
- Unweighted degree and clustering show artificial polar highs from denser grid cells, while n.s.i. measures compensate for this effect.Figure 6 compares degree in panels A and C and local clustering in B and D; surface-based node weights reflect the latitude-dependent grid density.Source: §2 · pp. 8–9, Figure 6 · p. 9
III. FUNCTIONAL NETWORKS: CONSTRUCTION AND ANALYSIS
- Functional networks represent statistical interdependencies within or between time-series fields, using measures such as lagged correlation and mutual information.Climate networks analyze a single climatological field, while coupled climate networks analyze relationships between multiple fields.Source: §III · p. 9
A. Coupling analysis
CouplingAnalysis estimates optionally lagged similarities between time series and can convert them into network links or use them as link weights. It offers linear and information-theoretic measures, including conditional measures intended to distinguish information transfer from shared pasts.
A. Coupling analysis
- CouplingAnalysis estimates optionally lagged similarity matrices that can be thresholded into network adjacency matrices or used in link-weighted measures.Supported similarities include Pearson correlation, mutual information, and multivariate extensions that can reduce effects of common drivers or indirect couplings.Source: A. Coupling analysis · p. 9, §1 · p. 10
1. Similarity measures for time series
- Lagged cross-correlation captures linear association and works with comparatively small samples, but cannot quantify nonlinear associations and can mislead under strong nonlinear relationships.Positive lags pair past X values with Y; negative lags reverse that temporal pairing.Source: §1 · p. 10
- Mutual information captures nonlinear association, while conditional mutual information measures dependence not contained in a third variable.The binning estimator can be heavily biased at common sample sizes around 10^3; the nearest-neighbor estimator is recommended for continuous variables, and Gaussian estimation targets the linear part under a bivariate-Gaussian assumption.Source: §1 · p. 10
- Bivariate information-transfer measures condition on past values to address shared history; MIT also conditions on the driver’s past but has greater nearest-neighbor estimator bias from its higher dimensionality.The nearest-neighbor conditional mutual information estimator trades bias against variance with its neighbor parameter k; larger k is better suited to conditional-independence tests in the stated setting.Source: §1 · pp. 10–11
2. Use case: coupled stochastic processes
In a four-variable process, MI gives ambiguous direction and a shifted lag peak, whereas ITY and MIT peak at the actual driving lag. The bivariate measures nevertheless show artifacts from indirect links and common drivers.
2. Use case: coupled stochastic processes
- ITY and MIT peak sharply at the true lag of 2, unlike MI, whose peak is shifted to lag 4; MIT is smaller because it also excludes driver autocorrelation.The process graph and lag-function matrix show the comparison for the example process.Source: Figure 7 · p. 11, §2 · pp. 11–12
- All three bivariate lagged measures can be nonzero without physical coupling because indirect links and common drivers create artifacts.The example includes a spurious peak from X3 to X4 despite no physical coupling.Source: §2 · p. 12
- MI and the bivariate ITY and MIT measures cannot reliably identify correct coupling lags when multiple lags are present.The example process includes autocorrelation and several driver-to-target lags.Source: §2 · pp. 11–12
3. Discussion and extensions
The section presents climate networks as a complementary way to analyze spatial statistical relationships and describes a degree-distribution kurtosis indicator for warning of an MOC transition. It also cautions that bivariate similarity networks do not establish causality.
3. Discussion and extensions
- Networks reconstructed from bivariate similarity measures characterize statistical associations between time series but cannot be interpreted causally.Source: §3 · p. 12
B. Climate networks
- Climate-network analysis complements multivariate statistical methods such as eigen analysis and has been applied to teleconnections, network backbones, bottlenecks, and ENSO dynamics.Source: B. Climate networks · p. 12
- Climate networks represent strong statistical interrelationships by thresholding similarity matrices; thresholds can reflect significance, vary by pair, or target a desired link density.Source: B. Climate networks · p. 12
1. Use case: climate networks for detecting climate transitions
- The climate-network workflow selects climate time series, preprocesses them and computes pairwise similarities, thresholds the similarity matrix, analyzes the network, then interprets results in Earth-system terms.Source: §1 · p. 13
- At 738 years, K_d rises significantly above control values and signals the MOC transition at least 100 years ahead.The figure marks the collapse at year 874; the warning signal lasts 44 years.Source: Figure 9 · p. 14, §1 · p. 14
- As freshwater inflow increases, high network degrees emerge in deep mid-latitude ocean nodes, especially in the South Atlantic, shifting degree distributions toward higher values.The kurtosis indicator captures this shift even though changes in the mean MOC pattern are relatively minor.Source: §1 · p. 14
2. Use case: seasonal and evolving climate network analysis of monsoon variability
The monsoon use case applies climate-network analysis to seasonal extreme rainfall and annual temperature variability. It identifies influential rainfall regions and links annual network variation to ENSO patterns.
2. Use case: seasonal and evolving climate network analysis of monsoon variability
- North Pakistan and the Eastern Ghats influence the distribution and propagation of extreme rainfall; North Pakistan is identified as a previously unknown influential region.Source: Figure 11 · p. 16, §2 · p. 16
- Rainfall networks use satellite precipitation extremes above each series’ 90th percentile and event synchronization, while annual temperature networks use zero-lag Pearson correlations.Source: §2 · p. 16
- The annual temperature-network structure is highly non-random and deterministic, with most average-path-length peaks corresponding to El Niño years and transitivity troughs to La Niña years.Source: §2 · p. 17
C. Coupled climate networks
pyunicorn’s coupled climate networks represent statistical dependencies between climate fields and provide weighted measures for analyzing their coupling. In the Northern Hemisphere example, the analysis identifies localized and hierarchical ocean–atmosphere structure, while cross-density alone does not describe within-field interactions.
C. Coupled climate networks
- CoupledClimateNetwork combines ClimateNetwork and InteractingNetworks, with weighted measures that support area-weighted analysis, including for regions near the poles.Coupled climate networks generalize climate-network analysis to dependencies between two or more climatological fields.Source: C. Coupled climate networks · p. 17
- The Northern Hemisphere analysis finds localized SST–HGT coupling in Atlantic and Pacific areas, while HGT nodes show broader areas of pronounced coupling with SST.The cross-degree density is a weighted share of connections to nodes in the opposite field; by definition, it contains no information about interactions within either field.Source: C. Coupled climate networks · p. 17, Figure 13 · p. 18
- SST nodes have lower n.s.i. cross-local clustering than HGT nodes, indicating that they preferentially couple with dynamically dissimilar HGT nodes.The measure represents the weighted share of mutually connected neighbors across the fields.Source: C. Coupled climate networks · p. 17, Figure 13 · p. 18
- The ocean-to-atmosphere interaction follows a hierarchy: larger areas of dynamically similar SST nodes couple with several dynamically dissimilar HGT areas.The authors suggest large-scale ocean currents interacting with different atmospheric regions along their flow as a possible explanation.Source: C. Coupled climate networks · pp. 17–18
IV. NETWORK-BASED TIME SERIES ANALYSIS
pyunicorn’s network-based time-series tools use recurrence-based methods to study dynamical properties and transitions, alongside visibility graphs for temporal features. Its recurrence analysis supports qualitative inspection and quantitative characterization of uni- and multivariate time series.
IV. NETWORK-BASED TIME SERIES ANALYSIS
- Network-based time-series analysis uses recurrence networks to examine phase-space geometry and visibility graphs to examine temporal features such as long-range correlations and time-reversal asymmetry.The paper demonstrates these methods with paleoclimate use cases focused on regime shifts or tipping points.Source: §IV · p. 18
A. Recurrence analysis
- Recurrence plots provide qualitative views of dynamics, while recurrence quantification analysis and recurrence networks can classify regimes and detect transitions or tipping points.Recurrence analysis also includes bivariate methods for studying coupling, including methods to detect coupling directionality.Source: A. Recurrence analysis · pp. 18–19
1. Recurrence quantification analysis
- RQA quantifies recurrence-matrix line-length distributions; pyunicorn provides measures including determinism, laminarity, diagonal-line entropy, and mean recurrence time.Resampled diagonal- and vertical-line distributions can be used to estimate confidence bounds for RQA measures.Source: §1 · p. 19
2. Recurrence network analysis
Recurrence networks treat phase-space state vectors as nodes connected by proximity, making network measures available for characterizing trajectory geometry. In a South China Sea paleoclimate example, recurrence measures track changes in SST regularity across climate transitions and monsoon variability.
2. Recurrence network analysis
- Recurrence networks are random geometric graphs: state vectors are nodes, and links represent proximity in phase space.They enable network measures such as transitivity and clustering to characterize trajectory geometry and distinguish dynamical regimes.Source: §2 · pp. 19–20
- Transitivity can be transformed into a global dimension-like measure, while transformed local clustering yields a dimension-like measure for each state vector.Multivariate extensions are used to investigate coupling direction and synchronization scenarios.Source: §2 · p. 20
3. Use case: identification of transitions in paleoclimate variability
- The paleoclimate use case analyzes South China Sea SST estimates over the past 3 Ma using sliding 410 ka windows stepped by 20 ka.It uses embedding dimension 6, an approximately 20 ka delay, and a recurrence threshold chosen to preserve a 7.5% recurrence rate.Source: §3 · pp. 20–21
- DET and T increase during the 2.8–2.2 Ma transition, rise again around 1.25 Ma, and are elevated from 0.6–0.2 Ma; lower values occur during 2.0–1.5 Ma and around 0.7 Ma.The authors associate higher DET and transitivity with more regular SST dynamics and lower values with more irregular variability, and report that the analysis confirms earlier links between the East Asian Monsoon and Milankovitch cycles.Source: §3 · p. 21, Figure 16 · p. 21
B. Visibility graphs
Visibility graphs turn time-series samples into nodes linked according to visibility relations, with graph properties related to the roughness of the series. Their time-directed structure supports forward–backward comparisons, but interpretation is bounded by univariate scope and network boundary effects.
B. Visibility graphs
- Visibility graphs encode line-of-sight relations between time-series samples, and their topological properties are related to the roughness of the underlying series.The paper also describes time-directed graph properties that separate contributions from past and future observations.Source: §1 · pp. 21–22, B. Visibility graphs · p. 21
1. Theory of time series visibility graphs
- Horizontal visibility graphs use a more restrictive linking condition than standard visibility graphs, so their link set is a subset; standard visibility graphs retain arbitrary affine invariance.Horizontal visibility graphs retain invariance only under uniform translation and rescaling.Source: §1 · p. 21
- Visibility graphs are tailored to univariate records, and missing information beyond the first and last samples can bias graph properties, especially path-based ones.The implementation provides boundary corrections for degree and closeness; improved treatment is planned but requires further analytical understanding.Source: §1 · p. 22
- Under fractional Brownian motion or related-process assumptions, visibility-graph degree scaling relates to the Hurst exponent, but its practical advantage over existing estimators is not established.The paper contrasts this with recurrence networks, whose power-law degree distributions relate to specific singularities in the state probability density.Source: §1 · p. 22
- Visibility graphs support forward–backward comparisons that form time-series irreversibility tests, which can evaluate the null hypothesis of linearity.The paper notes that irreversibility is a common hallmark of nonlinear dynamics.Source: §1 · p. 22
2. Use case: time irreversibility in glacial-deglacial dynamics
A visibility-graph test distinguishes the last-glacial GISP2 record from the Holocene in reversibility, with nonstationary sampling left as a caveat. The paper also describes surrogate time-series methods and pyunicorn’s flexible synthesis of network and time-series analysis.
2. Use case: time irreversibility in glacial-deglacial dynamics
- The analysis uses the 2 m-resolution GISP2 Greenland δ18O record across the Holocene and last glacial, with the Younger Dryas-Preboreal transition defining their boundary.The boundary is placed at about 11,650 years BP.Source: §2 · p. 22
- The test compares time-directed degree and local-clustering distributions with a Kolmogorov-Smirnov test, using 100 bootstrapped 80% samples per period for cross-validation.Each bootstrap preserves time ordering; the visibility graph represents observations as nodes connected when mutually visible.Source: §2 · p. 22, Figure 17 · p. 23
- The reversibility null is rejected for the last glacial but not the Holocene, indicating a strong nonlinear-dynamics signature in the glacial record.The authors note that changing sampling intervals in ice-core records may affect the test and require further study.Source: §2 · p. 23, Table II · p. 23
V. SURROGATE TIME SERIES
- pyunicorn provides surrogate series for significance testing, with methods preserving different properties such as amplitude distributions, power spectra, or recurrence structure.White-noise surrogates retain the amplitude distribution; Fourier surrogates retain the power spectrum; twin surrogates approximate recurrence structure.Source: §V · p. 23
- The described surrogate methods preserve properties of single series; multivariate methods preserving pairwise properties such as linear cross-correlation are not implemented.Surrogates can also support significance testing for functional-network links and network-based time-series findings.Source: §V · p. 24
VI. CONCLUSIONS AND PERSPECTIVES
- pyunicorn combines network and nonlinear time-series methods in a modular Python package, with compiled algorithms and sparse data structures supporting large analyses.The authors caution that future developments should be theoretically well-founded, explicable, and motivated by relevant research questions.Source: §VI · p. 24