RIDGEWALK is the jRidges module of jLab.

  RIDGEWALK  Extract wavelet transform ridges, including bias estimates. 
 
    [IR,JR,WR,FR]=RIDGEWALK(W,FS) where W is a wavelet transform matrix
    at frequecies FS, such as that returned by MORSEWAVE, returns the 
    wavelet ridges of transform W.
 
    The columns of W correspond to different frequencies, specified by the
    frequency array FS, at which the wavelet transform was performed.  Note
    that FS assumes a unit sample rate.  
 
    The frequencies FS are expected to be ordered from highest to lowest.  
 
    RIDGEWALK returns the following quantities along ridges
 
        IR     Ridge indices into rows of W (time) 
        JR     Ridge indices into columns of W (scale) 
        WR     Wavelet transfrom value along the ridge
        FR     Transform frequency values in radian frequency
 
    All output variables are column vectors with the ridges appended one
    atop the next, separated by a NaN.  Use COL2CELL(IR,JR,WR,FR) to 
    convert these concatenated column vectors into cell arrays.
 
    RIDGEWALK(DT,W,FS,...) 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.
    _______________________________________________________________________
 
    Masked-out regions
 
    RIDGEWALK permits the use to explicitly specify time-frequency regions 
    which should be excluded from the ridge analyis.
 
    RIDGEWALK(...,W,FS,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 options
 
    RIDGEWALK has other contingencies for rejecting spurious ridge points.
    These tend to occur on the flanks of interesting signals, and 
    reflect the wavelet structure rather than the signal structure.
 
    RIDGEWALK(...,{L,CHI}) specifies options for the ridge computation.
 
         L  -- Removes all ridges of less than L periods in length
       CHI  -- Removes all small amplitude ridge points having |W| 2*P/pi, with P 
    described shortly. This criterion means that the ridge must be longer
    than the number of oscillations in the central envelope of the wavelet.
 
    Here P is a quantity that characterizes the number of oscillations in a
    wavelet.  For the generalized Morse wavelets calculated by MORSEWAVE, 
    P is given by P=SQRT(BETA*GAMMA), see Lilly and Olhede (2009).
 
    The options cell may also include some additional parameters for hidden
    options that are used during testing. These should not be required by
    most users, but are documented in the function body for completeness.
    _______________________________________________________________________  
 
    Time-dependent frequency range
 
    The ridge curves may be limited to a time-varying frequency range.
 
    RIDGEWALK(DT,...,{FMAX,FMIN,L,CHI}) additionally specifies a maximum 
    frequency FMAX and minumum frequency FMIN for the ridges.  Only ridge
    points between these two frequencies are returned.
 
    FMAX and FMIN are both *radian* frequencies per unit time as specified
    by DT. DT is optional and its default value is unity.  Thus FMAX and 
    FMIN are directly comparable to the ridge frequency FR. 
    
    Both FMAX and FMIN are either scalars, or arrays the same length as W. 
    _______________________________________________________________________
 
    Output of bias parameters
 
    [IR,JR,WR,FR,BR,CR]=RIDGEWALK(...) optionally outputs two additional
    quantities along the ridges.
 
        BR     Instantaneous bandwidth  
        CR     Instantaneous curvature  
 
    When these 'bias parameters' BR and CR are small compared with the
    frequency, i.e. BR/FR << 1 and CR/(FR^2) << 1, then the signal is 
    accurately estimated, as discussed in 
 
       Lilly and Olhede (2010), On the analytic wavelet transform. 
            IEEE Trans. Info. Theory, 56 (8), 4135--4156.
 
    For more details, see INSTMOM.
    _______________________________________________________________________
 
    Joint ridges
 
    [IR,JR,WR,FR]=RIDGEWALK(W1,W2,...,WN,FS) finds the joint ridges of N 
    transforms that all have the same size.  
 
    In this case, there is only one set of ridges but N different values.
    IR and JR are still column vectors, but WR and FR are now arrays with N 
    columns, again with different ridges separated by NaNs. 
 
    For details on joint ridges, see
 
       Lilly and Olhede (2012), Analysis of Modulated Multivariate 
            Oscillations. IEEE Trans. Sig. Proc., 60 (2), 600--612.
    _______________________________________________________________________
    
    Bias parameters for joint ridges
 
    [IR,JR,WR,FR,BR,CR]=RIDGEWALK(W1,W2,...,WN,FS) for the case of joint
    ridges similarly outputs the two bias parameters along the ridges BR 
    and CR, which are the same size as WR and FR
 
    BR and CR are normalized versions of (17) and (18) of Lilly and Olhede 
    (2012). Both BR and CR have been normalized by dividing them by the 
    modulus of the estimated analytic signal, SQRT(SUM(ABS(WR).^2,2)).   
 
    The bias associated with the estimated signal is small compared to the 
    magnitude of the signal when the modulus of XCR is small.
 
    For more details on the bias parameters for multivariate signals see 
    Lilly and Olhede (2012).
    _______________________________________________________________________
 
    Cell array input / output 
 
    RIDGEWALK also works if the input transforms W1,W2,...WN are all cell
    arrays of transforms, say of length K.  In this case, all output 
    variables are also cell arrays of length K.
 
    In this case, DT, FMIN, and FMAX may all either be scalars or numeric
    arrays of length K.  FS may either be a numeric array, or a length K 
    cell array of numeric arrays.
 
    This is just a convenient way of organizing the ridges for multiple 
    input time series.
    ___________________________________________________________________
 
    Parallelization
 
    RIDGEWALK(...,'parallel'), when cell arrays are input, parallelizes the
    ridge computation using a PARFOR loop over the different time series.
    This requires that Matlab's Parallel Computing Toolbox be installed. 
    _______________________________________________________________________
 
    Interscale interpolation
    
    RIDGEWALK interpolates among discrete scale levels to yield more
    accurate values for the ridge quantities WR and FR using a fast
    quadratic interpolation.  
    
    See the low-level functions RIDGEINTERP and QUADINTERP for details.
    _______________________________________________________________________
 
    See also WAVETRANS, RIDGEMAP.
 
    'ridgewalk --t' runs a test.
    'ridgewalk --f' generates a sample figure.
 
    Usage: [ir,jr,wr,fr]=ridgewalk(w,fs);
           [ir,jr,wr,fr]=ridgewalk(w,fs,{L,CHI});
           [ir,jr,wr,fr]=ridgewalk(dt,w,fs,{L,CHI});
           [ir,jr,wr,fr]=ridgewalk(dt,wx,wy,fs,{L,CHI});
           [ir,jr,wr,fr,br,cr]=ridgewalk(dt,wx,wy,fs,{L,CHI});
           [ir,jr,wr,fr]=ridgewalk(dt,w,fs,bool,{L,CHI});
    _______________________________________________________________________
    This is part of JLAB --- type 'help jlab' for more information
    (C) 2004--2016 J.M. Lilly --- type 'help jlab_license' for details

contents | allhelp | index