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