Recurrence Graph

class driada.recurrence.recurrence_graph.RecurrenceGraph(data, method='knn', k=5, epsilon=None, metric='euclidean', theiler_window=None, create_nx_graph=False, verbose=False)[source]

Bases: ProximityGraph

Recurrence graph constructed from delay-embedded time series data.

Extends ProximityGraph (-> Network) with Theiler window removal and recurrence quantification analysis (RQA). Inherits spectral analysis, entropy, degree distribution, and randomization from Network.

Parameters:

  • data (ndarray of shape (m, N_embedded)) – Pre-embedded data matrix. Use takens_embedding() first.

  • method ({'knn', 'eps'}, default='knn') – Graph construction method.

  • k (int, default=5) – Number of neighbors for k-NN.

  • epsilon (float, optional) – Radius for epsilon-ball.

  • metric (str, default='euclidean') – Distance metric.

  • theiler_window (int or None, optional) – Remove entries where |i-j| < theiler_window.

  • verbose (bool, default=False) – Print progress.

Raises:

ValueError – If data is not 2D.

__init__(data, method='knn', k=5, epsilon=None, metric='euclidean', theiler_window=None, create_nx_graph=False, verbose=False)[source]

Initialize proximity graph from data.

Parameters:

  • d (ndarray of shape (n_features, n_samples)) – Data matrix where each column is a sample.

  • m_params (dict) – Metric parameters. Must contain ‘metric_name’.

  • g_params (dict) – Graph parameters. Must contain ‘g_method_name’.

  • create_nx_graph (bool, default=False) – Whether to create NetworkX representation.

  • verbose (bool, default=False) – Whether to print progress messages.

Raises:

ValueError – If data is not 2D or is empty. If required parameters are missing.

Notes

lost_nodes attribute is always set (even if empty). Data shape assumes (features, samples) format.

construct_adjacency()[source]

Build adjacency matrix with Theiler window applied before Network init.

Overrides ProximityGraph.construct_adjacency() to inject Theiler window removal at the correct point in the initialization sequence.

ProximityGraph.__init__ runs these steps in order:

  1. self.construct_adjacency() — builds adj, bin_adj

  2. Network.__init__(adj=…) — computes degree sequences, etc.

  3. self._checkpoint() — validates symmetry

By overriding step 1 to also apply the Theiler window, Network.__init__ at step 2 sees the already-filtered adjacency. This ensures degree sequences, spectral analysis, and all other Network properties are computed on the correct matrix — no stale state from post-init mutation.

property theiler_window

Theiler window applied to this recurrence graph.

property recurrence_rate

Fraction of recurrence points in the matrix.

classmethod from_adjacency(adj, theiler_window=None, create_nx_graph=False)[source]

Create RecurrenceGraph from pre-built adjacency matrix.

Bypasses ProximityGraph construction. Used for population recurrence graphs or loaded matrices.

The resulting object has full Network functionality (degrees, spectral analysis, RQA) but no embedding data — data, knn_indices, knn_distances, neigh_distmat, and metric are all None.

Parameters:

  • adj (scipy.sparse matrix) – Square adjacency matrix.

  • theiler_window (int or None) – Theiler window to record (not applied).

Return type:

RecurrenceGraph

rqa(l_min=2, v_min=2)[source]

Compute recurrence quantification analysis measures.

Parameters:

  • l_min (int, default=2) – Minimum diagonal line length.

  • v_min (int, default=2) – Minimum vertical line length.

Returns:

RQA measures. See compute_rqa for keys.

Return type:

dict