Skip to content

metrology.data_qualification

Random-data qualification: stationarity tests and Rice crossing statistics.

Before a record is averaged into a PSD, condensed into a Leq or fed to a GUM budget, Bendat & Piersol (Random Data, 4th ed., Sec. 10.3) require it to be qualified: classified as stationary or not, checked for periodicities and validated against acquisition anomalies. This module implements the two quantitative pillars of that chapter.

Stationarity (B&P Sec. 10.3.1.1). The record is divided into N equal intervals, a mean square value (or another moment) is computed for each, and the sequence is tested for underlying trends with a nonparametric test: no assumption about the sampling distribution of the values is needed. The book’s test is the reverse arrangement test (Sec. 4.5.2): count the pairs with . For an ordered sequence of independent observations that count A has mean N(N-1)/4 (Eq. (4.54)) and variance N(2N+5)(N-1)/72 (Eq. (4.55)), and the hypothesis of no trend is accepted at significance alpha when A falls inside the two-sided acceptance region of Table A.6 (for and : more than 64 and at most 125 reverse arrangements, the book’s Examples 4.4 and 10.3). The classical companion runs test (the run distribution tabulated in the third edition; Wald & Wolfowitz 1940) classifies each value as above or below the sequence median and counts runs of like classification: a trend produces too few runs, rapid alternation too many. Both tests are distribution-free and, per Sec. 10.3.1.1, work equally well on mean values, rms values, standard deviations or any other parameter sequence.

Level crossings and peaks (B&P Sec. 5.5, originally Rice). For a zero mean value stationary Gaussian record with one-sided autospectrum G(f), the geometric moments

(Eqs. (5.214)-(5.216)) determine every crossing and peak statistic:

  • the expected number of zero crossings per unit time (both slopes), (Eq. (5.195)), equivalently with the plain frequency moments ; twice the record’s apparent frequency;

  • the expected number of crossings of level a, (Eq. (5.196));

  • the expected number of maxima per unit time, (Eq. (5.211));

  • the irregularity factor , between 0 and 1 (Eq. (5.220)): 1 for narrow bandwidth data (one maximum per zero-crossing cycle), toward 0 as ever more local maxima ride on each cycle;

  • the peak probability functions: Rayleigh for narrow bandwidth data (Eqs. (5.206)-(5.207)), the standardized Gaussian for (Eq. (5.221)) and, in between, Rice’s mixture for the standardized peak height z (Eqs. (5.217) and (5.223) with ):

    where Q is the standardized normal exceedance (Eq. (5.250)).

stationarity_test and trend_test implement the first block, level_crossing_rate and peak_statistics the second, each comparing the counts measured on the record with the closed-form expectations.

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

level_crossing_rate(
x: Signal | NumericArrayLike,
fs: float | None = None,
*,
levels: NumericArrayLike | None = None,
nperseg: int | np.integer[Any] | None = None,
) -> LevelCrossingResult

Level-crossing rates of a record and their Rice expectations.

Counts the crossings of each level a (both slopes, B&P Sec. 5.5.1) and compares them with the closed forms for Gaussian data: the zero-crossing rate (Eq. (5.195)) and the level dependence (Eq. (5.196)), with the spectral moments taken from the record’s own Welch autospectrum. For low-pass white noise of bandwidth B the expectation is , an apparent frequency of 0.58 B (B&P Example 5.12), and for bandwidth-limited white noise centred on fc, (Example 5.13).

The record mean is removed first (the formulas hold for zero mean value records); levels are then relative to that mean. Crossings are counted as sign changes of the sampled record, so the sample rate must comfortably oversample the signal bandwidth for the count not to miss crossings between samples.

Parameters

Name Description
x Signal, 1-D. Accepts a phonometry.io.Signal, whose calibration is applied to the samples, which means levels has to be given in the same units, so pascals rather than digital ones, and sigma comes out in Pa. The crossing rates themselves are scale-free.
fs Sample rate, in Hz. Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises instead of silently winning.
levels Crossing levels in signal units about the mean (default: 13 levels evenly spaced over +-3 RMS).
nperseg Welch segment length for the spectral moments (default: the power_spectral_density default).

Returns: A LevelCrossingResult.

Raises

Exception When
ValueError If the inputs or parameters are invalid.
TypeError if levels holds a text or a value that is not a real number.
LevelCrossingResult(
levels: NDArray[np.float64],
rates: NDArray[np.float64],
rice_rates: NDArray[np.float64],
zero_crossing_rate: float,
zero_crossing_rate_rice: float,
apparent_frequency: float,
sigma: float,
duration_s: float,
fs: float,
)

Measured level-crossing rates against the Rice expectation.

All rates count crossings with both slopes per unit time, following B&P Sec. 5.5.1; the rate of zero crossings is twice the record’s apparent frequency. The Rice curve (Eq. (5.196)) holds for Gaussian records; systematic departures of the measured rates from it are themselves a useful non-Gaussianity screen (B&P Sec. 5.5.1.1).

Attributes

Name Description
levels Crossing levels a, in signal units (about the removed record mean).
rates Measured crossing rates per level, in 1/s.
rice_rates Rice expectation , 1/s.
zero_crossing_rate Measured zero-crossing rate N0, in 1/s.
zero_crossing_rate_rice Expected from the record’s Welch autospectrum moments (Eq. (5.195)), in 1/s.
apparent_frequency N0 / 2 from the spectral moments, in Hz (a 60 Hz sine crosses zero 120 times per second).
sigma RMS value of the demeaned record, in signal units.
duration_s Record duration used for the rates, in seconds.
fs Sample rate, in Hz.
LevelCrossingResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot measured crossing rates against the Rice curve.

Parameters

Name Description
language Label language, "en" (default) or "es".
peak_statistics(
x: Signal | NumericArrayLike,
fs: float | None = None,
*,
nperseg: int | np.integer[Any] | None = None,
) -> PeakStatisticsResult

Peak rate, irregularity factor and peak-height distribution of a record.

Detects the record’s local maxima and compares their rate and height distribution with the Rice closed forms for Gaussian data (B&P Secs. 5.5.2 to 5.5.4): expected maxima rate (Eq. (5.211)), irregularity factor (Eq. (5.220)) and the standardized peak-height distribution that interpolates between Rayleigh (narrow bandwidth, ) and Gaussian (wide bandwidth, ) via PeakStatisticsResult.peak_exceedance. The irregularity factor is the bridge to fatigue and vibro-acoustic damage models, where it selects the cycle-counting correction.

The record mean is removed first. The m4 moment weights the autospectrum by , so broadband instrumentation noise far above the physical band inflates M and deflates r: band-limit the record to the physically meaningful band first.

Parameters

Name Description
x Signal, 1-D. Accepts a phonometry.io.Signal, whose calibration is applied to the samples, so sigma comes out in Pa. The peak heights are standardized by it, so they and the rates do not move.
fs Sample rate, in Hz. Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises instead of silently winning.
nperseg Welch segment length for the spectral moments (default: the power_spectral_density default).

Returns: A PeakStatisticsResult.

Raises

Exception When
ValueError If the inputs or parameters are invalid.
PeakStatisticsResult(
peak_rate: float,
peak_rate_rice: float,
zero_crossing_rate_rice: float,
irregularity_factor: float,
peak_values: NDArray[np.float64],
sigma: float,
duration_s: float,
fs: float,
)

Peak (maxima) statistics of a record against the Rice expectations.

“Positive peaks” are the record’s local maxima, positive or negative in value (B&P Sec. 5.5.3). For Gaussian records the expected rate of maxima is (Eq. (5.211)), and the ratio , the irregularity factor, between 0 and 1 by the Schwartz inequality (Eq. (5.220)), fixes the standardized peak-height distribution: Rayleigh at (every cycle carries one maximum), Gaussian as (Sec. 5.5.4).

Attributes

Name Description
peak_rate Measured rate of local maxima, in 1/s.
peak_rate_rice Expected rate from the Welch autospectrum moments, in 1/s.
zero_crossing_rate_rice Expected , 1/s.
irregularity_factor N0 / (2 M) from the spectral moments.
peak_values Standardized heights of the detected maxima.
sigma RMS value of the demeaned record, in signal units.
duration_s Record duration used for the rates, in seconds.
fs Sample rate, in Hz.
PeakStatisticsResult.peak_density(
z: float | np.floating[Any] | np.integer[Any],
) -> float
PeakStatisticsResult.peak_density(
z: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]
PeakStatisticsResult.peak_density(
z: NumericArrayLike,
) -> float | NDArray[np.float64]

Peak probability density w(z) (B&P Eq. (5.217)).

Parameters

Name Description
z Standardized peak heights (units of the record RMS).

Returns: Probability density values, same shape. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
TypeError if z holds a text or a value that is not a real number.
PeakStatisticsResult.peak_exceedance(
z: float | np.floating[Any] | np.integer[Any],
) -> float
PeakStatisticsResult.peak_exceedance(
z: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]
PeakStatisticsResult.peak_exceedance(
z: NumericArrayLike,
) -> float | NDArray[np.float64]

at the record’s irregularity factor.

B&P Eq. (5.223): the probability that a maximum chosen at random exceeds z record RMS units. for narrow bandwidth data ( at , B&P Example 5.14) and the Gaussian exceedance in the wide bandwidth limit.

Parameters

Name Description
z Standardized peak heights (units of the record RMS).

Returns: Exceedance probabilities, same shape. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
TypeError if z holds a text or a value that is not a real number.
PeakStatisticsResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the empirical peak exceedance against the Rice curves.

Parameters

Name Description
language Label language, "en" (default) or "es".
stationarity_test(
x: Signal | NumericArrayLike,
fs: float | None = None,
*,
n_segments: int | np.integer[Any] = 20,
statistic: Literal['mean_square', 'rms', 'mean', 'variance'] = 'mean_square',
method: Literal['reverse_arrangements', 'runs'] = 'reverse_arrangements',
alpha: float = 0.05,
) -> StationarityTestResult

Test a record for stationarity via trends in segment statistics.

The B&P Sec. 10.3.1.1 procedure: (1) divide the record into n_segments equal intervals, assumed long enough for the values to be independent; (2) compute a mean square value (or another moment) for each interval; (3) test the sequence for underlying trends with a nonparametric test, with no knowledge of the record’s bandwidth or sampling distribution required. Nonstationarities that show in the mean square value (the usual case: gain drifts, level ramps, machinery running up) are detected regardless of the record’s spectrum; the default 20 segments matches the book’s worked Example 10.3, which rejects stationarity for a noise record with a 20 % gain ramp (, below the Table A.6 lower bound of 64).

Any trailing samples that do not fill the last segment are discarded. The segment count trades resolution against independence: each segment must remain long against the record’s lowest frequencies.

Parameters

Name Description
x Signal, 1-D. Accepts a phonometry.io.Signal, whose calibration is applied to the samples, so the per-segment values come out in Pa² for the squared statistics ('mean_square', the default, and 'variance') and in Pa for 'rms' and 'mean'. The verdict, the bounds and the p-value are scale-free.
fs Sample rate, in Hz. Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises instead of silently winning.
n_segments Number of equal intervals (default 20, as in B&P Example 10.3); at least 10, at most the record length in samples.
statistic Per-segment statistic: "mean_square" (default, the book’s choice), "rms", "mean" or "variance".
method Trend test: "reverse_arrangements" (default) or "runs".
alpha Two-sided significance level (default 0.05).

Returns: A StationarityTestResult.

Raises

Exception When
ValueError If the inputs or parameters are invalid.
TypeError if n_segments is a flag, a text or an array where a count goes, or statistic is not a text, or method is not a text.
StationarityTestResult(
segment_values: NDArray[np.float64],
segment_times: NDArray[np.float64],
statistic: Literal['mean_square', 'rms', 'mean', 'variance'],
method: Literal['reverse_arrangements', 'runs'],
trend_statistic: int,
mean: float,
standard_deviation: float,
p_value: float,
*,
alpha: float,
n_segments: int,
segment_duration_s: float,
fs: float,
)

A stationarity test on segment statistics of a single record.

The record was divided into n_segments equal intervals, the per-segment statistic sequence was computed, and the sequence was tested for trends with trend_test (the B&P Sec. 10.3.1.1 procedure). The hypothesis of stationarity is accepted when bounds[0] < trend_statistic <= bounds[1].

Attributes

Name Description
segment_values Per-segment values of the tested statistic.
segment_times Segment centre times, in seconds.
statistic The per-segment statistic: "mean_square", "rms", "mean" or "variance".
method Trend test used: "reverse_arrangements" or "runs".
trend_statistic Observed statistic of the trend test, the count of reverse arrangements or of runs.
mean Null mean of the count.
standard_deviation Null standard deviation of the count.
p_value Two-sided p-value of the observed count.
alpha Significance level (default 0.05).
n_segments Number of segments the record was divided into.
segment_duration_s Duration of each segment, in seconds.
fs Sample rate of the record, in Hz.

property

Acceptance region (lower, upper) at alpha, read from the segment values.

The same region trend_test reads on segment_values: B&P Table A.6’s convention for reverse arrangements, the exact percentage points about the segment values’ own median for runs.

StationarityTestResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the segment-statistic sequence with the test verdict.

Parameters

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

property

Whether the count falls inside the acceptance region, lower < trend_statistic <= upper.

trend_test(
values: NumericArrayLike,
*,
method: Literal['reverse_arrangements', 'runs'] = 'reverse_arrangements',
alpha: float = 0.05,
) -> TrendTestResult

Nonparametric trend test on a sequence of observations or estimates.

Tests the hypothesis that the sequence holds independent observations of one random variable (no underlying trend) without assuming any sampling distribution (B&P Sec. 4.5.2). Two classical statistics:

  • "reverse_arrangements" (default): the count A of pairs with . A downward trend inflates A, an upward trend depresses it. The acceptance region reproduces B&P Table A.6 (, N = 10 to 100); the p-value uses the exact Mahonian null distribution up to .
  • "runs": values are classified against the sequence median and runs of like classification are counted (the run test of B&P’s earlier editions; Wald & Wolfowitz 1940). Trends and slow drifts produce too few runs, alternation too many. Exact conditional distribution at any N; values equal to the median are discarded.

The reverse arrangement test is the more powerful of the two against monotonic trends (B&P Sec. 4.5.2); the runs test also reacts to non-monotonic clustering.

Parameters

Name Description
values Observations or parameter estimates (e.g. segment mean square values), at least 10, as a sequence or an array.
method "reverse_arrangements" (default) or "runs".
alpha Two-sided significance level (default 0.05, the level tabulated by B&P).

Returns: A TrendTestResult.

Raises

Exception When
ValueError If the inputs or parameters are invalid.
TypeError if alpha is not a single number, or method is not a text, or values holds a text or a value that is not a real number.
TrendTestResult(
values: NDArray[np.float64],
method: Literal['reverse_arrangements', 'runs'],
statistic: int,
n: int,
mean: float,
standard_deviation: float,
p_value: float,
*,
alpha: float,
median: float | None = None,
)

A nonparametric trend test on a sequence of parameter estimates.

The hypothesis of no underlying trend is accepted at significance alpha when statistic lies inside the two-sided acceptance region lower < statistic <= upper (B&P Sec. 4.5.2 and Table A.6 for reverse arrangements); p_value is the exact two-sided tail probability of the observed count.

Attributes

Name Description
values The tested sequence (for "runs", after discarding values exactly equal to the median).
method "reverse_arrangements" or "runs".
statistic Observed count: reverse arrangements A or runs r.
n Number of observations used.
mean Null mean of the statistic (B&P Eq. (4.54) for A).
standard_deviation Null standard deviation (B&P Eq. (4.55) for A).
p_value Two-sided p-value from the exact null distribution (normal approximation above for reverse arrangements).
alpha Significance level of the region (default 0.05).
median For "runs", the median of the original sequence against which each value was classified (before values equal to it were discarded); None for "reverse_arrangements".

property

Acceptance region (lower, upper) at alpha, read from the sequence.

Percentage points such that the no-trend hypothesis is accepted when lower < statistic <= upper. For reverse arrangements these follow B&P Table A.6’s own convention (normal approximation with continuity correction, which reproduces the book’s tabulated entries exactly; the table is not derivable from the exact Mahonian distribution), so at an acceptance boundary the verdict and the exact p_value can disagree by one count. For runs they are the exact percentage points of the counts above and below median.

TrendTestResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the tested sequence against its sample index with the verdict.

Draws the sequence of observations against a plain sample index and states the outcome in the legend: the reverse-arrangement count A (or the run count r), the acceptance region and whether the no-trend hypothesis is accepted. For the runs test the classification median is drawn as a reference line.

Parameters

Name Description
ax Existing Axes to draw on, or None (default) to create a fresh figure and axes.
language Label language, "en" (default) or "es".
kwargs Extra keyword arguments forwarded to the sequence plot call (e.g. color, lw, marker).

Returns: The Axes the sequence was drawn on, so the figure can be composed further.

property

Whether the statistic falls inside the acceptance region.

lower < statistic <= upper: the no-trend hypothesis is accepted at alpha.