// 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