Ir al contenido

signals: envelope

La referencia de la API se publica en inglés en los dos idiomas: se genera a partir de los docstrings del código, que son su texto original.

Every name on this page is published by phonometry.signals: from phonometry import signals, then signals.<name>.

Envelope and instantaneous phase via the Hilbert transform.

Signal-envelope analysis following Bendat & Piersol, Random Data: Analysis and Measurement Procedures (4th ed., 2010), Chapter 13. The analytic signal (Eq. 13.15, with the Hilbert transform of x) yields

  • the envelope (Eq. 13.17),
  • the instantaneous phase , unwrapped (Eq. 13.18), and
  • the instantaneous frequency (Eq. 13.19).

The analytic signal is computed the way the book recommends (Section 13.1.1): the one-sided spectrum construction for , at DC and 0 for (Eq. 13.25), which is exactly what scipy.signal.hilbert implements, and the same construction the ECMA-418-2 psychoacoustic chain of phonometry.psychoacoustics applies per auditory band (its Formulae 65/119 take |hilbert| and subsample by 32; the standard can subsample directly because each band is narrow). Closed-form pairs from Table 13.1 (cos → sin, an AM envelope recovered exactly) anchor the tests.

The envelope of a band-limited signal is itself low-frequency, so the result offers optional decimation: an anti-aliased zero-phase FIR decimator for general records, or plain subsampling (antialias=False) matching the ECMA-internal convention when the input is already narrowband.

The envelope spectrum (envelope_spectrum) transforms the detected envelope itself: Section 13.3 of the book runs a band-pass filter and a square-law envelope detector into a DC remover before correlating (Figure 13.11), because the spectral content of the envelope, not of the signal, is where amplitude modulations show as discrete lines. The optional band argument reproduces the figure’s band-pass front end (the classical bearing-envelope chain: isolate the resonance band, then envelope it). An AM tone with modulation frequency (on an analysis bin) and depth m puts a line of closed-form amplitude at exactly , the anchor the tests pin; off-bin modulation lines read low by the taper’s scalloping loss.

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

envelope(
x: Signal | NumericArrayLike,
fs: float | None = None,
*,
decimation_factor: int | np.integer[Any] = 1,
antialias: bool = True,
) -> EnvelopeResult

Envelope, instantaneous phase and frequency via Hilbert transform.

Builds the analytic signal by the one-sided spectrum construction of Bendat & Piersol Eq. 13.25 (scipy.signal.hilbert) and returns the envelope , the unwrapped instantaneous phase and the instantaneous frequency (Eqs. 13.17-13.19). For an amplitude-modulated carrier with u low-frequency and non-negative the envelope recovers exactly in the ideal continuous case (Eq. 13.27); a discrete record shows small edge effects at the record boundaries.

The optional decimation reduces the output rate by an integer factor: the envelope is anti-alias filtered with a zero-phase FIR decimator by default, or plainly subsampled with antialias=False, the convention the ECMA-418-2 loudness/roughness chain applies internally after its auditory bandpass, appropriate when the input is already narrowband. The phase and instantaneous frequency, smooth after unwrapping and differentiated at full rate, are subsampled onto the same time axis.

Parameters

Name Description
x Signal, 1-D. Accepts a phonometry.io.Signal, whose calibration is applied to the samples, so the envelope and the carried waveform come out in Pa, and the carried waveform comes back as a Signal. The phase and the instantaneous frequency 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.
decimation_factor Integer output decimation (default 1: off).
antialias Anti-alias filter the decimated envelope (default True).

Returns: An EnvelopeResult.

Raises

Exception When
ValueError If the inputs or parameters are invalid.
TypeError if decimation_factor is a flag, a text or an array where a count goes.
envelope_spectrum(
x: Signal | NumericArrayLike,
fs: float | None = None,
*,
kind: Literal['magnitude', 'squared'] = 'magnitude',
window: str | tuple[str | NumericArrayLike, ...] = 'hann',
nfft: int | np.integer[Any] | None = None,
remove_dc: bool = True,
band: tuple[float, float] | None = None,
) -> EnvelopeSpectrumResult

Amplitude spectrum of the envelope: where modulations become lines.

Follows the structure of Bendat & Piersol Section 13.3 (Figure 13.11): a band-pass filter (optional here), an envelope detector, a DC remover, and a spectral view of what is left. The detector is the Hilbert envelope (kind="magnitude", the practical default) or the book’s square-law detector (kind="squared"); its mean is removed (kept in EnvelopeSpectrumResult.mean_level) and the remainder is tapered and transformed once, scaled by the taper’s coherent gain so a sinusoidal modulation whose frequency falls on an analysis bin reads out as a line at its exact amplitude. An off-bin modulation frequency reads low by the taper’s scalloping loss (up to about 1.4 dB, ~15 %, for the default Hann midway between bins), like any single-record amplitude spectrum.

Closed forms for an AM tone with and on an analysis bin:

  • kind="magnitude": a line of amplitude at ; mean level .
  • kind="squared": lines at and at ; mean level .

Amplitude modulation of rotating machinery (bearing and gear defect frequencies), mains hum and wind-turbine amplitude modulation appear the same way: lines at the modulation frequency and its harmonics, separated from the carrier’s own spectrum. For the classical bearing chain (isolate a structural-resonance band excited by the defect impacts, then envelope it) pass the resonance band as band: the record is band-pass filtered (zero-phase, so the modulation phase is untouched) before the detector, the Figure 13.11 front end.

Parameters

Name Description
x Signal, 1-D. Accepts a phonometry.io.Signal, whose calibration is applied to the samples, so the envelope, its spectral amplitude and the mean level come out in Pa under the default kind='magnitude', and in Pa² under 'squared', which squares the envelope before transforming it.
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.
kind "magnitude" (default) or "squared".
window Taper, a scipy window name or a tuple of a name and its parameters, such as ("kaiser", 8.6) (default Hann). The amplitude is corrected for the taper’s coherent gain.
nfft FFT length, at least x.size (default: the record length).
remove_dc Remove the envelope mean before the transform (default True, the Figure 13.11 DC remover); the mean is reported either way.
band Optional (low, high) band-pass edges, in Hz (), applied to the record before envelope detection as a zero-phase 4th-order Butterworth (scipy.signal.sosfiltfilt, giving an 8th-order magnitude roll-off). Default None: detect on the record as given.

Returns: An EnvelopeSpectrumResult. A finite record whose transform or squared envelope leaves the floating-point range gives an envelope, a mean level and a spectrum that are not finite; a squared envelope whose samples are finite but whose sum leaves the range gives a mean level that is not, and a spectrum bin the one-sided doubling takes past the range an amplitude that is not.

Raises

Exception When
ValueError If the inputs or parameters are invalid.
TypeError if nfft is a flag, a text or an array where a count goes, kind is not a text, or an edge of band is not a real number.
EnvelopeResult(
times: NDArray[np.float64],
envelope: NDArray[np.float64],
phase_rad: NDArray[np.float64],
instantaneous_frequency: NDArray[np.float64],
fs: float,
signal: Signal | NDArray[np.float64],
signal_fs: float,
decimation_factor: int,
*,
antialias: bool,
)

Envelope and instantaneous phase of a signal (B&P Chapter 13).

All output arrays share the (possibly decimated) time axis times; the original record is kept at full rate for plotting.

Attributes

Name Description
times Time axis of the outputs, in seconds.
envelope Envelope (Eq. 13.17).
phase_rad Unwrapped instantaneous phase , in radians (Eq. 13.18).
instantaneous_frequency , in Hz (Eq. 13.19), differentiated at full rate before any decimation.
fs Sample rate of the outputs, in Hz (signal_fs divided by decimation_factor).
signal The analysed record, at full rate, in the type it arrived as: a Signal when the input was one (in pascals and carrying calibration_factor=1.0 when the input was calibrated), a bare array otherwise.
signal_fs Sample rate of signal, in Hz.
decimation_factor Integer decimation applied to the outputs (1: none).
antialias Whether the decimation was anti-alias filtered.
EnvelopeResult.plot(
ax: None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> tuple[Axes, Axes]
EnvelopeResult.plot(
ax: Axes,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the signal with its envelope and the instantaneous frequency.

Parameters

Name Description
language Label language, "en" (default) or "es".
EnvelopeSpectrumResult(
frequencies: NDArray[np.float64],
amplitude: NDArray[np.float64],
mean_level: float,
kind: Literal['magnitude', 'squared'],
times: NDArray[np.float64],
envelope: NDArray[np.float64],
window: str | tuple[str | NumericArrayLike, ...],
*,
remove_dc: bool,
fs: float,
nfft: int,
band: tuple[float, float] | None = None,
)

Amplitude spectrum of a signal’s envelope (B&P Section 13.3).

Attributes

Name Description
frequencies Frequency axis of the spectrum, in Hz.
amplitude One-sided amplitude spectrum of the (mean-removed) envelope: the height of a discrete modulation line in the units of the envelope itself, exact when the modulation frequency falls on an analysis bin (off-bin lines read low by the taper’s scalloping loss; see envelope_spectrum). The zero-frequency bin is not doubled.
mean_level Mean of the detected envelope (the DC the remover of Figure 13.11 takes out): the carrier amplitude for kind="magnitude", its mean square for kind="squared".
kind "magnitude" (Hilbert envelope ) or "squared" (the book’s square-law detector, ).
times Time axis of envelope, in seconds.
envelope The detector output that was transformed, at full rate (before mean removal and tapering).
window The taper applied before the transform, a window name or a tuple of a name and its parameters, as given (a list parameter as a tuple).
remove_dc Whether the envelope mean was removed first.
fs Sample rate of the analysed record, in Hz.
nfft FFT length used.
band (low, high) edges of the zero-phase band-pass pre-filter applied before envelope detection, in Hz, or None (no pre-filter).
EnvelopeSpectrumResult.plot(
ax: None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> tuple[Axes, Axes]
EnvelopeSpectrumResult.plot(
ax: Axes,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the detected envelope and its amplitude spectrum.

With ax given, only the spectrum panel is drawn on it.

Parameters

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