DOC: signal: add an example cross-spectrogram application

[sancholp]

Is your feature request related to a problem? Please describe.

There is functionality for calculating the stft or the spectrogram (Sxx=Zxx**2) of a signal, but there is no functionality to do a similar process to analyze the temporal correlations of two signals. A function plotting some kind of "csd spectrogram" Zxy would be useful. Similarly, a "coherence spectrogram" Sxy analogous to the spectrogram function.

Describe the solution you'd like.

The function scipy.stats.stft calls _spectral_helper(x, x, ...). In other words, it calculates the spectral density of x(f)x*(f). To get the csd one would need to call _spectral_helper(x, y, ...) and calculate x(f)y*(f). (See wikipedia).

Describe alternatives you've considered.

The package GWpy, designed for data analysis in gravitational wave astronomy, already has such functionality. See docs of csd_spectrogram and coherence_spectrogram.

Additional context (e.g. screenshots, GIFs)

No response

[lucascolley]

cc @DietBru

[DietBru]

SciPy 1.12 introduced a new ShortTimeFFT.spectrogram() method, which also provides cross-spectrogram functionality.

@sancholp, do you happen to know of an application for a cross-spectrogram, which would easy to explain in a few words? It would be nice to have a cross-spectrogram example in the ShortTimeFFT.spectrogram() documentation.

[sancholp]

Two signals x and y might be correlated (coherent) only in certain times and certain frequencies. With such a spectrogram it is easy to see where and when these signals are correlated.

[DietBru]

Added an appropriate example in PR #20610­ -- reviews and comments are always welcome.