Overview

Harmonic Analysis.

Modules:

Name	Description
cli	CLI for harm_analysis.

Functions:

Name	Description
harm_analysis	Harmonic Analysis.
spec_analysis	Spectral Analysis.

harm_analysis

harm_analysis(
    x,
    fs=1,
    bw=None,
    n_harm=5,
    window=None,
    plot=False,
    ax=None,
)

Harmonic Analysis.

Calculates SNR, THD, Fundamental power, and Noise power of the input signal x.

The total harmonic distortion is determined from the fundamental frequency and the first five harmonics using a power spectrum of the same length as the input signal. A hann window is applied to the signal, before the power spectrum is obtained.

For simulations with an injected tone.

Parameters:

Name	Type	Description	Default
x	array_like	Input signal, containing a tone.	required
fs	float	Sampling frequency.	1
n_harm	int	Number of harmonics used in the THD calculation.	5
window	array_like	Window that will be multiplied with the signal. Default is Hann window.	None
bw	float	Bandwidth to use for the calculation of the metrics, in same units as fs. Also useful to filter another tone (or noise) with amplitude greater than the fundamental and located above a certain frequency (see shaped noise example).	None
plot	bool or None	If True, the power spectrum result is plotted. If specified, an ax must be provided, and the function returns a dictionary with the results and the specified axes (ax). If plot is not set, only the results are returned.	False
ax	Axes or None	Axes to be used for plotting. Required if plot is set to True.	None

Returns:

Name	Type	Description
properties	dict	Dictionary containing the analysis results fund_db: Fundamental power in decibels. fund_freq Frequency of the fundamental tone. dc_db: DC power in decibels. noise_db: Noise power in decibels. harm_db: Harmonics power in decibels. harm_freq: Harmonics frequency in Hz. thd_db: Total harmonic distortion in decibels. Returns numpy.nan if n_harm is 0 or if all harmonics are outside the bandwidth. snr_db: Signal-to-noise ratio in decibels. sinad_db: Signal-to-noise-and-distortion ratio in decibels. thdn_db: Total harmonic distortion plus noise in decibels. total_noise_and_dist_db: Total noise and distortion in decibels.
ax	matplotlib axes	If plot is set to True, the Axes used for plotting is returned.

Notes:

The function fails if the fundamental is not the highest spectral component in the signal.

Ensure that the frequency components are far enough apart to accommodate for the sidelobe width of the Hann window. If this is not feasible, you can use a different window by using the "window" input.

References:

• [1] Harris, Fredric J. "On the use of windows for harmonic analysis with the discrete Fourier transform." Proceedings of the IEEE 66.1 (1978): 51-83.
• [2] Cerna, Michael, and Audrey F. Harvey. The fundamentals of FFT-based signal analysis and measurement. Application Note 041, National Instruments, 2000.

spec_analysis

spec_analysis(
    x,
    fs=1,
    window=None,
    plot=False,
    ax=None,
    distance=6,
    prominence=10,
    height=None,
)

Spectral Analysis.

Auto-detects DC, tones, and noise from the spectrum.

Parameters:

Name	Type	Description	Default
x	array_like	Input signal, containing a tone.	required
fs	float	Sampling frequency.	1
window	array_like	Window that will be multiplied with the signal. Default is Hann window.	None
plot	bool or None	If True, the power spectrum result is plotted. If specified, an ax must be provided, and the function returns a dictionary with the results and the specified axes (ax). If plot is not set, only the results are returned.	False
distance	int	Required minimal horizontal distance (>= 1) in samples between neighbouring peaks. Smaller peaks are removed first until the condition is fulfilled for all remaining peaks.	6
prominence	int	Required prominence of peaks in dB. Either a number, None, or an array matching x	10
height	int | None	Required height of peaks in dB. Either a number, None, an array matching x.	None
ax	Axes or None	Axes to be used for plotting. Required if plot is set to True.	None

Returns:

Name	Type	Description
properties	dict	A dictionary containing the analysis results dc: DC level in the same units as the input signal x. dc_db: DC power in decibels. noise_db: Noise power in decibels. tones_db: Array with the amplitude of the detected tones in dB. tones_freq: Array with the frequencies of the detected tones in Hz.
	axes	If plot is set to True, the Axes used for plotting is returned.