spectral-cross-coherence

Spectral cross-coherence and cross-phase

The two-channel companion to the single-channel power-spectral-density workflow (solar-wind-turbulence-spectrum). From two scalar time series over the same interval, compute the magnitude-squared coherence C_xy(f) ∈ [0,1] (how linearly related the two channels are at each frequency) and the cross-phase ∠P_xy(f) (the phase lag between them). This is how you ask whether two signals share a common wave at frequency f, and which one leads — e.g. B_R vs B_T, B vs density (compressional vs incompressible), or the same channel on two spacecraft for propagation timing.

When to use

• "Are these two channels coherent at frequency f, and what's the phase lag?"
• "Is this fluctuation compressional?" — coherence/phase between |B| and density.
• Wave-mode / propagation: phase lag between two components, or the same field on two spacecraft.

Tool chain (existing tools only)

create_spedas_analysis_bundle → load_data_source → browse_data_parameters → fetch_data_product (×2, or one multi-component fetch + derive the two scalars) → local scipy coherence/csd on a common uniform time grid → write per-panel .npz → render_tplot. There is no dedicated pyspedas coherence tool — the spectral step is a small local computation, the same pattern as the local PSD step in the turbulence skill.

Backend (VERIFIED contract)

There is no MCP/pyspedas cross-coherence tool; you compute it locally with scipy and persist .npz artifacts. The verified numeric contract:

• Input is a state array, not a stored tplot var: scipy works on plain in-memory ndarrays x, y that you have already loaded from the fetched files and resampled to one common uniform time grid. Coherence requires identical sampling — same fs, same length, sample-aligned — so both channels must be interpolated onto the same numeric Unix-second grid before this step. There is no tplot variable and no dict/tuple handed back by a tool here.
• scipy.signal.coherence(x, y, fs=fs, nperseg=...) → returns a plain tuple (f, Cxy): f = frequency ndarray, Cxy = magnitude-squared coherence ndarray in [0,1]. Welch-averaged over segments.
• scipy.signal.csd(x, y, fs=fs, nperseg=...) → returns (f, Pxy): Pxy is the complex cross-spectral density. Cross-phase = numpy.angle(Pxy) (rad); convert to degrees for the panel: numpy.degrees(numpy.angle(Pxy)).
• Both calls return plain ndarrays computed locally (same as the pwrspc-style PSD step); nothing is stored as a tplot variable.
• render_tplot = ONE 2-D matrix per .npz. A coherence-vs-frequency curve and a phase-vs-frequency curve are two separate panels, so write one .npz per panel (do not pack both into one multi-key file and expect a 2-panel stack). Keep them side-by-side on the same frequency axis.