This page was created by the IDL library routine `mk_html_help2`.

Last modified: Fri Jun 8 01:15:11 2007.

# Directory Listing of Routines

# ssl_general/davin/tools/tplot/wvlt

- WAV_DATA
- WAVE_SIGNIF
- WAVELET
- WAVETEST

# Routine Descriptions

## WAVELET

[Next Routine] [List of Routines]

     NAME:   WAVELET

     PURPOSE:   Compute the WAVELET transform of a 1D time series.

     CALLING SEQUENCE:

          wave = WAVELET(Y,DT)

     INPUTS:

        Y = the time series of length N.

        DT = amount of time between each Y value, i.e. the sampling time.

     OUTPUTS:

        WAVE is the WAVELET transform of Y. This is a complex array
        of dimensions (N,J+1). FLOAT(WAVE) gives the WAVELET amplitude,
        ATAN(IMAGINARY(WAVE),FLOAT(WAVE)) gives the WAVELET phase.
        The WAVELET power spectrum is ABS(WAVE)^2.

     OPTIONAL KEYWORD INPUTS:

        S0 = the smallest scale of the wavelet.  Default is 2*DT.

        DJ = the spacing between discrete scales. Default is 0.125.
             A smaller # will give better scale resolution, but be slower to plot.

        J = the # of scales minus one. Scales range from S0 up to S0*2^(J*DJ),
            to give a total of (J+1) scales. Default is J = (LOG2(N DT/S0))/DJ.

        MOTHER = A string giving the mother wavelet to use.
                Currently, 'Morlet','Paul','DOG' (derivative of Gaussian)
                are available. Default is 'Morlet'.

        PARAM = optional mother wavelet parameter.
                For 'Morlet' this is k0 (wavenumber), default is 6.
                For 'Paul' this is m (order), default is 4.
                For 'DOG' this is m (m-th derivative), default is 2.

        PAD = if set, then pad the time series with enough zeroes to get
             N up to the next higher power of 2. This prevents wraparound
             from the end of the time series to the beginning, and also
             speeds up the FFT's used to do the wavelet transform.
             This will not eliminate all edge effects (see COI below).

        LAG1 = LAG 1 Autocorrelation, used for SIGNIF levels. Default is 0.0

        SIGLVL = significance level to use. Default is 0.95

        VERBOSE = if set, then print out info for each analyzed scale.

        RECON = if set, then reconstruct the time series, and store in Y.
                Note that this will destroy the original time series,
                so be sure to input a dummy copy of Y.

        FFT_THEOR = theoretical background spectrum as a function of
                    Fourier frequency. This will be smoothed by the
                    wavelet function and returned as a function of PERIOD.

     OPTIONAL KEYWORD OUTPUTS:

        PERIOD = the vector of "Fourier" periods (in time units) that corresponds
               to the SCALEs.

        SCALE = the vector of scale indices, given by S0*2^(j*DJ), j=0...J
                where J+1 is the total # of scales.

        COI = if specified, then return the Cone-of-Influence, which is a vector
            of N points that contains the maximum period of useful information
            at that particular time.
            Periods greater than this are subject to edge effects.
            This can be used to plot COI lines on a contour plot by doing:
                IDL>  CONTOUR,wavelet,time,period
                IDL>  PLOTS,time,coi,NOCLIP=0

        YPAD = returns the padded time series that was actually used in the
             wavelet transform.

        DAUGHTER = if initially set to 1, then return the daughter wavelets.
             This is a complex array of the same size as WAVELET. At each scale
             the daughter wavelet is located in the center of the array.

        SIGNIF = output significance levels as a function of PERIOD

        FFT_THEOR = output theoretical background spectrum (smoothed by the
                    wavelet function), as a function of PERIOD.

     [ Defunct INPUTS:
     [   OCT = the # of octaves to analyze over.           ]
     [         Largest scale will be S0*2^OCT.             ]
     [         Default is (LOG2(N) - 1).                   ]
     [   VOICE = # of voices in each octave. Default is 8. ]
     [          Higher # gives better scale resolution,    ]
     [          but is slower to plot.                     ]
     ]

(See ssl_general/davin/tools/tplot/wvlt/wavelet.pro)

## WAVETEST

[Previous Routine] [Next Routine] [List of Routines]

     NAME:   WAVETEST

     PURPOSE:   Example IDL program for WAVELET, using NINO3 SST dataset

     EXECUTION:

                IDL> .run wavetest

     See "http://paos.colorado.edu/research/wavelets/"
     Written January 1998 by C. Torrence

(See ssl_general/davin/tools/tplot/wvlt/wavetest.pro)

## WAVE_SIGNIF

[Previous Routine] [Next Routine] [List of Routines]

     NAME:   WAVE_SIGNIF

     PURPOSE:   Compute the significance levels for a wavelet transform.

     CALLING SEQUENCE:

          result = WAVE_SIGNIF(y,dt,scale,sigtest)

     INPUTS:

        Y = the time series, or, the VARIANCE of the time series.
            (If this is a single number, it is assumed to be the variance...)

        DT = amount of time between each Y value, i.e. the sampling time.

        SCALE = the vector of scale indices, from previous call to WAVELET.

        SIGTEST = 0, 1, or 2.    If omitted, then assume 0.

              If 0 (the default), then just do a regular chi-square test,
           		 i.e. Eqn (18) from Torrence & Compo.
              If 1, then do a "time-average" test, i.e. Eqn (23).
           		 In this case, DOF should be set to NA, the number
           		 of local wavelet spectra that were averaged together.
           		 For the Global Wavelet Spectrum, this would be NA=N,
           		 where N is the number of points in your time series.
              If 2, then do a "scale-average" test, i.e. Eqns (25)-(28).
           		 In this case, DOF should be set to a
           		 two-element vector [S1,S2], which gives the scale
           		 range that was averaged together.
           		 e.g. if one scale-averaged scales between 2 and 8,
                         then DOF=[2,8].

     OUTPUTS:

        result = significance levels as a function of SCALE,
                 or if /CONFIDENCE, then confidence intervals

     OPTIONAL KEYWORD INPUTS:

        MOTHER = A string giving the mother wavelet to use.
                Currently, 'Morlet','Paul','DOG' (derivative of Gaussian)
                are available. Default is 'Morlet'.

        PARAM = optional mother wavelet parameter.
                For 'Morlet' this is k0 (wavenumber), default is 6.
                For 'Paul' this is m (order), default is 4.
                For 'DOG' this is m (m-th derivative), default is 2.

        LAG1 = LAG 1 Autocorrelation, used for SIGNIF levels. Default is 0.0

        SIGLVL = significance level to use. Default is 0.95

        DOF = degrees-of-freedom for signif test.
              IF SIGTEST=0, then (automatically) DOF = 2 (or 1 for MOTHER='DOG')
              IF SIGTEST=1, then DOF = NA, the number of times averaged together.
              IF SIGTEST=2, then DOF = [S1,S2], the range of scales averaged.

       	 Note: IF SIGTEST=1, then DOF can be a vector (same length as SCALEs),
       		   in which case NA is assumed to vary with SCALE.
       		   This allows one to average different numbers of times
       		   together at different scales, or to take into account
       		   things like the Cone of Influence.
       		   See discussion following Eqn (23) in Torrence & Compo.

        GWS = global wavelet spectrum. If input then this is used
              as the theoretical background spectrum,
              rather than white or red noise.

        CONFIDENCE = if set, then return a Confidence INTERVAL.
                     For SIGTEST=0,2 this will be two numbers, the lower & upper.
                     For SIGTEST=1, this will return an array (J+1)x2,
                     where J+1 is the number of scales.

     OPTIONAL KEYWORD OUTPUTS:

        PERIOD = the vector of "Fourier" periods (in time units) that corresponds
               to the SCALEs.

        FFT_THEOR = output theoretical red-noise spectrum as fn of PERIOD.

(See ssl_general/davin/tools/tplot/wvlt/wave_signif.pro)

## WAV_DATA

[Previous Routine] [List of Routines]

      Procedure:  wav_data,'name'
      Purpose:  computes the wavelet transform of tplot variables.
      Author: Davin Larson

(See ssl_general/davin/tools/tplot/wvlt/wav_data.pro)