gwadama.plotting#

plotting.py

Custom plotting functions

gwadama.plotting.plot_spectrogram_with_instantaneous_features(strain_array, time_array, fs=16384, outseg=None, outfreq=None, window=None, hop=32, mfft=None, vmin=None, vmax=None, spec_log=True, spec_norm=True, spec_interpol='lanczos', if_line_width=2) → tuple[Figure, tuple[Axes, Axes, Axes], ndarray[Any, dtype[_ScalarType_co]]][source]#

Plot the spectrogram, instantaneous frequency, and strain’s waveform.

This function generates a multi-panel plot consisting of:

  1. A spectrogram of the gravitational wave strain, obtained using Short-Time Fourier Transform (STFT), visualizing the frequency evolution over time.

  2. The instantaneous frequency of the strain, plotted on top of the spectrogram to show the frequency changes in real time.

  3. The raw gravitational wave strain in the time domain, shown above the spectrogram for direct comparison.

Key features of the plot:

  • Spectrogram: The frequency content of the gravitational wave signal is displayed over time using a color map (inferno), with the x-axis representing time (in milliseconds) and the y-axis representing frequency (in Hz).

  • Instantaneous Frequency: Plots the instantaneous frequency of the strain over time, highlighting the frequency variations.

  • Energy Normalization: The spectrogram uses a logarithmic scale for the energy (power spectral density, PSD), optionally normalized by the maximum energy value in the signal.

  • Dynamic Range Control: The color scale of the spectrogram can be adjusted via the vmin parameter to emphasize specific energy levels.

  • Time-Domain Waveform: A plot of the original strain data in the time domain is shown above the spectrogram, providing context for the signal’s evolution.

  • Segmentation: The user can specify the time (outseg) and frequency (outfreq) ranges to focus on specific parts of the data.

  • Customization: The plot has a black background, white grid lines, and labeled colorbars for clarity.

Parameters:
strain_arraynumpy.ndarray

The time-domain strain data of the gravitational wave signal.

time_arraynumpy.ndarray

Array of time stamps corresponding to the strain data.

fsint, optional

The sampling frequency of the data in Hz (default is 2^14, or 16384 Hz).

outsegtuple, optional

A tuple specifying the time range (start, end) in seconds for the x-axis. If None, the entire time range of the input data is used.

outfreqtuple, optional

A tuple specifying the frequency range (start, end) in Hz for the y-axis. If None, the full frequency range (up to Nyquist frequency) is used.

windownumpy.ndarray, optional

The window function applied during STFT computation (default is a Tukey window).

hopint, optional

The hop size between successive STFT windows (default is 32).

mfftint, optional

The number of points in the FFT used for STFT computation (default is None).

vmin, vmaxfloat, optional

The minimum/maximum value for the color scale in the spectrogram. This controls the dynamic range of the color map.

spec_logbool, optional

If true, represent np.log10(Sxx).

spec_normbool, optional

If true, normalize the spectrogram to the maximum energy value.

spec_interpolstr, optional

Interpolation used for visual representation (default ‘Lanczos’). See matplotlib.pyplot.imshow for other options.

if_line_widthint | float, optional

The line width of the instantaneous frequency plot (default is 2).

Returns:
figmatplotlib.figure.Figure

The figure object containing the complete plot.

axsList[matplotlib.axes.Axes]

A list of axes objects containing the spectrogram, the colorbar, and the time-domain plots.

Sxxnumpy.ndarray

The computed spectrogram (PSD values) of the input strain data.

Notes

  • The y-axis of the spectrogram uses a kilohertz scale for readability.

  • The time-domain waveform is plotted without axes labels for simplicity.

  • Instantaneous frequency values below zero are masked to avoid displaying non-physical results.