Commandline Recurrence Plots

Version: 1.13z (Last mod: 2006-03-08)

Description

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.

More information about recurrence based methods can be found on the recurrence plot web site.

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.

For example:

rp -i soi.dat -r rp.dat -o rqa.dat -e 0.1 -m 3 -t 9

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');
S=sparse(RP(:,1),RP(:,2),RP(:,3));
spy(S)

or

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

dos('rp -i temp_data -s -m 3 -t 5 -e 0.7 -o rqa.dat');

or in a bash:

# 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

1. RR
2. DET
3. DET/RR
4. LAM
5. LAM/DET
6. L_max
7. L
8. L_entr
9. DIV
10. V_max
11. TT
12. V_entr
13. T1
14. 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).

• True64 OSF1(5.1) on alpha
• HP-UX 11 on HP U9000
• Solaris 5.9 on Sun
• Linux on i686
• Linux on AMD Opteron 64 (Intel compiler)
• Linux on AMD Opteron 64 (GNU compiler)
• Linux on Intel Itanium 2 (Intel compiler)
• Linux on Intel Itanium 2 (GNU compiler)
• Mac OSX (PowerPC)
• Mac OSX (Intel)
• Dos/Win on x86

Don't forget to make the file executable under the Unix systems (OSF, Linux, OS X) with the command

chmod a+x rp

A comfortable GUI for this commandline tool is available at
http://people.physik.hu-berlin.de/~schinkel/rqagui.html.

Version History

• 1.13 Bug for distance plots of short data series resolved
• 1.11 Order patterns recurrence plots included
• 1.10 Cummulative histogram of diagonal line lengths
• 1.9 Now stores also the diagonal line length histogram
• 1.8 Bug for Big-endian machines resolved; Mac supported
• 1.7 MSDOS supported
• 1.6 Recurrence plots can be saved as TIFF images (faster)
• 1.5 Recurrence times 1st and 2nd type added; bug fix for Theiler corrector
• 1.4 Version information added
• 1.3 Cross and joint recurrence plots added; multi-column input can be used instead of embedding
• 1.2 Computation time is shown
• 1.1 Initial version

Bugs/ Problems

Please send me bug reports or if any problem occured.

The TIFF-output in the Dos/Win version may fail.

Please note that the TIFF image contains 16bit values. Ensure that the image viewer you are using is able to display 16bit images.

Contact

Norbert Marwan, Potsdam, Germany