metrology.synchronous_average

Time synchronous averaging (TSA) of a periodic waveform in noise.

Time domain averaging extracts a repetitive signal of known period T from additive noise by ensemble-averaging successive length-T blocks, following P. D. McFadden, “A revised model for the extraction of periodic waveforms by time domain averaging”, Mechanical Systems and Signal Processing 1(1) 1987, 83-95. Given a signal y(t) = x(t) + e(t) with x periodic in T and e asynchronous, the average

`a(t) = (1/N) Σ_{n=0}^{N-1} y(t + n·T)`   (McFadden Eq. 5)

reinforces every component synchronous with T and suppresses the rest.

Two models, one implementation. McFadden distinguishes the existing comb-filter model from the revised model. In the frequency domain the average is the multiplication of Y(f) by the comb filter (Eq. 8)

`C(f) = (1/N)·sin(N·π·f·T) / sin(π·f·T)`,

whose magnitude |C(f)| = |sin(N·π·f·T) / (N·sin(π·f·T))| is a Dirichlet kernel: unity at every harmonic k/T (the teeth, Eq. 9, of unit height regardless of N) and zero at the nodes j/(N·T) with j not a multiple of N. That model assumes knowledge of y over infinite time and produces a result that is not exactly periodic. McFadden’s revised model applies a rectangular window of width T in the time domain and samples the transform in the frequency domain, so it needs only a finite block of the signal and yields a result that is exactly periodic and can be stored as a single period. The digital block average computed here, N consecutive periods of an integer number of samples reduced to one period, is that revised model: the returned period_waveform, repeated, is exactly periodic.

Noise reduction. Asynchronous noise of variance σ² averaged over N periods has residual variance σ²/N: the residual standard deviation falls as 1/√N and the amplitude signal-to-noise ratio improves by √N (a power reduction of 10·log₁₀ N dB, reported as noise_reduction_db).

Choosing N (McFadden’s revised-model correction). Because a discrete interfering tone at a non-harmonic order q = f·T is only attenuated, not removed, its rejection is optimised by choosing N so that a comb node lands exactly on it, i.e. the smallest N with N·q an integer. McFadden’s own example, a tone at 32.05 orders, is suppressed by more than 100 dB with N = 20 (since 20·32.05 = 641) yet — evaluating Eq. 8 at that order — by only about 14 dB with the common power-of-two choice N = 32 (32·32.05 = 1025.6; the paper makes the comparison but does not print this figure). Thus the habit of taking a power-of-two number of averages is not, in general, optimal.

Non-integer samples per period. When fs·T is not an integer the period boundaries fall between samples. Each block is then aligned to a common integer grid by the band-limited fractional delay of phonometry.metrology.signals.fractional_delay before averaging, so the periodic waveform is recovered within the interpolation error of that band-limited shift. An integer fs·T needs no interpolation and the waveform is recovered to machine precision. The averaged samples stay on the 1/fs sampling grid throughout: output sample m is the average of the input at the times n·T + m/fs, so the returned time axis is m/fs and the M = round(fs·T) samples cover one period exactly when fs·T is an integer and to within half a sample otherwise. No resampling onto an M-point angular grid is performed.

Auto-generated from the source docstrings by scripts/generate_api_docs.py (make api-docs). Do not edit by hand.

comb_filter_response

comb_filter_response(
    frequencies: NDArray[np.float64] | list[float],
    period: float,
    n_averages: int,
) -> NDArray[np.float64]

Magnitude of the N-period synchronous-averaging comb filter.

The closed form of McFadden Eq. 8, |C(f)| = |sin(N·π·f·T) / (N·sin(π·f·T))|, a Dirichlet kernel with unit-height teeth at the harmonics k/T (Eq. 9) and nodes at j/(N·T) for j not a multiple of N.

Parameters

Name	Description
frequencies	Frequencies at which to evaluate, in Hz.
period	Repetition period T, in seconds.
n_averages	Number of averaged periods N (at least 1).

Returns: The filter magnitude at each frequency (unitless; bounded by 1, though floating-point cancellation immediately beside a tooth can return values above 1 by a few parts in 1e9).

Raises

Exception	When
ValueError	If the parameters are invalid.

SynchronousAverageResult

SynchronousAverageResult(
    period_waveform: NDArray[np.float64],
    times: NDArray[np.float64],
    residual: NDArray[np.float64],
    n_averages: int,
    samples_per_period: int,
    period: float,
    fs: float,
    interpolated: bool,
    noise_reduction_db: float,
    residual_rms: float,
    comb_frequencies: NDArray[np.float64],
    comb_response: NDArray[np.float64],
)

Time synchronous average of a periodic waveform in noise.

Attributes

Name	Description
period_waveform	The averaged periodic waveform, one period of samples_per_period samples.
times	Time axis of period_waveform, in seconds: the sampling grid m/fs, m = 0 .. M-1 (the averaged samples stay on the 1/fs grid; see the module note). The axis spans one period exactly when fs·T is an integer, and to within half a sample otherwise.
residual	Input minus the periodic reconstruction, over the analysed span (n_averages·samples_per_period samples, aligned to the integer period grid): what is left after the synchronous component is removed.
n_averages	Number of periods averaged, N.
samples_per_period	Integer samples per period M after any alignment.
period	Repetition period T, in seconds.
fs	Sample rate, in Hz.
interpolated	Whether band-limited fractional-delay alignment was applied (True when fs·T is not an integer).
noise_reduction_db	Power reduction of asynchronous noise, 10·log₁₀ N dB (amplitude SNR gain √N).
residual_rms	Root-mean-square of residual.
comb_frequencies	Frequency axis of the comb-filter response, in Hz (from DC over a whole number of harmonics of 1/T).
comb_response	Magnitude of the comb filter (McFadden Eq. 8) on comb_frequencies.

SynchronousAverageResult.amplitude_snr_gain

property

Amplitude signal-to-noise improvement √N from averaging.

SynchronousAverageResult.plot()

SynchronousAverageResult.plot(
    ax: Axes | None = None,
    *,
    language: str = 'en',
    **kwargs: Any,
) -> Axes | NDArray[Any]

Plot the averaged waveform and the comb-filter magnitude.

With ax given, only the averaged-waveform panel is drawn on it.

Parameters

Name	Description
language	Label language, "en" (default) or "es".

time_synchronous_average

time_synchronous_average(
    x: NDArray[np.float64] | list[float],
    fs: float,
    period: float,
    *,
    n_averages: int | None = None,
    n_harmonics: int = 8,
) -> SynchronousAverageResult

Extract a periodic waveform of known period by time domain averaging.

Ensemble-averages N successive periods of the record (McFadden Eq. 5) to reinforce the component synchronous with period and suppress asynchronous noise, whose residual standard deviation falls as 1/√N. When fs·period is an integer the periods are sliced directly and a noiseless periodic signal is recovered exactly; otherwise each period is aligned to a common integer grid by the band-limited fractional delay of fractional_delay and recovered within that interpolation error.

Parameters

Name	Description
x	Signal, 1-D, containing the periodic component plus noise.
fs	Sample rate, in Hz.
period	Known repetition period T, in seconds (e.g. one revolution of a rotating machine).
n_averages	Number of whole periods to average (default: as many as the record holds). Choosing N so that N·q is an integer places a comb node on an interfering tone at order q and maximises its rejection (McFadden’s revised-model result).
n_harmonics	Number of harmonics of 1/T spanned by the returned comb-filter response (default 8).

Returns: A SynchronousAverageResult.

Raises

Exception	When
ValueError	If the inputs or parameters are invalid.