Spectrogram

class modusa.signals.spectrogram.Spectrogram(S: ndarray, f: ndarray, frame_rate: float, t0: float = 0.0, title: str | None = None)[source]

Bases: ModusaSignal

A 2D time–frequency representation of a signal.

Parameters:

  • S (np.ndarray) – 2D matrix representing the spectrogram (shape: [n_freqs, n_frames]).

  • f (np.ndarray) – Frequency axis corresponding to the rows of S (shape: [n_freqs]).

  • t (np.ndarray) – Time axis corresponding to the columns of S (shape: [n_frames]).

  • title (str, optional) – Optional title for the spectrogram (e.g., used in plotting).

property S: ndarray

Spectrogram matrix (freq × time).

property f: ndarray

Frequency axis.

property frame_rate: ndarray

Frequency axis.

property t0: ndarray

Frequency axis.

property t: ndarray

Time axis.

property shape: ndarray

Shape of the spectrogram (freqs, frames).

property ndim: ndarray

Number of dimensions (always 2).

property magnitude: Spectrogram

Return a new Spectrogram with magnitude values.

property power: Spectrogram

Return a new Spectrogram with power (magnitude squared).

property angle: Spectrogram

Return a new Spectrogram with phase angle (in radians).

property real: Spectrogram

Return a new Spectrogram with real part.

property imag: Spectrogram

Return a new Spectrogram with imaginary part.

property phase: Spectrogram

Return a new Spectrogram with normalized phase.

print_info() → None[source]

Print key information about the spectrogram signal.

crop(f_min: float | None = None, f_max: float | None = None, t_min: float | None = None, t_max: float | None = None) → Spectrogram[source]

Crop the spectrogram to a rectangular region in frequency-time space.

cropped = spec.crop(f_min=100, f_max=1000, t_min=5.0, t_max=10.0)
Parameters:

  • f_min (float or None) – Inclusive lower frequency bound. If None, no lower bound.

  • f_max (float or None) – Exclusive upper frequency bound. If None, no upper bound.

  • t_min (float or None) – Inclusive lower time bound. If None, no lower bound.

  • t_max (float or None) – Exclusive upper time bound. If None, no upper bound.

Returns:

Cropped spectrogram.

Return type:

Spectrogram

plot(ax: Axes | None = None, cmap: str = 'gray_r', title: str | None = None, Mlabel: str | None = None, ylabel: str | None = 'Frequency (hz)', xlabel: str | None = 'Time (sec)', ylim: tuple[float, float] | None = None, xlim: tuple[float, float] | None = None, highlight: list[tuple[float, float, float, float]] | None = None, vlines: list | None = None, hlines: list | None = None, origin: str = 'lower', gamma: int | float | None = None, show_colorbar: bool = True, cax: Axes | None = None, show_grid: bool = True, tick_mode: str = 'center', n_ticks: tuple[int, int] | None = None) → Figure[source]

Plot the spectrogram using Matplotlib.

fig = spec.plot(log_compression_factor=10, title="Log-scaled Spectrogram")
Parameters:

  • log_compression_factor (float or int, optional) – If specified, apply log-compression using log(1 + S * factor).

  • ax (matplotlib.axes.Axes, optional) – Axes to draw on. If None, a new figure and axes are created.

  • cmap (str, default "gray_r") – Colormap used for the image.

  • title (str, optional) – Title to use for the plot. Defaults to the signal’s title.

  • Mlabel (str, optional) – Label for the colorbar (e.g., “Magnitude”, “dB”).

  • ylabel (str, optional) – Label for the y-axis. Default is “Frequency (hz)”.

  • xlabel (str, optional) – Label for the x-axis. Default is “Time (sec)”.

  • ylim (tuple of float, optional) – Limits for the y-axis (frequency).

  • xlim (tuple of float, optional) – Limits for the x-axis (time).

  • highlight (list of (x, y, w, h), optional) – Rectangular regions to highlight, specified in data coordinates.

  • origin ({"lower", "upper"}, default "lower") – Origin position for the image (for flipping vertical axis).

  • show_colorbar (bool, default True) – Whether to display the colorbar.

  • cax (matplotlib.axes.Axes, optional) – Axis to draw the colorbar on. If None, uses default placement.

  • show_grid (bool, default True) – Whether to show the major gridlines.

  • tick_mode ({"center", "edge"}, default "center") – Whether to place ticks at bin centers or edges.

  • n_ticks (tuple of int, optional) – Number of ticks (y_ticks, x_ticks) to display on each axis.

Returns:

The figure object containing the plot.

Return type:

matplotlib.figure.Figure

sin()[source]

Element-wise sine of the spectrogram.

cos()[source]

Element-wise cosine of the spectrogram.

exp()[source]

Element-wise exponential of the spectrogram.

tanh()[source]

Element-wise hyperbolic tangent of the spectrogram.

log()[source]

Element-wise natural logarithm of the spectrogram.

log1p()[source]

Element-wise log(1 + M) of the spectrogram.

log10()[source]

Element-wise base-10 logarithm of the spectrogram.

log2()[source]

Element-wise base-2 logarithm of the spectrogram.

mean(axis: int | None = None) → float[source]

Return the mean of the spectrogram values.

std(axis: int | None = None) → float[source]

Return the standard deviation of the spectrogram values.

min(axis: int | None = None) → float[source]

Return the minimum value in the spectrogram.

max(axis: int | None = None) → float[source]

Return the maximum value in the spectrogram.

sum(axis: int | None = None) → float[source]

Return the sum of the spectrogram values.