ENH: Theiler window option for diagonal RQA measures in `RecurrencePlot`

[fkuehlein]

We had multiple requests about a missing theiler window option for RQA measures.

It should be noted that, apparently, excluding the diagonal and/or a Theiler window is useful in the analysis of diagonal structures (such as determinism). It is problematic though, when looking at vertical structures (such as laminarity or trapping time) because here the idea is to actually quantify the autocorrelation effects (i.e. how long the system state will stay within a range of epsilon), so the main diagonal and its vicinities are the source of relevant information.

Implementation should be straightforward. In the meantime, the example code below can be used as a workaround.

import numpy as np
from pyunicorn.timeseries import RecurrencePlot

# create example timeseries
x = np.linspace(0,2*np.pi, 20)
sine = np.sin(x)
# create recurrence plot
rp = RecurrencePlot(sine, threshold=0.5)
# calculate determinism
DET = rp.determinism()

# clear cache
rp.cache_clear()
# set width of Theiler window (n=1 for main diagonal only)
n = 3
# create mask to access corresponding entries of recurrence matrix
mask = np.zeros_like(rp.R, dtype=bool)
for i in range(len(sine)):
    mask[i:i+n, i:i+n] = True
# set diagonal (and subdiagonals) of recurrence matrix to zero
# by accessing the recurrence matrix rp.R
rp.R[mask] = 0
# calculate Theiler`d determinism
DET_th = rp.determinism()

Look into whether RecurrencePlot methods in question have overriding methods in child classes that could be similarly enhanced.

[keriheuer]

Is it possible to provide an update to this code snippet? The latest version of pyunicorn no longer has the method rp.clear_cache() so I can't figure out how to manually exclude the Theiler window anymore.

[fkuehlein]

sure!

The method RecurrencePlot.clear_cache() was substituted by RecurrencePlot.cache_clear() as of 93ab748.

However, I noticed that the recurrence matrix is currently not even cached, so the line can simply be left out. I edited the code accordingly in the above snipped.

EDIT: RP.determinism() is not cached, but it relies on RP.diagline_dist() which is cached. Therefore, the cache does need to be cleared before recalculating. I edited the above code snippet accordingly.