RQAMeasures

class eyefeatures.features.measures.RQAMeasures(metric=<function euclidean>, rho=0.1, min_length=1, measures=None, x=None, y=None, aoi=None, pk=None, return_df=True, ignore_errors=False)[source]

Bases: MeasureTransformer

Calculates REC, DET, LAM and CORM measures.

Recurrence Quantification Analysis (RQA) is a nonlinear technique to quantify the structure of dynamical systems based on recurrence plots. It identifies recurrent states and their patterns. - REC (Recurrence Rate): Percentage of recurrent points. - DET (Determinism): Percentage of recurrent points forming diagonal lines. - LAM (Laminarity): Percentage of recurrent points forming vertical/horizontal lines. - CORM (Center of Recurrence Mass): Average distance of recurrence points from the

main diagonal.

Parameters:

  • metric (Callable) – callable metric on R^2 points (e.g., scipy.spatial.distance.euclidean).

  • rho (float) – threshold radius for RQA matrix. Two points are considered recurrent if their distance is less than rho.

  • min_length (int) – minimum length of diagonal/vertical/horizontal lines to be counted.

  • measures (list[str]) – list of measures to calculate (subset of [‘rec’, ‘det’, ‘lam’, ‘corm’]).

  • x (str) – X coordinate column name.

  • y (str) – Y coordinate column name.

  • aoi (str) – Area Of Interest column name(-s).

  • pk (list[str]) – primary key.

  • return_df (bool) – whether to return output as DataFrame or numpy array.

  • ignore_errors (bool) – If True, return NaN when feature computation fails; otherwise raise.

get_feature_names_out(input_features=None)[source]

Returns the names of the features generated by this transformer.

Return type:

list[str]

The metrics calculated include Recurrence (REC), Determinism (DET), Laminarity (LAM), and Center of Recurrence Mass (CORM). These measures help to quantify the complexity and structure of the recurrence patterns within the data. In this example we use a default euclidean metric as metric. Parameters rho and min_length correspond for RQA matrix threshold radius and threshold length of its diagonal. In measures we specify the required features to calculate.

Recurrence matrix \(R\) is defined as \(R_{ij} = \mathbb{I}\left\{d(x_i, x_j) \leq \rho \right\}\):

  • Reccurence Rate counts the total number of recurrence points above the main diagonal of \(R\):

\[\text{REC} = \frac{2}{n(n-1)} \sum_{i=1}^n \sum_{j=i+1}^n R_{ij}\]

  • Determinism measures the percentage of recurrence points forming diagonal lines of length at least $L_{min}$:

\[\text{DET} = \frac{100 \cdot \sum_{l \geq L_{min}} l \cdot P(l)}{\sum_{i=1}^n \sum_{j=i+1}^n R_{ij}},\]
\[\text{ where } L_{min} - \text{ minimum line length}, \, P(l) - \text{probability of diagonal lines of length } l\]

  • Liminarity measures the percentage of recurrence points forming vertical or horizontal lines of length at least \(L_{min}\):

\[\text{LAM} = \frac{50 \left( \sum_{\text{HL}} \text{HL} + \sum_{\text{VL}} \text{VL}\right)}{\sum_{i=1}^n \sum_{j=i+1}^n R_{ij}},\]

where \(HL\) and \(VL\) represents the sums of horizontal and vertical lines of length at least \(L_{min}\).

  • Center of Recurrence Mass measures the weighted average of the distances between recurrence points, emphasizing the central tendency of recurrences in the matrix:

\[\text{CORM} = \frac{100 \cdot \sum_{i=1}^{n-1} \sum_{j=i+1}^n (j-i) R_{ij}}{(n-1) \cdot \sum_{i=1}^n \sum_{j=i+1}^n R_{ij}}\]

Reference

Anderson, N. C., Bischof, W. F., Laidlaw, K. E. W., Foulsham, T., Kingstone, A., & Cristino, F. (2013). Recurrence quantification analysis of eye movements. Behavior Research Methods, 45(3), 842–856. https://doi.org/10.3758/s13428-012-0299-5