Potsdam Institute for Climate Impact Research (PIK)
Interdisciplinary Center for Dynamics of Complex Systems (University of Potsdam)
Cardiovascular Physics Group (Humboldt-Universität zu Berlin)
PIK Logo
TOCSY - Toolboxes for Complex Systems
PIK/ Antique/ Blue
Home Home
ACE - Nonlinear Regression Analysis ACE
Adaptive Filtering Procedure Adaptive Filtering
CoinCalc - Event Coincidence Analysis CoinCalc
COPRA - Constructing Proxy Records From Age Models COPRA
Cross Recurrence Plot Toolbox CRP Toolbox
Commandline Recurrence Plots Commandline RPs
Analyse Coupling of Transient Dynamics Coupling Analysis
Identification of Coupling Direction Coupling Direction
Inner Composition Alignment IOTA
Dynamical Invariants by Recurrence Plots K2
Toolbox for the analysis of non-equidistantly sampled time series NEST
DSProlog DSProlog
Permutation Entropy PETROPY
pyunicorn ‐ UNIfied COmplex Network and Recurrence aNalysis toolbox pyunicorn
Symbolic Dynamics from Recurrence Plots RECGRAM
Recurrence Structure Analysis RSA
Wavelet and Coherence Analysis SOWAS
System Identification Tool System Identification
Time Series Graph and Momentary Information Transfer Estimation TiGraMITe

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.

OptionMeaning
-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)
-ccummulative histogramme
-f <string> format for recurrence plot file (ASCII, TIF), default=ASCII
-n <string> distance norm (EUCLIDEAN, MAX, MIN, OP), default=EUCLIDEAN
-m <number> embedding dimension, default=1
-t <number> embedding delay, default=1
-e <number> threshold, default=1 (if negative, a distance plot will be created)
-l <number> minimal diagonal line, default=2
-v <number> minimal vertical line, default=2
-w <number> Theiler corrector, default=1
-D <string> delimiter in data file, default=TAB
-d <string> delimiter for RQA file, default=TAB
-ssilent (no messages displayed)
-Vprint version information
-hprint this help text

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.

joint recurrence plot
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

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

last changes: Thu, 10 Sep 2020 09:05:16 UTC  



Creative Commons License

© 2004-2021 SOME RIGHTS RESERVED
University of Potsdam, Interdisciplinary Center for Dynamics of Complex Systems, Germany
Potsdam Institute for Climate Impact Research, Transdisciplinary Concepts and Methods, Germany

This work is licensed under a Creative Commons Attribution-NonCommercial-NoDerivs 2.0 Germany License.
Imprint, Data policy, Disclaimer

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.

@MEMBER OF PROJECT HONEY POT
Spam Harvester Protection Network
provided by Unspam