OPyTN - Ordinal Pattern Transition Networks

Python toolkit for constructing and analyzing ordinal pattern transition networks from time series data. Implements Bandt-Pompe symbolic encoding to transform temporal sequences into directed networks where ordinal patterns serve as nodes and transitions as weighted edges.

• Ordinal Pattern Analysis: Extract ordinal patterns from time series using Bandt-Pompe methodology
• Transition Network Construction: Build sparse adjacency matrices representing pattern transitions
• Circulance Measure: Compute network-based complexity measures for dynamical system characterization
• Automatic Parameter Selection: Smart embedding dimension and delay parameter estimation
• Efficient Implementation: Optimized for large time series using sparse matrix representations

pip install numpy scipy

git clone https://github.com/timocbro/OPyTN.git
cd OPyTN
pip install -e .

import numpy as np
from opytn import circulance_py, ordinal_patterns_t, OPTN_sparse

# Generate example time series (e.g., chaotic Lorenz system)
ts = np.random.randn(1000)  # Replace with your time series

# Compute circulance measure for complexity characterization
circulance, optimal_tau, embedding_dim = circulance_py(ts)

print(f"Circulance: {circulance}")
print(f"Optimal embedding delay: {optimal_tau}")
print(f"Embedding dimension: {embedding_dim}")

# Extract ordinal patterns
patterns = ordinal_patterns_t(ts, d=4, tau=2)

# Construct transition network
adjacency_matrix = OPTN_sparse(ts, embedding_dim=4, embedding_delay=2)

Computes the circulance measure for time series complexity analysis.

Parameters:

• TS (array): Input time series (minimum 241 data points)
• m (int, optional): Embedding dimension. If None, automatically determined
• delays (int/list, optional): Embedding delays to test. If None, tests all feasible delays

Returns:

• circulance (int): Minimum circulance value (1 indicates strict periodicity)
• optimal_tau (int): Embedding delay that minimizes circulance
• embedding_dim (int): Embedding dimension used

Extracts ordinal patterns from time series using time-delay embedding.

Parameters:

• ts (array): Input time series
• d (int): Embedding dimension
• tau (int): Embedding delay

Returns:

• patterns (list): List of ordinal pattern tuples

Constructs sparse ordinal pattern transition network.

Parameters:

• TS (array): Input time series
• embedding_dim (int): Embedding dimension
• embedding_delay (int): Embedding delay

Returns:

• adjacency (scipy.sparse.csr_matrix): Sparse adjacency matrix

Automatically determines embedding dimension based on time series length.

Finds maximum feasible embedding delay (loses ≤10% of data points when transforming time series in ordinal pattern sequence).

Ordinal Pattern Transition Networks (OPTNs) provide a powerful framework for analyzing complex dynamical systems by:

1. Symbolic Encoding: Converting continuous time series into discrete ordinal patterns
2. Network Representation: Mapping pattern transitions to directed network edges
3. Complexity Quantification: Using network topology to characterize system dynamics

The circulance measure quantifies the intersection of in-degree and out-degree distributions, providing insights into:

• Periodic systems (circulance ≈ 1)
• Quasi-periodic systems (low circulance)
• Chaotic systems (moderate circulance)
• Stochastic systems (high circulance)

• Time series classification and clustering
• Dynamical system characterization
• Change point detection
• Complexity analysis of physiological signals
• Financial time series analysis
• Climate data analysis

# Periodic signal
t = np.linspace(0, 10*np.pi, 1000)
periodic_ts = np.sin(t)
circ_periodic, _, _ = circulance_py(periodic_ts)

# Chaotic signal (Lorenz system)
# ... generate Lorenz time series
circ_chaotic, _, _ = circulance_py(lorenz_ts)

# Random signal
random_ts = np.random.randn(1000)
circ_random, _, _ = circulance_py(random_ts)

print(f"Periodic: {circ_periodic}, Chaotic: {circ_chaotic}, Random: {circ_random}")

We welcome contributions! Please see our Contributing Guidelines for details.

git clone https://github.com/timocbro/OPyTN.git
cd OPyTN
pip install -e ".[dev]"

If you use OPyTN in your research, please cite:

@software{opytn2025,
  title={OPyTN: Ordinal Pattern Transition Networks in Python},
  author={Timo Bröhl, Max Potratzki},
  year={2025},
  url={https://github.com/timocbro/OPyTN}
}

• Bandt, C., & Pompe, B. (2002). Permutation entropy: a natural complexity measure for time series. Physical Review Letters, 88(17), 174102.
• Small, M. (2013). Complex networks from time series: Capturing dynamics. IEEE International Symposium on Circuits and Systems.

This project is licensed under the MIT License - see the LICENSE file for details.

• Issues: Please use the GitHub issue tracker
• Email: [timo.broehl@uni-bonn.de]

Keywords: ordinal patterns, transition networks, time series analysis, complexity measures, dynamical systems, network analysis, Bandt-Pompe, symbolic dynamics