EDDYRIDGES is the jOceans module of jLab.

 EDDYRIDGES  Coherent eddy ridges from Lagrangian trajectories.
    EDDYRIDGES extracts eddy-like displacement signals from a float or 
    drifter position record using wavelet ridge analysis. 
    By default, EDDYRIDGES analyzes Lagrangian trajectories on the earth, 
    or from an earth-like model.  For analsis of trajectories in Cartesian
    model domains, see the 'Cartesian domains' section below.
    extraction algorithm and returns the results in a data structure,
    described below.
    The input arguments are as follows:
       NUM     Date in Matlab's DATENUM format 
       LAT     Latitude record of float
       LON     Longitude record of float
       FMAX    Maximum ratio of frequency to Coriolis frequency
       FMIN    Minimum ratio of frequency to Coriolis frequency
       P       Wavelet duration, P>=1 
       M       Ridge length cutoff in units of wavelet length 2P/pi
       RHO     Ridge trimming factor, removing RHO*P/pi from each end
    NUM, LAT, and LON are all column vectors of the same length, or cell 
    arrays of column vectors, while the other arguments are all scalars.  
    FMAX, FMIN, P, M, and RHO are parameters controlling the ridge
    analysis, described in more detail next.
    Analysis parameters
    EDDYRIDGES works by calling RIDGEWALK to determine time/frequency
    curves called "ridges" that are composed of special points, "ridge
    points", that identify modulated oscillations such as the signal of a
    coherent eddy.  RIDGEWALK in turn is based on a wavelet transform. 
    FMAX and FMIN define the frequency band for the ridge analysis, P 
    controls the wavelet used, and L and R are length and amplitude cutoffs
    applied during the ridge analysis to minimize spurious features.
    Frequency range: FMAX and FMIN
    FMAX and FMIN define a moving band of frequencies with respect to the
    local Coriolis frequency.  Both of these are positive numbers, with 1
    being the Corilios frequency.  Ridge point lying outside this band are
    rejected.  A typical choice of eddy band would be FMIN=1/32, FMAX=1/2.
    Wavelet duration: P
    The wavelet duration P controls the degree of time localization.  The 
    number of oscillations contained within the wavelet is roughly 2P/pi,
    so frequency resolution increases as P increases.  P should be greater
    than about SQRT(3). 
    Ridge length: M
    M sets the minimum length for a ridge, in units of the approximate 
    number of oscillations spanned by the wavelet, 2P/pi.  Thus the ridge
    must contain about M times as many oscillations as the wavelet.  The 
    ridges become more statistically significant as M increases.
    Ridge trimming: RHO
    After the ridge length criterion is applied, RHO*(2/pi) oscillations,
    corresponding to one wavelet half-width, are removed from each end of
    the ridge, as these are generally contaminated by edge effects.  The 
    choice RHO=1/2 is recommended.  Note the minium ridge length will then 
    be (M-RHO)*2P/pi. See RIDGETRIM for details.  
    The following parameter are output as fields of the structure STRUCT. 
    Type 'use struct' (using the actual name of the structure) to put these
    fields into named variables in the workspace. 
       Signal fields:
       NUM       Date in Matlab's DATENUM format along each ridge
       LAT       Latitude along each ridge
       LON       Longitude along each ridge
       LATRES    Latitude residual after subtracting eddy signal
       LONRES    Longitude residual after subtracting eddy signal
       ZHAT      Estimated eddy displacement XHAT+iYHAT, in kilometers     
       Ellipse fields:
       KAPPA     Ellipse amplitude SQRT((A^2+B^2)/2), in kilometers 
       XI        Ellipse circularity 2AB/(A^2+B^2), nondimensional
       THETA     Ellipse orientation, in radians
       PHI       Ellipse orbital phase, in radians
       OMEGA     Ellipse instantaneous frequency, in radians/day 
       UPSILON   Ellipse instantaneous bandwidth, in radians/day
       CHI       Ellipse normalized instantaneous curvature, nondimensional
       R         Ellipse geometric mean radius, in kilometers
       V         Ellipse kinetic energy velocity, in cm/s
       RO        Ellipse Rossby number, nondimensional
       Ridge fields:
       IR      Indices into rows of wavelet transform (time) 
       JR      Indices into columns of wavelet transform (scale) 
       KR      Indices into data columns or cells (time series number)
       LEN      Ridge length in number of complete periods
       PARAMS  Sub-structure of internal parameters used in the analysis
    PARAMS is a structure that contains the parameter values of FMAX, FMIN,
    P, M, RHO, GAMMA, BETA, and FS used in the analysis.  BETA is an array
    of length LENGTH(NUM), FS is a cell array of that length, and the other
    elements of PARAMS are all scalars. 
    Apart from PARAMS, all other output fields are cell arrays of column 
    with one ridge per cell.  
    Note that XI and V are signed quantities that are positive for
    counterclockwise rotation and negative for counterclockwise rotation, 
    while RO is a signed quantity that is positive for cyclonic and 
    negative for anticyclonic rotations.
    If more than one time series is input, the ridge field KR provides an
    index into the original column. To find all cells associated with the
    5th time series, for instance, use the index FIND(CELLFIRST(KR)==5).
    If you want the ridges to be separated for each input signal, call 
    EDDYRIDGES with an external loop.
    Cartesian domains
    EDDYRIDGES can also be used to analyze trajectories from idealized 
    model domains, which are better represented in Cartesian coordinates
    rather than latitude and longitude. 
    extraction on data with positions given in Cartesian coordinates.
    The first three input arguments have changed from the planetary case:
       F      Coriolis frequency of the model domain, in radians per second
       NUM    Time in days along each float trajectory
       Z      Complex-valued float location X+iY, in kilometers
    F must be a scalar, with LENGTH(F)=1, in order for EDDYRIDGES to know
    that the Cartesian algorithm is intended.  F is used to calculate the
    frequency range for the ridge analysis, and for the eddy Rossby number.  
    Note that for definiteness, EDDYRIDGES requires that the model fields 
    are expressed in particular physical units.
    EDDYRIDGES(F,FBETA,NUM,...) accounts for variations of the Coriolis
    frequency due to the beta effect in calculating the ridge frequency
    range.  FBETA is a scalar with units of radians per meter per second.
    The output arguments are then all the same, *except* for the signal 
    fields, which become
       Signal fields:
       NUM     Time in days along each ridge
       Z       Complex-valued float location X+iY, in kilometers
       ZRES    Residual after subtracting eddy XRES+iYRES, in kilometers
       ZHAT    Estimated eddy displacement XHAT+iYHAT, in kilometers     
    Only the signal fields changed.  All of the ellipse fields and ridge
    fields are the same as in the planetary case.  
    The values of F and BETA used are included in the sub-structure PARAMS.
    Algorithm variations
    By default, EDDYRIDGES uses a split-sides approach to finding the
    ridges, in which ridges dominated by positive rotations (XI>1) and
    those dominated by negative rotations (XI<1) are found separately
    and then combined; this is done using RIDGEWALK's 'mask' functionality.
    Under this approach, ridges are not permitted to change their sign of
    rotation.  This is physically realistic as particle paths in eddies are
    expected to be close to circular, with some distortion expected due
    ambient strain and other processes.  Eddies do not suddenly change
    their rotation sense from one sign to the other.  
    This algorithm has the effect of attenuating the detection of events 
    with wandering polarizations that are observed to occur regularly in 
    noise, but that are unlikely to correspond to eddies.
    For details, see 
        Lilly and Perez-Brunius (2021b), Extracting statistically 
            significant eddy signals from large Lagrangian datasets using
            wavelet ridge analysis, with application to the Gulf of Mexico.
    EDDYRIDGES(...,'nosplit') suppresses the use of this split-sides 
    algorithm, such that any polarization senses are permitted.
    Outputting the transforms
    Often it can be useful to look at the actual wavelet transforms, even
    if one does not want to output these when analyzing large datasets.  
    Therefore, if the input fields NUM, LAT, and LON contain only a single
    time series, the rotary transforms WP and WN computed internally by
    EDDYRIDGES are returned as the last two sub-fields of PARAMS.
    EDDYRIDGES(...,'parallel') parellelizes the computation by using a 
    PARFOR when looping over multiple trajectories.
    'eddyridges --t' runs a test.
    See also RIDGEWALK.
    Usage: struct=eddyridges(num,lat,lon,1/2,1/64,3,0,1);
    This is part of JLAB --- type 'help jlab' for more information
    (C) 2013--2021 J.M. Lilly --- type 'help jlab_license' for details

contents | allhelp | index