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=2, 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.

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 for automatic selection)

  • osr – Oversampling ratio

  • max_harmonic – Number of harmonics for THD calculation

  • nf_method – Noise floor calculation method (0=median, 1=trimmed mean, 2=exclude harmonics)

  • 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.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 = 2, 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 data for ADC analysis.

Parameters:

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

  • fs (float) – Sampling frequency in Hz

  • max_scale_range (float, optional) – Full scale range. If None, uses (max - min)

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

  • side_bin (int, optional) – Side bins to exclude around signal. If None, automatically determined based on: - Coherent signal (error < 0.01): ceil(enbw) - Non-coherent signal: ceil(2*enbw) + 1 where enbw is the window’s equivalent noise bandwidth factor

  • osr (int) – Oversampling ratio

  • max_harmonic (int) – Maximum harmonic number for THD (default: 5 means harmonics 2-5)

  • nf_method (int) – Noise floor method: 0=median, 1=trimmed mean, 2=exclude harmonics

  • assumed_sig_pwr_dbfs (float, optional) – Override signal power (dBFS)

  • coherent_averaging (bool) – If True, performs coherent averaging with phase alignment

  • cutoff_freq (float) – High-pass cutoff frequency (Hz)

  • verbose (int) – Verbosity level

Returns:

Contains ‘metrics’ and ‘plot_data’ dictionaries

Return type:

dict

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

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