crqa.m

function xout=crqa(varargin)
%CRQA   Computes and plots the CRQA measures.
%    Y=CRQA(X [,Y] [,param1,param2,...]) 
%    Recurrence quantification analysis of the cross recurrence
%    plot of the vectors X and Y. 
%
%    The input vectors can be multi-column vectors, where
%    each column will be used as a component of the 
%    phase-space vector. However, if the first column is
%    monotonically increasing, it will be used as an
%    time scale for plotting.
%
%    Y=CRQA(X,M,T,E,W,WS,LMIN,VMIN,TW) computes the 
%    recurrence quantification analysis of the recurrence
%    plot of X by using the dimension M, delay T, the
%    size of neighbourhood E, the window size W and 
%    a window shifting value of WS. LMIN and VMIN 
%    specify the minimal length of diagonal and vertical 
%    line structures (default is 2) and TW specifies the
%    Theiler window (default is 1).
%
%    CRQA(...) without any output arguments opens a
%    GUI for interactively control the CRQA. If an
%    output is specified with using the option 'gui',
%    then the output will contain the figure handle.
% 
%    Parameters: 
%    Dimension M, delay T, the size of
%    neighbourhood E, the window size W and the shift
%    value WS are the first five numbers after the data 
%    series; if W is empty, the whole plot will be calculated.
%    The next two optional numeric parameters LMIN and VMIN
%    specify the minimal length of line structures.
%
%    As the last numeric parameter, the size of the Theiler 
%    window TW can be specified (default is 1). This window 
%    excludes the recurrence points parallel to the main 
%    diagonal from the analysis. The application of the
%    Theiler window is useful only for recurrence plots. In
%    cross recurrence plots, the size of the Theiler window will
%    be set automatically to zero.
%
%    Further parameters can be used to switch between various 
%    methods of finding the neighbours of the phasespace 
%    trajectory, to suppress the normalization of the data 
%    and to suppress the GUI (useful in order to use this 
%    programme by other programmes). The minimal length of 
%    diagonal and vertical structures can be setted only in 
%    the GUI.
%
%    Methods of finding the neighbours.
%      maxnorm     - Maximum norm.
%      euclidean   - Euclidean norm.
%      minnorm     - Minimum norm.
%      nrmnorm     - Euclidean norm between normalized vectors
%                    (all vectors have the length one).
%      rr          - Maximum norm, fixed recurrence rate.
%      fan         - Fixed amount of nearest neighbours.
%      inter       - Interdependent neighbours.
%      omatrix     - Order matrix.
%      opattern    - Order patterns recurrence plot.
%
%    Normalization of the data series.
%      normalize   - Normalization of the data.
%      nonormalize - No normalization of the data.
%
%    Suppressing the GUI.
%      gui         - Creates the GUI.
%      nogui       - Suppresses the GUI.
%      silent      - Suppresses all output.
%
%    Parameters not needed to be specified.
%
%    Output:
%      Y(:, 1) = RR     (recurrence rate)
%      Y(:, 2) = DET    (determinism)
%      Y(:, 3) = <L>    (mean diagonal line length)
%      Y(:, 4) = Lmax   (maximal diagonal line length)
%      Y(:, 5) = ENTR   (entropy of the diagonal line lengths)
%      Y(:, 6) = LAM    (laminarity)
%      Y(:, 7) = TT     (trapping time)
%      Y(:, 8) = Vmax   (maximal vertical line length)
%      Y(:, 9) = T1     (recurrence time of 1st type)
%      Y(:,10) = T2     (recurrence time of 2nd type)
%      Y(:,11) = RTE    (recurrence time entropy, i.e., RPDE)
%      Y(:,12) = Clust  (clustering coefficient)
%      Y(:,13) = Trans  (transitivity)
%
%    The window of length w is applied on the data and not on the RP, 
%    i.e. the RP will have smaller size than the window, thus w-(m-1)*tau. 
%    If we consider the data window at time i ... i+w, the corresponding RQA 
%    measures are assigned to time i. Therefore, if you see a beginning 
%    of a transition in the plot of the RQA measures at time i, this 
%    transition will probably happen at time i+w-(m-1)*tau. 
%
%    Warning:
%    The RQA measures may differ from those of the RQA programmes by
%    Charles Webber Jr. For compatibility use a Theiler window of
%    size one and ensure that the data are normalized before by the
%    same distance which is used in the RQA programmes; e.g. normalize
%    with the maximal phase space diameter, which can be estimated 
%    with the programme PSS:
%
%      RQA = crqa(100*x/pss(x,dim,lag,'euclidean'),...
%               dim,lag,e,[],[],l_min,v_min,1,...
%               'euclidean','nonormalize','silent')
%
%    Examples: a = randn(300,1);
%              crqa(a,1,1,.2,40,2,'euc')
%
%              N = 500; w = 40; ws = 2;
%              a = 3.4:.6/(N-1):4;
%              b = .5; for i = 2:N, b(i) = a(i)*b(i-1)*(1-b(i-1)); end
%              y = crqa(b,3,2,.1,w,ws);
%              subplot(2,1,1), plot(a,b,'.','markersize',.1)
%              title('logistic map'), axis([3.4 4 0 1])
%              subplot(2,1,2), plot(a(1:ws:N-w),y(1:ws:N-w,1))
%              ylabel('recurrence rate'), axis([3.4 4 0 1])
%
%      
%    See also CRQAD, CRQAD_BIG, CRP, CRP2, CRP_BIG, DL, TT, PSS.
%
%    References: 
%    Marwan, N., Romano, M. C., Thiel, M., Kurths, J.: 
%    Recurrence Plots for the Analysis of Complex Systems, 
%    Phys. Rep., 438, 2007.
%
%    Little, M., McSharry, P., Roberts, S., Costello, D., Moroz, I.:
%    Exploiting Nonlinear Recurrence and Fractal Scaling Properties 
%    for Voice Disorder Detection, Biomed. Eng. Online, 6, 2007.
%
%    Boccaletti, S., Latora, V., Moreno, Y., Chavez, M., Hwang, D.-U.:
%    Complex networks: Structures and dynamics,
%    Phys. Rep., 424, 2006.
%
%    Marwan, N., Donges, J. F., Zou, Y., Donner, R. V., Kurths, J.: 
%    Complex network approach for recurrence analysis of time series, 
%    Phys. Lett. A, 373(46), 2009. 

% Copyright (c) 2008-2009
% Norbert Marwan, Potsdam Institute for Climate Impact Research, Germany
% http://www.pik-potsdam.de
%
% Copyright (c) 1998-2008
% Norbert Marwan, Potsdam University, Germany
% http://www.agnld.uni-potsdam.de
%
% $Date$
% $Revision$
%
% $Log$
% Revision 5.50  2014/09/23 07:11:25  marwan
% Matlab R2014b incompatibility issues fixed
%
% Revision 5.49  2014/01/07 15:41:16  marwan
% bug in windowing approach when using window length = data length fixed
%
% Revision 5.48  2014/01/07 07:55:29  marwan
% corrected output length, RQA measures of last window added
%
% Revision 5.47  2013/08/22 06:35:01  marwan
% bugfix in estimation black and white vertical lines
%
% Revision 5.46  2013/08/21 09:09:59  marwan
% bugfix for mixed output RTE and T2
% bugfix for recurrence time estimation
%
% Revision 5.45  2012/11/14 13:07:03  marwan
% bugfix for RTE for very short time series
%
% Revision 5.44  2010/09/09 10:40:01  marwan
% bugfix in cross version for calculation of network measures
%
% Revision 5.43  2010/08/27 11:16:31  marwan
% fix output of network measures
%
% Revision 5.42  2010/07/07 08:26:30  marwan
% updated references
% bug in mean clustering coefficient
%
% Revision 5.41  2010/06/30 12:01:53  marwan
% RPDE, Clustering and Transitivity added
%
% Revision 5.40  2010/06/29 12:48:56  marwan
% better debugging performance if error occurs
%
% Revision 5.39  2010/01/06 08:58:59  marwan
% adding pdist as an alternative to get the RP
%
% Revision 5.38  2009/05/14 16:20:32  marwan
% automatic window length determination restored back
% further argument checking (extreme embedding) added
%
% Revision 5.37  2009/03/31 12:28:26  marwan
% automatic window length determination corrected
%
% Revision 5.36  2009/03/24 08:35:00  marwan
% corrected DET calculation when using Theiler window
%
% Revision 5.35  2008/03/05 17:43:08  marwan