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

Last modified: Mon Nov 5 01:15:46 2012.

# Directory Listing of Routines

# ssl_general/science/wavpol

- TWAVPOL
- WAVPOL

# Routine Descriptions

## TWAVPOL

[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

    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, at this stage no units

             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.

             Ellipticity:The ratio (minor axis)/(major axis) of the
    		ellipse transcribed by the field variations of the
    		components transverse to the Z direction. The sign
    		indicates the direction of rotation of the field vector in
      		the plane. 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
    		polarisation.

             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: aaflores $
     $LastChangedDate: 2012-01-26 17:01:34 -0800 (Thu, 26 Jan 2012) $
     $LastChangedRevision: 9630 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/science/wavpol/twavpol.pro $

(See ssl_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
    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

    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, at this stage no units

             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.

             Ellipticity:The ratio (minor axis)/(major axis) of the
    		ellipse transcribed by the field variations of the
    		components transverse to the Z direction. The sign
    		indicates the direction of rotation of the field vector in
      		the plane. 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
    		polarisation.

             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%. Remembercomparing two straight lines yields 100% polarisation.

     $LastChangedBy: jwl $
     $LastChangedDate: 2012-09-17 10:32:23 -0700 (Mon, 17 Sep 2012) $
     $LastChangedRevision: 10921 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/science/wavpol/wavpol.pro $

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