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

Last modified: Sat Sep 20 18:17:31 2025.

# Directory Listing of Routines

# general/science/wavpol

- HAMMING_WINDOW
- HANN_WINDOW
- TWAVPOL
- WAVPOL

# Routine Descriptions

## HAMMING_WINDOW

[Next Routine] [List of Routines]

     NAME: hamming_window

    PURPOSE: Return a Hamming smoothing window of order M (usually odd).

    w(n) = w = 0.54 - 0.46*cos(2 pi n/(m-1))  for 0 <= n <= m-1

    EXAMPLE: hamming_window(7,/rescale)

    CALLING SEQUENCE: hamming_window(m, /normalize)

    INPUTS:
           m: length of desired smoothing window
    ;
    Keywords:
      normalize (optional):  If set, divide by the sum of the w(n) values so the weights sum to 1.0

    OUTPUTS: M-element double precision array containing the smoothing weights

     $LastChangedBy: egrimes $
     $LastChangedDate: 2022-08-18 14:05:08 -0700 (Thu, 18 Aug 2022) $
     $LastChangedRevision: 31024 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/wavpol/wavpol.pro $

(See general/science/wavpol/hamming_window.pro)

## HANN_WINDOW

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

     NAME: hann_window

    PURPOSE: Return a Hann smoothing window of order M (usually odd).

    w(n) = w = 0.5 - 0.5*cos(2 pi n/(m-1))  for 0 <= n <= m-1

    EXAMPLE: hann_window(7,/normalize)

    CALLING SEQUENCE: hann_window(m, /normalize)

    INPUTS:
           m: length of desired smoothing window
    ;
    Keywords:
      normalize (optional):  If set, divide by the sum of the w(n) values so the weights sum to 1.0

    OUTPUTS: M-element double precision array containing the smoothing weights

     $LastChangedBy: egrimes $
     $LastChangedDate: 2022-08-18 14:05:08 -0700 (Thu, 18 Aug 2022) $
     $LastChangedRevision: 31024 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/wavpol/wavpol.pro $

(See general/science/wavpol/hann_window.pro)

## TWAVPOL

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

     NAME:twavpol

    PURPOSE:To perform polarisation analysis of three orthogonal component time
             series data, using tplot variables.

    EXAMPLE: twavpol,'in_data',prefix='in_data',freqline=fl

    INPUTS: tvarname: the name of the tplot variable upon which it will
    operate

    prefix(optional): the prefix to be assigned to the tplot variables that will be
    output, defaults to tvarname

           Subroutine assumes data are in righthanded fieldaligned
    	coordinate system with Z pointing the direction
           of the ambient magnetic field.

    Keywords:
      nopfft(optional) = Number of points in FFT

      steplength(optional) = The amount of overlap between successive FFT intervals

      bin_freq (optional): No. of bins in frequency domain

    OUTPUTS:
              error(optional): named variable in which to return the
              error state of this procedure call. 1 = success, 0 = failure

              freqline(optional): assign a named variable to this keyword
              to store the frequencies of each y-index

             timeline(optional): assign a named variable to this keyword
             to store the times of each x-index

    The program outputs five spectral results derived from the
             fourier transform of the covariance matrix (spectral matrix)
    This version stores these outputs as tplot variables with the
    specified prefix
             These are follows:

             Wave power: On a linear scale (units of nT^2/Hz if input Bx, By, Bz are in nT)

             Degree of Polarisation:
    		This is similar to a measure of coherency between the input
    		signals, however unlike coherency it is invariant under
    		coordinate transformation and can detect pure state waves
    		which may exist in one channel only.100% indicates a pure
    		state wave. Less than 70% indicates noise. For more
    		information see J. C. Samson and J. V. Olson 'Some comments
    		on the description of the polarization states
    		of waves' Geophys. J. R. Astr. Soc. (1980) v61 115-130

       Wavenormal Angle:
         The angle between the direction of minimum variance
         calculated from the complex off diagonal elements of the
         spectral matrix and the Z direction of the input ac field data.
         for magnetic field data in field aligned coordinates this is the
         wavenormal angle assuming a plane wave. See:
         Means, J. D. (1972), Use of the three-dimensional covariance
         matrix in analyzing the polarization properties of plane waves,
         J. Geophys. Res., 77(28), 5551-5559,
         doi:10.1029/JA077i028p05551.

       Ellipticity:
         The ratio (minor axis)/(major axis) of the ellipse transcribed
         by the field variations of the components transverse to the
         Z direction (Samson and Olson, 1980). The sign indicates
         the direction of rotation of the field vector in the plane (cf.
         Means, (1972)).
         Negative signs refer to left-handed rotation about the Z
         direction. In the field aligned coordinate system these signs
         refer to plasma waves of left and right handed polarization.

             Helicity:Similar to Ellipticity except defined in terms of the
    	direction of minimum variance instead of Z. Stricltly the Helicity
    	is defined in terms of the wavenormal direction or k.
    	However since from single point observations the
    	sense of k cannot be determined,  helicity here is
    	simply the ratio of the minor to major axis transverse to the
           minimum variance direction without sign.

    NOTES:
    1. Although the input is in the form of a tplot variable, the
    output is currently in the form of arrays

    2. -If one component is an order of magnitude or more  greater than
    	the other two then the polarisation results saturate and erroneously
    	indicate high degrees of polarisation at all times and
    	frequencies.

    3. Time series should be eyeballed before running the program.
    	 For time series containing very rapid changes or spikes
    	 the usual problems with Fourier analysis arise.
    	 Care should be taken in evaluating degree of polarisation results.

    4. For meaningful results there should be significant wave power at the
    	 frequency where the polarisation approaches
    	 100%. Remembercomparing two straight lines yields 100% polarisation.

     $LastChangedBy: egrimes $
     $LastChangedDate: 2018-11-15 18:20:42 -0800 (Thu, 15 Nov 2018) $
     $LastChangedRevision: 26129 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/wavpol/twavpol.pro $

(See general/science/wavpol/twavpol.pro)

## WAVPOL

[Previous Routine] [List of Routines]

     NAME:wavpol

     MODIFICATION HISTORY:Written By Chris Chaston, 30-10-96
             :Modified by Vassilis, 2001-07-11
             :Modified by Olivier Le Contel, 2008-07
                  to be able to change nopfft and steplength
             :Modified by O. Le Contel, 2016-03
                  to be able to change frequency averaging parameter by adding bin_freq keyword
             :Modified by O. Le Contel, LPP, 2016-07, in order to manage data gaps in the waveform
                  using test written by K. Bromund (in thm_cal_scm)
             :Modified by egrimes, merging OLE's changes with SPEDAS's wavpol:
                 gamma -> gammay (avoids confusion with IDL's gamma function)
                 redefined W (fixed bug reported by Justin Lee) -> W=Total(smooth^2) / double(nopfft)
                 added pspec3 input, pspec[x,y,z], returns pspec3 (changes from Justin Lee) - added to original 10/10/2013
                 converted () to [], fixed tabbing
                 updated documentation with changes from Justin Lee - added to original 9/23/2014
             :Modified by egrimes, now checking for 0s in the output time series, setting those
                 data values to NaNs
             :Modified by jwl, generate smoothing array on the fly with the correct number of bins

    PURPOSE:To perform polarisation analysis of three orthogonal component time
             series data.

    EXAMPLE: wavpol,ct,Bx,By,Bz,timeline,freqline,powspec,degpol,waveangle,elliptict,helict

    CALLING SEQUENCE: wavpol,ct,Bx,By,Bz,timeline,freqline,powspec,degpol,waveangle,elliptict,helict

    INPUTS:ct,Bx,By,Bz, are IDL arrays of the time series data; ct is cline time

           Subroutine assumes data are in righthanded fieldaligned
    	coordinate system with Z pointing the direction
           of the ambient magnetic field.

           threshold:-if this keyword is set then results for ellipticity,
           helicity and wavenormal are set to Nan if below 0.6 deg pol

    Keywords:
      nopfft (optional): Number of points in FFT

      steplength (optional): The amount of overlap between successive FFT intervals

      bin_freq (optional): No. of bins in frequency domain

    OUTPUTS: The program outputs five spectral results derived from the
             fourier transform of the covariance matrix (spectral matrix)
             These are follows:

             Wave power: On a linear scale (units of nT^2/Hz if input Bx, By, Bz are in nT)

             Degree of Polarisation:
    		This is similar to a measure of coherency between the input
    		signals, however unlike coherency it is invariant under
    		coordinate transformation and can detect pure state waves
    		which may exist in one channel only.100% indicates a pure
    		state wave. Less than 70% indicates noise. For more
    		information see J. C. Samson and J. V. Olson 'Some comments
    		on the description of the polarization states
    		of waves' Geophys. J. R. Astr. Soc. (1980) v61 115-130

             Wavenormal Angle:
         The angle between the direction of minimum variance
         calculated from the complex off diagonal elements of the
         spectral matrix and the Z direction of the input ac field data.
         for magnetic field data in field aligned coordinates this is the
         wavenormal angle assuming a plane wave. See:
         Means, J. D. (1972), Use of the three-dimensional covariance
         matrix in analyzing the polarization properties of plane waves,
         J. Geophys. Res., 77(28), 5551-5559,
         doi:10.1029/JA077i028p05551.

             Ellipticity:
         The ratio (minor axis)/(major axis) of the ellipse transcribed
         by the field variations of the components transverse to the
         Z direction (Samson and Olson, 1980). The sign indicates
         the direction of rotation of the field vector in the plane (cf.
         Means, (1972)).
         Negative signs refer to left-handed rotation about the Z
         direction. In the field aligned coordinate system these signs
         refer to plasma waves of left and right handed polarization.

             Helicity:Similar to Ellipticity except defined in terms of the
    	direction of minimum variance instead of Z. Stricltly the Helicity
    	is defined in terms of the wavenormal direction or k.
    	However since from single point observations the
    	sense of k cannot be determined,  helicity here is
    	simply the ratio of the minor to major axis transverse to the
           minimum variance direction without sign.

    RESTRICTIONS:-If one component is an order of magnitude or more  greater than
    	the other two then the polarisation results saturate and erroneously
    	indicate high degrees of polarisation at all times and
    	frequencies. Time series should be eyeballed before running the program.
    	 For time series containing very rapid changes or spikes
    	 the usual problems with Fourier analysis arise.
    	 Care should be taken in evaluating degree of polarisation results.
    	 For meaningful results there should be significant wave power at the
    	 frequency where the polarisation approaches
    	 100%. Remember, comparing two straight lines yields 100% polarisation.

     $LastChangedBy: jwl $
     $LastChangedDate: 2025-03-29 21:55:43 -0700 (Sat, 29 Mar 2025) $
     $LastChangedRevision: 33213 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/wavpol/wavpol.pro $

(See general/science/wavpol/wavpol.pro)