RIDGEWALK is the jRidges module of jLab.

  RIDGEWALK  Extract wavelet transform ridges, including bias estimates. 
 
    [WR,IR,JR,OMEGA]=RIDGEWALK(W,FS) where W is a wavelet transform matrix 
    computed at frequecies FS, returns the wavelet ridges of transform W.
 
    See WAVETRANS for details on the transform matrix W and frequencies FS.
 
    RIDGEWALK returns the following quantities along ridges
 
        WR       Wavelet transfrom value along the ridge
        IR       Ridge indices into rows of W (time) 
        JR       Ridge indices into columns of W (scale) 
        OMEGA    Instantaneous frequency along the ridge
 
    All output variables are column vectors with the ridges appended one
    atop the next, separated by a NaN.  Use COL2CELL(WR,IR,JR,OMEGA) to 
    convert these concatenated column vectors into cell arrays, or else
    COL2MAT(WR,IR,JR,OMEGA) to convert them into matrices.  
 
    The minimum length of any ridge is two data points. 
 
    The wavelet transform along the ridge, WR, estimates the analytic part 
    of modulated oscillations present in original time series.  
 
    RIDGEWALK(DT,...) uses a sample rate DT to compute the ridge frequency
    FR.  The default value of DT is unity.  This does not affect the 
    specification of FS, which is given in terms of a unit sample rate.
    _______________________________________________________________________
 
    Joint ridges
 
    [W1R,W2R,...,WNR,IR,JR,OMEGA]=RIDGEWALK(W1,W2,...,WN,FS) finds the 
    joint ridges of N transforms that all have the same size.  All output
    fields remain column vectors.
 
    In this case, there is only one set of ridges but N different transform
    values. FR is then called the joint instantaneous frequency.
 
    For details on joint ridges, see
 
       Lilly and Olhede (2012), Analysis of Modulated Multivariate 
            Oscillations. IEEE Trans. Sig. Proc., 60 (2), 600--612.
    _______________________________________________________________________
 
    Error estimate
 
    [...,OMEGA,CHI]=RIDGEWALK(...,FS,P), where P=SQRT(BETA*GAMMA) 
    characterizes the Morse wavelet used to form the wavelet transform, 
    also returns an error estimate CHI along the ridges.
 
    CHI measures the error with which the transforms estimate the analytic 
    signals of modulated oscillations, arising from bias due to the 
    modulation strength.  CHI<<1 for signals that are accurately estimated. 
 
    This works for either univariate ridges or for the joint ridges.
 
    CHI is defined as the right-hand side of Eqn. (62) of Lilly and Olhede 
    (2012), "Analysis of modulated multivariate oscillations."  It is a
    normalized version of a quantity known as the instantaneous curvature. 
    _______________________________________________________________________  
 
    Artifact removal
    
    RIDGEWALK has several features to minimize artifacts.
 
    RIDGEWALK(...,FS,P,M) removes all ridges less than M*(2P/pi) periods in 
    length. Since the number of periods in a generalized Morse wavelet is 
    about 2P/pi, M gives the minimum number of wavelet lengths in a ridge.
 
    To avoid spurious ridges due to the ridge analysis essentially seeing
    the wavelet, one should definitely choose M>=1/2 and generally M>=1.
    Experiments in noise show a big jump in ridge occurences below M=1/2. 
 
    RIDGEWALK(...,FS,P,M,RHO) applies RIDGETRIM at level RHO, removing 
    RHO*(P/pi) oscillations from the beginning and end of each ridge,
    as these are generally contaminated by edge effects.  
   
    A choice of RHO=1 is recommended, or one wavelet half-width. 
 
    RIDGETRIM is applied after the pruning set by M.  The shortest possible
    ridge is then roughly (M-RHO)*(2P/pi).  Thus if the ridge trimming is 
    applied, M will only have a net effect if it is greater than RHO.
    _______________________________________________________________________  
 
    Time-dependent frequency range
 
    RIDGEWALK(...,[FMAX,FMIN]) specifies a maximum frequency and minumum
    frequency FMAX and FMIN for the ridges.  These may be either scalars or
    column vectors with the same number of rows as W.  Only ridge points 
    between these two frequencies are used for the ridges.
 
    FMAX and FMIN are both *radian* frequencies per unit time as specified
    by DT, and thus have the same units as the ridge frequency FR. 
    _______________________________________________________________________
 
    Masked-out regions
 
    RIDGEWALK permits the use to explicitly specify time-frequency regions 
    which should be excluded from the ridge analyis.
 
    RIDGEWALK(...,'mask',BOOL), where BOOL is a boolean array of the same
    size as W, then those points for which BOOL is false will be excluded 
    from the ridge analysis. In addition, ridges are not permitted to cross
    such regions, to prevent spurious chaining between distant frequencies.
 
    This functionality is useful if we have ancillary information, such as
    a local signal-to-noise estimate, that can help determine a priori
    which time-frequency points appear to be statistically significant. 
    _______________________________________________________________________
 
    Additional output arguments
 
    [...,OMEGA,CHI,DEV1,DEV2]=RIDGEWALK(...,FS,P,...) additionally outputs 
    the first and second order deviations DEV1 and DEV2 along ridges.
    These are *arrays* with one column per input transform and defined in 
    Eqns. (17) and (18) of Lilly and Olhede (2012). 
 
    The normalized magnitudes of the deviation vectors give generalizations
    of the instantaeous bandwidth and instantaneous curvature, 
    respectively, see Eqn. (19) of Lilly and Olhede (2012). 
    _______________________________________________________________________  
 
    See also WAVETRANS, RIDGEMAP, RIDGETRIM.
 
    'ridgewalk --t' runs a test.
    'ridgewalk --f' generates a sample figure.
 
    Usage: [wr,ir,jr,omega,chi,dev1,dev2]=ridgewalk(w,fs,P);
           [wr,ir,jr,omega,chi,dev1,dev2]=ridgewalk(w,fs,P,M);
           [wr,ir,jr,omega,chi,dev1,dev2]=ridgewalk(dt,w,fs,P,M);
           [wxr,wyr,ir,jr,omega,chi,dev1,dev2]=ridgewalk(dt,wx,wy,fs,P,M);
           [wxr,wyr,ir,jr,omega,chi,dev1,dev2]=ridgewalk(dt,wx,wy,fs,P,M);
           [wxr,wyr,ir,jr,omega,chi,dev1,dev2]...
                                          =ridgewalk(dt,wx,wy,fs,P,M,rho);
    _______________________________________________________________________
    This is part of JLAB --- type 'help jlab' for more information
    (C) 2004--2020 J.M. Lilly --- type 'help jlab_license' for details

contents | allhelp | index