feat: initial release

Assisted-by: GLM 5.3 Flash

signal/doc.go

@@ -0,0 +1,55 @@
+// 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