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)[源代码]

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

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

参数:

  • 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.

返回:

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)

返回类型:

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][源代码]

Calculate spectrum data for ADC analysis.

参数:

  • 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

返回:

Contains 'metrics' and 'plot_data' dictionaries

返回类型:

dict

adctoolbox.spectrum.plot_spectrum(compute_results, show_title=True, show_label=True, plot_harmonics_up_to=3, ax=None)[源代码]

Pure spectrum plotting using pre-computed analysis results.

参数:

  • 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][源代码]

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.

参数:

  • 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.

返回:

Full results dictionary from compute_spectrum with coherent_averaging=True

返回类型:

dict

adctoolbox.spectrum.plot_spectrum_polar(analysis_results, show_metrics=True, harmonic=5, fixed_radial_range=None, ax=None)[源代码]

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

参数:

  • 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