@danielsimonjr/mathts-functions 0.33.0 → 0.35.0

package/dist/signal/fft.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Fast Fourier Transform (FFT)
+ *
+ * Implements the Cooley-Tukey radix-2 decimation-in-time FFT algorithm.
+ * For non-power-of-2 lengths, zero-pads to next power of 2.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Complex number representation for FFT
+ */
+export interface ComplexNumber {
+    re: number;
+    im: number;
+}
+/**
+ * FFT result containing the frequency spectrum
+ */
+export interface FFTResult {
+    /** Complex frequency components */
+    spectrum: ComplexNumber[];
+    /** Original signal length before padding */
+    originalLength: number;
+    /** Padded length (power of 2) */
+    paddedLength: number;
+}
+/**
+ * Create a complex number
+ */
+export declare function complex(re: number, im?: number): ComplexNumber;
+/**
+ * Complex conjugate
+ */
+export declare function complexConj(a: ComplexNumber): ComplexNumber;
+/**
+ * Complex magnitude
+ */
+export declare function complexAbs(a: ComplexNumber): number;
+/**
+ * Complex phase/argument
+ */
+export declare function complexArg(a: ComplexNumber): number;
+/**
+ * Compute the Fast Fourier Transform of a real or complex signal.
+ *
+ * Uses the Cooley-Tukey radix-2 decimation-in-time algorithm.
+ * Input is zero-padded to the next power of 2 if necessary.
+ *
+ * @param signal - Input signal (real numbers or complex numbers)
+ * @returns FFT result with spectrum and length info
+ *
+ * @example
+ * ```typescript
+ * // FFT of a real signal
+ * const signal = [1, 0, -1, 0];
+ * const result = fft(signal);
+ * console.log(result.spectrum); // Frequency components
+ *
+ * // FFT of a complex signal
+ * const complexSignal = [
+ *   { re: 1, im: 0 },
+ *   { re: 0, im: 1 },
+ * ];
+ * const result2 = fft(complexSignal);
+ * ```
+ */
+export declare function fft(signal: number[] | Float64Array | ComplexNumber[]): FFTResult;
+/**
+ * Compute the Inverse Fast Fourier Transform.
+ *
+ * Recovers the time-domain signal from its frequency spectrum.
+ *
+ * @param spectrum - Complex frequency spectrum
+ * @param originalLength - Optional: truncate result to this length
+ * @returns Recovered signal
+ *
+ * @example
+ * ```typescript
+ * // Round-trip test
+ * const signal = [1, 2, 3, 4];
+ * const result = fft(signal);
+ * const recovered = ifft(result.spectrum, result.originalLength);
+ * // recovered ≈ signal
+ * ```
+ */
+export declare function ifft(spectrum: ComplexNumber[], originalLength?: number): ComplexNumber[];
+/**
+ * Compute the real part of IFFT result
+ */
+export declare function ifftReal(spectrum: ComplexNumber[], originalLength?: number): number[];
+/**
+ * Compute the magnitude spectrum (|X(k)|)
+ */
+export declare function fftMagnitude(spectrum: ComplexNumber[]): number[];
+/**
+ * Compute the power spectrum (|X(k)|²)
+ */
+export declare function fftPower(spectrum: ComplexNumber[]): number[];
+/**
+ * Compute the phase spectrum (arg(X(k)))
+ */
+export declare function fftPhase(spectrum: ComplexNumber[]): number[];
+/**
+ * Compute FFT frequency bins for a given sample rate
+ *
+ * @param n - Number of FFT points
+ * @param sampleRate - Sample rate in Hz
+ * @returns Array of frequencies in Hz
+ */
+export declare function fftFrequencies(n: number, sampleRate?: number): number[];
+/**
+ * Compute the 2D FFT of a matrix
+ *
+ * @param matrix - 2D array of real or complex values
+ * @returns 2D frequency spectrum
+ */
+export declare function fft2(matrix: number[][] | ComplexNumber[][]): ComplexNumber[][];
+/**
+ * Compute the 2D inverse FFT
+ *
+ * @param spectrum - 2D frequency spectrum
+ * @returns 2D spatial domain result
+ */
+export declare function ifft2(spectrum: ComplexNumber[][]): ComplexNumber[][];
+/**
+ * Shift zero-frequency component to center of spectrum
+ *
+ * @param spectrum - FFT spectrum
+ * @returns Shifted spectrum
+ */
+export declare function fftshift<T>(spectrum: T[]): T[];
+/**
+ * Inverse of fftshift
+ */
+export declare function ifftshift<T>(spectrum: T[]): T[];
+//# sourceMappingURL=fft.d.ts.map

package/dist/signal/fft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fft.d.ts","sourceRoot":"","sources":["../../src/signal/fft.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,mCAAmC;IACnC,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,4CAA4C;IAC5C,cAAc,EAAE,MAAM,CAAC;IACvB,iCAAiC;IACjC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,GAAE,MAAU,GAAG,aAAa,CAEjE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,aAAa,GAAG,aAAa,CAE3D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,CAEnD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,CAEnD;AA0DD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,YAAY,GAAG,aAAa,EAAE,GAAG,SAAS,CAqChF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,IAAI,CAAC,QAAQ,EAAE,aAAa,EAAE,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,aAAa,EAAE,CAuBxF;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,aAAa,EAAE,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAGrF;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,MAAM,EAAE,CAEhE;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,MAAM,EAAE,CAE5D;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,MAAM,EAAE,CAE5D;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,GAAE,MAAU,GAAG,MAAM,EAAE,CAa1E;AAED;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,GAAG,aAAa,EAAE,EAAE,GAAG,aAAa,EAAE,EAAE,CAoC9E;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,QAAQ,EAAE,aAAa,EAAE,EAAE,GAAG,aAAa,EAAE,EAAE,CA8BpE;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAI9C;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAI/C"}

package/dist/signal/fir-smoothing.d.ts

@@ -0,0 +1,62 @@
+type Vec = readonly number[] | Float64Array;
+/** Polynomial/deconvolution division result: `signal = conv(divisor, quotient) + remainder`. */
+export interface DeconvolveResult {
+    quotient: number[];
+    remainder: number[];
+}
+/**
+ * FIR bandpass filter coefficients by the windowed-sinc method (Hamming
+ * window): `h[n] = (f2·sinc(f2·(n−M/2)) − f1·sinc(f1·(n−M/2)))·hamming[n]`,
+ * `M = numtaps−1`. `[f1, f2]` are cutoffs normalized to Nyquist (1 = Nyquist).
+ * This is the array-cutoff (bandpass) case the scalar-only `firwin` in
+ * `../signal-filter-extra.ts` didn't support (resolves the Phase-0 note).
+ */
+export declare function firwinBandpass(numtaps: number, cutoffs: readonly [number, number]): number[];
+/**
+ * Savitzky-Golay smoothing (`scipy.signal.savgol_filter`, default `mode='interp'`).
+ * For each interior position, fits a degree-`polyorder` polynomial (via the
+ * normal equations over a Vandermonde of the window offsets) to the centered
+ * `windowLength`-point window and takes the fitted value at the center. Edge
+ * points reuse the nearest full boundary window's fit, evaluated at the edge
+ * point's actual offset from that window's center (scipy's boundary handling).
+ * Exact on polynomials of degree <= `polyorder`.
+ */
+export declare function savgol(x: Vec, windowLength: number, polyorder: number): number[];
+/**
+ * FIR/polynomial deconvolution (`scipy.signal.deconvolve`): standard
+ * synthetic long division so that `signal = conv(divisor, quotient) + remainder`,
+ * with `quotient` of length `signal.length - divisor.length + 1` and
+ * `remainder` the same length as `signal` (zero when `divisor` exactly divides).
+ */
+export declare function deconvolve(signal: Vec, divisor: Vec): DeconvolveResult;
+/**
+ * Wiener adaptive filter (`scipy.signal.wiener`-style, per-sample noise
+ * estimate): local mean `m` and variance `v` over a sliding window of size
+ * `mysize` (same-length, zero-padded at the edges — matches `convDirect`'s
+ * `'same'` convention), noise power `= mean(v)`; output
+ * `m + max(0, v−noise)/max(v, noise)·(x−m)` (0 where both `v` and `noise` are 0).
+ */
+export declare function wiener(x: Vec, mysize?: number): number[];
+/**
+ * Least-squares linear-phase FIR design (`scipy.signal.firls`): `bands` is a
+ * flat list of `[lo, hi]` band-edge pairs (normalized to Nyquist, 1 = Nyquist)
+ * and `desired` the corresponding response values at those edges (linearly
+ * interpolated within each band; gaps between bands are unconstrained
+ * transition regions). Solves the normal equations of the cosine-basis
+ * representation of a symmetric (Type I odd-length / Type II even-length)
+ * linear-phase filter against a dense trapezoid-quadrature sampling of the
+ * specified bands, then maps the fitted basis coefficients back to taps.
+ */
+export declare function firls(numtaps: number, bands: readonly number[], desired: readonly number[]): number[];
+/**
+ * Parks-McClellan-style equiripple FIR design. **This is NOT the exact
+ * Remez-exchange algorithm** — it is Lawson's algorithm, an iteratively
+ * reweighted least squares (IRLS) scheme that approximates the minimax
+ * (Chebyshev) solution by repeatedly re-solving the `firls` normal equations
+ * with per-sample weights pushed up wherever the previous iteration's error
+ * was largest, converging toward (but not guaranteed to reach) a true
+ * equiripple response. Documented as approximate per the Task 3 spec.
+ */
+export declare function remez(numtaps: number, bands: readonly number[], desired: readonly number[]): number[];
+export {};
+//# sourceMappingURL=fir-smoothing.d.ts.map

package/dist/signal/fir-smoothing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fir-smoothing.d.ts","sourceRoot":"","sources":["../../src/signal/fir-smoothing.ts"],"names":[],"mappings":"AAUA,KAAK,GAAG,GAAG,SAAS,MAAM,EAAE,GAAG,YAAY,CAAC;AAG5C,gGAAgG;AAChG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAsCD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,EAAE,CAa5F;AA+BD;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CA4BhF;AAID;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,GAAG,gBAAgB,CAiBtE;AAID;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,SAAI,GAAG,MAAM,EAAE,CAsBnD;AAoHD;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CACnB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,MAAM,EAAE,CAUV;AAED;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CACnB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,MAAM,EAAE,CAkBV"}

package/dist/signal/iir-design.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Chebyshev I/II and elliptic (Cauer) IIR filter design, plus the supporting
+ * `zpk2sos`/`sosfilt`/`bilinear`/`buttord` utilities. Extends the Butterworth
+ * pipeline in `../signal-filter-extra.ts` with two more analog prototypes and
+ * reuses its shared zpk→transfer-function plumbing (`analogToDigital`,
+ * `polyFromRoots`). Matches `scipy.signal` — every coefficient set pinned
+ * against `scipy.signal.{cheby1,cheby2,ellip,bilinear,buttord}` (see
+ * `functions/tests/iir-design.test.ts`).
+ *
+ * The elliptic prototype (`ellipap`) follows Orfanidis, "Lecture Notes on
+ * Elliptic Filter Design" (the algorithm scipy itself implements): the filter
+ * degree equation is solved in closed form via the theta-function nome
+ * expansion (`ellipdeg`), and the "arc Jacobi sc" root (`arcJacSc1`) via the
+ * descending Landen transformation (`arcJacSn`) — no numerical optimizer is
+ * needed. Reuses the repo's existing AGM-based `ellipticKScalar` and
+ * `jacobiSN`/`jacobiCN`/`jacobiDN` (Phase 5 special functions, `m = k²`
+ * convention, matching scipy's `ellipk`/`ellipj`).
+ */
+import { Complex } from '@danielsimonjr/mathts-core';
+import { type FilterBtype } from '../signal-filter-extra.js';
+type Vec = readonly number[] | Float64Array;
+/**
+ * Chebyshev Type I digital IIR filter design — equiripple in the passband, `rp`
+ * dB of ripple. `Wn` is the cutoff (scalar) or `[low, high]` band edges,
+ * normalized to Nyquist. Matches `scipy.signal.cheby1(N, rp, Wn, btype)`.
+ */
+export declare function cheby1(N: number, rp: number, Wn: number | readonly number[], btype?: FilterBtype): {
+    b: number[];
+    a: number[];
+};
+/**
+ * Chebyshev Type II digital IIR filter design — equiripple in the stopband,
+ * `rs` dB of stopband attenuation, monotone passband. `Wn` is the cutoff
+ * (scalar) or `[low, high]` band edges, normalized to Nyquist. Matches
+ * `scipy.signal.cheby2(N, rs, Wn, btype)`.
+ */
+export declare function cheby2(N: number, rs: number, Wn: number | readonly number[], btype?: FilterBtype): {
+    b: number[];
+    a: number[];
+};
+/**
+ * Elliptic (Cauer) digital IIR filter design — equiripple in both passband
+ * (`rp` dB) and stopband (`rs` dB); the steepest roll-off of the four classical
+ * IIR families for a given order. `Wn` is the cutoff (scalar) or `[low, high]`
+ * band edges, normalized to Nyquist. Matches `scipy.signal.ellip(N, rp, rs, Wn,
+ * btype)` exactly (verified against `scipy.signal` 1.17.1 — see
+ * `functions/tests/iir-design.test.ts`); this is a full port of scipy's
+ * closed-form (nome-based) elliptic design, not an approximation.
+ */
+export declare function ellip(N: number, rp: number, rs: number, Wn: number | readonly number[], btype?: FilterBtype): {
+    b: number[];
+    a: number[];
+};
+/**
+ * Analog-to-digital bilinear (Tustin) transform of a transfer function: given
+ * `H(s) = b(s)/a(s)` (coefficients highest-degree-first), substitutes
+ * `s = 2·fs·(z−1)/(z+1)` to produce the digital `{ b, a }` (no pre-warping is
+ * done — the caller pre-warps `fs`/critical frequencies if needed). Matches
+ * `scipy.signal.bilinear(b, a, fs)`.
+ */
+export declare function bilinear(bIn: Vec, aIn: Vec, fs: number): {
+    b: number[];
+    a: number[];
+};
+/**
+ * Minimum Butterworth filter order (and the corresponding `-3dB`-ish natural
+ * frequency `Wn`) meeting a passband/stopband spec, for a digital lowpass
+ * (`wp < ws`) or highpass (`wp > ws`) filter. `wp`/`ws` are normalized to
+ * Nyquist (0..1); `gpass`/`gstop` are in dB. Matches
+ * `scipy.signal.buttord(wp, ws, gpass, gstop)` (scalar/digital case only —
+ * the bandpass/bandstop array form is not implemented).
+ */
+export declare function buttord(wp: number, ws: number, gpass: number, gstop: number): {
+    N: number;
+    Wn: number;
+};
+type ZpkRoot = number | Complex;
+/**
+ * Group zeros/poles/gain into cascaded second-order sections:
+ * `[[b0,b1,b2,a0,a1,a2], …]`, each a monic-denominator biquad (`a0 = 1`) with
+ * the overall gain folded into the first section's numerator. `z` is
+ * zero-padded (roots at the origin) if shorter than `p`. Matches
+ * `scipy.signal.zpk2sos` in effect (the two decompositions can differ in
+ * pairing order, but the resulting cascaded transfer function is identical).
+ */
+export declare function zpk2sos(z: readonly ZpkRoot[], p: readonly ZpkRoot[], k: number): number[][];
+/**
+ * Apply a cascade of second-order sections (`[[b0,b1,b2,a0,a1,a2], …]`, as
+ * produced by `zpk2sos`) to `x`, each biquad in direct-form-II transposed.
+ * Matches `scipy.signal.sosfilt(sos, x)`.
+ */
+export declare function sosfilt(sos: readonly (readonly number[])[], x: Vec): number[];
+export {};
+//# sourceMappingURL=iir-design.d.ts.map

package/dist/signal/iir-design.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"iir-design.d.ts","sourceRoot":"","sources":["../../src/signal/iir-design.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,EAOL,KAAK,WAAW,EACjB,MAAM,2BAA2B,CAAC;AAKnC,KAAK,GAAG,GAAG,SAAS,MAAM,EAAE,GAAG,YAAY,CAAC;AAoB5C;;;;GAIG;AACH,wBAAgB,MAAM,CACpB,CAAC,EAAE,MAAM,EACT,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EAC9B,KAAK,GAAE,WAAmB,GACzB;IAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAI9B;AAgCD;;;;;GAKG;AACH,wBAAgB,MAAM,CACpB,CAAC,EAAE,MAAM,EACT,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EAC9B,KAAK,GAAE,WAAmB,GACzB;IAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAI9B;AAkJD;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CACnB,CAAC,EAAE,MAAM,EACT,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EAC9B,KAAK,GAAE,WAAmB,GACzB;IAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAK9B;AA4BD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,GAAG;IAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CA8BrF;AAID;;;;;;;GAOG;AACH,wBAAgB,OAAO,CACrB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAc3B;AAID,KAAK,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAoDhC;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,SAAS,OAAO,EAAE,EAAE,CAAC,EAAE,SAAS,OAAO,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,CAmB3F;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,GAAG,GAAG,MAAM,EAAE,CAS7E"}

package/dist/signal/spectral-peaks.d.ts

@@ -0,0 +1,115 @@
+/** Options for {@link findPeaks}. */
+export interface FindPeaksOptions {
+    /** Minimum peak value to keep. */
+    height?: number;
+    /** Minimum index separation between kept peaks (greedily keeps the taller peak). */
+    distance?: number;
+    /** Minimum topographic prominence to keep (see {@link peakWidths} for the definition). */
+    prominence?: number;
+}
+/**
+ * Find strict local-maxima peak indices in `x` (`x[i-1] < x[i] > x[i+1]`), then
+ * optionally filter by minimum `height`, minimum index `distance` (greedily keeping
+ * the taller peak of any too-close pair), and/or minimum topographic `prominence` —
+ * `scipy.signal.find_peaks`.
+ *
+ * @param x - Input signal
+ * @param opts - `{ height?, distance?, prominence? }`
+ * @returns Ascending indices of the surviving peaks
+ */
+export declare function findPeaks(x: readonly number[], opts?: FindPeaksOptions): number[];
+/**
+ * Width (in samples) of each peak at `relHeight` down from the peak toward its
+ * topographic base (see {@link peakProminence}), with linearly-interpolated crossing
+ * points — `scipy.signal.peak_widths`.
+ *
+ * @param x - Input signal
+ * @param peaks - Peak indices (e.g. from {@link findPeaks})
+ * @param relHeight - Fraction of the prominence to descend (default 0.5, i.e. FWHM-style)
+ * @returns Width per peak, same order as `peaks`
+ */
+export declare function peakWidths(x: readonly number[], peaks: readonly number[], relHeight?: number): number[];
+/** Options shared by {@link csd} and {@link coherence}. */
+export interface CsdOptions {
+    /** Segment length (default `min(256, x.length, y.length)`). */
+    nperseg?: number;
+    /** Samples of overlap between segments (default `floor(nperseg/2)`). */
+    noverlap?: number;
+    /** Window applied to each segment (default `'hann'`) — see {@link windowFunction}. */
+    window?: string;
+    /** Sample rate in Hz, used to scale frequencies and power (default 1). */
+    fs?: number;
+}
+/**
+ * Cross-spectral density of `x` and `y` via Welch's overlapped-segment-averaging
+ * method (segment, window, FFT, average `X·conj(Y)`) — `scipy.signal.csd`.
+ *
+ * @param x - First signal
+ * @param y - Second signal
+ * @param opts - `{ nperseg?, noverlap?, window?, fs? }`
+ * @returns `{ frequencies, power }` — `power` is the magnitude of the averaged
+ *   cross spectrum at each frequency bin
+ */
+export declare function csd(x: readonly number[], y: readonly number[], opts?: CsdOptions): {
+    frequencies: number[];
+    power: number[];
+};
+/**
+ * Magnitude-squared coherence between `x` and `y`: `|Pxy|² / (Pxx·Pyy)`, per Welch
+ * frequency bin — `scipy.signal.coherence`. Values lie in `[0, 1]`.
+ *
+ * @param x - First signal
+ * @param y - Second signal
+ * @param opts - `{ nperseg?, noverlap?, window?, fs? }`
+ * @returns `{ frequencies, coherence }`
+ */
+export declare function coherence(x: readonly number[], y: readonly number[], opts?: CsdOptions): {
+    frequencies: number[];
+    coherence: number[];
+};
+/** Options for {@link stft} / {@link istft} — must match between the two calls. */
+export interface StftOptions {
+    /** Frame length (default 256). */
+    nperseg?: number;
+    /** Samples of overlap between frames (default `floor(nperseg/2)`). */
+    noverlap?: number;
+    /** Window applied to each frame (default `'hann'`) — see {@link windowFunction}. */
+    window?: string;
+}
+/** `stft`'s output: one row per frame, one column per (non-redundant-truncated) frequency bin. */
+export interface StftResult {
+    re: number[][];
+    im: number[][];
+}
+/**
+ * Short-time Fourier transform: windowed, overlapping frames, each FFT'd independently
+ * — `scipy.signal.stft` (magnitude/phase convention; frames are not scaled).
+ *
+ * @param x - Input signal
+ * @param opts - `{ nperseg?, noverlap?, window? }`
+ * @returns `{ re, im }`, each `number[frame][bin]`
+ */
+export declare function stft(x: readonly number[], opts?: StftOptions): StftResult;
+/**
+ * Inverse short-time Fourier transform via overlap-add: each frame is inverse-FFT'd
+ * back to `nperseg` samples, re-windowed, and accumulated; the accumulation is
+ * normalized by the running sum of squared window values (the standard
+ * constant-overlap-add / COLA normalization), so reconstruction is exact in the
+ * interior wherever the window's overlap sum is nonzero — `scipy.signal.istft`.
+ *
+ * @param S - `{ re, im }` as returned by {@link stft}
+ * @param opts - `{ nperseg?, noverlap?, window? }` — must match the `stft` call
+ * @returns Reconstructed signal
+ */
+export declare function istft(S: StftResult, opts?: StftOptions): number[];
+/**
+ * Downsample `x` by an integer factor `q`: apply a Butterworth anti-alias lowpass
+ * (order 4, cutoff `min(0.8/q, 0.99)` of Nyquist) with zero-phase `filtfilt`, then
+ * take every `q`-th sample — `scipy.signal.decimate` (IIR mode).
+ *
+ * @param x - Input signal
+ * @param q - Downsampling factor (positive integer)
+ * @returns Downsampled signal, length `ceil(x.length / q)`
+ */
+export declare function decimate(x: readonly number[], q: number): number[];
+//# sourceMappingURL=spectral-peaks.d.ts.map

package/dist/signal/spectral-peaks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spectral-peaks.d.ts","sourceRoot":"","sources":["../../src/signal/spectral-peaks.ts"],"names":[],"mappings":"AAoBA,qCAAqC;AACrC,MAAM,WAAW,gBAAgB;IAC/B,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0FAA0F;IAC1F,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA2DD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAmBjF;AAyBD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACxB,CAAC,EAAE,SAAS,MAAM,EAAE,EACpB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,SAAS,SAAM,GACd,MAAM,EAAE,CAQV;AAMD,2DAA2D;AAC3D,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAgED;;;;;;;;;GASG;AACH,wBAAgB,GAAG,CACjB,CAAC,EAAE,SAAS,MAAM,EAAE,EACpB,CAAC,EAAE,SAAS,MAAM,EAAE,EACpB,IAAI,CAAC,EAAE,UAAU,GAChB;IAAE,WAAW,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAI5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CACvB,CAAC,EAAE,SAAS,MAAM,EAAE,EACpB,CAAC,EAAE,SAAS,MAAM,EAAE,EACpB,IAAI,CAAC,EAAE,UAAU,GAChB;IAAE,WAAW,EAAE,MAAM,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,CAahD;AAMD,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,kGAAkG;AAClG,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC;IACf,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,UAAU,CAoBzE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,MAAM,EAAE,CA6BjE;AAMD;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,SAAS,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAclE"}

package/dist/signal/wavelets.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Phase 6 Task 4 — inverse DWT, multilevel wavedec/waverec (perfect
+ * reconstruction), and the continuous wavelet transform (CWT).
+ *
+ * `idwt`/`wavedec`/`waverec` must invert the existing `dwt` (`../typed/signal.ts`)
+ * exactly, so they match its Haar convention bit-for-bit: analysis filters
+ * scaled by `s = 1/sqrt(2)`, `approx[i] = s*(x[2i]+x[2i+1])`,
+ * `detail[i] = s*(x[2i]-x[2i+1])`. Haar's synthesis (reconstruction) filters
+ * are the time-reverse of its analysis filters — for a symmetric 2-tap filter
+ * that reversal is a no-op, so the closed-form inverse below is exact:
+ * `x[2i] = s*(approx[i]+detail[i])`, `x[2i+1] = s*(approx[i]-detail[i])`.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Inverse single-level discrete wavelet transform. Upsamples `approx`/`detail`
+ * and combines them with the Haar synthesis filters, exactly inverting `dwt`.
+ *
+ * @param approx - Approximation (low-pass) coefficients
+ * @param detail - Detail (high-pass) coefficients, same length as `approx`
+ * @param wavelet - Wavelet name (currently only 'haar'/'db1', matching `dwt`)
+ * @returns Reconstructed signal, length `2 * approx.length`
+ */
+export declare function idwt(approx: number[], detail: number[], wavelet?: string): number[];
+/**
+ * Multilevel discrete wavelet decomposition: repeatedly applies `dwt` to the
+ * approximation coefficients.
+ *
+ * @param x - Input signal
+ * @param wavelet - Wavelet name (passed through to `dwt`)
+ * @param level - Number of decomposition levels (>= 1)
+ * @returns `[cA_level, cD_level, cD_{level-1}, ..., cD_1]` (pywt order)
+ */
+export declare function wavedec(x: number[], wavelet?: string, level?: number): number[][];
+/**
+ * Inverse of `wavedec`: repeatedly applies `idwt` from the coarsest level
+ * (`coeffs[0]` = cA_level) up to the finest detail (`coeffs[coeffs.length-1]`
+ * = cD_1), reconstructing the original signal.
+ *
+ * @param coeffs - Coefficient arrays as returned by `wavedec`
+ * @param wavelet - Wavelet name (passed through to `idwt`)
+ * @returns Reconstructed signal
+ */
+export declare function waverec(coeffs: number[][], wavelet?: string): number[];
+/**
+ * Continuous wavelet transform: convolves `x` with a discretized, normalized
+ * wavelet at each requested scale.
+ *
+ * @param x - Input signal
+ * @param scales - Wavelet scales to evaluate (each > 0)
+ * @param wavelet - 'ricker' (Mexican-hat, default) or 'morlet'
+ * @returns `scales.length` x `x.length` matrix, row `i` = CWT at `scales[i]`
+ */
+export declare function cwt(x: number[], scales: number[], wavelet?: string): number[][];
+//# sourceMappingURL=wavelets.d.ts.map

package/dist/signal/wavelets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wavelets.d.ts","sourceRoot":"","sources":["../../src/signal/wavelets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,MAAe,GAAG,MAAM,EAAE,CAgB3F;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,MAAe,EAAE,KAAK,GAAE,MAAU,GAAG,MAAM,EAAE,EAAE,CAc5F;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,GAAE,MAAe,GAAG,MAAM,EAAE,CAU9E;AA2BD;;;;;;;;GAQG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,MAAiB,GAAG,MAAM,EAAE,EAAE,CAYzF"}

package/dist/signal-filter-extra.d.ts

@@ -1,4 +1,12 @@
+/**
+ * Digital filter design + application (Wave D / remaining). FIR window design
+ * (`firwin`), IIR Butterworth design (`butter`), the direct-form filter (`lfilter`),
+ * and zero-phase filtering (`filtfilt`). Matches `scipy.signal`. `butter` reuses the
+ * core `Complex` type for the analog-pole bilinear-transform pipeline.
+ */
+import { Complex } from '@danielsimonjr/mathts-core';
 type Vec = readonly number[] | Float64Array;
+export declare const sinc: (x: number) => number;
 /**
  * FIR lowpass filter coefficients by the windowed-sinc method (Hamming window,
  * normalized to unit DC gain) — `scipy.signal.firwin(numtaps, cutoff)` with the
@@ -22,12 +30,43 @@ export declare function lfilterZi(b: Vec, a: Vec): number[];
  * magnitude response is applied with no phase distortion.
  */
 export declare function filtfilt(b: Vec, a: Vec, x: Vec): number[];
+export declare const cAdd: (p: Complex, q: Complex) => Complex;
+export declare const cSub: (p: Complex, q: Complex) => Complex;
+export declare const cMul: (p: Complex, q: Complex) => Complex;
+export declare const cDiv: (p: Complex, q: Complex) => Complex;
+/** Scale a Complex by a real number (`Complex.mul` only accepts `Scalar`, not `number`). */
+export declare const cScale: (p: Complex, s: number) => Complex;
+/** Real polynomial coefficients (highest degree first) of ∏(x − rₖ). */
+export declare function polyFromRoots(roots: Complex[]): number[];
+/** Analog lowpass prototype: zeros, poles, gain (cutoff normalized to 1 rad/s). */
+export interface AnalogProto {
+    z: Complex[];
+    p: Complex[];
+    k: number;
+}
+export type FilterBtype = 'low' | 'high' | 'bandpass' | 'bandstop';
+/** zpk → transfer-function coefficients (scipy `zpk2tf`). */
+export declare function zpkToTf(z: Complex[], p: Complex[], k: number): {
+    b: number[];
+    a: number[];
+};
+/**
+ * Digital IIR filter design pipeline shared by butter/cheby1/cheby2/ellip:
+ * pre-warp `Wn` → frequency-transform the analog lowpass prototype (`proto`,
+ * cutoff normalized to 1 rad/s) to the requested `btype` → bilinear transform →
+ * zpk2tf. Matches `scipy.signal.iirfilter`'s internal pipeline (fs = 2 convention).
+ */
+export declare function analogToDigital(proto: AnalogProto, Wn: number | readonly number[], btype: FilterBtype): {
+    b: number[];
+    a: number[];
+};
 /**
  * Butterworth IIR filter design — returns `{ b, a }` transfer-function coefficients.
- * `N` is the order, `Wn` the cutoff normalized to Nyquist (0..1). Lowpass only
- * (`btype='low'`, the common case). Matches `scipy.signal.butter(N, Wn)`.
+ * `N` is the order, `Wn` the cutoff (scalar) or `[low, high]` band edges, normalized
+ * to Nyquist (0..1). `btype` defaults to `'low'` (matches the original 2-arg call
+ * unchanged). Matches `scipy.signal.butter(N, Wn, btype)`.
  */
-export declare function butter(N: number, Wn: number): {
+export declare function butter(N: number, Wn: number | readonly number[], btype?: FilterBtype): {
     b: number[];
     a: number[];
 };

package/dist/signal-filter-extra.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"signal-filter-extra.d.ts","sourceRoot":"","sources":["../src/signal-filter-extra.ts"],"names":[],"mappings":"AAYA,KAAK,GAAG,GAAG,SAAS,MAAM,EAAE,GAAG,YAAY,CAAC;AAK5C;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAahE;AAkCD;;;GAGG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,MAAM,EAAE,CAExD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,MAAM,EAAE,CAqBlD;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,MAAM,EAAE,CAqBzD;AAuBD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG;IAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CA4B1E"}
+{"version":3,"file":"signal-filter-extra.d.ts","sourceRoot":"","sources":["../src/signal-filter-extra.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAMrD,KAAK,GAAG,GAAG,SAAS,MAAM,EAAE,GAAG,YAAY,CAAC;AAG5C,eAAO,MAAM,IAAI,GAAI,GAAG,MAAM,KAAG,MAA+D,CAAC;AAEjG;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAahE;AAkCD;;;GAGG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,MAAM,EAAE,CAExD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,MAAM,EAAE,CAuBlD;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,MAAM,EAAE,CA+BzD;AAMD,eAAO,MAAM,IAAI,GAAI,GAAG,OAAO,EAAE,GAAG,OAAO,KAAG,OAAmB,CAAC;AAClE,eAAO,MAAM,IAAI,GAAI,GAAG,OAAO,EAAE,GAAG,OAAO,KAAG,OAAmB,CAAC;AAClE,eAAO,MAAM,IAAI,GAAI,GAAG,OAAO,EAAE,GAAG,OAAO,KAAG,OAAwB,CAAC;AACvE,eAAO,MAAM,IAAI,GAAI,GAAG,OAAO,EAAE,GAAG,OAAO,KAAG,OAAsB,CAAC;AACrE,4FAA4F;AAC5F,eAAO,MAAM,MAAM,GAAI,GAAG,OAAO,EAAE,GAAG,MAAM,KAAG,OAAqC,CAAC;AAErF,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,EAAE,CAWxD;AAED,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,CAAC,EAAE,OAAO,EAAE,CAAC;IACb,CAAC,EAAE,OAAO,EAAE,CAAC;IACb,CAAC,EAAE,MAAM,CAAC;CACX;AAED,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;AAoFnE,6DAA6D;AAC7D,wBAAgB,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG;IAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAE3F;AAgBD;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,WAAW,EAClB,EAAE,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EAC9B,KAAK,EAAE,WAAW,GACjB;IAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAgB9B;AAaD;;;;;GAKG;AACH,wBAAgB,MAAM,CACpB,CAAC,EAAE,MAAM,EACT,EAAE,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EAC9B,KAAK,GAAE,WAAmB,GACzB;IAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAG9B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danielsimonjr/mathts-functions",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "description": "Mathematical functions for MathTS - arithmetic, algebra, trigonometry, statistics, and more",
   "author": "Daniel Simon Jr.",
   "license": "MIT",