This page was created by the IDL library routine
mk_html_help2.
Last modified: Thu Aug 6 12:53:14 2020.
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/tags/spedas_4_0/general/science/wavpol/twavpol.pro $
(See general/science/wavpol/twavpol.pro)
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
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%. 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/tags/spedas_4_0/general/science/wavpol/wavpol.pro $
(See general/science/wavpol/wavpol.pro)