Wave

polarization(S0, S1, S2, S3)
polarization(S::StokesVector)

Compute the degree of polarization (p) from Stoke parameters or a Stokes vector.

Reference

• Wikipedia
• Stokes parameters

polarization(S)

Compute the degree of polarization (DOP) p^2 from spectral matrix S.

\[\begin{aligned} p^2 &= 1-\frac{(tr 𝐒)^2-(tr 𝐒^2)}{(tr 𝐒)^2-n^{-1}(tr 𝐒)^2} \\ &= \frac{n(tr 𝐒^2)-(tr 𝐒)^2}{(n-1)(tr 𝐒)^2} \end{aligned}\]

wpol_helicity(S, waveangle)

Compute helicity and ellipticity for a single frequency.

Arguments

• S: Spectral matrix for a single frequency, size (3,3)
• waveangle: Wave normal angle for this frequency

Returns

• helicity: Average helicity across the three components
• ellipticity: Average ellipticity across the three components

spectral_matrix(Xf)

Compute the spectral matrix $S$ defined by

\[S_{ij}(f) = X_i(f) X_j^*(f),\]

where $X_i(f)$=Xf[f, i] is the FFT of the i-th component and * denotes complex conjugation.

spectral_matrix(X, window)

Compute the spectral matrix $S(f)$ given the time series data X.

Returns a 3-D array of size $N_{freq}, n, n$, where $N_{freq} = \lfloor N/2 \rfloor$ and n is the dimensionality (number of components).

Arguments

• X: Matrix where each column is a component of the multivariate time series, or a vector of vectors.
• window: A window function (optional). If not provided, a rectangular window (no windowing) is used.

twavpol(x)

A convenience wrapper around wavpol that works with DimensionalData arrays.

It automatically extracts the time dimension and returns the results as a DimStack with properly labeled dimensions.

wavpol(X, fs=1; nfft=256, noverlap=div(nfft, 2), smooth_t=_smooth_t(nfft), smooth_f=hamming(3), nbuffers=Threads.nthreads())

Perform polarization analysis of n-component time series data.

For each FFT window (with specified overlap), the routine:

1. Applies a time-domain window function and computes the FFT to construct the spectral matrix $S(f)$
2. Applies frequency smoothing using a window function
3. Computes wave parameters: power, degree of polarization, wave normal angle, ellipticity, and helicity

The analysis assumes the data are in a right-handed, field-aligned coordinate system (with Z along the ambient magnetic field).

Arguments

• X: Matrix where each column is a component of the multivariate time series
• fs: Sampling frequency (default: 1)

Keywords

• nfft: Number of points for FFT (default: 256)
• noverlap: Number of overlapping points between windows (default: nfft÷2)
• smooth_t: Time domain window function (default: Hann window)
• smooth_f: Frequency domain smoothing window (default: 3-point Hamming window)
• nbuffers: Number of pre-allocated buffers for parallel processing (default: number of threads)

Returns

A named tuple containing:

• indices: Time indices for each FFT window
• freqs: Frequency array
• power: Power spectral density, normalized by frequency bin width and window function
• degpol: Degree of polarization [0,1]
• waveangle: Wave normal angle [0,π/2]
• ellipticity: Wave ellipticity [-1,1], negative for left-hand polarized
• helicity: Wave helicity

See also: polarization, wave_normal_angle, wpol_helicity