This professional scientific software computes
recurrence
plots, cross recurrence plots, joint recurrence plots
and recurrence quantification analysis on commandline of
Unix and DOS/DOS-emulated systems. It is able to
work with really long data series. However, the output of the
results (plots) have to be prepared with external programmes
(e.g. gnuplot or Matlab).

The state space trajectory can be reconstructed from single time-series
by time-delay embedding. Alternatively, the columns of input data
can be used as the components of the state space vectors.

Currently the following RQA measures will be computed:

Recurrence rate RR

Determinism DET

Laminarity LAM

maximal diagonal line length L_max

maximal vertical line length V_max

mean diagonal line length L_mean

Trapping time TT

Entropy of diagonal line length distribution L_entr

Entropy of vertical line length distribution V_entr

Divergence DIV (= 1/L_max)

Ratio DET/RR

Ratio LAM/DET

Recurrence times 1st type T1

Recurrence times 2nd type T2

This software will be further improved.

Usage

The general usage is

rp -i data_file

or

./rp -i data_file

(in Unix systems if the programme is in the same folder)

You can specify embedding parameters dimension and delay,
the recurrence threshold, Theiler corrector and the minimal
lengths for diagonal and vertical lines by adding the
corresponding options.

Instead of embedding, the columns of input data
can be used as the components of the state space vectors.
Note that
then the dimension is automatically given by the numbers of the
columns, i. e. it is not necessary to use the option -m.
Any additional embedding dimension specified by this option
would mean an addtional embedding (e. g., 3 columns
and an embedding of 2 would result in a 6-dimensional phase
space).
Moreover, check the successful import of the columns by looking at the
first line of the output, where it is clearly stated how many
columns were read.

(Cross/joint) recurrence plot and RQA results can be stored in ASCII files with
options -r and -o, respectively. The (cross/joint) recurrence
plot file contains the coordinates of recurrence points.

Option

Meaning

-i <string>

data filename (input)

-j <string>

filename of additional data for CRP/JRP (input)

-J

compute JRP instead of default CRP (only if 2nd data is given)

-r <string>

filename recurrence plot (output)

-o <string>

filename RQA measures (output)

-p <string>

filename histogramme diagonal line lengths (output)

-c

cummulative histogramme

-f <string>

format for recurrence plot file (ASCII, TIF), default=ASCII

will compute a recurrence plot of the data stored in file soi.dat,
by using an embedding of dimension 3, a delay 9 and a recurrence threshold
of 0.1. The resulting recurrence plot is stored in file rp.dat
and the RQA measures are stored in file rqa.dat.

rp -i os1 -j os2 -r rp.tif -f TIF -J -e 0.1 -w 0

will yield the joint recurrence plot between data os1 and os2
without embedding as a TIFF image rp.tif. The Theiler window
is set to zero in order to get also the main diagonal line in the joint recurrence plot.

A negative threshold value computes the distance matrix instead of the binary
recurrence matrix:

rp -i lorenz.dat -r rp.dat -e -1 -w 0

(where the three components of the Lorenz-system form three columns in file
lorenz.dat) will yield the distance matrix of the phase space trajectory
defined by the three-dimensional system given in lorenz.dat.

Using the option -n OP, an order patterns recurrence plot is created:

rp -i lorenz.dat -r rp.dat -n OP -m 3 -t 7

Visualization of the recurrence plot from ASCII data for example with Matlab:

RP=load('rp.dat');
for i=1:length(RP);X(RP(i,1),RP(i,2))=1;end
imagesc(X)
colormap(flipud(gray))

More examples can be found in Sect. "Tips"!

Tips

Possible maximal data length For RQA, the possible data length can be maximized
by calculating only the RQA measures without creating
the recurrence plot.

Windowed RQA Calculating the RQA in small windows (for detecing transitions)
can be done by using a script.

For example in Matlab:

% import some data
x=load('soi3.dat');
% data length
N = length(x);
% window length and window step size
w = 100; s = 10;
for i = 1:s:N-w
% make sub-string of data
sub_x = x(i:i+w-1);
% save sub-string of data
save('temp_data','-ascii','sub_x')
% call extern rp programme
unix('./rp -i temp_data -s -m 3 -t 5 -e 0.7 -o rqa.dat');
end
delete('temp_data')

Please note that under a MS Windows operating system, you have to call
the external programme by

# define data file
data="soi3.dat"
# data length
N=`awk 'END { print NR }' $data`
# window length and window step size
w=100; s=10
Ne=`expr $N - $w`
i=1
while [ $i -le $Ne ]
do
i2=`expr $N - $i + 1`
# make sub-string of data
tail -n$i2 $data | head -n$w > temp_data
# call rp programme
./rp -i temp_data -s -m 3 -t 5 -e 0.7 -o rqa.dat
i=`expr $i + $s`
done
rm temp_data

Plot RQA measures RQA measures will be added to the
same file, if it exists (see example above), hence, an existing
RQA file will not be replaced. This allows us to compute several
data sets and to store the results in only one file, or to
compute windowed RQA measures (e.g. for detecting transitions), respectively.
However, this requires to delete an already existing rqa file or to
use a new file name for the rqa file, if the RQA measures should not
be added to the existing file.

Import and plot RQA measures with Matlab:

% import RQA measures
rqa = [];
% open RQA data file
fid = fopen('rqa.dat','r');
while 1
% read RQA data
dataStr = fgetl(fid);
% leave the loop if end of file
if ~ischar(dataStr), break, end
% neglect comments line (e.g. header)
if isempty(findstr(dataStr, '#'))
% import RQA measures into local variable rqa
rqa = [rqa;str2num(dataStr)];
end
end
% close RQA data file
fclose(fid);
% plot recurrence rate
plot(rqa(:,1))

The columns in the RQA output are

RR

DET

DET/RR

LAM

LAM/DET

L_max

L

L_entr

DIV

V_max

TT

V_entr

T1

T2

License

Warning

I give no warranty for the programme and the results obtained
from using this programme. It lies in the responsibility of the
user to check the results.

Screenshot

Download

It is recommended to rename the downloaded file to rp (except
for Windows, where it should be rp.exe).

Please respect the copyrights! The content is protected
by the Creative
Commons License. If you use the provided programmes, text or figures,
you have to refer to the given publications and this web site
(tocsy.pik-potsdam.de)
as well.