Recurrence

polars_ts.imaging.recurrence

Recurrence plot imaging and Recurrence Quantification Analysis (RQA).

Converts time series to 2D binary/grayscale recurrence plot images and extracts RQA features (recurrence rate, determinism, laminarity, entropy, trapping time).

_recurrence_matrix(x, threshold, metric, normalize)

Compute recurrence plot for a single 1D series.

to_recurrence_plot(df, threshold=0.1, metric='euclidean', normalize=True, id_col='unique_id', target_col='y')

Convert time series to recurrence plot images.

For each series, computes the pairwise distance matrix between all timepoints and optionally binarises it with a threshold.

Parameters

df DataFrame with columns id_col and target_col. threshold Binarisation threshold. Points closer than this are marked as recurrent (1). Set to None for a grayscale distance matrix. metric Point-wise distance metric (any metric supported by scipy.spatial.distance.cdist). normalize Z-normalize each series before computing distances. id_col Column identifying each time series. target_col Column with the time series values.

Returns

dict[str, np.ndarray] Mapping from series ID to a square 2D numpy array (n x n).

_diagonal_lines(R)

Extract lengths of diagonal lines (excluding main diagonal).

_vertical_lines(R)

Extract lengths of vertical lines.

rqa_features(R, l_min=2)

Extract Recurrence Quantification Analysis features from a recurrence plot.

Parameters

R Square binary recurrence plot (values 0 or 1). l_min Minimum line length to count for determinism and laminarity.

Returns

dict[str, float] Dictionary with keys: recurrence_rate, determinism, laminarity, mean_diagonal, mean_vertical, entropy.