56 lines
2.7 KiB
Go
56 lines
2.7 KiB
Go
|
// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
|
||
|
|
// SPDX-License-Identifier: MIT
|
||
|
|
|
||
|
|
// Package signal carries the transforms, spectra, filters and stencils
|
||
|
|
// of the library: the Fourier, cosine, sine and wavelet transforms, the
|
||
|
|
// spectral estimators, IIR filter design and application, sample-rate
|
||
|
|
// conversion, the Hilbert envelope, convolution and pooling, rank
|
||
|
|
// filters, spatial stencils, state-space estimation and time-series
|
||
|
|
// models.
|
||
|
|
//
|
||
|
|
// # Shape of the API
|
||
|
|
//
|
||
|
|
// Every call takes whole arrays and returns whole arrays. Arrays are
|
||
|
|
// immutable values, so no call modifies its input: a transform that
|
||
|
|
// needs scratch space runs on a private copy.
|
||
|
|
//
|
||
|
|
// The package holds no state between calls. There is no streaming
|
||
|
|
// filter object and nothing to plan or reuse: a design returns the
|
||
|
|
// direct-form coefficients b and a, and the caller hands those to
|
||
|
|
// FilterApply for one pass or to Filtfilt for a zero-phase forward and
|
||
|
|
// backward sweep. A wavelet family is named at every call for the same
|
||
|
|
// reason.
|
||
|
|
//
|
||
|
|
// # What the package does not do
|
||
|
|
//
|
||
|
|
// - No second-order-section cascade. Every design returns direct-form
|
||
|
|
// coefficients, and direct-form filtering loses digits as the order
|
||
|
|
// climbs; past roughly order eight the caller is expected to split
|
||
|
|
// the design into second-order sections.
|
||
|
|
// - No complex input to the estimators and resamplers. WelchPSD,
|
||
|
|
// Spectrogram, STFT, LombScargle, Decimate, Resample,
|
||
|
|
// AnalyticSignal and the Kalman filters refuse a complex array. The
|
||
|
|
// Fourier transforms are the complex path: FFT, IFFT, FFTN and
|
||
|
|
// their relatives accept a real or a complex array, while RFFT and
|
||
|
|
// IRFFT are the real-input pair.
|
||
|
|
// - No batched or multi-channel spectral work. WelchPSD, STFT,
|
||
|
|
// Spectrogram, the resamplers, the filter application and the
|
||
|
|
// wavelet transforms take one rank-1 signal per call, so a stack of
|
||
|
|
// channels is looped by the caller.
|
||
|
|
// - No statistical distributions, hypothesis tests or regressions.
|
||
|
|
// Those live in the stats package; the models this package fits are
|
||
|
|
// the autoregression, the ARMA model and the state-space model.
|
||
|
|
//
|
||
|
|
// # Conventions
|
||
|
|
//
|
||
|
|
// A sample rate is named fs and given in hertz. A cutoff or a band edge
|
||
|
|
// lies strictly inside (0, fs/2). A design returns the coefficients in
|
||
|
|
// the u = z⁻¹ convention with the denominator leading a one, so a[0] is
|
||
|
|
// 1 and a[1] is the first feedback tap. A spectral estimate is
|
||
|
|
// one-sided unless the call says otherwise, with the doubling applied
|
||
|
|
// between DC and the Nyquist bin. A wavelet transform packs its
|
||
|
|
// coefficients as [A_levels, D_levels, …, D_1], the deepest
|
||
|
|
// approximation first and the finest detail last, the layout DWT and
|
||
|
|
// DaubechiesDWT share.
|
||
|
|
package signal
|