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

Two-Tone Spectrum

adctoolbox.analyze_two_tone_spectrum(data: ndarray, fs: float = 1.0, max_scale_range: float | None = None, harmonic: int = 3, win_type: str = 'hann', side_bin: int = 1, coherent_averaging: bool = False, create_plot: bool = True, show_title: bool = True, show_labels: bool = True, ax=None) → dict[source]

Two-tone spectrum analysis with IMD calculation. (Wrapper function for modular core and plotting)

This function calculates IMD metrics and optionally plots the two-tone spectrum.

Parameters:

  • data – ADC output data, shape (M, N) for M runs or (N,) for single run

  • fs – Sampling frequency (Hz)

  • max_scale_range – Full scale range (max-min) for normalization

  • harmonic – Number of harmonics to mark on plot

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

  • side_bin – Number of side bins around fundamental

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

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

  • show_title – Display title (True) or not (False)

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

  • 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_db: Signal-to-Noise and Distortion Ratio (dB)

  • sfdr_db: Spurious-Free Dynamic Range (dB)

  • snr_db: Signal-to-Noise Ratio (dB)

  • thd_db: Total Harmonic Distortion (dB)

  • signal_power_1_dbfs: Power of first tone (dBFS)

  • signal_power_2_dbfs: Power of second tone (dBFS)

  • noise_floor_db: Noise floor (dB)

  • imd2_dbc: 2nd order intermodulation distortion (dBc)

  • imd3_dbc: 3rd order intermodulation distortion (dBc)

Return type:

dict

adctoolbox.spectrum.compute_two_tone_spectrum(data: ndarray, fs: float = 1.0, max_scale_range: float | None = None, win_type: str = 'hann', side_bin: int = 1, harmonic: int = 7, coherent_averaging: bool = False) → dict[str, any][source]

Calculate two-tone spectrum data with IMD analysis.

Pure calculation function - no plotting or side effects. Follows the modular architecture pattern.

Parameters:

  • data (np.ndarray) – ADC output data, shape (M, N) for M runs or (N,) for single run

  • fs (float, optional) – Sampling frequency (Hz), default: 1.0

  • max_scale_range (float, optional) – Maximum code range, default: max-min of data

  • win_type (str, optional) – Window type: ‘hann’, ‘blackman’, ‘hamming’, ‘boxcar’, default: ‘hann’

  • side_bin (int, optional) – Side bins to include in signal power, default: 1

  • harmonic (int, optional) – Number of harmonic orders to calculate for IMD products, default: 7

  • coherent_averaging (bool, optional) – If True, performs coherent averaging with phase alignment, default: False

Returns:

Dictionary containing: - ‘metrics’: Performance metrics (enob, sndr, sfdr, snr, thd, etc.) - ‘plot_data’: Data for plotting (freq, spec_db, bin1, bin2, etc.) - ‘imd_bins’: IMD product bin locations

Return type:

dict