pyrfu.pyrf.wavepolarize_means#

pyrfu.pyrf.wavepolarize_means(b_wave, b_bgd, min_psd: float = 1e-25, nop_fft: int = 256)[source]#

Analysis the polarization of magnetic wave using “means” method

Parameters:

  • b_wave (xarray.DataArray) – Time series of the magnetic field from Search Coil Magnetometer (SCM).

  • b_bgd (xarray.DataArray) – Time series of the magnetic field from Flux Gate Magnetometer (FGM).

  • min_psd (float, Optional) – Threshold for the analysis (e.g 1.0e-7). Below this value, the SVD analysis is meaningless if min_psd is not given, SVD analysis will be done for all waves. Default min_psd = 1e-25.

  • nop_fft (int, Optional) – Number of points in FFT. Default is 256.

Returns:

  • b_psd (xarray.DataArray) – Power spectrum density of magnetic filed wave [nT^2 Hz^-1 for B in nT].

  • wave_angle (xarray.DataArray) – Spectrogram of the wave normal angle in degrees (form 0 to 90)

  • deg_pol (xarray.DataArray) – Spectrogram of the degree of polarization (form 0 to 1).

  • ellipticity (xarray.DataArray) – Spectrogram of the ellipticity (form -1 to 1)

  • helicity (xarray.DataArray) – Spectrogram of the helicity (form -1 to 1)

Notes

Port of irf_wavepolarize_means.m (H. Fu), with the following differences: the FFT windows advance by half a window (irfu-matlab shifts the data and the window start, so that the windows advance by a full window and wrap around the end of the data), all the full windows are used, the time tags are at the window centres, and the frequencies are those of the FFT bins (irfu-matlab labels bin k with frequency k instead of k - 1 times the bin width). The rotation angles of the state vectors use a two-argument arctangent, as in the original IDL wavpol (irfu-matlab uses a one-argument arctangent, which is wrong when the denominator is negative), and the window and frequency smoothing are those of IDL and pyspedas wavpol, with which the results agree to rounding.

b_wave and b_bgd should be from the same satellite and in the same coordinates

Warning

If one component is an order of magnitude or more greater than the other two then the polarization results saturate and erroneously indicate high degrees of polarization 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 polarization results. For meaningful results there should be significant wave power at the frequency where the polarization approaches 100%. Remember comparing two straight lines yields 100% polarization.

Examples

>>> from pyrfu import pyrf
>>> polarization = pyrf.wavepolarize_means(b_wave, b_bgd)
>>> polarization = pyrf.wavepolarize_means(b_wave, b_bgd, 1.0e-7)
>>> polarization = pyrf.wavepolarize_means(b_wave, b_bgd, 1.0e-7, 256)