Spectrum Analysis (spectrum)#

The spectrum module provides FFT-based spectrum analysis tools.

Single-Tone Spectrum#

adctoolbox.analyze_spectrum(data, fs=1.0, osr=1, max_scale_range=None, win_type='hann', side_bin=None, max_harmonic=5, nf_method=0, assumed_sig_pwr_dbfs=nan, coherent_averaging=False, create_plot: bool = True, show_title=True, show_label=True, plot_harmonics_up_to=3, ax=None)[source]#

Spectral analysis and plotting. (Wrapper function for modular core and plotting)

This function first calculates all metrics and then conditionally plots the spectrum.

For the Virtuoso/ADE-Explorer dark-theme stem plot variant, see analyze_spectrum_virtuoso (separate function with its own defaults — rectangular window, dark-theme plotter).

Parameters:

  • data – Input data (N,) or (M, N)

  • fs – Sampling frequency

  • max_scale_range – Full scale range for normalization. Can be: scalar (direct range), tuple/list [min, max], or None (auto-detect)

  • win_type – Window function type (‘hann’, ‘hamming’, ‘boxcar’)

  • side_bin – Number of side bins around fundamental. None triggers waveform-based auto detection in compute_spectrum; pass an explicit integer to force a fixed signal-lobe width.

  • osr – Oversampling ratio

  • max_harmonic – Number of harmonics for THD calculation

  • nf_method – Noise floor method (0=auto default, 1=median, 2=trimmed mean, 3=exclude, 4=legacy wide exclude)

  • assumed_sig_pwr_dbfs – Pre-defined signal level in dBFS

  • create_plot – Plot the spectrum (True) or not (False)

  • show_title – Display auto-generated title (True) or not (False)

  • show_label – Add labels and annotations (True) or not (False)

  • plot_harmonics_up_to – Number of harmonics to mark on the plot

  • ax – Optional matplotlib axes object. If None and create_plot=True, a new figure is created.

Returns:

Dictionary with performance metrics:

  • enob: Effective Number of Bits

  • sndr_dbc: Signal-to-Noise and Distortion Ratio (dBc)

  • sfdr_dbc: Spurious-Free Dynamic Range (dBc)

  • snr_dbc: Signal-to-Noise Ratio (dBc)

  • thd_dbc: Total Harmonic Distortion (dBc)

  • sig_pwr_dbfs: Signal power (dBFS)

  • noise_floor_dbfs: Noise floor (dBFS)

  • nsd_dbfs_hz: Noise Spectral Density (dBFS/Hz)

Return type:

dict

adctoolbox.analyze_spectrum_virtuoso(data, fs=1.0, osr=1, max_scale_range=None, win_type='rectangular', side_bin=None, max_harmonic=5, nf_method=0, assumed_sig_pwr_dbfs=nan, coherent_averaging=False, create_plot: bool = True, show_title=True, show_label=True, plot_harmonics_up_to=3, ax=None)[source]#

Same as analyze_spectrum, but defaults are tuned for Cadence Virtuoso / ADE-Explorer aesthetics:

  • win_type defaults to ‘rectangular’ (one stem = one bin, no main-lobe smearing — matches what ADE Explorer renders by default).

  • Plot rendered by plot_spectrum_virtuoso (black canvas, red stems, yellow/cyan annotation markers, fine dotted grid).

All other parameters and the returned metric dict are identical to analyze_spectrum. Pass win_type=’hann’ explicitly if you want Hann metrics with the Virtuoso plot style.

adctoolbox.extract_freq_components(din, bands)[source]#

Extract signal components within specified frequency bands.

Parameters:

  • din (np.ndarray) – Input data matrix (N x M or M x N). Must be real-valued.

  • bands (np.ndarray) – Frequency bands matrix (P x 2), each row [low_freq, high_freq]. Frequencies normalized: 0 = DC, 0.5 = Nyquist.

Returns:

Output data with only components in specified bands.

Return type:

np.ndarray

adctoolbox.quick_sndr(data, fs=1.0, win_type='hann', side_bin=None, max_scale_range=None)[source]#

SNDR + ENOB from a single 1-D capture (same SNDR definition as analyze_spectrum).

Parameters:

  • data – Time-domain samples, shape (N,)

  • fs – Sample rate (Hz)

  • win_type – Window name (‘hann’, ‘rectangular’, …)

  • side_bin – Side bins around fundamental. None uses the window’s coherent default fast path. “auto” uses waveform-based side-bin detection matching compute_spectrum(..., side_bin=None); this adds an extra ideal-tone FFT pass and assumes a dominant single-tone capture. For multi-tone, strongly distorted, or very noisy captures, pass an explicit integer.

  • max_scale_range – Optional full-scale range for input normalization

Returns:

{'sndr_dbc': float, 'enob': float}

Return type:

dict

adctoolbox.sweep_performance_vs_osr(data: ndarray, osr: ndarray | None = None, harmonic: int = 5, create_plot: bool = True, ax: Axes | None = None, logscale: bool = True, smooth: int | None = None) → dict[source]#

Sweep ADC performance metrics versus oversampling ratio.

Parameters:

  • data (np.ndarray) – Input signal (1D), typically ADC output samples.

  • osr (np.ndarray, optional) – OSR values to evaluate. Default: N/2 / (N/2, N/2-1, …, 1).

  • harmonic (int, default=5) – Number of harmonics to mark on plot.

  • create_plot (bool, default=True) – If True, create performance plot(s).

  • ax (plt.Axes, optional) – Axes for main performance plot. If None and create_plot, creates 2-subplot figure (performance + slope).

  • logscale (bool, default=True) – Use logarithmic OSR axis, matching MATLAB perfosr default.

  • smooth (int, optional) – Half-width used for local SNDR slope estimation. Default matches the local MATLAB-style heuristic.

Returns:

‘osr’: OSR values ‘sndr’: SNDR in dB at each OSR ‘sfdr’: Fast residual-spectrum single-bin SFDR estimate in dB at each OSR ‘enob’: ENOB in bits at each OSR

Return type:

dict

adctoolbox.spectrum.compute_spectrum(data: ndarray, fs: float = 1.0, max_scale_range: float | list[float] | tuple[float | None | list[float]] = None, win_type: str = 'hann', side_bin: int | None = None, osr: int = 1, max_harmonic: int = 5, nf_method: int = 0, assumed_sig_pwr_dbfs: float | None = None, coherent_averaging: bool = False, cutoff_freq: float = 0, verbose: int = 0) → dict[str, ndarray | float | dict][source]#

Calculate spectrum metrics aligned with MATLAB plotspec.m.

Parameters:

  • data – Input ADC data, shape (N,) or (M, N)

  • fs – Sampling frequency in Hz

  • max_scale_range – Full scale range for normalization

  • win_type – Window type: ‘boxcar’, ‘hann’, ‘hamming’, etc.

  • side_bin – Side bins around fundamental; None triggers auto detection

  • osr – Oversampling ratio

  • max_harmonic – Maximum harmonic order for THD (5 => H2..H5)

  • nf_method – 0=auto (default), 1=median, 2=trimmed mean, 3=exclude harmonics, 4=legacy wide harmonic exclusion

  • assumed_sig_pwr_dbfs – Override signal power in dBFS

  • coherent_averaging – Use coherent FFT averaging when True

  • cutoff_freq – High-pass cutoff in Hz

  • verbose – Verbosity level

adctoolbox.spectrum.plot_spectrum(compute_results, show_title=True, show_label=True, plot_harmonics_up_to=3, ax=None)[source]#

Pure spectrum plotting using pre-computed analysis results.

Parameters:

  • compute_results – Dictionary containing ‘metrics’ and ‘plot_data’ from compute_spectrum

  • show_label – Add labels and annotations (True) or not (False)

  • plot_harmonics_up_to – Number of harmonics to highlight

  • show_title – Display auto-generated title (True) or not (False)

  • ax – Optional matplotlib axes object

adctoolbox.spectrum.plot_spectrum_virtuoso(compute_results, show_title=True, show_label=True, plot_harmonics_up_to=3, ax=None, baseline_db=None)[source]#

Virtuoso/ADE-Explorer style spectrum plot with annotations.

Parameters:

  • compute_results (dict) – Output of compute_spectrum.

  • show_title (bool) – Show auto-generated plot title.

  • show_label (bool) – Add fundamental marker, spur marker, harmonics markers, and the metric text block. Set False for a bare-stem look.

  • plot_harmonics_up_to (int) – Highlight harmonics up to this order (HD2..HDk).

  • ax (matplotlib.axes.Axes, optional) – Target axes. If None, uses current axes. Axes + figure facecolor will be set to black.

  • baseline_db (float, optional) – Bottom of stem bars in dB. None → adaptive (min(spec) - 5).

Polar Spectrum Plots#

adctoolbox.analyze_spectrum_polar(data: ndarray, max_code: float | None = None, harmonic: int = 5, osr: int = 1, cutoff_freq: float = 0, fs: float = 1.0, win_type: str = 'boxcar', create_plot: bool = True, ax=None, fixed_radial_range: float | None = None) → dict[str, Any][source]#

Polar phase spectrum analysis and plotting. (Wrapper function for modular core and plotting)

This function calculates coherent spectrum with phase alignment and optionally plots it in polar format.

Parameters:

  • data – Input ADC data, shape (N,) or (M, N)

  • max_code – Maximum code level for normalization. If None, uses (max - min)

  • harmonic – Number of harmonics to mark on polar plot

  • osr – Oversampling ratio

  • cutoff_freq – High-pass cutoff frequency in Hz

  • fs – Sampling frequency in Hz

  • win_type – Window function type (‘boxcar’, ‘hann’, ‘hamming’)

  • create_plot – Plot the polar spectrum (True) or not (False)

  • ax – Optional matplotlib polar axes object. If None and create_plot=True, uses current axes.

  • fixed_radial_range – Fixed radial range in dB. If None, auto-scales.

Returns:

Full results dictionary from compute_spectrum with coherent_averaging=True

Return type:

dict

adctoolbox.spectrum.plot_spectrum_polar(analysis_results, show_metrics=True, harmonic=5, fixed_radial_range=None, ax=None)[source]#

Pure polar spectrum plotting using pre-computed coherent spectrum results.

Parameters:

  • analysis_results – Dictionary containing output from compute_spectrum(coherent_averaging=True)

  • show_metrics – Display metrics annotations (True) or not (False)

  • harmonic – Number of harmonics to mark on the plot

  • fixed_radial_range – Fixed radial range in dB. If None, auto-scales.

  • ax – Optional matplotlib polar axes object