ts2net 0.9.0

Time series to network conversion and analysis

ts2net

Time series to networks. Clean API for visibility graphs, recurrence networks, and transition networks.

Install

Basic Installation

Installs core network builders and sklearn integration:

# Using uv (recommended)
uv pip install ts2net

# Or using pip
pip install ts2net

Optional Feature Tiers

# YAML pipeline CLI + Parquet I/O
uv pip install "ts2net[pipeline]"

# Structural decomposition (BSTS)
uv pip install "ts2net[bsts]"

# Performance acceleration (Numba)
uv pip install "ts2net[speed]"

# All optional features
uv pip install "ts2net[all]"

Extra	Includes	Use when
(core)	numpy, scipy, networkx, sklearn, matplotlib	Building networks, sklearn features
[pipeline]	click, pyyaml, polars, pyarrow	ts2net run, Parquet ingestion
[bsts]	statsmodels	Structural decomposition
[polars]	polars, pyarrow	Polars-only ingestion (subset of pipeline)
[speed]	numba	100–180× visibility graph speedup
[all]	everything above + dtw, cnn, examples, viz	Full development setup

Development Installation

For development, use uv:

# Clone the repository
git clone https://github.com/kylejones200/ts2net.git
cd ts2net

# Install with uv (creates virtual environment and installs dependencies)
uv sync --group dev

# Build Rust extension
uv run maturin develop --release

Optional Dependencies

# Using uv
uv pip install "ts2net[pipeline]"   # CLI + Parquet pipeline
uv pip install "ts2net[bsts]"       # BSTS decomposition
uv pip install "ts2net[speed]"      # Performance acceleration (Numba)
uv pip install "ts2net[dtw]"        # DTW distance (tslearn)
uv pip install "ts2net[cnn]"        # Temporal CNN embeddings (PyTorch)
uv pip install "ts2net[examples]"   # Example dependencies
uv pip install "ts2net[all]"        # All optional features

# Or using pip
pip install "ts2net[pipeline]"
pip install "ts2net[bsts]"
pip install "ts2net[speed]"

Verify Installation

import ts2net
print(ts2net.__version__)

from ts2net import HVG
import numpy as np
x = np.random.randn(100)
hvg = HVG()
hvg.build(x)
print(f"Installation successful: {hvg.n_nodes} nodes, {hvg.n_edges} edges")

Quick Start

import numpy as np
from ts2net import HVG

x = np.random.randn(1000)

hvg = HVG()
hvg.build(x)

print(hvg.n_nodes, hvg.n_edges)
print(hvg.degree_sequence())

Adjacency Matrix

A = hvg.adjacency_matrix()
print(A.shape)  # (1000, 1000)

NetworkX (Optional)

NetworkX is optional. Convert only if needed:

G = hvg.as_networkx()
import networkx as nx
print(nx.average_clustering(G))

Structural Decomposition and Residual Topology

For time series with predictable structure (seasonality, trends), decompose first, then analyze the residual:

from ts2net.bsts import features, BSTSSpec

# Decompose and analyze residual in one pass
spec = BSTSSpec(
    level=True,
    trend=False,
    seasonal_periods=[24, 168]  # Daily and weekly for hourly data
)

result = features(x, methods=['hvg', 'transition'], bsts=spec)

# Access three feature blocks
raw_stats = result.raw_stats              # Basic series statistics
structural_stats = result.structural_stats # Component variances, seasonal strength
residual_network_stats = result.residual_network_stats  # Network features from residual

Use cases:

• Compare meters/wells without seasonal confounds
• Flag series where structural model fails (high residual complexity)
• Separate predictable structure from irregular dynamics

Installation: BSTS requires the [bsts] extra (statsmodels is not in the core install):

uv pip install "ts2net[bsts]"
# Or: pip install "ts2net[bsts]"

See examples/bsts_features.py for complete examples.

Large Series

For large series, use output modes to control memory usage:

# Degrees only (most memory efficient)
hvg = HVG(output="degrees")
hvg.build(x)
degrees = hvg.degree_sequence()  # Fast, no edge storage

# Stats only (summary statistics without edges)
hvg = HVG(output="stats")
hvg.build(x)
stats = hvg.stats()  # n_nodes, n_edges, avg_degree, etc.

# Full edges (default, use for small-medium series)
hvg = HVG(output="edges")
hvg.build(x)
edges = hvg.edges  # Full edge list

Scale Guidelines

Series Length	Method	Recommended Settings	Memory Risk
n < 10k	All methods	output="edges"	Safe
10k < n < 100k	HVG	output="edges" or output="degrees"	Safe with sparse
10k < n < 100k	NVG	limit=2000-5000, output="degrees"	Use horizon limit
10k < n < 100k	Recurrence	rule='knn', k=10-30	Avoid exact all-pairs
n > 100k	HVG	output="degrees" or output="stats"	Safe
n > 100k	NVG	limit=2000-5000, max_edges=1e6, output="degrees"	Required limits
n > 100k	Recurrence	rule='knn', k=10-30, output="degrees"	kNN only

Critical Warnings:

• Dense adjacency matrices are disabled by default for n > 50k (prevents 63GB+ memory blowup)
• NVG without limit can create millions of edges for smooth series
• Recurrence exact all-pairs is O(n²) memory - use kNN for large n
• NetworkX conversion refused for n > 200k (use force=True to override)

Memory Estimates:

• Dense adjacency: ~8 * n² bytes (e.g., 90k nodes = 63 GB)
• Sparse adjacency: ~16 * m bytes where m = edges (e.g., 100k edges = 1.6 MB)
• Edge list: ~16 * m bytes (similar to sparse)
• Degrees only: ~8 * n bytes (e.g., 90k nodes = 720 KB)

Methods

Visibility Graphs

HVG - Horizontal Visibility Graph

from ts2net import HVG

hvg = HVG(weighted=False, limit=None)
hvg.build(x)

NVG - Natural Visibility Graph

from ts2net import NVG

# For large series, use horizon limit and bounded work
nvg = NVG(weighted=False, limit=5000, max_edges=1_000_000, output="degrees")
nvg.build(x)

# Or with memory limit
nvg = NVG(limit=2000, max_memory_mb=100)  # Caps at ~100MB
nvg.build(x)

Recurrence Networks

Phase space recurrence:

from ts2net import RecurrenceNetwork

rn = RecurrenceNetwork(m=3, tau=1, rule='knn', k=5)
rn.build(x)

Parameters:

• m: embedding dimension (None = auto via FNN)
• tau: time delay
• rule: 'knn', 'epsilon', 'radius'
• k: neighbors for k-NN
• epsilon: threshold for epsilon-recurrence

Transition Networks

Symbolic dynamics:

from ts2net import TransitionNetwork

tn = TransitionNetwork(symbolizer='ordinal', order=3)
tn.build(x)

Symbolizers:

• 'ordinal': ordinal patterns
• 'equal_width': equal-width bins
• 'equal_freq': equal-frequency bins (quantiles)
• 'kmeans': k-means clustering

Compare Methods

from ts2net import build_network

x = np.random.randn(1000)

for method in ['hvg', 'nvg', 'recurrence', 'transition']:
    if method == 'recurrence':
        g = build_network(x, method, m=3, rule='knn', k=5)
    elif method == 'transition':
        g = build_network(x, method, symbolizer='ordinal', order=3)
    else:
        g = build_network(x, method)
    
    print(f"{method}: {g.n_edges} edges")

Output:

hvg: 1979 edges
nvg: 2931 edges
recurrence: 3159 edges
transition: 18 edges

Multivariate

Multiple time series → network where nodes = time series:

from ts2net.multivariate import ts_dist, net_knn

X = np.random.randn(30, 1000)  # 30 series, 1000 points each

D = ts_dist(X, method='dtw', n_jobs=-1)
G = net_knn(D, k=5)

print(G.n_nodes, G.n_edges)

Distance methods: 'correlation', 'dtw', 'nmi', 'voi', 'es', 'vr'

Network builders: net_knn, net_enn, net_weighted

Performance

With Numba (recommended):

pip install numba

Speedups:

• HVG: 100x faster
• NVG: 180x faster
• Recurrence: 10x faster

API

All methods follow the same pattern:

builder = Method(**params)
builder.build(x)

# Access results
builder.n_nodes
builder.n_edges
builder.edges                # list of tuples
builder.degree_sequence()    # numpy array
builder.adjacency_matrix()   # numpy array
builder.as_networkx()        # optional conversion

Troubleshooting

Common Issues

Memory errors with large time series:

• Use output="degrees" or output="stats" instead of output="edges"
• For NVG, always set limit parameter (e.g., limit=5000)
• For recurrence networks, use rule='knn' with small k (10-30) instead of exact all-pairs

Slow performance:

• Install Numba: uv pip install numba or pip install numba (100-180x speedup for visibility graphs)
• Use output="degrees" if you don't need full edge lists
• For multivariate, use n_jobs=-1 for parallel distance computation

Import errors:

• Ensure you're using Python 3.12+
• If Rust extension fails to build, install Rust: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
• For development, run maturin develop --release after installing Rust

NetworkX conversion refused:

• For very large graphs (n > 200k), NetworkX conversion is disabled by default
• Use force=True to override: hvg.as_networkx(force=True)
• Consider using output="degrees" or output="stats" instead

Getting Help

• Full Documentation
• Open an Issue
• Examples

Citation

Multivariate methods based on:

Ferreira, L.N. (2024). From time series to networks in R with the ts2net package. Applied Network Science, 9(1), 32. https://doi.org/10.1007/s41109-024-00642-2

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Case Study

Try the Spain smart meter case study in Binder (no dataset download required):

License

MIT