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