Signal Processing Toolbox (signal)

Digital filter design (IIR/FIR), filter implementation (filtfilt/sosfilt), spectral analysis (FFT/pwelch/spectrogram), windows, and waveforms. More...

Files
file	convolution.hpp
file	extras.hpp
file	buffer.hpp
file	filter.hpp
file	poly_utils.hpp
file	quantizers.hpp
file	shiftdata.hpp
file	sosfilt.hpp
file	spec_driven.hpp
file	frequency_response.hpp
file	predicates.hpp
file	responses.hpp
file	unwrap.hpp
file	analog_filters.hpp
file	filter_design.hpp
file	iir_designs.hpp
file	conversions.hpp
file	conversions_extras.hpp
file	dbconv.hpp
file	findpeaks.hpp
file	pulse_metrics.hpp
file	sig_utils.hpp
file	signal_stats.hpp
file	sigroi.hpp
	Signal-region-of-interest utilities.
file	vibration.hpp
file	extras.hpp
file	multirate.hpp
file	medfilt.hpp
file	sgolay.hpp
file	periodogram_pwelch.hpp
file	signal_modeling.hpp
file	spectral_metrics.hpp
	Spectral measurement functions.
file	spectrogram.hpp
file	dct.hpp
file	extras.hpp
file	fft.hpp
file	fwht.hpp
file	goertzel.hpp
file	hilbert.hpp
file	transform_helpers.hpp
file	waveform_generation.hpp
file	windows.hpp

Classes
struct	nk::signal::Fir2Options
	Optional arguments for fir2. More...
struct	nk::signal::CusumResult
	Result of cusum — [iupper, ilower, uppersum, lowersum]. More...

Enumerations
enum class	nk::signal::FilterType { FilterType::Lowpass , FilterType::Highpass , FilterType::Bandpass , FilterType::Bandstop }
	Filter response type for IIR designs. More...

Functions
Value	nk::signal::conv (const Value &a, const Value &b, const std::string &shape="full", std::pmr::memory_resource *mr=nullptr)
	1-D convolution of two real vectors.
std::tuple< Value, Value >	nk::signal::deconv (const Value &b, const Value &a, std::pmr::memory_resource *mr=nullptr)
	Polynomial long-division: b = conv(a, q) + r.
std::tuple< Value, Value >	nk::signal::xcorr (const Value &x, const Value &y, std::pmr::memory_resource *mr=nullptr)
	Cross-correlation of two real vectors.
std::tuple< Value, Value >	nk::signal::xcorr (const Value &x, std::pmr::memory_resource *mr=nullptr)
	Auto-correlation — equivalent to xcorr(x, x).
std::tuple< Value, Value >	nk::signal::xcov (const Value &x, const Value &y, int maxlag, const std::string &scaleopt, std::pmr::memory_resource *mr=nullptr)
	Cross-covariance of two real vectors.
std::tuple< Value, Value >	nk::signal::xcov (const Value &x, const Value &y, std::pmr::memory_resource *mr=nullptr)
	Cross-covariance with full lags and "none" scaling.
std::tuple< Value, Value >	nk::signal::xcov (const Value &x, std::pmr::memory_resource *mr=nullptr)
	Auto-covariance — equivalent to xcov(x, x).
Value	nk::signal::conv2 (const Value &A, const Value &B, const std::string &shape="full", std::pmr::memory_resource *mr=nullptr)
	2-D convolution of two real matrices.
Value	nk::signal::filter2 (const Value &h, const Value &X, const std::string &shape="same", std::pmr::memory_resource *mr=nullptr)
	2-D filter — filter2(h, X[, shape]).
Value	nk::signal::convn (const Value &A, const Value &B, const std::string &shape="full", std::pmr::memory_resource *mr=nullptr)
	N-D convolution.
Value	nk::signal::cconv (const Value &x, const Value &y, size_t n=0, std::pmr::memory_resource *mr=nullptr)
	Circular (cyclic) convolution of two real vectors.
Value	nk::signal::convmtx (const Value &h, size_t n, std::pmr::memory_resource *mr=nullptr)
	Convolution matrix for an impulse response.
Value	nk::signal::xcorr2 (const Value &A, const Value &B, std::pmr::memory_resource *mr=nullptr)
	2-D cross-correlation of two real matrices.
long	nk::signal::finddelay (const Value &x, const Value &y, long max_lag=0, std::pmr::memory_resource *mr=nullptr)
	Estimate the integer delay between two signals.
std::tuple< Value, Value >	nk::signal::alignsignals (const Value &x, const Value &y, long max_lag=0, std::pmr::memory_resource *mr=nullptr)
	Align two signals by zero-padding the leading one.
Value	nk::signal::buffer (const Value &x, int n, int p=0, const Value &opt=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Partition x into frames of length n.
std::tuple< Value, Value >	nk::signal::buffer2 (const Value &x, int n, int p=0, const Value &opt=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	2-output form: [Y, Z] = buffer(x, n, p, opt).
Value	nk::signal::filter (const Value &b, const Value &a, const Value &x, std::pmr::memory_resource *mr=nullptr)
	Direct-form II transposed IIR / FIR filter.
Value	nk::signal::filtfilt (const Value &b, const Value &a, const Value &x, std::pmr::memory_resource *mr=nullptr)
	Zero-phase forward-backward filtering.
Value	nk::signal::polyscale (const Value &p, const Value &scale, std::pmr::memory_resource *mr=nullptr)
	Radial scaling of polynomial roots (y = polyscale(p, scale)).
Value	nk::signal::polystab (const Value &a, std::pmr::memory_resource *mr=nullptr)
	Stabilise a polynomial (b = polystab(a)).
Value	nk::signal::uencode (const Value &u, int N, double V=1.0, bool signedOutput=false, std::pmr::memory_resource *mr=nullptr)
	Quantise and encode u as N-bit integers (y = uencode(u, N, V, type)).
Value	nk::signal::udecode (const Value &u, int N, double V=1.0, bool wrapOnOverflow=false, std::pmr::memory_resource *mr=nullptr)
	Decode integer data back to double with peak ±V (y = udecode(u, N, V, overflow)).
std::tuple< Value, Value, Value >	nk::signal::shiftdata (const Value &x, int dim=0, std::pmr::memory_resource *mr=nullptr)
	Move a chosen dimension to the leading axis for dim-aware processing.
Value	nk::signal::unshiftdata (const Value &x, const Value &perm, const Value &nshifts, std::pmr::memory_resource *mr=nullptr)
	Inverse of shiftdata.
Value	nk::signal::sosfilt (const Value &sos, const Value &x, std::pmr::memory_resource *mr=nullptr)
	Apply a second-order-sections cascade to a signal.
Value	nk::signal::sosfiltfilt (const Value &sos, const Value &x, std::pmr::memory_resource *mr=nullptr)
	Zero-phase forward + backward SOS cascade.
Value	nk::signal::lowpass (const Value &x, double fpass, double fs, int order=8, std::pmr::memory_resource *mr=nullptr)
	One-call zero-phase Butterworth lowpass filter.
Value	nk::signal::highpass (const Value &x, double fpass, double fs, int order=8, std::pmr::memory_resource *mr=nullptr)
	One-call zero-phase Butterworth highpass filter.
Value	nk::signal::bandpass (const Value &x, double flo, double fhi, double fs, int order=8, std::pmr::memory_resource *mr=nullptr)
	One-call zero-phase Butterworth bandpass filter.
Value	nk::signal::bandstop (const Value &x, double flo, double fhi, double fs, int order=8, std::pmr::memory_resource *mr=nullptr)
	One-call zero-phase Butterworth bandstop (notch) filter.
std::tuple< Value, Value >	nk::signal::freqz (const Value &b, const Value &a, size_t npts=512, std::pmr::memory_resource *mr=nullptr, bool whole=false, double fs=0.0)
	Frequency response of a digital filter.
std::tuple< Value, Value >	nk::signal::freqz (const Value &b, const Value &a, const Value &wvec, std::pmr::memory_resource *mr=nullptr)
	freqz(b, a, w): response at the GIVEN normalised radian frequencies (the vector-w form).
std::tuple< Value, Value >	nk::signal::phasez (const Value &b, const Value &a, size_t npts=512, std::pmr::memory_resource *mr=nullptr, double fs=0.0)
	Unwrapped phase response of a digital filter.
std::tuple< Value, Value >	nk::signal::grpdelay (const Value &b, const Value &a, size_t npts=512, std::pmr::memory_resource *mr=nullptr, double fs=0.0)
	Group delay of a digital filter.
bool	nk::signal::isfir (const Value &b)
	Detects whether a digital filter is FIR.
bool	nk::signal::isfir (const Value &b, const Value &a)
	Detects FIR with explicit denominator.
bool	nk::signal::isstable (const Value &b, const Value &a, std::pmr::memory_resource *mr=nullptr)
	Detects whether a digital filter is BIBO-stable.
bool	nk::signal::isminphase (const Value &b, const Value &a, std::pmr::memory_resource *mr=nullptr)
	Detects whether a digital filter is minimum-phase.
bool	nk::signal::ismaxphase (const Value &b, const Value &a, std::pmr::memory_resource *mr=nullptr)
	Detects whether a digital filter is maximum-phase.
bool	nk::signal::islinphase (const Value &b, const Value &a)
	Detects whether a digital filter has linear phase.
bool	nk::signal::isallpass (const Value &b, const Value &a)
	Detects whether a digital filter is all-pass.
int	nk::signal::filtord (const Value &b)
	Filter order.
int	nk::signal::filtord (const Value &b, const Value &a)
	Filter order with explicit denominator (n = filtord(b, a)).
int	nk::signal::firtype (const Value &b)
	FIR filter type classification (1–4).
double	nk::signal::filternorm (const Value &b, const Value &a, double pnorm=2.0, std::pmr::memory_resource *mr=nullptr)
	L_p norm of a digital filter's frequency response.
std::tuple< Value, Value >	nk::signal::impz (const Value &b, const Value &a, size_t n=0, std::pmr::memory_resource *mr=nullptr)
	Impulse response of a digital filter.
size_t	nk::signal::impzlength (const Value &b, const Value &a, std::pmr::memory_resource *mr=nullptr)
	Heuristic estimate of the number of significant impulse-response samples.
std::tuple< Value, Value >	nk::signal::stepz (const Value &b, const Value &a, size_t n=0, std::pmr::memory_resource *mr=nullptr)
	Step response of a digital filter.
std::tuple< Value, Value >	nk::signal::phasedelay (const Value &b, const Value &a, size_t n=512, std::pmr::memory_resource *mr=nullptr)
	Phase delay of a digital filter.
std::tuple< Value, Value >	nk::signal::zerophase (const Value &b, const Value &a, size_t n=512, std::pmr::memory_resource *mr=nullptr)
	Equivalent zero-phase response.
Value	nk::signal::unwrap (const Value &phase, std::pmr::memory_resource *mr=nullptr)
	Unwrap a wrapped radian phase sequence.
std::tuple< Value, Value, Value >	nk::signal::buttap (int N, std::pmr::memory_resource *mr=nullptr)
	Butterworth analog lowpass prototype.
std::tuple< Value, Value, Value >	nk::signal::cheb1ap (int N, double Rp, std::pmr::memory_resource *mr=nullptr)
	Chebyshev type-I analog lowpass prototype.
std::tuple< Value, Value, Value >	nk::signal::cheb2ap (int N, double Rs, std::pmr::memory_resource *mr=nullptr)
	Chebyshev type-II analog lowpass prototype.
std::tuple< Value, Value, Value >	nk::signal::besselap (int N, std::pmr::memory_resource *mr=nullptr)
	Bessel-Thompson analog lowpass prototype.
std::tuple< Value, Value, Value >	nk::signal::ellipap (int N, double Rp, double Rs, std::pmr::memory_resource *mr=nullptr)
	Elliptic (Cauer) analog lowpass prototype.
std::tuple< Value, Value, Value >	nk::signal::lp2lp (const Value &z, const Value &p, double k, double Wo, std::pmr::memory_resource *mr=nullptr)
	Scale an analog lowpass prototype to cutoff Wo.
std::tuple< Value, Value, Value >	nk::signal::lp2hp (const Value &z, const Value &p, double k, double Wo, std::pmr::memory_resource *mr=nullptr)
	Lowpass → highpass frequency transformation.
std::tuple< Value, Value, Value >	nk::signal::lp2bp (const Value &z, const Value &p, double k, double Wo, double Bw, std::pmr::memory_resource *mr=nullptr)
	Lowpass → bandpass frequency transformation.
std::tuple< Value, Value, Value >	nk::signal::lp2bs (const Value &z, const Value &p, double k, double Wo, double Bw, std::pmr::memory_resource *mr=nullptr)
	Lowpass → bandstop frequency transformation ([z', p', k'] = lp2bs(z, p, k, Wo, Bw)).
std::tuple< Value, Value >	nk::signal::bilinear (const Value &b, const Value &a, double fs, double fp=0.0, std::pmr::memory_resource *mr=nullptr)
	Bilinear (Tustin) transform of an analog filter (b, a) to digital.
std::tuple< Value, Value >	nk::signal::impinvar (const Value &b, const Value &a, double fs, double tol=1e-3, std::pmr::memory_resource *mr=nullptr)
	Impulse-invariance design: digital filter with the same impulse-response samples as the analog filter sampled at rate fs.
Value	nk::signal::freqs (const Value &b, const Value &a, const Value &w, std::pmr::memory_resource *mr=nullptr)
	Frequency response of an analog filter b(s)/a(s).
std::tuple< Value, Value >	nk::signal::butter (int N, double Wn, const std::string &type="low", std::pmr::memory_resource *mr=nullptr)
	Butterworth IIR lowpass / highpass filter design.
Value	nk::signal::fir1 (int N, double Wn, const std::string &type="low", std::pmr::memory_resource *mr=nullptr)
	FIR filter design via windowed-sinc (Hamming window).
Value	nk::signal::firls (int N, const Value &F, const Value &A, std::pmr::memory_resource *mr=nullptr)
	Least-squares FIR filter design (Type-I linear-phase only).
std::tuple< Value, Value >	nk::signal::cell2sos (const Value &C, std::pmr::memory_resource *mr=nullptr)
	cell2sos(C) — convert cell array of {Bi, Ai} pairs to L×6 SOS matrix.
Value	nk::signal::fir2 (int n, const Value &f, const Value &m, const Fir2Options &opts={}, std::pmr::memory_resource *mr=nullptr)
	Frequency-sampling FIR filter design (b = fir2(n, f, m [, npt] [, lap] [, window])).
std::tuple< Value, double >	nk::signal::firpm (int N, const Value &F, const Value &A, const Value &W=Value::Empty, const std::string &ftype="", std::pmr::memory_resource *mr=nullptr)
	firpm(N, F, A [, W] [, ftype]) — Parks-McClellan optimal equiripple FIR (Remez exchange).
std::tuple< Value, Value >	nk::signal::cheby1 (int N, double Rp, const Value &Wn, FilterType ftype=FilterType::Lowpass, bool analog=false, std::pmr::memory_resource *mr=nullptr)
	Chebyshev type-I IIR filter design.
std::tuple< Value, Value >	nk::signal::cheby2 (int N, double Rs, const Value &Wn, FilterType ftype=FilterType::Lowpass, bool analog=false, std::pmr::memory_resource *mr=nullptr)
	Chebyshev type-II (inverse Chebyshev) IIR filter design.
std::tuple< Value, Value >	nk::signal::besself (int N, const Value &Wn, FilterType ftype=FilterType::Lowpass, bool analog=false, std::pmr::memory_resource *mr=nullptr)
	Bessel-Thompson IIR filter design.
std::tuple< Value, Value >	nk::signal::butter (int N, const Value &Wn, FilterType ftype=FilterType::Lowpass, bool analog=false, std::pmr::memory_resource *mr=nullptr)
	Butterworth IIR filter — maximally flat passband, shared pipeline with cheby1/besself.
std::tuple< Value, Value >	nk::signal::ellip (int N, double Rp, double Rs, const Value &Wn, FilterType ftype=FilterType::Lowpass, bool analog=false, std::pmr::memory_resource *mr=nullptr)
	Elliptic (Cauer) IIR filter design.
std::tuple< int, Value >	nk::signal::buttord (const Value &Wp, const Value &Ws, double Rp, double Rs, bool analog=false, std::pmr::memory_resource *mr=nullptr)
	Butterworth filter order estimator.
std::tuple< int, Value >	nk::signal::cheb1ord (const Value &Wp, const Value &Ws, double Rp, double Rs, bool analog=false, std::pmr::memory_resource *mr=nullptr)
	Chebyshev type-I order estimator ([N, Wn] = cheb1ord(Wp, Ws, Rp, Rs, analog)).
std::tuple< int, Value >	nk::signal::cheb2ord (const Value &Wp, const Value &Ws, double Rp, double Rs, bool analog=false, std::pmr::memory_resource *mr=nullptr)
	Chebyshev type-II order estimator ([N, Wn] = cheb2ord(Wp, Ws, Rp, Rs, analog)).
std::tuple< int, Value >	nk::signal::ellipord (const Value &Wp, const Value &Ws, double Rp, double Rs, bool analog=false, std::pmr::memory_resource *mr=nullptr)
	Elliptic (Cauer) order estimator ([N, Wn] = ellipord(Wp, Ws, Rp, Rs, analog)).
std::tuple< int, Value, Value, Value >	nk::signal::firpmord (const Value &F, const Value &A, const Value &dev, double fs=2.0, std::pmr::memory_resource *mr=nullptr)
	Parks-McClellan FIR order estimator.
std::tuple< int, Value, double, std::string >	nk::signal::kaiserord (const Value &F, const Value &A, const Value &dev, double fs=2.0, std::pmr::memory_resource *mr=nullptr)
	Kaiser-window FIR order estimator.
Value	nk::signal::zp2sos (const Value &zeros, const Value &poles, double gain, std::pmr::memory_resource *mr=nullptr)
	Convert zeros / poles / gain to a second-order-sections (SOS) matrix.
std::tuple< Value, double >	nk::signal::zp2sosWithGain (const Value &zeros, const Value &poles, double gain, std::pmr::memory_resource *mr=nullptr, bool surplusAtOrigin=true)
	Convert zeros / poles / gain to (SOS, gain) — the two-output form.
Value	nk::signal::tf2sos (const Value &b, const Value &a, std::pmr::memory_resource *mr=nullptr)
	Convert a transfer-function pair (b, a) to an SOS matrix.
std::tuple< Value, double >	nk::signal::tf2sosWithGain (const Value &b, const Value &a, std::pmr::memory_resource *mr=nullptr)
	Two-output form of tf2sos: returns (sos, g).
std::tuple< Value, Value >	nk::signal::sos2tf (const Value &sos, double g=1.0, std::pmr::memory_resource *mr=nullptr)
	Second-order sections to transfer function.
std::tuple< Value, Value, double >	nk::signal::sos2zp (const Value &sos, double g=1.0, std::pmr::memory_resource *mr=nullptr)
	Second-order sections to zero / pole / gain.
std::tuple< Value, Value, double >	nk::signal::tf2zpk (const Value &b, const Value &a, std::pmr::memory_resource *mr=nullptr)
	Transfer function to zero / pole / gain.
std::tuple< Value, Value, double >	nk::signal::ctf2zp (const Value &NUM, const Value &DEN, const Value &SV=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Cascaded transfer function to zero / pole / gain.
Value	nk::signal::scaleFilterSections (const Value &CTFNum, const Value &SV, std::pmr::memory_resource *mr=nullptr)
	Scale numerator coefficients of a cascaded transfer function.
std::tuple< Value, Value, Value, Value >	nk::signal::tf2ss (const Value &b, const Value &a, std::pmr::memory_resource *mr=nullptr)
	Transfer function to state space (controllable canonical form).
std::tuple< Value, Value >	nk::signal::ss2tf (const Value &A, const Value &B, const Value &C, double D=0.0, std::pmr::memory_resource *mr=nullptr)
	State space to transfer function (SISO only).
std::tuple< Value, Value, double >	nk::signal::ss2zp (const Value &A, const Value &B, const Value &C, double D=0.0, std::pmr::memory_resource *mr=nullptr)
	State space → zero / pole / gain ([z, p, k] = ss2zp(A, B, C, D)).
std::tuple< Value, Value, Value, Value >	nk::signal::zp2ss (const Value &z, const Value &p, double k, std::pmr::memory_resource *mr=nullptr)
	Zero / pole / gain to state space (via zp2tf then tf2ss).
std::tuple< Value, Value, Value, Value >	nk::signal::sos2ss (const Value &sos, double g=1.0, std::pmr::memory_resource *mr=nullptr)
	Second-order sections to state space (via sos2tf then tf2ss).
Value	nk::signal::ss2sos (const Value &A, const Value &B, const Value &C, double D=0.0, std::pmr::memory_resource *mr=nullptr)
	State space → second-order sections (sos = ss2sos(A, B, C, D)).
Value	nk::signal::db (const Value &x, const std::string &signalType="voltage", std::pmr::memory_resource *mr=nullptr)
	Convert magnitude or power to decibels.
Value	nk::signal::db2mag (const Value &d, std::pmr::memory_resource *mr=nullptr)
	Inverse of db in voltage form: \( y = 10^{d/20} \).
Value	nk::signal::mag2db (const Value &x, std::pmr::memory_resource *mr=nullptr)
	Magnitude to decibels (voltage form): \( y = 20 \log_{10} x \).
Value	nk::signal::db2pow (const Value &d, std::pmr::memory_resource *mr=nullptr)
	Inverse of pow2db: \( y = 10^{d/10} \).
Value	nk::signal::pow2db (const Value &p, std::pmr::memory_resource *mr=nullptr)
	Power to decibels: \( y = 10 \log_{10} p \).
std::tuple< Value, Value >	nk::signal::findpeaks (const Value &x, std::pmr::memory_resource *mr=nullptr)
	Locate strict local maxima in a signal.
Value	nk::signal::statelevels (const Value &x, std::pmr::memory_resource *mr=nullptr)
	Estimate the [low, high] state levels of a step-shaped signal.
Value	nk::signal::midcross (const Value &x, const Value &fs=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Mid-state crossing times.
Value	nk::signal::risetime (const Value &x, const Value &fs=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Rise time of positive-going transitions.
Value	nk::signal::falltime (const Value &x, const Value &fs=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Fall time of negative-going transitions (90% → 10%).
Value	nk::signal::slewrate (const Value &x, const Value &fs=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Slew rate of each transition.
Value	nk::signal::overshoot (const Value &x, const Value &fs=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Percent overshoot above the upper state.
Value	nk::signal::undershoot (const Value &x, const Value &fs=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Percent undershoot below the lower state level.
Value	nk::signal::settlingtime (const Value &x, const Value &fs=Value::Empty, double tol=0.02, std::pmr::memory_resource *mr=nullptr)
	Settling time of each transition.
Value	nk::signal::pulsewidth (const Value &x, const Value &fs=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Duration each pulse stays above the mid-state.
Value	nk::signal::pulseperiod (const Value &x, const Value &fs=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Period between consecutive same-direction mid-state crossings.
Value	nk::signal::pulsesep (const Value &x, const Value &fs=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Separation between consecutive pulses (time below mid-state).
Value	nk::signal::dutycycle (const Value &x, const Value &fs=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Duty cycle: fraction of each pulse period spent above the mid-state.
std::pair< Value, Value >	nk::signal::seqperiod (const Value &x, double tol=0.0, std::pmr::memory_resource *mr=nullptr)
	Find the smallest repetition period of a signal.
std::pair< Value, Value >	nk::signal::zerocrossrate (const Value &x, double level=0.0, std::pmr::memory_resource *mr=nullptr)
	Zero-crossing rate of a signal.
CusumResult	nk::signal::cusum (const Value &x, double climit=5.0, double mshift=1.0, const Value &tmean=Value::Empty, const Value &tdev=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	CUSUM change detector ([iu, il, us, ls] = cusum(x, climit, mshift, tmean, tdev)).
Value	nk::signal::rms (const Value &x, int dim=0, std::pmr::memory_resource *mr=nullptr)
	Root-mean-square along a dimension.
Value	nk::signal::rssq (const Value &x, int dim=0, std::pmr::memory_resource *mr=nullptr)
	Root-sum-of-squares along a dimension.
Value	nk::signal::peak2peak (const Value &x, int dim=0, std::pmr::memory_resource *mr=nullptr)
	Peak-to-peak amplitude along a dimension.
Value	nk::signal::peak2rms (const Value &x, int dim=0, std::pmr::memory_resource *mr=nullptr)
	Peak-to-RMS ratio along a dimension.
Value	nk::signal::binmask2sigroi (const Value &m, std::pmr::memory_resource *mr=nullptr)
	Binary mask → ROI pairs (roi = binmask2sigroi(m)).
Value	nk::signal::sigroi2binmask (const Value &roi, int64_t len=-1, std::pmr::memory_resource *mr=nullptr)
	ROI pairs → binary mask (m = sigroi2binmask(roi, len)).
Value	nk::signal::extendsigroi (const Value &roi, int64_t Lpre, int64_t Lpost, std::pmr::memory_resource *mr=nullptr)
	Extend each ROI (roi = extendsigroi(roi, Lpre, Lpost)).
Value	nk::signal::shortensigroi (const Value &roi, int64_t Lpre, int64_t Lpost, std::pmr::memory_resource *mr=nullptr)
	Shrink each ROI (roi = shortensigroi(roi, Lpre, Lpost)).
Value	nk::signal::mergesigroi (const Value &roi, int64_t sep, std::pmr::memory_resource *mr=nullptr)
	Merge near-adjacent ROIs (roi = mergesigroi(roi, sep)).
Value	nk::signal::removesigroi (const Value &roi, int64_t maxLen, std::pmr::memory_resource *mr=nullptr)
	Drop short ROIs (roi = removesigroi(roi, maxLen)).
Value	nk::signal::extractsigroi (const Value &x, const Value &roi, bool concat=false, std::pmr::memory_resource *mr=nullptr)
	Extract signal slices indexed by ROIs (y = extractsigroi(x, roi, concat)).
Value	nk::signal::sigrangebinmask (const Value &x, double threshold, std::pmr::memory_resource *mr=nullptr)
	Range-based binary mask, single-threshold form (m = sigrangebinmask(x, threshold) ≡ x > threshold).
Value	nk::signal::sigrangebinmask (const Value &x, double lo, double hi, std::pmr::memory_resource *mr=nullptr)
	Range-based binary mask, interval form (m = sigrangebinmask(x, [lo, hi]) ≡ lo <= x <= hi).
std::tuple< Value, Value >	nk::signal::envspectrum (const Value &x, double fs=0.0, std::pmr::memory_resource *mr=nullptr)
	Envelope spectrum: magnitude FFT of the AC-coupled analytic-signal envelope.
std::tuple< Value, Value >	nk::signal::tachorpm (const Value &x, double fs, const Value &threshold=Value::Empty, int ppr=1, std::pmr::memory_resource *mr=nullptr)
	Convert a tachometer pulse signal to an RPM trace.
Value	nk::signal::rainflow (const Value &x, std::pmr::memory_resource *mr=nullptr)
	Rainflow cycle counting (ASTM E1049-85).
std::tuple< Value, Value >	nk::signal::tsa (const Value &x, double fs, const Value &rpm, double fs_rpm, int n_per_rev=1024, std::pmr::memory_resource *mr=nullptr)
	Time-synchronous average (TSA).
Value	nk::signal::upfirdn (const Value &x, const Value &h, size_t p, size_t q=1, std::pmr::memory_resource *mr=nullptr)
	Upsample-FIR-Downsample (polyphase) rational rate conversion.
Value	nk::signal::interp (const Value &x, size_t r, size_t n=4, double alpha=0.5, std::pmr::memory_resource *mr=nullptr)
	Integer-factor interpolation with a low-pass FIR kernel.
Value	nk::signal::intfilt (size_t r, size_t n=4, double alpha=0.5, std::pmr::memory_resource *mr=nullptr)
	Design an FIR interpolation kernel.
Value	nk::signal::fftfilt (const Value &b, const Value &x, size_t nfft=0, std::pmr::memory_resource *mr=nullptr)
	Overlap-add FFT-based FIR filtering.
Value	nk::signal::downsample (const Value &x, size_t n, std::pmr::memory_resource *mr=nullptr, size_t phase=0)
	Integer-rate downsampling — keep every n-th sample.
Value	nk::signal::upsample (const Value &x, size_t n, std::pmr::memory_resource *mr=nullptr, size_t phase=0)
	Integer-rate upsampling — zero-stuff between samples.
Value	nk::signal::decimate (const Value &x, size_t factor, std::pmr::memory_resource *mr=nullptr)
	Integer-factor decimation with anti-alias filtering.
Value	nk::signal::resample (const Value &x, size_t p, size_t q, std::pmr::memory_resource *mr=nullptr)
	Rational rate conversion: change rate by factor p/q.
Value	nk::signal::medfilt1 (const Value &x, size_t k=3, bool zeropad=true, std::pmr::memory_resource *mr=nullptr)
	1-D median filter.
Value	nk::signal::sgolay (int order, int framelen, std::pmr::memory_resource *mr=nullptr)
	Savitzky-Golay filter projection matrix.
Value	nk::signal::sgolayDiff (int order, int framelen, std::pmr::memory_resource *mr=nullptr)
	Savitzky-Golay differentiation-filter matrix (the second output G of MATLAB's [B,G] = sgolay(order,framelen)).
Value	nk::signal::sgolayfilt (const Value &x, int order, int framelen, std::pmr::memory_resource *mr=nullptr)
	Savitzky-Golay smoothing of a 1-D signal.
Value	nk::signal::sgolayfilt (const Value &x, int order, int framelen, const Value &weights, int dim, std::pmr::memory_resource *mr=nullptr)
	Savitzky-Golay smoothing with optional weighting and dimension.
std::tuple< Value, Value >	nk::signal::periodogram (const Value &x, const Value &window, size_t nfft, double fs=2.0 *3.14159265358979323846, std::pmr::memory_resource *mr=nullptr)
	Single-segment periodogram PSD estimate.
Value	nk::signal::periodogramConf (const Value &Pxx, double confidenceLevel, bool realInput, bool nfftEven, std::pmr::memory_resource *mr=nullptr)
	Chi-square confidence interval for a periodogram PSD estimate.
std::tuple< Value, Value >	nk::signal::pwelch (const Value &x, const Value &window, size_t noverlap, size_t nfft, double fs=2.0 *3.14159265358979323846, std::pmr::memory_resource *mr=nullptr)
	Welch's averaged, modified periodogram PSD estimate.
std::tuple< Value, Value >	nk::signal::cpsd (const Value &x, const Value &y, const Value &window, size_t noverlap, size_t nfft, double fs=2.0 *3.14159265358979323846, std::pmr::memory_resource *mr=nullptr)
	Cross-PSD via Welch's method.
std::tuple< Value, Value >	nk::signal::mscohere (const Value &x, const Value &y, const Value &window, size_t noverlap, size_t nfft, double fs=2.0 *3.14159265358979323846, std::pmr::memory_resource *mr=nullptr)
	Magnitude-squared coherence via Welch's method.
std::tuple< Value, Value >	nk::signal::tfestimate (const Value &x, const Value &y, const Value &window, size_t noverlap, size_t nfft, double fs=2.0 *3.14159265358979323846, std::pmr::memory_resource *mr=nullptr)
	Transfer-function estimate via Welch's method.
std::tuple< Value, Value >	nk::signal::pyulear (const Value &x, int p, size_t nfft, std::pmr::memory_resource *mr=nullptr)
	Yule-Walker autoregressive PSD estimate.
std::tuple< Value, Value >	nk::signal::pburg (const Value &x, int p, size_t nfft, std::pmr::memory_resource *mr=nullptr)
	Burg's AR PSD estimate ([Pxx, F] = pburg(x, p, nfft)).
std::tuple< Value, Value, Value >	nk::signal::levinson (const Value &r, int n=-1, std::pmr::memory_resource *mr=nullptr)
	Levinson-Durbin recursion: solve a Hermitian Toeplitz system.
std::tuple< Value, Value >	nk::signal::rlevinson (const Value &a, double efinal, std::pmr::memory_resource *mr=nullptr)
	Inverse Levinson recursion: recover autocorrelation from AR poly.
std::tuple< Value, Value, Value >	nk::signal::aryule (const Value &x, int p, std::pmr::memory_resource *mr=nullptr)
	Yule-Walker AR(p) parameter estimation.
std::tuple< Value, Value, Value >	nk::signal::arburg (const Value &x, int p, std::pmr::memory_resource *mr=nullptr)
	Burg's AR(p) parameter estimation.
std::tuple< Value, Value >	nk::signal::lpc (const Value &x, int p, std::pmr::memory_resource *mr=nullptr)
	Linear-prediction coefficients (aryule alias + sqrt-error gain).
std::tuple< Value, Value >	nk::signal::ac2poly (const Value &R, std::pmr::memory_resource *mr=nullptr)
	Autocorrelation → AR poly (composes levinson).
Value	nk::signal::poly2ac (const Value &a, double e, std::pmr::memory_resource *mr=nullptr)
	AR poly + prediction error → autocorrelation.
std::tuple< Value, Value >	nk::signal::ac2rc (const Value &R, std::pmr::memory_resource *mr=nullptr)
	Autocorrelation → reflection coefficients.
Value	nk::signal::schurrc (const Value &R, std::pmr::memory_resource *mr=nullptr)
	Schur reflection coefficients from autocorrelation.
Value	nk::signal::rc2ac (const Value &k, double r0, std::pmr::memory_resource *mr=nullptr)
	Reflection coefficients + r[0] → autocorrelation.
std::tuple< Value, Value >	nk::signal::poly2rc (const Value &a, double efinal=0.0, std::pmr::memory_resource *mr=nullptr)
	AR poly → reflection coefficients (step-down recursion).
std::tuple< Value, Value >	nk::signal::rc2poly (const Value &k, double r0=1.0, std::pmr::memory_resource *mr=nullptr)
	Reflection coefficients → AR poly (step-up recursion).
Value	nk::signal::is2rc (const Value &is, std::pmr::memory_resource *mr=nullptr)
	Inverse-sine parameterisation → reflection coefficients.
Value	nk::signal::rc2is (const Value &k, std::pmr::memory_resource *mr=nullptr)
	Reflection coefficients → inverse-sine parameterisation.
Value	nk::signal::lar2rc (const Value &g, std::pmr::memory_resource *mr=nullptr)
	Log-area-ratio → reflection coefficients.
Value	nk::signal::rc2lar (const Value &k, std::pmr::memory_resource *mr=nullptr)
	Reflection coefficients → log-area-ratio.
std::tuple< Value, Value >	nk::signal::arcov (const Value &x, int p, std::pmr::memory_resource *mr=nullptr)
	Covariance method AR estimation.
std::tuple< Value, Value >	nk::signal::armcov (const Value &x, int p, std::pmr::memory_resource *mr=nullptr)
	Modified-covariance AR estimation.
std::tuple< Value, Value >	nk::signal::prony (const Value &h, int nb, int na, std::pmr::memory_resource *mr=nullptr)
	Prony IIR identification from impulse response.
std::tuple< Value, Value >	nk::signal::stmcb (const Value &h, int nb, int na, int niter=5, std::pmr::memory_resource *mr=nullptr)
	Steiglitz–McBride IIR identification ([b, a] = stmcb(h, nb, na, niter)).
Value	nk::signal::corrmtx (const Value &x, int m, std::pmr::memory_resource *mr=nullptr)
	Generate the autocorrelation data matrix.
std::tuple< Value, Value >	nk::signal::pmusic (const Value &x, int p, int nfft=256, double fs=2.0 *3.14159265358979323846, std::pmr::memory_resource *mr=nullptr)
	MUSIC pseudospectrum ([P, F] = pmusic(x, p, nfft, fs)).
std::tuple< Value, Value >	nk::signal::peig (const Value &x, int p, int nfft=256, double fs=2.0 *3.14159265358979323846, std::pmr::memory_resource *mr=nullptr)
	Eigenvector pseudospectrum ([P, F] = peig(x, p, nfft, fs)).
Value	nk::signal::poly2lsf (const Value &a, std::pmr::memory_resource *mr=nullptr)
	AR poly → line-spectral frequencies (radians).
Value	nk::signal::lsf2poly (const Value &lsf, std::pmr::memory_resource *mr=nullptr)
	Line-spectral frequencies → AR poly.
std::tuple< Value, Value >	nk::signal::invfreqs (const Value &H, const Value &w, int nb, int na, std::pmr::memory_resource *mr=nullptr)
	Fit analog filter to a frequency response (Levi equation-error LSQ).
std::tuple< Value, Value >	nk::signal::invfreqz (const Value &H, const Value &w, int nb, int na, std::pmr::memory_resource *mr=nullptr)
	Digital counterpart of invfreqs.
Value	nk::signal::bandpower (const Value &x, const Value &fs=Value::Empty, const Value &freqrange=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Power in a frequency band (p = bandpower(x, fs, freqrange)).
Value	nk::signal::meanfreq (const Value &x, const Value &fs=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Power-weighted mean frequency.
Value	nk::signal::medfreq (const Value &x, const Value &fs=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Median frequency.
Value	nk::signal::enbw (const Value &window, const Value &fs=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Equivalent noise bandwidth of a window (b = enbw(window, fs)).
std::tuple< Value, Value, Value, Value >	nk::signal::obw (const Value &x, const Value &fs=Value::Empty, double p=0.99, std::pmr::memory_resource *mr=nullptr)
	Occupied bandwidth at fraction p of total power ([bw, flo, fhi, power] = obw(x, fs, p)).
Value	nk::signal::powerbw (const Value &x, const Value &fs=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	3-dB power bandwidth around the dominant peak.
Value	nk::signal::spectralcrest (const Value &x, const Value &fs=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Spectral crest: max(P) / mean(P) (peakedness).
Value	nk::signal::spectralflatness (const Value &x, const Value &fs=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Spectral flatness: geomean(P) / mean(P).
Value	nk::signal::spectralentropy (const Value &x, const Value &fs=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Shannon entropy of the normalised PSD.
Value	nk::signal::spectralkurtosis (const Value &x, const Value &fs=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Kurtosis of the PSD treated as a frequency distribution.
Value	nk::signal::spectralskewness (const Value &x, const Value &fs=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Skewness of the PSD treated as a frequency distribution.
Value	nk::signal::snr (const Value &x, const Value &fs=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Signal-to-noise ratio in dB.
Value	nk::signal::sinad (const Value &x, const Value &fs=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Signal-to-noise-and-distortion in dB.
Value	nk::signal::thd (const Value &x, const Value &fs=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Total harmonic distortion in dB.
Value	nk::signal::sfdr (const Value &x, const Value &fs=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Spurious-free dynamic range in dB.
Value	nk::signal::instfreq (const Value &x, const Value &fs=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Instantaneous frequency via Hilbert transform.
Value	nk::signal::instbw (const Value &x, const Value &fs=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Instantaneous bandwidth.
std::tuple< Value, Value, Value >	nk::signal::spectrogram (const Value &x, const Value &window, size_t noverlap, size_t nfft, std::pmr::memory_resource *mr=nullptr)
	Short-time Fourier transform with explicit (S, F, T) outputs.
Value	nk::signal::stft (const Value &x, const Value &window, std::size_t overlap, std::size_t fftLength, const std::string &range, std::pmr::memory_resource *mr=nullptr)
	Full two-sided / centred / one-sided STFT.
Value	nk::signal::istft (const Value &S, const Value &window, std::size_t overlap, std::size_t fftLength, const std::string &range, std::pmr::memory_resource *mr=nullptr)
	Inverse STFT via overlap-add.
std::tuple< Value, Value, Value >	nk::signal::iscola (const Value &window, std::size_t noverlap, const std::string &method, std::pmr::memory_resource *mr=nullptr)
	Constant OverLap-Add (COLA) compliance check (tf = iscola(window, noverlap[, method])).
Value	nk::signal::dct (const Value &x, std::pmr::memory_resource *mr=nullptr)
	Type-II discrete cosine transform (the default form).
Value	nk::signal::idct (const Value &x, std::pmr::memory_resource *mr=nullptr)
	Inverse Type-II DCT (1-D form).
Value	nk::signal::dct (const Value &x, int n, int dim, std::pmr::memory_resource *mr=nullptr)
	DCT-II with explicit length / axis.
Value	nk::signal::idct (const Value &x, int n, int dim, std::pmr::memory_resource *mr=nullptr)
	Inverse DCT-II with explicit length / axis.
Value	nk::signal::dftmtx (size_t N, std::pmr::memory_resource *mr=nullptr)
	N×N complex DFT matrix.
Value	nk::signal::bitrevorder (const Value &x, std::pmr::memory_resource *mr=nullptr)
	Re-order a sequence by bit-reversed indices.
Value	nk::signal::dst (const Value &x, std::pmr::memory_resource *mr=nullptr)
	Type-II Discrete Sine Transform.
Value	nk::signal::idst (const Value &y, std::pmr::memory_resource *mr=nullptr)
	Inverse Type-II DST.
Value	nk::signal::rceps (const Value &x, std::pmr::memory_resource *mr=nullptr)
	Real cepstrum: real(ifft(log(abs(fft(x))))).
std::pair< Value, Value >	nk::signal::rcepsMinPhase (const Value &x, std::pmr::memory_resource *mr=nullptr)
	Real cepstrum and its minimum-phase reconstruction ([y, ym] = rceps(x)).
Value	nk::signal::cceps (const Value &x, std::pmr::memory_resource *mr=nullptr, double *ndOut=nullptr)
	Complex cepstrum: ifft(log(fft(x))) with phase unwrapping.
Value	nk::signal::icceps (const Value &c, std::pmr::memory_resource *mr=nullptr)
	Inverse complex cepstrum: real(ifft(exp(fft(c)))).
Value	nk::signal::fft (const Value &x, int n=-1, int dim=0, std::pmr::memory_resource *mr=nullptr)
	1-D discrete Fourier transform along a given dimension.
Value	nk::signal::ifft (const Value &X, int n=-1, int dim=0, std::pmr::memory_resource *mr=nullptr)
	1-D inverse discrete Fourier transform along a given dimension.
Value	nk::signal::ifftSymmetric (const Value &X, int n=-1, int dim=0, std::pmr::memory_resource *mr=nullptr)
	Inverse DFT with conjugate-symmetric input (MATLAB's ifft(X,..., 'symmetric')).
Value	nk::signal::fft2 (const Value &X, int m=-1, int n=-1, std::pmr::memory_resource *mr=nullptr)
	2-D forward FFT.
Value	nk::signal::ifft2 (const Value &X, int m=-1, int n=-1, std::pmr::memory_resource *mr=nullptr)
	2-D inverse FFT (Y = ifft2(X, m, n)).
Value	nk::signal::ifft2Symmetric (const Value &X, std::pmr::memory_resource *mr=nullptr)
	2-D inverse FFT with conjugate-symmetric input (MATLAB's ifft2(X,'symmetric')).
Value	nk::signal::fftn (const Value &X, Span< const std::size_t > sz={}, std::pmr::memory_resource *mr=nullptr)
	N-D forward FFT.
Value	nk::signal::ifftn (const Value &X, Span< const std::size_t > sz={}, std::pmr::memory_resource *mr=nullptr)
	N-D inverse FFT (Y = ifftn(X, sz)).
Value	nk::signal::czt (const Value &x, int m, Complex w, Complex a, std::pmr::memory_resource *mr=nullptr)
	Chirp Z-transform (Bluestein).
Value	nk::signal::interpft (const Value &x, int n, int dim=0, std::pmr::memory_resource *mr=nullptr)
	FFT-based band-limited interpolation of x to n equispaced samples.
Value	nk::signal::fwht (const Value &x, std::size_t n, const std::string &ordering, std::pmr::memory_resource *mr=nullptr)
	Fast Walsh-Hadamard transform (y = fwht(x[, n[, ordering]])).
Value	nk::signal::ifwht (const Value &y, std::size_t n, const std::string &ordering, std::pmr::memory_resource *mr=nullptr)
	Inverse fast Walsh-Hadamard transform (x = ifwht(y[, n[, ordering]])).
Value	nk::signal::goertzel (const Value &x, const Value &ind, std::pmr::memory_resource *mr=nullptr)
	Goertzel algorithm — single-frequency DFT evaluation.
Value	nk::signal::hilbert (const Value &x, std::pmr::memory_resource *mr=nullptr)
	Analytic signal via the discrete Hilbert transform.
Value	nk::signal::envelope (const Value &x, std::pmr::memory_resource *mr=nullptr)
	Amplitude envelope of a real signal: |hilbert(x)|.
std::pair< Value, Value >	nk::signal::envelope_pair (const Value &x, std::pmr::memory_resource *mr=nullptr)
	2-output envelope (DC-symmetric form).
std::pair< Value, Value >	nk::signal::envelope_full (const Value &x, int mode, std::size_t n, std::pmr::memory_resource *mr=nullptr)
	Full multi-mode envelope computation.
Value	nk::signal::nextpow2 (double n, std::pmr::memory_resource *mr=nullptr)
	Smallest integer p such that \( 2^p \ge n \) (scalar form).
Value	nk::signal::nextpow2 (const Value &x, std::pmr::memory_resource *mr=nullptr)
	Vectorised nextpow2 — applies elementwise to an array.
Value	nk::signal::fftshift (const Value &x, std::pmr::memory_resource *mr=nullptr)
	DC-to-center reordering for FFT output (multidim form).
Value	nk::signal::ifftshift (const Value &x, std::pmr::memory_resource *mr=nullptr)
	Inverse of fftshift — shift by floor(extent/2).
Value	nk::signal::fftshift (const Value &x, int dim, std::pmr::memory_resource *mr=nullptr)
	Single-dim fftshift — shift only along axis dim.
Value	nk::signal::ifftshift (const Value &x, int dim, std::pmr::memory_resource *mr=nullptr)
	Single-dim ifftshift — inverse of single-dim fftshift.
Value	nk::signal::rectpuls (const Value &t, double w=1.0, std::pmr::memory_resource *mr=nullptr)
	Rectangular pulse of unit amplitude on the open interval (-w/2, w/2).
Value	nk::signal::tripuls (const Value &t, double w=1.0, std::pmr::memory_resource *mr=nullptr)
	Triangular pulse of unit amplitude on |t| ≤ w/2.
Value	nk::signal::gauspuls (const Value &t, double fc, double bw=0.5, std::pmr::memory_resource *mr=nullptr)
	Gaussian-modulated sinusoid.
Value	nk::signal::pulstran (const Value &t, const Value &d, const std::string &fnName, double fcOrW=1.0, double bw=0.5, std::pmr::memory_resource *mr=nullptr)
	Pulse train: Σ_i fn(t - d_i) for a named pulse type.
Value	nk::signal::pulstranHandle (Span< const double > t, Span< const double > d, FnHandle fn, std::pmr::memory_resource *mr=nullptr)
	Pulse train with a callback-based pulse generator.
Value	nk::signal::chirp (const Value &t, double f0, double t1, double f1, const std::string &method="linear", std::pmr::memory_resource *mr=nullptr)
	Frequency-modulated cosine (chirp).
Value	nk::signal::square (const Value &t, double duty=50.0, std::pmr::memory_resource *mr=nullptr)
	Square wave with period 2π.
Value	nk::signal::sawtooth (const Value &t, double width=1.0, std::pmr::memory_resource *mr=nullptr)
	Sawtooth wave on period 2π.
Value	nk::signal::sinc (const Value &t, std::pmr::memory_resource *mr=nullptr)
	Normalised cardinal sine: sinc(0) = 1, otherwise sin(πt)/(πt).
Value	nk::signal::gmonopuls (const Value &t, double fc, std::pmr::memory_resource *mr=nullptr)
	Gaussian monopulse at centre frequency fc.
Value	nk::signal::diric (const Value &x, int n, std::pmr::memory_resource *mr=nullptr)
	Dirichlet (periodic-sinc) function of order n.
Value	nk::signal::modulate (const Value &x, double Fc, double Fs, const std::string &method, const Value &opt=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Analog modulation: AM / FM / PM family.
Value	nk::signal::demod (const Value &y, double Fc, double Fs, const std::string &method, const Value &opt=Value::Empty, std::pmr::memory_resource *mr=nullptr)
	Analog demodulation (AM family).
Value	nk::signal::vco (const Value &x, double fc, double fs, std::pmr::memory_resource *mr=nullptr)
	Voltage-controlled (frequency-modulated) oscillator.
Value	nk::signal::vco (const Value &x, double fmin, double fmax, double fs, std::pmr::memory_resource *mr=nullptr)
	Voltage-controlled oscillator, explicit [Fmin, Fmax] range form (y = vco(x, [fmin fmax], fs)).
Value	nk::signal::hamming (size_t N, std::pmr::memory_resource *mr=nullptr)
	Hamming window of length N.
Value	nk::signal::hann (size_t N, std::pmr::memory_resource *mr=nullptr)
	Hann (Hanning) window of length N.
Value	nk::signal::blackman (size_t N, std::pmr::memory_resource *mr=nullptr)
	Blackman window of length N — classic 3-term cosine sum.
Value	nk::signal::kaiser (size_t N, double beta, std::pmr::memory_resource *mr=nullptr)
	Kaiser window of length N with shape parameter β.
Value	nk::signal::rectwin (size_t N, std::pmr::memory_resource *mr=nullptr)
	Rectangular window of length N — all ones.
Value	nk::signal::bartlett (size_t N, std::pmr::memory_resource *mr=nullptr)
	Bartlett window of length N — triangular with zero endpoints.
Value	nk::signal::triang (size_t N, std::pmr::memory_resource *mr=nullptr)
	Triangular window of length N — non-zero endpoints variant of Bartlett.
Value	nk::signal::tukeywin (size_t N, double r=0.5, std::pmr::memory_resource *mr=nullptr)
	Tukey (cosine-tapered) window of length N.
Value	nk::signal::flattopwin (size_t N, std::pmr::memory_resource *mr=nullptr)
	Flat-top window of length N — 5-term cosine sum, optimised for amplitude accuracy (not frequency resolution).
Value	nk::signal::gausswin (size_t N, double alpha=2.5, std::pmr::memory_resource *mr=nullptr)
	Gaussian window of length N.
Value	nk::signal::chebwin (size_t N, double at=100.0, std::pmr::memory_resource *mr=nullptr)
	Dolph-Chebyshev window of length N — equiripple sidelobes at given attenuation.
Value	nk::signal::parzenwin (size_t N, std::pmr::memory_resource *mr=nullptr)
	Parzen (de la Vallée Poussin) window of length N — piecewise cubic.
Value	nk::signal::nuttallwin (size_t N, std::pmr::memory_resource *mr=nullptr)
	Nuttall window of length N — 4-term, continuous-first-derivative.
Value	nk::signal::taylorwin (size_t N, int nbar=4, double sll=-30.0, std::pmr::memory_resource *mr=nullptr)
	Taylor window of length N — radar / antenna design.
Value	nk::signal::blackmanharris (size_t N, std::pmr::memory_resource *mr=nullptr)
	Blackman-Harris window of length N — 4-term, minimum-sidelobe.
Value	nk::signal::bohmanwin (size_t N, std::pmr::memory_resource *mr=nullptr)
	Bohman window of length N — convolution of two half-cosine pulses.
Value	nk::signal::barthannwin (size_t N, std::pmr::memory_resource *mr=nullptr)
	Modified Bartlett-Hann window of length N.

Detailed Description

Digital filter design (IIR/FIR), filter implementation (filtfilt/sosfilt), spectral analysis (FFT/pwelch/spectrogram), windows, and waveforms.

Enumeration Type Documentation

FilterType

enum class nk::signal::FilterType

strong

Filter response type for IIR designs.

Enumerator
Lowpass	Pass below the cutoff, stop above.
Highpass	Pass above the cutoff, stop below.
Bandpass	Pass between two cutoffs.
Bandstop	Stop between two cutoffs, pass elsewhere.

Definition at line 25 of file iir_designs.hpp.

Function Documentation

ac2poly()

std::tuple< Value, Value > nk::signal::ac2poly	(	const Value &	R,
		std::pmr::memory_resource *	mr = nullptr )

Autocorrelation → AR poly (composes levinson).

Parameters

R	Autocorrelation sequence (length n+1).
mr	Memory resource (nullptr → process default).

Returns

Tuple (a, e).

ac2rc()

std::tuple< Value, Value > nk::signal::ac2rc	(	const Value &	R,
		std::pmr::memory_resource *	mr = nullptr )

Autocorrelation → reflection coefficients.

Parameters

R	Autocorrelation sequence.
mr	Memory resource (nullptr → process default).

Returns

Tuple (k, r0) — reflection coefficients and r[0].

alignsignals()

std::tuple< Value, Value > nk::signal::alignsignals	(	const Value &	x,
		const Value &	y,
		long	max_lag = 0,
		std::pmr::memory_resource *	mr = nullptr )

Align two signals by zero-padding the leading one.

Calls finddelay(x, y, max_lag) internally, then zero-pads on the left so the returned xa and ya are time-aligned and have equal length.

Parameters

x	First signal.
y	Second signal.
max_lag	Cap on the search range. 0 ≡ full.
mr	Memory resource (nullptr → process default).

Returns

Tuple (xa, ya) with numel(xa) == numel(ya).

arburg()

std::tuple< Value, Value, Value > nk::signal::arburg	(	const Value &	x,
		int	p,
		std::pmr::memory_resource *	mr = nullptr )

Burg's AR(p) parameter estimation.

Minimises the sum of forward + backward prediction error variances in an order-recursive fashion. Numerically stable for short signals where Yule-Walker autocorrelation estimates are biased.

Parameters

x	Real 1-D signal.
p	AR model order.
mr	Memory resource (nullptr → process default).

Returns

Tuple (a, e, k) — AR poly, error variance, reflection coefficients (see levinson).

See also

aryule, pburg

arcov()

std::tuple< Value, Value > nk::signal::arcov	(	const Value &	x,
		int	p,
		std::pmr::memory_resource *	mr = nullptr )

Covariance method AR estimation.

Minimises the forward prediction error energy over n = p..N-1. Avoids the bias of Yule-Walker but lacks the BIBO guarantee of Burg.

Parameters

x	Real 1-D signal.
p	AR order.
mr	Memory resource (nullptr → process default).

Returns

Tuple (a, e).

See also

armcov, arburg

armcov()

std::tuple< Value, Value > nk::signal::armcov	(	const Value &	x,
		int	p,
		std::pmr::memory_resource *	mr = nullptr )

Modified-covariance AR estimation.

Averages forward + backward prediction error energies. Tighter peak detection than the basic covariance method.

Parameters

x	Real 1-D signal.
p	AR order.
mr	Memory resource (nullptr → process default).

Returns

Tuple (a, e).

See also

arcov, arburg

aryule()

std::tuple< Value, Value, Value > nk::signal::aryule	(	const Value &	x,
		int	p,
		std::pmr::memory_resource *	mr = nullptr )

Yule-Walker AR(p) parameter estimation.

Solves the normal equations on the biased autocorrelation sequence via Levinson-Durbin.

Parameters

x	Real 1-D signal.
p	AR model order.
mr	Memory resource (nullptr → process default).

Returns

Tuple (a, e, k) (see levinson).

See also

arburg, levinson, pyulear

bandpass()

Value nk::signal::bandpass	(	const Value &	x,
		double	flo,
		double	fhi,
		double	fs,
		int	order = 8,
		std::pmr::memory_resource *	mr = nullptr )

One-call zero-phase Butterworth bandpass filter.

Implemented as a cascade of highpass(x, flo) then lowpass(x, fhi). For narrow bands consider designing a single bandpass filter via butter(N, [flo fhi]/fs*2, "bandpass") and filtfilt directly.

Parameters

x	Input signal.
flo	Lower cutoff in Hz.
fhi	Upper cutoff in Hz (flo < fhi < fs/2).
fs	Sample rate in Hz.
order	Order per cascade stage. Default 8.
mr	Memory resource (nullptr → process default).

Returns

Filtered signal.

Note

Cascaded-stage approximation; accurate enough for typical wide passbands. For sharp transitions design a single-stage BP filter directly.

bandpower()

Value nk::signal::bandpower	(	const Value &	x,
		const Value &	fs = Value::Empty,
		const Value &	freqrange = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Power in a frequency band (p = bandpower(x, fs, freqrange)).

• fs.isEmpty(): returns mean(x^2) (Parseval-equivalent total power, ignoring freqrange).
• fs > 0 and freqrange.isEmpty(): integrates the full PSD.
• fs > 0 and freqrange = [f1 f2]: integrates the PSD over [f1, f2].

Parameters

x	Real 1-D signal.
fs	Sample rate in Hz, or Value::Empty.
freqrange	Optional [fLo, fHi] band edges in Hz.
mr	Memory resource (nullptr → process default).

Returns

Scalar DOUBLE power.

bandstop()

Value nk::signal::bandstop	(	const Value &	x,
		double	flo,
		double	fhi,
		double	fs,
		int	order = 8,
		std::pmr::memory_resource *	mr = nullptr )

One-call zero-phase Butterworth bandstop (notch) filter.

Implemented as the additive inverse: bandstop(x) = lowpass(x, flo) + highpass(x, fhi). Cancellation in the stopband is approximate.

Parameters

x	Input signal.
flo	Lower stopband edge in Hz.
fhi	Upper stopband edge in Hz (flo < fhi < fs/2).
fs	Sample rate in Hz.
order	Order per stage. Default 8.
mr	Memory resource (nullptr → process default).

Returns

Filtered signal.

barthannwin()

Value nk::signal::barthannwin	(	size_t	N,
		std::pmr::memory_resource *	mr = nullptr )

Modified Bartlett-Hann window of length N.

Linear combination of Bartlett and Hann: better sidelobes than Bartlett while keeping a triangular envelope.

Parameters

N	Window length, ≥ 1.
mr	Memory resource (nullptr → process default).

Returns

N×1 DOUBLE column vector.

bartlett()

Value nk::signal::bartlett	(	size_t	N,
		std::pmr::memory_resource *	mr = nullptr )

Bartlett window of length N — triangular with zero endpoints.

Formula: \( w(n) = 1 - |2n - (N-1)| / (N-1) \) for n = 0..N-1. Endpoints are exactly zero (unlike triang).

Parameters

N	Window length, ≥ 1.
mr	Memory resource (nullptr → process default).

Returns

N×1 DOUBLE column vector.

besselap()

std::tuple< Value, Value, Value > nk::signal::besselap	(	int	N,
		std::pmr::memory_resource *	mr = nullptr )

Bessel-Thompson analog lowpass prototype.

Poles of a reverse Bessel polynomial. Maximally flat group delay (linear phase) in the passband. besselap normalises so |H(jΩ)| = 1/√2 at Ω = 1 rad/s — group-delay normalisation, not magnitude — and this function matches.

Parameters

N	Filter order, ≥ 1.
mr	Memory resource (nullptr → process default).

Returns

Tuple (z, p, k) — empty zeros, N poles, scalar gain.

besself()

std::tuple< Value, Value > nk::signal::besself	(	int	N,
		const Value &	Wn,
		FilterType	ftype = FilterType::Lowpass,
		bool	analog = false,
		std::pmr::memory_resource *	mr = nullptr )

Bessel-Thompson IIR filter design.

Maximally flat group delay in the passband. besself is analog-only by default; here analog = false enables a digital design via the bilinear transform (the resulting digital filter approximates the analog group-delay characteristic).

Parameters

N	Filter order.
Wn	Cutoff frequency (digital: normalised; analog: rad/s).
ftype	Response type.
analog	Analog-domain flag.
mr	Memory resource (nullptr → process default).

Returns

Tuple (b, a).

bilinear()

std::tuple< Value, Value > nk::signal::bilinear	(	const Value &	b,
		const Value &	a,
		double	fs,
		double	fp = 0.0,
		std::pmr::memory_resource *	mr = nullptr )

Bilinear (Tustin) transform of an analog filter (b, a) to digital.

Maps s → (2/T)·(z-1)/(z+1) with T = 1/fs. The optional pre-warp frequency fp adjusts the effective sample rate so that the digital response matches the analog response exactly at fp.

Parameters

b	Analog numerator polynomial.
a	Analog denominator polynomial.
fs	Sample rate (Hz).
fp	Pre-warp frequency (Hz). 0.0 (default) → no pre-warp.
mr	Memory resource (nullptr → process default).

Returns

Tuple (bd, ad) — digital numerator / denominator.

See also

impinvar

binmask2sigroi()

Value nk::signal::binmask2sigroi	(	const Value &	m,
		std::pmr::memory_resource *	mr = nullptr )

Binary mask → ROI pairs (roi = binmask2sigroi(m)).

Parameters

m	Logical column.
mr	Memory resource (nullptr → process default).

Returns

N × 2 matrix of 1-based inclusive [start, end] runs; empty mask → 0 × 0 matrix.

See also

sigroi2binmask

bitrevorder()

Value nk::signal::bitrevorder	(	const Value &	x,
		std::pmr::memory_resource *	mr = nullptr )

Re-order a sequence by bit-reversed indices.

For a length-N vector with N a power of 2, output[k] = input[brev(k)], where brev(k) reverses the bits of the log2(N)-bit index.

Used as a pre/post-step in some FFT decimation-in-frequency algorithms.

Parameters

x	Real or complex input vector. Length must be a power of 2.
mr	Memory resource (nullptr → process default).

Returns

Same-shape Value with elements permuted.

Exceptions

nk::Error

if numel(x) is not a power of 2.

blackman()

Value nk::signal::blackman	(	size_t	N,
		std::pmr::memory_resource *	mr = nullptr )

Blackman window of length N — classic 3-term cosine sum.

Formula: \( w(n) = 0.42 - 0.5\cos(2\pi n/(N-1)) + 0.08\cos(4\pi n/(N-1)) \). Symmetric. Sidelobe attenuation ≈ -58 dB.

Parameters

N	Window length, ≥ 1.
mr	Memory resource (nullptr → process default).

Returns

N×1 DOUBLE column vector.

blackmanharris()

Value nk::signal::blackmanharris	(	size_t	N,
		std::pmr::memory_resource *	mr = nullptr )

Blackman-Harris window of length N — 4-term, minimum-sidelobe.

Like Nuttall but optimised purely for minimum sidelobe height (no derivative constraint). Sidelobe attenuation ≈ -92 dB.

Parameters

N	Window length, ≥ 1.
mr	Memory resource (nullptr → process default).

Returns

N×1 DOUBLE column vector.

bohmanwin()

Value nk::signal::bohmanwin	(	size_t	N,
		std::pmr::memory_resource *	mr = nullptr )

Bohman window of length N — convolution of two half-cosine pulses.

Smoother than Bartlett, lower sidelobes than Hann.

Parameters

N	Window length, ≥ 1.
mr	Memory resource (nullptr → process default).

Returns

N×1 DOUBLE column vector.

buffer()

Value nk::signal::buffer	(	const Value &	x,
		int	n,
		int	p = 0,
		const Value &	opt = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Partition x into frames of length n.

Returns the frame matrix Y only. Use buffer2 for the (Y, Z) form where Z holds the partial trailing samples.

Parameters

x	Input signal (row or column vector).
n	Frame length.
p	Overlap behaviour: p == 0: non-overlapping, last frame zero-padded; p > 0: overlap with p initial-zero samples; p < 0: skip |p| samples between frames.
opt	String ("nodelay") or numeric initial-condition vector. Value::Empty = default.
mr	Memory resource (nullptr → process default).

Returns

Frame matrix Y.

See also

buffer2

buffer2()

std::tuple< Value, Value > nk::signal::buffer2	(	const Value &	x,
		int	n,
		int	p = 0,
		const Value &	opt = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

2-output form: [Y, Z] = buffer(x, n, p, opt).

Y has only complete frames (no trailing zero-pad). Z holds the partial-frame remainder, shaped to match x's orientation.

Parameters

x	Input signal (row or column vector).
n	Frame length.
p	Overlap behaviour (see buffer).
opt	String ("nodelay") or numeric initial-condition vector; Value::Empty = default.
mr	Memory resource (nullptr → process default).

Returns

Tuple (Y, Z).

See also

buffer

buttap()

std::tuple< Value, Value, Value > nk::signal::buttap	(	int	N,
		std::pmr::memory_resource *	mr = nullptr )

Butterworth analog lowpass prototype.

All poles lie on the unit circle in the s-plane. Maximally flat magnitude response. No finite zeros (all-pole).

Parameters

N	Filter order, ≥ 1.
mr	Memory resource (nullptr → process default).

Returns

Tuple (z, p, k) — empty zeros, N poles, scalar gain.

See also

cheb1ap, cheb2ap, besselap, ellipap

butter() [1/2]

std::tuple< Value, Value > nk::signal::butter	(	int	N,
		const Value &	Wn,
		FilterType	ftype = FilterType::Lowpass,
		bool	analog = false,
		std::pmr::memory_resource *	mr = nullptr )

Butterworth IIR filter — maximally flat passband, shared pipeline with cheby1/besself.

butter(N, Wn, 's') designs in the s-domain (Wn in rad/s, any positive value); digital Wn stays normalised (0,1).

Parameters

N	Filter order (band designs double it).
Wn	Cutoff(s): scalar or 2-element vector.
ftype	Response type (low/high/bandpass/stop).
analog	True for the s-domain ('s' flag).

butter() [2/2]

std::tuple< Value, Value > nk::signal::butter	(	int	N,
		double	Wn,
		const std::string &	type = "low",
		std::pmr::memory_resource *	mr = nullptr )

Butterworth IIR lowpass / highpass filter design.

Returns (b, a) — numerator and denominator polynomials.

Parameters

N	Filter order (integer >= 1).
Wn	Normalized cutoff frequency in (0, 1) — fraction of Nyquist.
type	"low" (default) or "high".
mr	Memory resource (nullptr → process default).

Exceptions

Error

if Wn is out of (0, 1) or type is unrecognised.

auto [b, a] = butter(4, 0.3);  // 4th-order lowpass  

buttord()

std::tuple< int, Value > nk::signal::buttord	(	const Value &	Wp,
		const Value &	Ws,
		double	Rp,
		double	Rs,
		bool	analog = false,
		std::pmr::memory_resource *	mr = nullptr )

Butterworth filter order estimator.

Returns the minimum order N and natural frequency Wn such that a Butterworth filter butter(N, Wn, …) has passband ripple ≤ Rp dB and stopband attenuation ≥ Rs dB.

Parameters

Wp	Passband edge(s). Scalar for LP/HP; 2-vector for BP/BS. Digital: normalised to Nyquist (0..1).
Ws	Stopband edge(s), same shape as Wp.
Rp	Maximum allowed passband ripple in dB, > 0.
Rs	Minimum required stopband attenuation in dB, > 0.
analog	Analog-domain flag.
mr	Memory resource (nullptr → process default).

Returns

Tuple (N, Wn) — order and cutoff(s) for butter.

auto [N, Wn] = buttord(0.2, 0.3, 1.0, 30.0);   // LP: 1 dB pass / 30 dB stop
auto [b, a]  = butter(N, Wn);

See also

butter, cheb1ord, cheb2ord, ellipord

cceps()

Value nk::signal::cceps	(	const Value &	x,
		std::pmr::memory_resource *	mr = nullptr,
		double *	ndOut = nullptr )

Complex cepstrum: ifft(log(fft(x))) with phase unwrapping.

Unlike rceps, preserves both magnitude and phase information, enabling exact inversion via icceps.

Parameters

x	Real input vector.
mr	Memory resource (nullptr → process default).
ndOut	If non-null, receives nd — the integer (circular) delay removed by the rcunwrap linear-phase term, i.e. the 2nd output of MATLAB [xhat, nd] = cceps(x).

Returns

Same-length DOUBLE vector.

See also

icceps, rceps

cconv()

Value nk::signal::cconv	(	const Value &	x,
		const Value &	y,
		size_t	n = 0,
		std::pmr::memory_resource *	mr = nullptr )

Circular (cyclic) convolution of two real vectors.

Computes \( out[k] = \sum_{m=0}^{N-1} x[m] \cdot y[(k - m) \bmod N] \) for k = 0..N-1. Inputs are zero-padded to length N before the cyclic wrap. When n == 0 (default), N = max(numel(x), numel(y)).

FFT-based fast path is used when n ≥ numel(x) + numel(y) - 1 (the length at which circular conv collapses to linear conv); otherwise the direct O(N²) loop is used.

Parameters

x	First real vector (any length).
y	Second real vector (any length).
n	Output / wrap length. 0 ≡ max(numel(x), numel(y)).
mr	Memory resource (nullptr → process default).

Returns

1×n DOUBLE row vector.

Value c = cconv({1, 2, 3, 4}, {1, 1, 1});  // length 4 cyclic conv  

cell2sos()

std::tuple< Value, Value > nk::signal::cell2sos	(	const Value &	C,
		std::pmr::memory_resource *	mr = nullptr )

cell2sos(C) — convert cell array of {Bi, Ai} pairs to L×6 SOS matrix.

2-output form [S, G] = cell2sos(C) extracts the leading scalar gain section if present (when C{1} = {scalar_b, scalar_a}). Linear (length-2) sections are zero-padded on the right to length 3.

cheb1ap()

std::tuple< Value, Value, Value > nk::signal::cheb1ap	(	int	N,
		double	Rp,
		std::pmr::memory_resource *	mr = nullptr )

Chebyshev type-I analog lowpass prototype.

Equiripple passband at Rp dB; no finite zeros (all-pole).

Parameters

N	Filter order, ≥ 1.
Rp	Passband ripple in dB, > 0.
mr	Memory resource (nullptr → process default).

Returns

Tuple (z, p, k).

cheb1ord()

std::tuple< int, Value > nk::signal::cheb1ord	(	const Value &	Wp,
		const Value &	Ws,
		double	Rp,
		double	Rs,
		bool	analog = false,
		std::pmr::memory_resource *	mr = nullptr )

Chebyshev type-I order estimator ([N, Wn] = cheb1ord(Wp, Ws, Rp, Rs, analog)).

Wn is the passband edge, usable directly with cheby1.

Parameters

Wp,Ws,Rp,Rs,analog,mr

See buttord.

Returns

Tuple (N, Wn).

See also

buttord, cheby1

cheb2ap()

std::tuple< Value, Value, Value > nk::signal::cheb2ap	(	int	N,
		double	Rs,
		std::pmr::memory_resource *	mr = nullptr )

Chebyshev type-II analog lowpass prototype.

Monotonic passband, equiripple stopband at Rs dB. Has finite zeros on the imaginary axis.

Parameters

N	Filter order, ≥ 1.
Rs	Stopband attenuation in dB, > 0.
mr	Memory resource (nullptr → process default).

Returns

Tuple (z, p, k).

cheb2ord()

std::tuple< int, Value > nk::signal::cheb2ord	(	const Value &	Wp,
		const Value &	Ws,
		double	Rp,
		double	Rs,
		bool	analog = false,
		std::pmr::memory_resource *	mr = nullptr )

Chebyshev type-II order estimator ([N, Wn] = cheb2ord(Wp, Ws, Rp, Rs, analog)).

Wn is the stopband edge, usable directly with cheby2.

Parameters

Wp,Ws,Rp,Rs,analog,mr

See buttord.

Returns

Tuple (N, Wn).

See also

buttord, cheby2

chebwin()

Value nk::signal::chebwin	(	size_t	N,
		double	at = 100.0,
		std::pmr::memory_resource *	mr = nullptr )

Dolph-Chebyshev window of length N — equiripple sidelobes at given attenuation.

All sidelobes have height exactly -at dB below mainlobe peak. Minimises mainlobe width for the given sidelobe ripple.

Parameters

N	Window length, ≥ 1.
at	Sidelobe attenuation in dB (positive number; 100 → -100 dB). Default 100.
mr	Memory resource (nullptr → process default).

Returns

N×1 DOUBLE column vector.

Exceptions

nk::Error

if at ≤ 0.

cheby1()

std::tuple< Value, Value > nk::signal::cheby1	(	int	N,
		double	Rp,
		const Value &	Wn,
		FilterType	ftype = FilterType::Lowpass,
		bool	analog = false,
		std::pmr::memory_resource *	mr = nullptr )

Chebyshev type-I IIR filter design.

Returns digital (or analog) filter coefficients (b, a) of order N with equiripple passband and monotonic stopband. The order-N filter has Rp dB peak-to-peak ripple in the passband.

Parameters

N	Filter order, ≥ 1. For bandpass / bandstop the output order is 2N (each transform doubles).
Rp	Passband ripple in dB, > 0 (typical 0.1–3 dB).
Wn	Cutoff frequency. Digital: normalised to Nyquist (0 < Wn < 1). Analog: rad/s. Scalar for LP/HP, 2-vector [lo hi] for BP/BS.
ftype	Response type (default Lowpass for scalar Wn, Bandpass for 2-vector Wn).
analog	true → analog-domain design (skip bilinear).
mr	Memory resource (nullptr → process default).

Returns

Tuple (b, a) — numerator and denominator coefficients.

auto [b, a] = cheby1(4, 0.5, 0.3);                     // 0.5 dB ripple LP
auto [b, a] = cheby1(4, 1.0, {0.3, 0.6}, FilterType::Bandpass);

See also

cheby2, ellip, butter

cheby2()

std::tuple< Value, Value > nk::signal::cheby2	(	int	N,
		double	Rs,
		const Value &	Wn,
		FilterType	ftype = FilterType::Lowpass,
		bool	analog = false,
		std::pmr::memory_resource *	mr = nullptr )

Chebyshev type-II (inverse Chebyshev) IIR filter design.

Equiripple stopband at Rs dB attenuation, monotonic passband.

Parameters

N	Filter order.
Rs	Stopband attenuation in dB, > 0 (typical 40–60 dB).
Wn	Cutoff frequency (see cheby1).
ftype	Response type.
analog	Analog-domain flag.
mr	Memory resource (nullptr → process default).

Returns

Tuple (b, a).

See also

cheby1, ellip

chirp()

Value nk::signal::chirp	(	const Value &	t,
		double	f0,
		double	t1,
		double	f1,
		const std::string &	method = "linear",
		std::pmr::memory_resource *	mr = nullptr )

Frequency-modulated cosine (chirp).

Three sweep laws:

• "linear" — \( y = \cos(2\pi (f_0 t + ((f_1-f_0)/(2 t_1)) t^2)) \)
• "quadratic" — \( y = \cos(2\pi (f_0 t + ((f_1-f_0)/(3 t_1^2)) t^3)) \)
• "logarithmic" — \( y = \cos(2\pi f_0 ((\beta^t - 1)/\ln\beta)) \), \( \beta = (f_1/f_0)^{1/t_1} \). Requires f0 > 0, f1 > 0, f1 != f0.

Parameters

t	Time samples.
f0	Initial frequency in Hz.
t1	Reference time.
f1	Frequency at time t1 (Hz).
method	"linear" (default), "quadratic", or "logarithmic".
mr	Memory resource (nullptr → process default).

Returns

Same-shape DOUBLE array.

conv()

Value nk::signal::conv	(	const Value &	a,
		const Value &	b,
		const std::string &	shape = "full",
		std::pmr::memory_resource *	mr = nullptr )

1-D convolution of two real vectors.

Computes \( c[k] = \sum_{j} a[j] \cdot b[k - j] \) (the standard non-cyclic convolution). Switches between direct O(na·nb) and FFT-based O((na+nb)·log(na+nb)) implementations based on input size.

Parameters

a	First input vector (real, any length).
b	Second input vector (real, any length).
shape	Output trimming mode: "full" (default): full convolution, length na + nb - 1. "same": central na samples (or max of na, nb), aligned to a. "valid": only the region where the two inputs overlap fully, length |na - nb| + 1.
mr	Memory resource (nullptr → process default).

Returns

1-D DOUBLE vector with the shape per the shape flag.

Exceptions

nk::Error

on unknown shape keyword.

Value c = conv({1, 2, 3}, {1, 1, 1});            // full: {1, 3, 6, 5, 3}
Value s = conv({1, 2, 3, 4, 5}, {1, 1, 1}, "same"); // {3, 6, 9, 12, 9}

See also

conv2, convn, deconv, cconv

conv2()

Value nk::signal::conv2	(	const Value &	A,
		const Value &	B,
		const std::string &	shape = "full",
		std::pmr::memory_resource *	mr = nullptr )

2-D convolution of two real matrices.

Computes \( C[i,j] = \sum_{m,n} A[m,n] \cdot B[i-m, j-n] \) with zero-padding outside the input range.

Parameters

A	First matrix.
B	Second matrix.
shape	Output trimming: "full" (default): (rA + rB - 1) × (cA + cB - 1). "same": size of A, centered on the full result. "valid": only the fully-overlapping region.
mr	Memory resource (nullptr → process default).

Returns

DOUBLE matrix with the shape per the shape flag.

Exceptions

nk::Error

on unknown shape.

Note

Direct nested-loop implementation; for large inputs FFT-based 2-D convolution would be faster but is not yet wired in.

See also

conv, convn, filter2

convmtx()

Value nk::signal::convmtx	(	const Value &	h,
		size_t	n,
		std::pmr::memory_resource *	mr = nullptr )

Convolution matrix for an impulse response.

convmtx(h, n) returns a matrix M such that M * x == conv(h, x) for any column vector x of length n. The shape depends on the orientation of h:

• h is a row → returns n × (n + nh - 1); each row is h shifted right.
• h is a column → returns (n + nh - 1) × n; each column is h shifted down.

where nh = numel(h).

Parameters

h	Impulse response, real row or column vector. Must be non-empty.
n	Number of shifts (must be > 0).
mr	Memory resource (nullptr → process default).

Returns

Convolution matrix per the shape rules above.

Exceptions

nk::Error

if n == 0 or h is empty.

convn()

Value nk::signal::convn	(	const Value &	A,
		const Value &	B,
		const std::string &	shape = "full",
		std::pmr::memory_resource *	mr = nullptr )

N-D convolution.

Generalisation of conv / conv2 to N dimensions. Currently supports 1-D, 2-D, and 3-D inputs.

Parameters

A	First N-D array.
B	Second N-D array.
shape	Output trimming ("full" / "same" / "valid").
mr	Memory resource (nullptr → process default).

Returns

DOUBLE array with shape per shape.

Exceptions

nk::Error

on unknown shape or unsupported rank.

See also

conv, conv2

corrmtx()

Value nk::signal::corrmtx	(	const Value &	x,
		int	m,
		std::pmr::memory_resource *	mr = nullptr )

Generate the autocorrelation data matrix.

Returns the (n+m) × (m+1) matrix X such that X'·X is the biased autocorrelation matrix Rxx (default 'autocorrelation' method). Other methods ('covariance', 'prewindowed', etc.) are deferred.

Parameters

x	Real 1-D signal.
m	Order parameter (X has m+1 columns).
mr	Memory resource (nullptr → process default).

Returns

(n+m) × (m+1) data matrix.

cpsd()

std::tuple< Value, Value > nk::signal::cpsd	(	const Value &	x,
		const Value &	y,
		const Value &	window,
		size_t	noverlap,
		size_t	nfft,
		double	fs = 2.0 *3.14159265358979323846,
		std::pmr::memory_resource *	mr = nullptr )

Cross-PSD via Welch's method.

Estimates the one-sided cross-spectrum \( P_{xy}(f) = E[X(f) \cdot Y^*(f)] \) using the same windowing / segmentation rules as pwelch.

Parameters

x	First real 1-D signal.
y	Second real 1-D signal (same length as x).
window	Window. Value::Empty → Hamming(256).
noverlap	Overlap. 0 → half window length.
nfft	FFT size. 0 → nextPow2(winLen).
fs	Sample rate.
mr	Memory resource (nullptr → process default).

Returns

Tuple (Pxy, F) — Pxy is COMPLEX.

See also

pwelch, mscohere, tfestimate

ctf2zp()

std::tuple< Value, Value, double > nk::signal::ctf2zp	(	const Value &	NUM,
		const Value &	DEN,
		const Value &	SV = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Cascaded transfer function to zero / pole / gain.

NUM (K × Q+1) and DEN (K × R+1) define K cascaded biquad-like sections. The optional SV (scalar or K+1 vector) provides per-section scale values; default 1.

Parameters

NUM	K × (Q+1) numerator-of-section matrix.
DEN	K × (R+1) denominator-of-section matrix.
SV	Section scale values. Value::Empty → all 1.
mr	Memory resource (nullptr → process default).

Returns

Tuple (Z, P, K_gain).

See also

scaleFilterSections

cusum()

CusumResult nk::signal::cusum	(	const Value &	x,
		double	climit = 5.0,
		double	mshift = 1.0,
		const Value &	tmean = Value::Empty,
		const Value &	tdev = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

CUSUM change detector ([iu, il, us, ls] = cusum(x, climit, mshift, tmean, tdev)).

Standardises x to (x - tmean) / tdev, accumulates the one-sided CUSUM statistics with an mshift/2 slack, and reports the first sample index at which each one-sided sum first exceeds climit. The target mean / std default to the mean / std of the first 25 samples.

Parameters

x	Input signal.
climit	Control limit in standard-deviation units (default 5).
mshift	Mean shift to detect, in standard-deviation units (default 1).
tmean	Target mean (Value::Empty → mean(x(1:25))).
tdev	Target std-dev (Value::Empty → std(x(1:25))).
mr	Memory resource (nullptr → process default).

Returns

CusumResult { iupper, ilower, uppersum, lowersum }.

czt()

Value nk::signal::czt	(	const Value &	x,
		int	m,
		Complex	w,
		Complex	a,
		std::pmr::memory_resource *	mr = nullptr )

Chirp Z-transform (Bluestein).

Computes \( Y[k] = \sum_{n=0}^{N-1} x[n] \cdot a^{-n} \cdot w^{n k} \) for k = 0..m-1. Generalises fft to arbitrary contour points on the z-plane (zoom FFT, fractional-rate FFT, etc.).

Defaults that recover fft:

• m = N (input length)
• w = exp(-2πj / m)
• a = 1.0

Algorithm: Bluestein decomposition n·k = (n² + k² − (k−n)²)/2 converts the sum into a convolution g ⋆ h evaluated via an FFT of length L = nextPow2(N + m − 1).

For 2-D input, transforms each column independently. 3-D input is not supported.

Parameters

x	Input (real or complex), 1-D or 2-D.
m	Number of output points.
w	Ratio between consecutive contour points (complex).
a	Starting contour point (complex).
mr	Memory resource (nullptr → process default).

Returns

m-length (or m × Ncols) COMPLEX result.

// Zoom around a narrow band [f1, f2] of an N-sample sequence,
// sampling m points:
Complex w = std::polar(1.0, -2 * M_PI * (f2 - f1) / m);
Complex a = std::polar(1.0, -2 * M_PI * f1);
Value Y = czt(x, m, w, a);

db()

Value nk::signal::db	(	const Value &	x,
		const std::string &	signalType = "voltage",
		std::pmr::memory_resource *	mr = nullptr )

Convert magnitude or power to decibels.

For signalType == "voltage" (default): \( y = 20 \log_{10} |x| \).

For signalType == "power": \( y = 10 \log_{10} |x| \).

Complex input is reduced to magnitude before the log.

Parameters

x	Input (real or complex, any shape). Non-positive magnitudes yield -inf.
signalType	"voltage" (default) or "power".
mr	Memory resource (nullptr → process default).

Returns

DOUBLE array, same shape as x.

Exceptions

nk::Error

on unknown signalType.

See also

db2mag, db2pow, mag2db, pow2db

db2mag()

Value nk::signal::db2mag	(	const Value &	d,
		std::pmr::memory_resource *	mr = nullptr )

Inverse of db in voltage form: \( y = 10^{d/20} \).

Parameters

d	Magnitudes in dB.
mr	Memory resource (nullptr → process default).

Returns

DOUBLE array, same shape as d.

See also

db, mag2db

db2pow()

Value nk::signal::db2pow	(	const Value &	d,
		std::pmr::memory_resource *	mr = nullptr )

Inverse of pow2db: \( y = 10^{d/10} \).

Parameters

d	Power values in dB.
mr	Memory resource (nullptr → process default).

Returns

DOUBLE array of linear-power values.

See also

pow2db

dct() [1/2]

Value nk::signal::dct	(	const Value &	x,
		int	n,
		int	dim,
		std::pmr::memory_resource *	mr = nullptr )

DCT-II with explicit length / axis.

Parameters

x	Real input (1-D or 2-D).
n	Output length along dim. n <= 0 ≡ use native extent. n > axis_len zero-pads; n < axis_len truncates.
dim	Axis to transform along. 0 (default) = first non-singleton. 1 = rows, 2 = columns.
mr	Memory resource (nullptr → process default).

Returns

DOUBLE array with dim axis replaced by length n.

Value Y = dct(matrix, -1, 1);   // per-column DCT of a 2-D matrix

dct() [2/2]

Value nk::signal::dct	(	const Value &	x,
		std::pmr::memory_resource *	mr = nullptr )

Type-II discrete cosine transform (the default form).

1-D entry point — computes \( Y[k] = w[k] \sum_{n=0}^{N-1} x[n] \cos\!\left(\frac{\pi (2n+1) k}{2N}\right) \) where \( w[0] = \sqrt{1/N},\ w[k>0] = \sqrt{2/N} \) (orthonormal form).

Parameters

x	Real 1-D vector.
mr	Memory resource (nullptr → process default).

Returns

Same-shape DOUBLE vector.

Value Y = dct({1.0, 2.0, 3.0, 4.0});  

See also

idct

decimate()

Value nk::signal::decimate	(	const Value &	x,
		size_t	factor,
		std::pmr::memory_resource *	mr = nullptr )

Integer-factor decimation with anti-alias filtering.

Pipeline: design an FIR lowpass with cutoff 1/factor of Nyquist and order 8 · factor (clamped to nx - 1), filter, then downsample by factor. Suppresses aliasing that would otherwise wrap into the preserved Nyquist band.

Parameters

x	Input signal.
factor	Decimation factor, ≥ 1.
mr	Memory resource (nullptr → process default).

Returns

Decimated signal, length ceil(nx / factor).

See also

downsample, resample

deconv()

std::tuple< Value, Value > nk::signal::deconv	(	const Value &	b,
		const Value &	a,
		std::pmr::memory_resource *	mr = nullptr )

Polynomial long-division: b = conv(a, q) + r.

Recovers the quotient q and remainder r such that the original polynomial relationship holds (the [q, r] = deconv(b, a) form).

Parameters

b	Dividend polynomial (real row/column vector).
a	Divisor polynomial. a[0] must be non-zero. length(a) must be ≤ length(b).
mr	Memory resource (nullptr → process default).

Returns

Tuple (q, r) with length(q) = length(b) - length(a) + 1 and length(r) = length(b).

Exceptions

nk::Error

if a is longer than b, or a[0] == 0.

See also

conv

demod()

Value nk::signal::demod	(	const Value &	y,
		double	Fc,
		double	Fs,
		const std::string &	method,
		const Value &	opt = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Analog demodulation (AM family).

Supported method:

• "am" / "amdsb-sc" — multiply by cos(2π Fc t), then lowpass.
• "amdsb-tc" — same, but opt is the DC offset to subtract.

Pipeline: y · cos(2π Fc t) → 5th-order Butterworth lowpass at cutoff 2·Fc/Fs via filtfilt.

Parameters

y	Received signal.
Fc	Carrier frequency in Hz.
Fs	Sample rate in Hz.
method	Demodulation type.
opt	Method-specific scalar (DC offset for amdsb-tc).
mr	Memory resource (nullptr → process default).

Returns

Demodulated message signal.

Note

KNOWN GAPs: "fm" / "pm" (use Hilbert, blocked on toolboxes/signal FFT sign-convention bug), "amssb", "pwm", "ptm", "ppm", "qam".

See also

modulate

dftmtx()

Value nk::signal::dftmtx	(	size_t	N,
		std::pmr::memory_resource *	mr = nullptr )

N×N complex DFT matrix.

Returns the matrix \( F \) with \( F[k][n] = \exp(-2\pi j \cdot k \cdot n / N) \), so that for any column vector x, F * x == fft(x, N).

Parameters

N	Matrix dimension, ≥ 1.
mr	Memory resource (nullptr → process default).

Returns

N×N COMPLEX matrix.

Value F = dftmtx(8);  Value X = F * x;  // FFT via matmul  

diric()

Value nk::signal::diric	(	const Value &	x,
		int	n,
		std::pmr::memory_resource *	mr = nullptr )

Dirichlet (periodic-sinc) function of order n.

\( y(x) = \frac{\sin(nx/2)}{n \sin(x/2)} \) for x not a multiple of 2π; at x = 2π k: y = (-1)^{k(n-1)}.

Parameters

x	Real array.
n	Order, positive integer.
mr	Memory resource (nullptr → process default).

Returns

Same-shape DOUBLE array.

downsample()

Value nk::signal::downsample	(	const Value &	x,
		size_t	n,
		std::pmr::memory_resource *	mr = nullptr,
		size_t	phase = 0 )

Integer-rate downsampling — keep every n-th sample.

y[i] = x[i · n]. Does NOT apply an anti-aliasing filter — use decimate when you need that. Output length is ceil(nx / n). Orientation (row vs. column) is preserved.

Parameters

x	Input signal.
n	Decimation factor, ≥ 1.
mr	Memory resource (nullptr → process default).

Returns

Downsampled signal.

See also

decimate, upsample, resample

phase (0 ≤ phase < n) offsets the first kept sample: the output is x[phase], x[phase+n], ….

dst()

Value nk::signal::dst	(	const Value &	x,
		std::pmr::memory_resource *	mr = nullptr )

Type-II Discrete Sine Transform.

Computes \( Y[k] = \sum_{n=0}^{N-1} x[n] \cdot \sin\!\left(\frac{\pi (n+1)(k+1)}{N+1}\right) \) for k = 0..N-1.

Parameters

x	Real input vector.
mr	Memory resource (nullptr → process default).

Returns

Same-length DOUBLE vector.

See also

idst, dct

dutycycle()

Value nk::signal::dutycycle	(	const Value &	x,
		const Value &	fs = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Duty cycle: fraction of each pulse period spent above the mid-state.

Parameters

x	Real 1-D signal.
fs	Sample rate in Hz. Value::Empty → samples (units cancel in the ratio).
mr	Memory resource (nullptr → process default).

Returns

Column vector of values in [0, 1], one entry per period.

See also

pulsewidth, pulseperiod

ellip()

std::tuple< Value, Value > nk::signal::ellip	(	int	N,
		double	Rp,
		double	Rs,
		const Value &	Wn,
		FilterType	ftype = FilterType::Lowpass,
		bool	analog = false,
		std::pmr::memory_resource *	mr = nullptr )

Elliptic (Cauer) IIR filter design.

Equiripple in both passband (Rp dB) and stopband (Rs dB). The most frequency-selective IIR design for a given order.

Parameters

N	Filter order.
Rp	Passband ripple in dB, > 0.
Rs	Stopband attenuation in dB, > 0, > Rp.
Wn	Cutoff frequency (see cheby1).
ftype	Response type.
analog	Analog-domain flag.
mr	Memory resource (nullptr → process default).

Returns

Tuple (b, a).

ellipap()

std::tuple< Value, Value, Value > nk::signal::ellipap	(	int	N,
		double	Rp,
		double	Rs,
		std::pmr::memory_resource *	mr = nullptr )

Elliptic (Cauer) analog lowpass prototype.

Equiripple in both bands. Algorithm: Sophocleous / Orfanidis formulas built on Jacobi elliptic functions and the degree equation K(k')/K(k) = (1/N) · K(k1')/K(k1). Has finite zeros on the imaginary axis (transmission zeros).

Parameters

N	Filter order, ≥ 1.
Rp	Passband ripple in dB, > 0.
Rs	Stopband attenuation in dB, > Rp.
mr	Memory resource (nullptr → process default).

Returns

Tuple (z, p, k).

ellipord()

std::tuple< int, Value > nk::signal::ellipord	(	const Value &	Wp,
		const Value &	Ws,
		double	Rp,
		double	Rs,
		bool	analog = false,
		std::pmr::memory_resource *	mr = nullptr )

Elliptic (Cauer) order estimator ([N, Wn] = ellipord(Wp, Ws, Rp, Rs, analog)).

Wn for direct use with ellip. KNOWN GAP: bandstop case (Wp 2-vec with Wp[0] > Ws[0]) deferred. Lowpass / highpass / bandpass supported.

Parameters

Wp,Ws,Rp,Rs,analog,mr

See buttord.

Returns

Tuple (N, Wn).

See also

buttord, ellip

enbw()

Value nk::signal::enbw	(	const Value &	window,
		const Value &	fs = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Equivalent noise bandwidth of a window (b = enbw(window, fs)).

\( \mathrm{ENBW} = f_s \cdot \sum w_n^2 \big/ (\sum w_n)^2 \). Dimensionless when fs.isEmpty().

Parameters

window	Window vector.
fs	Sample rate, or Value::Empty.
mr	Memory resource (nullptr → process default).

Returns

Scalar ENBW.

envelope()

Value nk::signal::envelope	(	const Value &	x,
		std::pmr::memory_resource *	mr = nullptr )

Amplitude envelope of a real signal: |hilbert(x)|.

Parameters

x	Real input signal.
mr	Memory resource (nullptr → process default).

Returns

DOUBLE vector of the same length as x.

See also

hilbert, envelope_full

envelope_full()

std::pair< Value, Value > nk::signal::envelope_full	(	const Value &	x,
		int	mode,
		std::size_t	n,
		std::pmr::memory_resource *	mr = nullptr )

Full multi-mode envelope computation.

Parameters

x	Real input signal.
mode	Envelope algorithm: 0: default, FFT-based |hilbert(x - mean)| 1: 'analytic' — n-tap Kaiser-tapered Hilbert FIR 2: 'rms' — sliding RMS over n-sample window 3: 'peak' — cubic spline through local maxima / minima with MinPeakDistance = n
n	Window / filter length (modes 1, 2, 3); ignored for 0.
mr	Memory resource (nullptr → process default).

Returns

(yupper, ylower). For modes 0–2 the envelopes are symmetric around the signal mean; mode 3 is spline-interpolated and generally asymmetric.

envelope_pair()

std::pair< Value, Value > nk::signal::envelope_pair	(	const Value &	x,
		std::pmr::memory_resource *	mr = nullptr )

2-output envelope (DC-symmetric form).

Computes yupper = mean + |hilbert(x - mean)|, ylower = mean - |hilbert(x - mean)|. Subtracting the mean before the Hilbert transform avoids edge artefacts from a DC offset.

Parameters

x	Real input signal.
mr	Memory resource (nullptr → process default).

Returns

(yupper, ylower) — bind with auto [up, lo] = envelope_pair(x);.

envspectrum()

std::tuple< Value, Value > nk::signal::envspectrum	(	const Value &	x,
		double	fs = 0.0,
		std::pmr::memory_resource *	mr = nullptr )

Envelope spectrum: magnitude FFT of the AC-coupled analytic-signal envelope.

Pipeline: |hilbert(x - mean(x))| → fft → |·|. Used in vibration diagnostics to extract modulation frequencies (e.g. bearing fault signatures) from a high-frequency carrier.

Parameters

x	Real 1-D signal.
fs	Sample rate in Hz. 0.0 (default) → frequencies returned in rad/sample ([0, π]). With fs > 0 → Hz ([0, fs/2]).
mr	Memory resource (nullptr → process default).

Returns

Tuple (Es, F) — magnitude spectrum and frequency grid, both single-sided column vectors of length floor(N/2)+1.

See also

hilbert

extendsigroi()

Value nk::signal::extendsigroi	(	const Value &	roi,
		int64_t	Lpre,
		int64_t	Lpost,
		std::pmr::memory_resource *	mr = nullptr )

Extend each ROI (roi = extendsigroi(roi, Lpre, Lpost)).

Extends each ROI by Lpre samples on the left and Lpost on the right; clamps start to >= 1.

Parameters

roi	N × 2 ROI matrix.
Lpre	Left extension.
Lpost	Right extension.
mr	Memory resource (nullptr → process default).

Returns

Extended ROI matrix.

See also

shortensigroi

extractsigroi()

Value nk::signal::extractsigroi	(	const Value &	x,
		const Value &	roi,
		bool	concat = false,
		std::pmr::memory_resource *	mr = nullptr )

Extract signal slices indexed by ROIs (y = extractsigroi(x, roi, concat)).

Parameters

x	Source signal (column vector).
roi	N × 2 ROI matrix.
concat	false (default) → return a cell of column-vector slices; true → return a single concatenated column.
mr	Memory resource (nullptr → process default).

Returns

Cell or concatenated column.

falltime()

Value nk::signal::falltime	(	const Value &	x,
		const Value &	fs = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Fall time of negative-going transitions (90% → 10%).

Mirror of risetime for downward transitions.

Parameters

x	Real 1-D signal.
fs	Sample rate in Hz. Value::Empty → samples.
mr	Memory resource (nullptr → process default).

Returns

Column vector of fall times; one per detected transition.

See also

risetime, slewrate

fft()

Value nk::signal::fft	(	const Value &	x,
		int	n = -1,
		int	dim = 0,
		std::pmr::memory_resource *	mr = nullptr )

1-D discrete Fourier transform along a given dimension.

Call forms:

• fft(x) — along the first non-singleton dimension
• fft(x, n) — zero-pad or truncate to length n first
• fft(x, -1, k) — along dimension k (1=rows, 2=cols, 3=pages)
• fft(x, n, k) — both n and dim explicit

Forward transform is always complex-typed; an inverse transform that happens to produce a real result (imaginary part ≤ 1e-10 everywhere) is automatically downgraded to DOUBLE.

Parameters

x	Input — real or complex, 1-D / 2-D / 3-D. Empty → empty.
n	Output length per transform along dim. -1 (default) keeps the input length; n > axis_len zero-pads; n < axis_len truncates.
dim	Axis to transform along. 0 (default) = first non-singleton dimension (a row vector therefore stays a row vector). 1 = rows, 2 = columns, 3 = pages.
mr	Memory resource (nullptr → process default).

Returns

Value of the same shape as x with the chosen axis replaced by the output length; COMPLEX-typed.

Exceptions

nk::Error

if dim is outside {0, 1, 2, 3}, or the request would extend a singleton axis.

Value X = fft({1.0, 2.0, 3.0, 4.0});       // 4-pt FFT
Value Y = fft(x, 8);                       // zero-pad to 8 samples
Value Z = fft(matrix3d, -1, 2);            // transform along columns

See also

ifft, fft2, fftn, czt

fft2()

Value nk::signal::fft2	(	const Value &	X,
		int	m = -1,
		int	n = -1,
		std::pmr::memory_resource *	mr = nullptr )

2-D forward FFT.

Equivalent to fft(fft(X, m, 1), n, 2). m == -1 and / or n == -1 keep the corresponding dimension at its current length.

Parameters

X	2-D input (real or complex).
m	Number of rows for the FFT, -1 keeps size(X, 1).
n	Number of columns, -1 keeps size(X, 2).
mr	Memory resource (nullptr → process default).

Returns

m × n COMPLEX matrix.

See also

ifft2, fftn

fftfilt()

Value nk::signal::fftfilt	(	const Value &	b,
		const Value &	x,
		size_t	nfft = 0,
		std::pmr::memory_resource *	mr = nullptr )

Overlap-add FFT-based FIR filtering.

Filters x with FIR b using the overlap-add method on blocks of length nfft. For long signals and moderately long filters this is substantially faster than filter(b, [1], x).

Parameters

b	FIR filter coefficients.
x	Input signal.
nfft	FFT block size. 0 (default) → chooses a heuristic based on numel(b).
mr	Memory resource (nullptr → process default).

Returns

Filtered signal of length numel(x).

See also

filter, conv

fftn()

Value nk::signal::fftn	(	const Value &	X,
		Span< const std::size_t >	sz = {},
		std::pmr::memory_resource *	mr = nullptr )

N-D forward FFT.

Call forms:

• fftn(X) — FFT along every dimension of X at its current length.
• fftn(X, sz) — same, but axis k is zero-padded or truncated to sz[k] before its FFT. sz.size() must be ≤ ndims(X).

Implemented as fft along each axis in turn (axis order does not affect the result).

Parameters

X	N-D input.
sz	Per-axis target sizes (empty Span → use X's current shape).
mr	Memory resource (nullptr → process default).

Returns

Same-shape (or sz-shape) COMPLEX array.

See also

fft, fft2, ifftn

fftshift() [1/2]

Value nk::signal::fftshift	(	const Value &	x,
		int	dim,
		std::pmr::memory_resource *	mr = nullptr )

Single-dim fftshift — shift only along axis dim.

Parameters

x	Input array.
dim	Axis (1 = rows, 2 = cols, 3 = pages).
mr	Memory resource (nullptr → process default).

Returns

Same-shape array shifted along dim.

fftshift() [2/2]

Value nk::signal::fftshift	(	const Value &	x,
		std::pmr::memory_resource *	mr = nullptr )

DC-to-center reordering for FFT output (multidim form).

Cyclically shifts x by ceil(extent/2) along every non-singleton dimension. After fftshift(fft(x)) the DC component (k = 0) lies at the center of each axis. For odd extents the first ceil(N/2) elements move to the back.

Parameters

x	Input array (any shape, any type).
mr	Memory resource (nullptr → process default).

Returns

Same-shape and same-type array with elements permuted.

See also

ifftshift, fft

filter()

Value nk::signal::filter	(	const Value &	b,
		const Value &	a,
		const Value &	x,
		std::pmr::memory_resource *	mr = nullptr )

Direct-form II transposed IIR / FIR filter.

Implements the standard difference equation

\[ a_0\, y[n] = \sum_{k=0}^{M} b_k\, x[n-k] - \sum_{k=1}^{N} a_k\, y[n-k] \]

Normalisation by a[0] is folded into the coefficients up-front, so the runtime per-sample cost is one MAC per b and a coefficient.

Parameters

b	Numerator polynomial. Must be non-empty.
a	Denominator polynomial. a[0] must be non-zero.
x	Input signal (real vector or matrix).
mr	Memory resource (nullptr → process default).

Returns

Filtered signal, same shape as x.

Exceptions

nk::Error

if a[0] == 0 or either polynomial is empty.

auto [b, a] = butter(4, 0.3);
Value y = filter(b, a, x);

See also

filtfilt, sosfilt

filter2()

Value nk::signal::filter2	(	const Value &	h,
		const Value &	X,
		const std::string &	shape = "same",
		std::pmr::memory_resource *	mr = nullptr )

2-D filter — filter2(h, X[, shape]).

Equivalent to conv2(X, rot90(h, 2), shape): the filter kernel h is rotated 180° before convolution, matching the engineering convention used in image filtering.

Parameters

h	Filter kernel (2-D matrix).
X	Input image (2-D matrix).
shape	Output trimming, see conv2. Default "same".
mr	Memory resource (nullptr → process default).

Returns

Filtered DOUBLE matrix.

See also

conv2

filternorm()

double nk::signal::filternorm	(	const Value &	b,
		const Value &	a,
		double	pnorm = 2.0,
		std::pmr::memory_resource *	mr = nullptr )

L_p norm of a digital filter's frequency response.

For \( p = 2 \) (default, energy norm):

\[ \|H\|_2 = \sqrt{\frac{1}{\pi} \int_0^{\pi} |H(e^{j\omega})|^2 \, d\omega} \]

For \( p = \infty \) (peak gain):

\[ \|H\|_\infty = \max_{\omega \in [0, \pi]} |H(e^{j\omega})| \]

Parameters

b	Numerator polynomial. Must be non-empty.
a	Denominator polynomial. Must be non-empty and a[0] != 0.
pnorm	Either 2.0 (default) or std::numeric_limits<double>::infinity().
mr	Memory resource for the internal freqz grid (nullptr → default).

Returns

Non-negative L_p norm. +inf when the filter is unstable and pnorm == inf.

Exceptions

nk::Error

if b / a empty, a[0] == 0, or pnorm is neither 2 nor +inf.

Note

Internally evaluates freqz on a uniform 8192-point grid on \( [0, \pi] \) (the default NFFT).

auto [b, a] = butter(4, 0.3);
double e = filternorm(b, a);                                    // L_2
double p = filternorm(b, a, std::numeric_limits<double>::infinity()); // L_inf

See also

freqz, isstable

filtfilt()

Value nk::signal::filtfilt	(	const Value &	b,
		const Value &	a,
		const Value &	x,
		std::pmr::memory_resource *	mr = nullptr )

Zero-phase forward-backward filtering.

Applies filter(b, a, ·) twice: once forward, once on the reversed signal, then reverses again. Cancels the filter's phase response so the output has zero phase distortion (but doubles the effective magnitude response).

Uses edge-reflected padding (length 3 · max(nb, na)) to suppress startup transients at both ends.

Parameters

b	Numerator polynomial.
a	Denominator polynomial. a[0] != 0.
x	Input signal. Length must exceed 3 · max(nb, na).
mr	Memory resource (nullptr → process default).

Returns

Zero-phase filtered signal, same shape as x.

Exceptions

nk::Error

if a[0] == 0 or x is too short.

See also

filter

filtord() [1/2]

int nk::signal::filtord

(

const Value &

b

)

Filter order.

Returns:

• FIR (a omitted or a == [1]): length(b_trimmed) - 1.
• IIR: max(length(b_trimmed), length(a_trimmed)) - 1.

Trailing zeros of b and a are trimmed before counting.

Parameters

b	Numerator polynomial.

Returns

Integer filter order.

filtord() [2/2]

int nk::signal::filtord	(	const Value &	b,
		const Value &	a )

Filter order with explicit denominator (n = filtord(b, a)).

IIR formula: max(length(b_trimmed), length(a_trimmed)) - 1. Trailing zeros of b and a are trimmed before counting.

Parameters

b	Numerator polynomial.
a	Denominator polynomial.

Returns

Integer filter order.

finddelay()

long nk::signal::finddelay	(	const Value &	x,
		const Value &	y,
		long	max_lag = 0,
		std::pmr::memory_resource *	mr = nullptr )

Estimate the integer delay between two signals.

Returns the lag d (in samples) such that x(t) ≈ y(t - d). A positive d means y lags x. Computed as the lag corresponding to the maximum of the cross-correlation xcorr(x, y).

Parameters

x	First signal.
y	Second signal.
max_lag	Cap on the search range in samples. 0 (default) → full range, ±max(nx, ny) - 1.
mr	Memory resource (nullptr → process default).

Returns

Integer lag in samples (signed).

findpeaks()

std::tuple< Value, Value > nk::signal::findpeaks	(	const Value &	x,
		std::pmr::memory_resource *	mr = nullptr )

Locate strict local maxima in a signal.

A sample at position i is a peak iff x[i-1] < x[i] > x[i+1]. The endpoints (i = 0 or last) are never returned as peaks.

Parameters

x	Real 1-D signal.
mr	Memory resource (nullptr → process default).

Returns

Tuple (peakValues, peakIndices). Indices are 1-based; both outputs are row vectors of the same length, empty when no peaks exist.

Note

Plateaus (x[i] == x[i+1]) do not count as peaks under the strict-inequality rule.

auto [pks, locs] = findpeaks({1.0, 3.0, 1.0, 5.0, 2.0});
// pks  = {3.0, 5.0}; locs = {2, 4}

fir1()

Value nk::signal::fir1	(	int	N,
		double	Wn,
		const std::string &	type = "low",
		std::pmr::memory_resource *	mr = nullptr )

FIR filter design via windowed-sinc (Hamming window).

Returns the impulse response coefficients b (row vector of length N+1).

Parameters

N	Filter order (>= 1). Output length is N+1.
Wn	Normalized cutoff frequency in (0, 1) — fraction of Nyquist.
type	"low" (default) or "high".
mr	Memory resource (nullptr → process default).

fir2()

Value nk::signal::fir2	(	int	n,
		const Value &	f,
		const Value &	m,
		const Fir2Options &	opts = {},
		std::pmr::memory_resource *	mr = nullptr )

Frequency-sampling FIR filter design (b = fir2(n, f, m [, npt] [, lap] [, window])).

Designs an order-n FIR filter whose magnitude response is the piecewise-linear interpolation of the (f, m) breakpoints. The desired response is sampled on a uniform grid, inverse-transformed, and windowed (frequency-sampling method). An odd n with a non-zero response at the Nyquist frequency is increased by one.

Parameters

n	Filter order (positive integer). Output length is n+1, or n+2 if n is odd-corrected.
f	Break frequencies in [0, 1] (1 = Nyquist). f(1)=0, f(end)=1, non-decreasing.
m	Desired amplitude at each break frequency.
opts	Optional npt / lap / window; see Fir2Options.
mr	Memory resource (nullptr → process default).

Returns

Filter coefficients as a row vector.

Value b = fir2(50, {0,0.3,0.5,0.7,1}, {1,1,0,0,0});  

firls()

Value nk::signal::firls	(	int	N,
		const Value &	F,
		const Value &	A,
		std::pmr::memory_resource *	mr = nullptr )

Least-squares FIR filter design (Type-I linear-phase only).

Solves the weighted least-squares problem on a piecewise-linear desired amplitude response specified by frequency-edge / amplitude pairs. Returns the impulse response coefficients b (row vector of length N+1).

Parameters

N	Filter order (must be even — Type-I only). Length = N+1.
F	Vector of band-edge frequencies in [0, 1] (Nyquist=1), must have even length and be non-decreasing.
A	Desired amplitudes at each F point (same length as F). Within each band [F[2k], F[2k+1]] the desired amp is linearly interpolated from A[2k] to A[2k+1].
mr	Memory resource (nullptr → process default).

Exceptions

Error

if N is odd, or F/A invalid.

Value b = firls(40, {0, 0.4, 0.5, 1.0}, {1, 1, 0, 0});  

firpm()

std::tuple< Value, double > nk::signal::firpm	(	int	N,
		const Value &	F,
		const Value &	A,
		const Value &	W = Value::Empty,
		const std::string &	ftype = "",
		std::pmr::memory_resource *	mr = nullptr )

firpm(N, F, A [, W] [, ftype]) — Parks-McClellan optimal equiripple FIR (Remez exchange).

Returns (b, err) — b is the row vector of length N+1 of filter coefficients, err is the peak ripple magnitude |δ|. Supports all four linear-phase FIR types via the Q-factor trick:

• Type I (even N, symmetric) — Q(ω) = 1
• Type II (odd N, symmetric) — Q(ω) = cos(ω/2)
• Type III (even N, anti-symmetric) — Q(ω) = sin(ω)
• Type IV (odd N, anti-symmetric) — Q(ω) = sin(ω/2) Type III / IV are selected by passing ftype = "hilbert" (constant amplitude) or "differentiator" (amplitude linear in frequency).

Parameters

N	Filter order ≥ 3.
F	Band edges in [0,1] (Nyquist=1), even-length, non-decreasing.
A	Desired amplitude at each F point — piecewise linear interpolation inside each band.
W	Optional weight per band (length = F.numel()/2). Pass an empty Value{} for unit weights everywhere.
ftype	"" / "hilbert" / "differentiator" (case-insensitive). Empty / unset → Type I (even N) or II (odd N).
mr	Memory resource (nullptr → process default).

KNOWN GAPS: no fresp function-handle form, lgrid fixed at the default (16), no 3rd res output struct.

auto [h, err] = firpm(30, {0,0.4,0.5,1}, {1,1,0,0});            // LP
auto [h, err] = firpm(30, {0,0.4,0.5,1}, {1,1,0,0}, {1, 10});   // weighted
auto [h, err] = firpm(30, {0.05, 0.95}, {1, 1}, {}, "hilbert"); // Type III

firpmord()

std::tuple< int, Value, Value, Value > nk::signal::firpmord	(	const Value &	F,
		const Value &	A,
		const Value &	dev,
		double	fs = 2.0,
		std::pmr::memory_resource *	mr = nullptr )

Parks-McClellan FIR order estimator.

Returns (N, ff, aa, wts) — order plus the band-edge, amplitude, and weight vectors suitable for direct use with firpm.

Parameters

F	Vector of band-edge frequencies in Hz (length 2·numel(A) - 2).
A	Vector of binary amplitudes per band (0 = stopband, 1 = passband).
dev	Maximum allowed linear deviation per band.
fs	Sample rate. Default 2.0 → F is normalised to Nyquist.
mr	Memory resource (nullptr → process default).

Returns

Tuple (N, ff, aa, wts).

auto [N, ff, aa, wts] = firpmord({1500, 2000}, {1, 0}, {0.01, 0.05}, 8000);
auto [h, err] = firpm(N, ff, aa, wts);

See also

firpm

firtype()

int nk::signal::firtype

(

const Value &

b

)

FIR filter type classification (1–4).

• Type 1: even order (odd length), b symmetric.
• Type 2: odd order (even length), b symmetric.
• Type 3: even order (odd length), b antisymmetric.
• Type 4: odd order (even length), b antisymmetric.

Parameters

b	Numerator polynomial of a linear-phase FIR.

Returns

Type number in {1, 2, 3, 4}.

Exceptions

nk::Error

if b is neither symmetric nor antisymmetric within tolerance.

See also

islinphase

flattopwin()

Value nk::signal::flattopwin	(	size_t	N,
		std::pmr::memory_resource *	mr = nullptr )

Flat-top window of length N — 5-term cosine sum, optimised for amplitude accuracy (not frequency resolution).

Used in calibration / amplitude-measurement applications: the flat passband near DC ensures accurate peak-amplitude readout even when a tone falls between bins.

Parameters

N	Window length, ≥ 1.
mr	Memory resource (nullptr → process default).

Returns

N×1 DOUBLE column vector.

freqs()

Value nk::signal::freqs	(	const Value &	b,
		const Value &	a,
		const Value &	w,
		std::pmr::memory_resource *	mr = nullptr )

Frequency response of an analog filter b(s)/a(s).

Evaluates H(jω) = B(jω) / A(jω) at the angular frequencies in w.

Parameters

b	Analog numerator polynomial.
a	Analog denominator polynomial.
w	Angular frequencies in rad/s.
mr	Memory resource (nullptr → process default).

Returns

COMPLEX vector of H(jω) values, same shape as w.

See also

freqz

freqz()

std::tuple< Value, Value > nk::signal::freqz	(	const Value &	b,
		const Value &	a,
		size_t	npts = 512,
		std::pmr::memory_resource *	mr = nullptr,
		bool	whole = false,
		double	fs = 0.0 )

Frequency response of a digital filter.

Computes \( H(e^{j\omega}) = \frac{B(e^{j\omega})}{A(e^{j\omega})} \) on a uniform grid \( \omega \in [0, \pi] \).

Parameters

b	Numerator polynomial (real row / column vector).
a	Denominator polynomial. For FIR, pass {1.0}. a[0] must be non-zero.
npts	Number of frequency points. Default 512.
mr	Memory resource (nullptr → process default).

Returns

Tuple (H, W):

• H — npts × 1 COMPLEX vector of response values.
• W — npts × 1 DOUBLE vector of frequencies in rad/sample.

auto [b, a] = butter(4, 0.3);
auto [H, w] = freqz(b, a, 1024);
// magnitude in dB:
// mag_dB = 20*log10(abs(H))

See also

phasez, grpdelay, freqs

whole selects the full unit circle: the grid spans [0, 2π) with w = 2π·(0:n-1)/n (MATLAB freqz(..., 'whole')). Default is the half circle [0, π), w = π·(0:n-1)/n.

fs > 0 selects the sample-rate form freqz(b, a, n, fs): the returned frequency vector is then in Hz over [0, fs/2) (or [0, fs) with whole). The response H is unchanged — only the frequency axis is rescaled by fs/(2π).

fwht()

Value nk::signal::fwht	(	const Value &	x,
		std::size_t	n,
		const std::string &	ordering,
		std::pmr::memory_resource *	mr = nullptr )

Fast Walsh-Hadamard transform (y = fwht(x[, n[, ordering]])).

Computes y = (1/N) · H_natural · x (the discrete Walsh-Hadamard transform), normalised so that y(1) = mean(x). For matrix x the transform is applied column-wise.

Length handling:

• If n == 0 (omitted), the transform length defaults to the next power of 2 ≥ length(x) (zero-padding if needed).
• If n is given it must be a power of 2: x is truncated or zero-padded to length n.

Orderings:

• "sequency" (default) — Walsh-function order (rows sorted by zero-crossing count). Equivalent to dyadic then gray-code permutation g(i) = i XOR (i>>1).
• "hadamard" — natural Hadamard order (recursive Sylvester construction).
• "dyadic" — bit-reversed natural order (Paley order).

Parameters

x	Real input vector / matrix.
n	Transform length (0 → auto-promote to next pow-2).
ordering	"sequency" (default), "hadamard", or "dyadic".
mr	Memory resource (nullptr → process default).

Returns

Walsh-Hadamard coefficients.

See also

ifwht

gauspuls()

Value nk::signal::gauspuls	(	const Value &	t,
		double	fc,
		double	bw = 0.5,
		std::pmr::memory_resource *	mr = nullptr )

Gaussian-modulated sinusoid.

\( y(t) = \exp(-\alpha t^2) \cos(2\pi f_c t) \) where α is set so the envelope reaches bw fractional bandwidth at the -6 dB level (bwr = -6 dB hard-coded).

Parameters

t	Time samples.
fc	Centre frequency in Hz.
bw	Fractional bandwidth. Default 0.5.
mr	Memory resource (nullptr → process default).

Returns

Same-shape DOUBLE array.

gausswin()

Value nk::signal::gausswin	(	size_t	N,
		double	alpha = 2.5,
		std::pmr::memory_resource *	mr = nullptr )

Gaussian window of length N.

Formula: \( w(n) = \exp\!\left(-\frac{1}{2}\left(\alpha \frac{n - (N-1)/2}{(N-1)/2}\right)^2\right) \).

α controls the width: smaller α → wider mainlobe / smaller sidelobes.

Parameters

N	Window length, ≥ 1.
alpha	Shape parameter > 0. Default 2.5.
mr	Memory resource (nullptr → process default).

Returns

N×1 DOUBLE column vector.

Exceptions

nk::Error

if α ≤ 0.

gmonopuls()

Value nk::signal::gmonopuls	(	const Value &	t,
		double	fc,
		std::pmr::memory_resource *	mr = nullptr )

Gaussian monopulse at centre frequency fc.

\( y(t) = \frac{2\pi f_c t}{\sqrt{K}} \exp(-2 (\pi f_c t)^2) \) where K is chosen so the pulse peak equals 1 at t = 1/(2π fc).

Parameters

t	Time samples.
fc	Centre frequency in Hz.
mr	Memory resource (nullptr → process default).

Returns

Same-shape DOUBLE array.

goertzel()

Value nk::signal::goertzel	(	const Value &	x,
		const Value &	ind,
		std::pmr::memory_resource *	mr = nullptr )

Goertzel algorithm — single-frequency DFT evaluation.

Returns the DFT of x at the (1-based) frequency indices in ind. Faster than a full FFT when only a handful of bins are needed, since it uses an O(N) IIR filter per output bin instead of O(N log N).

Typical use: DTMF / tone detection, where only a small fixed set of frequency bins matters.

Parameters

x	Real input signal (1-D vector).
ind	1-based DFT bin indices to evaluate (real, any shape). Fractional indices are allowed (non-integer Goertzel).
mr	Memory resource (nullptr → process default).

Returns

COMPLEX Value with the same shape as ind. Each entry contains X[ind[k] - 1] where X = fft(x, length(x)).

// Detect a 1.5 kHz tone in a 8 kHz-sampled signal of length 1024:
double bin = 1500.0 / 8000.0 * 1024.0;
Value Y = goertzel(x, {bin + 1.0});  // 1-based
double magnitude = std::abs(Y.complexData()[0]);

See also

fft

grpdelay()

std::tuple< Value, Value > nk::signal::grpdelay	(	const Value &	b,
		const Value &	a,
		size_t	npts = 512,
		std::pmr::memory_resource *	mr = nullptr,
		double	fs = 0.0 )

Group delay of a digital filter.

Computes the negative derivative of the unwrapped phase response with respect to ω, i.e. \( \tau_g(\omega) = -\frac{d\phi}{d\omega} \). Implemented via finite-differences of unwrap(angle(freqz(…))) on the uniform grid; endpoint values use one-sided differences.

Parameters

b	Numerator polynomial.
a	Denominator polynomial.
npts	Number of frequency points. Default 512.
mr	Memory resource (nullptr → process default).

Returns

Tuple (gd, W) — group delay in samples per radian and frequency grid in rad/sample.

See also

freqz, phasez, phasedelay

fs > 0 (the grpdelay(b,a,n,fs) form) returns the frequency vector in Hz over [0, fs/2) instead of rad/sample; the group delay (in samples) is unchanged.

hamming()

Value nk::signal::hamming	(	size_t	N,
		std::pmr::memory_resource *	mr = nullptr )

Hamming window of length N.

Formula: \( w(n) = 0.54 - 0.46 \cos\!\left(\frac{2\pi n}{N-1}\right) \) for n = 0..N-1. Symmetric (endpoints equal).

Parameters

N	Window length, ≥ 1. N == 1 returns the scalar 1.0.
mr	Memory resource (nullptr → process default).

Returns

N×1 DOUBLE column vector.

Value w = hamming(64);  

hann()

Value nk::signal::hann	(	size_t	N,
		std::pmr::memory_resource *	mr = nullptr )

Hann (Hanning) window of length N.

Formula: \( w(n) = 0.5\,(1 - \cos(2\pi n/(N-1))) \) for n = 0..N-1. Symmetric. Endpoints are exactly zero.

Parameters

N	Window length, ≥ 1.
mr	Memory resource (nullptr → process default).

Returns

N×1 DOUBLE column vector.

highpass()

Value nk::signal::highpass	(	const Value &	x,
		double	fpass,
		double	fs,
		int	order = 8,
		std::pmr::memory_resource *	mr = nullptr )

One-call zero-phase Butterworth highpass filter.

Parameters

x	Input signal.
fpass	Cutoff frequency in Hz, 0 < fpass < fs/2.
fs	Sample rate in Hz, > 0.
order	Filter order. Default 8.
mr	Memory resource (nullptr → process default).

Returns

Filtered signal.

See also

lowpass

hilbert()

Value nk::signal::hilbert	(	const Value &	x,
		std::pmr::memory_resource *	mr = nullptr )

Analytic signal via the discrete Hilbert transform.

Computes \( z[n] = x[n] + j \hat{x}[n] \), where \( \hat{x} \) is the Hilbert transform of x. Implemented in the frequency domain: FFT → zero out negative frequencies → double positive frequencies → inverse FFT.

The result is useful for envelope detection, instantaneous frequency estimation, and single-sideband modulation.

Parameters

x	Real input signal (1-D vector).
mr	Memory resource (nullptr → process default).

Returns

COMPLEX vector of the same length as x.

Value z = hilbert(signal);
Value envelope = abs(z);        // amplitude envelope
Value phase    = angle(z);      // instantaneous phase

See also

envelope, envelope_full

icceps()

Value nk::signal::icceps	(	const Value &	c,
		std::pmr::memory_resource *	mr = nullptr )

Inverse complex cepstrum: real(ifft(exp(fft(c)))).

Recovers the original signal from a complex cepstrum produced by cceps.

Parameters

c	Complex cepstrum.
mr	Memory resource (nullptr → process default).

Returns

Same-length DOUBLE vector.

See also

cceps

idct() [1/2]

Value nk::signal::idct	(	const Value &	x,
		int	n,
		int	dim,
		std::pmr::memory_resource *	mr = nullptr )

Inverse DCT-II with explicit length / axis.

Exact left-inverse of dct(const Value &, int, int, std::pmr::memory_resource *).

Parameters

x	Real input (1-D or 2-D) of DCT coefficients.
n	Output length along dim. n <= 0 ≡ use native extent. n > axis_len zero-pads; n < axis_len truncates.
dim	Axis to transform along. 0 (default) = first non-singleton. 1 = rows, 2 = columns.
mr	Memory resource (nullptr → process default).

Returns

DOUBLE array with dim axis replaced by length n.

See also

dct

idct() [2/2]

Value nk::signal::idct	(	const Value &	x,
		std::pmr::memory_resource *	mr = nullptr )

Inverse Type-II DCT (1-D form).

Exact left-inverse of dct(const Value &, std::pmr::memory_resource *).

Parameters

x	Real 1-D vector (DCT coefficients).
mr	Memory resource (nullptr → process default).

Returns

Same-shape DOUBLE vector (reconstructed signal).

See also

dct

idst()

Value nk::signal::idst	(	const Value &	y,
		std::pmr::memory_resource *	mr = nullptr )

Inverse Type-II DST.

Type-II DST is involutive up to the factor 2/(N+1). This function returns the properly-scaled inverse.

Parameters

y	Real input vector (output of dst).
mr	Memory resource (nullptr → process default).

Returns

Same-length DOUBLE vector.

See also

dst

ifft()

Value nk::signal::ifft	(	const Value &	X,
		int	n = -1,
		int	dim = 0,
		std::pmr::memory_resource *	mr = nullptr )

1-D inverse discrete Fourier transform along a given dimension.

Same parameter semantics as fft. The result may downgrade to DOUBLE when the spectrum is conjugate-symmetric (imag ≤ 1e-10).

Parameters

X	Input spectrum (real or complex).
n	Output length, -1 keeps input length.
dim	Transform axis (see fft).
mr	Memory resource (nullptr → process default).

Returns

Inverse-transformed Value.

See also

fft

ifft2()

Value nk::signal::ifft2	(	const Value &	X,
		int	m = -1,
		int	n = -1,
		std::pmr::memory_resource *	mr = nullptr )

2-D inverse FFT (Y = ifft2(X, m, n)).

Inverse of fft2; same shape semantics. May downgrade output to DOUBLE when the result is real within tolerance (imag ≤ 1e-10).

Parameters

X	2-D input spectrum.
m	Number of rows, -1 keeps size(X, 1).
n	Number of columns, -1 keeps size(X, 2).
mr	Memory resource (nullptr → process default).

Returns

m × n array (COMPLEX or DOUBLE).

See also

fft2, ifft, ifftn

ifft2Symmetric()

Value nk::signal::ifft2Symmetric	(	const Value &	X,
		std::pmr::memory_resource *	mr = nullptr )

2-D inverse FFT with conjugate-symmetric input (MATLAB's ifft2(X,'symmetric')).

Treats X as conjugate-symmetric so the inverse transform is exactly real (DOUBLE). Decomposes into the 1-D ifftSymmetric over each dimension of length > 1. 2-D only; the resize form ifft2(X,m,n,'symmetric') is a deferred gap.

Parameters

X	2-D input spectrum (real or complex).
mr	Memory resource (nullptr → process default).

Returns

Real (DOUBLE) 2-D inverse transform.

See also

ifft2, ifftSymmetric

ifftn()

Value nk::signal::ifftn	(	const Value &	X,
		Span< const std::size_t >	sz = {},
		std::pmr::memory_resource *	mr = nullptr )

N-D inverse FFT (Y = ifftn(X, sz)).

Inverse of fftn; same shape semantics. May downgrade to DOUBLE when imag(Y) ≤ 1e-10 everywhere.

Parameters

X	N-D input spectrum.
sz	Per-axis target sizes (empty Span → use X's current shape).
mr	Memory resource (nullptr → process default).

Returns

Same-shape (or sz-shape) array (COMPLEX or DOUBLE).

See also

fftn, ifft, ifft2

ifftshift() [1/2]

Value nk::signal::ifftshift	(	const Value &	x,
		int	dim,
		std::pmr::memory_resource *	mr = nullptr )

Single-dim ifftshift — inverse of single-dim fftshift.

Parameters

x	Input array.
dim	Axis (1 = rows, 2 = cols, 3 = pages).
mr	Memory resource (nullptr → process default).

Returns

Same-shape array shifted along dim.

ifftshift() [2/2]

Value nk::signal::ifftshift	(	const Value &	x,
		std::pmr::memory_resource *	mr = nullptr )

Inverse of fftshift — shift by floor(extent/2).

fftshift and ifftshift are exact inverses for any extent (they differ only when N is odd; for even N they coincide).

Parameters

x	Input array (any shape, any type).
mr	Memory resource (nullptr → process default).

Returns

Same-shape and same-type array with elements permuted.

See also

fftshift

ifftSymmetric()

Value nk::signal::ifftSymmetric	(	const Value &	X,
		int	n = -1,
		int	dim = 0,
		std::pmr::memory_resource *	mr = nullptr )

Inverse DFT with conjugate-symmetric input (MATLAB's ifft(X,..., 'symmetric')).

Treats X as conjugate-symmetric along dim: the lower half X[0..floor(L/2)] is authoritative (the DC and, for even L, the Nyquist bin are forced real), the upper half is reconstructed as conj(X[k]), and the inverse transform is returned as an exactly real (DOUBLE) result. Differs from real(ifft(X)), which instead averages the conjugate-symmetric part of X.

Parameters

X	Input spectrum (real or complex), vector or matrix.
n	Output length, -1 keeps input length (pads/truncates first).
dim	Transform axis (0 = first non-singleton).
mr	Memory resource (nullptr → process default).

Returns

Real (DOUBLE) inverse transform.

See also

ifft

ifwht()

Value nk::signal::ifwht	(	const Value &	y,
		std::size_t	n,
		const std::string &	ordering,
		std::pmr::memory_resource *	mr = nullptr )

Inverse fast Walsh-Hadamard transform (x = ifwht(y[, n[, ordering]])).

Inverse of fwht. Because H_natural · H_natural = N · I, the inverse multiplies the natural-order coefficients by H_natural without the 1/N scaling — round-trip is exact in integer arithmetic. Non-natural orderings are first permuted back to natural before the inverse butterfly.

Parameters

y	Walsh-Hadamard coefficient vector / matrix.
n	Transform length (0 → auto-promote to next pow-2).
ordering	Matching ordering string used in fwht.
mr	Memory resource (nullptr → process default).

Returns

Reconstructed signal.

See also

fwht

impinvar()

std::tuple< Value, Value > nk::signal::impinvar	(	const Value &	b,
		const Value &	a,
		double	fs,
		double	tol = 1e-3,
		std::pmr::memory_resource *	mr = nullptr )

Impulse-invariance design: digital filter with the same impulse-response samples as the analog filter sampled at rate fs.

Partial-fraction-based; preserves transient response of the analog filter. Aliasing may be significant if the analog filter has significant energy above fs/2.

Parameters

b	Analog numerator polynomial.
a	Analog denominator polynomial.
fs	Sample rate (Hz).
tol	Tolerance for pole multiplicity detection. Default 1e-3.
mr	Memory resource (nullptr → process default).

Returns

Tuple (bd, ad) — digital coefficients.

See also

bilinear

impz()

std::tuple< Value, Value > nk::signal::impz	(	const Value &	b,
		const Value &	a,
		size_t	n = 0,
		std::pmr::memory_resource *	mr = nullptr )

Impulse response of a digital filter.

Computes the first n samples of h[k] = filter(b, a, δ[k]), where δ is the unit impulse.

Parameters

b	Numerator polynomial.
a	Denominator polynomial. Pass {1.0} for FIR.
n	Number of output samples. 0 (default) → use impzlength to pick a reasonable default.
mr	Memory resource (nullptr → process default).

Returns

Tuple (h, t) — impulse response samples and zero-based sample indices (DOUBLE column vectors of length n).

auto [b, a] = butter(4, 0.3);
auto [h, t] = impz(b, a, 128);

See also

impzlength, stepz

impzlength()

size_t nk::signal::impzlength	(	const Value &	b,
		const Value &	a,
		std::pmr::memory_resource *	mr = nullptr )

Heuristic estimate of the number of significant impulse-response samples.

FIR filters (a is scalar 1) → returns numel(b). IIR filters → returns max(50, ceil(-log(1e-5) / log(max_pole_radius))), clipped to [50, 8192].

Parameters

b	Numerator polynomial.
a	Denominator polynomial.
mr	Memory resource (nullptr → process default).

Returns

Suggested impulse-response length.

See also

impz

instbw()

Value nk::signal::instbw	(	const Value &	x,
		const Value &	fs = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Instantaneous bandwidth.

\( b_i = |dA/dt| \big/ (2\pi A) \) where A is the analytic-signal envelope.

Parameters

x	Real 1-D signal.
fs	Sample rate (Hz) or Value::Empty.
mr	Memory resource (nullptr → process default).

Returns

Column vector of length numel(x) - 1.

See also

instfreq, hilbert

instfreq()

Value nk::signal::instfreq	(	const Value &	x,
		const Value &	fs = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Instantaneous frequency via Hilbert transform.

\( f_i[n] = \dfrac{1}{2\pi}\,\dfrac{d\,\mathrm{unwrap}(\angle z[n])}{dt} \) where z = hilbert(x). Implemented as centered differences of the unwrapped analytic-signal phase.

Parameters

x	Real 1-D signal.
fs	Sample rate (Hz) or Value::Empty (output in rad/sample).
mr	Memory resource (nullptr → process default).

Returns

Column vector of length numel(x) - 1.

See also

instbw, hilbert

interp()

Value nk::signal::interp	(	const Value &	x,
		size_t	r,
		size_t	n = 4,
		double	alpha = 0.5,
		std::pmr::memory_resource *	mr = nullptr )

Integer-factor interpolation with a low-pass FIR kernel.

Designs an FIR low-pass of length 2·n·r + 1 and applies it after zero-stuffing by r. Output length is numel(x) · r.

Parameters

x	Input signal.
r	Interpolation factor, ≥ 2.
n	Half-window length in input samples. Default 4.
alpha	Normalised passband edge in fractions of input Nyquist. Default 0.5.
mr	Memory resource (nullptr → process default).

Returns

Interpolated signal of length numel(x) · r.

See also

intfilt, resample

interpft()

Value nk::signal::interpft	(	const Value &	x,
		int	n,
		int	dim = 0,
		std::pmr::memory_resource *	mr = nullptr )

FFT-based band-limited interpolation of x to n equispaced samples.

Algorithm: forward FFT → zero-pad in the frequency domain → inverse FFT → scale by n / m. The result is the trigonometric interpolant of x evaluated at n uniform points.

Parameters

x	Input signal.
n	Number of output samples along dim.
dim	Axis to interpolate along. 0 → first non-singleton.
mr	Memory resource (nullptr → process default).

Returns

Same shape as x with dim axis replaced by length n.

See also

fft

intfilt()

Value nk::signal::intfilt	(	size_t	r,
		size_t	n = 4,
		double	alpha = 0.5,
		std::pmr::memory_resource *	mr = nullptr )

Design an FIR interpolation kernel.

Returns the impulse response usable directly with upfirdn. Length 2·n·r + 1. The filter is a windowed sinc with passband edge at alpha · (Nyquist / r).

Parameters

r	Interpolation factor, ≥ 2.
n	Half-window length in input samples. Default 4.
alpha	Passband edge in fractions of the post-interpolation Nyquist. Default 0.5.
mr	Memory resource (nullptr → process default).

Returns

1 × (2·n·r + 1) DOUBLE FIR kernel.

See also

interp, upfirdn

invfreqs()

std::tuple< Value, Value > nk::signal::invfreqs	(	const Value &	H,
		const Value &	w,
		int	nb,
		int	na,
		std::pmr::memory_resource *	mr = nullptr )

Fit analog filter to a frequency response (Levi equation-error LSQ).

Solves for (b, a) of orders (nb, na) minimising \( \sum_k |A(j\omega_k) H_k - B(j\omega_k)|^2 \).

Parameters

H	Desired complex response samples.
w	Angular frequencies in rad/s, same length as H.
nb	Numerator order.
na	Denominator order.
mr	Memory resource (nullptr → process default).

Returns

Tuple (b, a).

See also

invfreqz, freqs

invfreqz()

std::tuple< Value, Value > nk::signal::invfreqz	(	const Value &	H,
		const Value &	w,
		int	nb,
		int	na,
		std::pmr::memory_resource *	mr = nullptr )

Digital counterpart of invfreqs.

w is in [0, π]; the polynomial is in z^{-1}.

Parameters

H	Desired complex response samples.
w	Normalised digital frequencies in [0, π], length matches H.
nb	Numerator order.
na	Denominator order.
mr	Memory resource (nullptr → process default).

Returns

Tuple (b, a).

See also

invfreqs, freqz

is2rc()

Value nk::signal::is2rc	(	const Value &	is,
		std::pmr::memory_resource *	mr = nullptr )

Inverse-sine parameterisation → reflection coefficients.

Parameters

is	Inverse-sine parameter vector.
mr	Memory resource (nullptr → process default).

Returns

Reflection-coefficient vector.

See also

rc2is

isallpass()

bool nk::signal::isallpass	(	const Value &	b,
		const Value &	a )

Detects whether a digital filter is all-pass.

All-pass means |H(e^{jω})| = const for all ω. Equivalent algebraic test (within tolerance): a == flip(b).

Parameters

b	Numerator polynomial.
a	Denominator polynomial.

Returns

true if all-pass.

iscola()

std::tuple< Value, Value, Value > nk::signal::iscola	(	const Value &	window,
		std::size_t	noverlap,
		const std::string &	method,
		std::pmr::memory_resource *	mr = nullptr )

Constant OverLap-Add (COLA) compliance check (tf = iscola(window, noverlap[, method])).

Sums the (possibly squared) window shifted by hop = M - noverlap in the stable overlap region and tests whether the result is constant to within 2 * eps. Returns the truth value plus the median m and the maximum deviation maxDev of the stable region.

Parameters

window	Analysis window vector (length M).
noverlap	Number of samples shared between consecutive frames (must satisfy 0 <= noverlap < M).
method	"wola" (default, sum of w²) or "ola" (sum of w).
mr	Memory resource (nullptr → process default).

Returns

Tuple (tf, m, maxDev) — tf is 1.0 or 0.0, m is the median of the stable-region sum, maxDev is the maximum absolute deviation from m.

See also

stft, istft

isfir() [1/2]

bool nk::signal::isfir

(

const Value &

b

)

Detects whether a digital filter is FIR.

A filter is FIR when its denominator is effectively [1] — either a literal scalar 1, or a vector with only a[0] non-zero (within tolerance 1e-12).

Parameters

b	Numerator polynomial.

Returns

true if FIR. The single-arg form assumes a == [1].

isfir() [2/2]

bool nk::signal::isfir	(	const Value &	b,
		const Value &	a )

Detects FIR with explicit denominator.

Same FIR criterion as isfir(const Value &): denominator must be effectively [1] within tolerance.

Parameters

b	Numerator polynomial.
a	Denominator polynomial.

Returns

true if FIR.

islinphase()

bool nk::signal::islinphase	(	const Value &	b,
		const Value &	a )

Detects whether a digital filter has linear phase.

For FIR filters this is equivalent to b being symmetric (b == flip(b)) or antisymmetric (b == -flip(b)). IIR with non-trivial denominator → returns false (linear phase is impossible for stable rational IIR).

Parameters

b	Numerator polynomial.
a	Denominator polynomial.

Returns

true if linear-phase.

See also

firtype, isfir

ismaxphase()

bool nk::signal::ismaxphase	(	const Value &	b,
		const Value &	a,
		std::pmr::memory_resource *	mr = nullptr )

Detects whether a digital filter is maximum-phase.

True iff every zero of B(z) lies strictly outside the unit circle (|z| > 1 + tol).

Parameters

b	Numerator polynomial.
a	Denominator polynomial.
mr	Memory resource (nullptr → process default).

Returns

true if maximum-phase.

See also

isminphase

isminphase()

bool nk::signal::isminphase	(	const Value &	b,
		const Value &	a,
		std::pmr::memory_resource *	mr = nullptr )

Detects whether a digital filter is minimum-phase.

True iff every zero of B(z) lies inside the unit circle AND the filter is stable.

Parameters

b	Numerator polynomial.
a	Denominator polynomial.
mr	Memory resource (nullptr → process default).

Returns

true if minimum-phase.

See also

isstable, ismaxphase

isstable()

bool nk::signal::isstable	(	const Value &	b,
		const Value &	a,
		std::pmr::memory_resource *	mr = nullptr )

Detects whether a digital filter is BIBO-stable.

Returns true iff every pole of A(z) is strictly inside the unit circle (|p| < 1 - tol, tol = 1e-12).

Parameters

b	Numerator polynomial.
a	Denominator polynomial.
mr	Memory resource for the internal root-finder (nullptr → default).

Returns

true if stable.

See also

isminphase, ismaxphase

istft()

Value nk::signal::istft	(	const Value &	S,
		const Value &	window,
		std::size_t	overlap,
		std::size_t	fftLength,
		const std::string &	range,
		std::pmr::memory_resource *	mr = nullptr )

Inverse STFT via overlap-add.

Round-trips x == istft(stft(x, …), …) exactly (within ulp) on COLA-compliant configurations such as hann(N, 'periodic') with 75% overlap.

Parameters must match the analysis-side spelling so we know whether to undo a one-sided or centered packing before the inverse FFT.

Parameters

S	STFT matrix produced by stft.
window	Same window vector used in analysis.
overlap	Same overlap.
fftLength	Same FFT length.
range	Same range keyword.
mr	Memory resource (nullptr → process default).

Returns

Reconstructed signal as a column vector.

See also

stft

kaiser()

Value nk::signal::kaiser	(	size_t	N,
		double	beta,
		std::pmr::memory_resource *	mr = nullptr )

Kaiser window of length N with shape parameter β.

Formula: \( w(n) = I_0\!\left(\beta\sqrt{1-(2n/(N-1)-1)^2}\right) / I_0(\beta) \) where \( I_0 \) is the zeroth-order modified Bessel function.

β controls the tradeoff between mainlobe width and sidelobe height: β=0 ≡ rectangular, β=5 ≈ Hamming sidelobes, β=8 ≈ Blackman sidelobes, β=14 ≈ -120 dB sidelobes.

Parameters

N	Window length, ≥ 1.
beta	Shape parameter, β ≥ 0.
mr	Memory resource (nullptr → process default).

Returns

N×1 DOUBLE column vector.

Value w = kaiser(128, 8.0);  // Blackman-like sidelobes  

kaiserord()

std::tuple< int, Value, double, std::string > nk::signal::kaiserord	(	const Value &	F,
		const Value &	A,
		const Value &	dev,
		double	fs = 2.0,
		std::pmr::memory_resource *	mr = nullptr )

Kaiser-window FIR order estimator.

Returns (N, Wn, beta, ftype) such that fir1(N, Wn, ftype, kaiser(N+1, beta), 'noscale') meets the design specs.

Parameters

F	Transition-band edge frequencies in Hz.
A	Binary amplitudes per band (0 / 1).
dev	Maximum linear deviation per band.
fs	Sample rate (default 2 → normalised).
mr	Memory resource (nullptr → process default).

Returns

Tuple (N, Wn, beta, ftype). ftype is one of "low", "high", "stop", "bandpass", "DC-0", "DC-1".

See also

fir1, kaiser

lar2rc()

Value nk::signal::lar2rc	(	const Value &	g,
		std::pmr::memory_resource *	mr = nullptr )

Log-area-ratio → reflection coefficients.

Parameters

g	Log-area-ratio vector.
mr	Memory resource (nullptr → process default).

Returns

Reflection-coefficient vector.

See also

rc2lar

levinson()

std::tuple< Value, Value, Value > nk::signal::levinson	(	const Value &	r,
		int	n = -1,
		std::pmr::memory_resource *	mr = nullptr )

Levinson-Durbin recursion: solve a Hermitian Toeplitz system.

Given the first row r (length n+1) of a Hermitian Toeplitz matrix, computes the AR(n) coefficients via the order-recursive Levinson algorithm. Returns the AR poly, the residual prediction error variance, and the reflection coefficients.

Parameters

r	First row of the Toeplitz matrix (autocorrelation sequence).
n	AR order. -1 (default) → numel(r) - 1.
mr	Memory resource (nullptr → process default).

Returns

Tuple (a, e, k):

• a — AR coefficient vector of length n+1, with a[0] = 1.
• e — prediction error power (scalar).
• k — reflection coefficients of length n.

See also

rlevinson, aryule, poly2rc

lowpass()

Value nk::signal::lowpass	(	const Value &	x,
		double	fpass,
		double	fs,
		int	order = 8,
		std::pmr::memory_resource *	mr = nullptr )

One-call zero-phase Butterworth lowpass filter.

Designs an order-order Butterworth lowpass with cutoff fpass Hz, then applies filtfilt for zero-phase response.

Parameters

x	Input signal (any shape; columns filtered independently).
fpass	Cutoff frequency in Hz, 0 < fpass < fs/2.
fs	Sample rate in Hz, > 0.
order	Filter order. Default 8.
mr	Memory resource (nullptr → process default).

Returns

Filtered signal, same shape as x.

Value y = lowpass(audio, 4000.0, 48000.0);  // 4 kHz LP at 48 kHz  

See also

highpass, bandpass, bandstop, butter

lp2bp()

std::tuple< Value, Value, Value > nk::signal::lp2bp	(	const Value &	z,
		const Value &	p,
		double	k,
		double	Wo,
		double	Bw,
		std::pmr::memory_resource *	mr = nullptr )

Lowpass → bandpass frequency transformation.

Applies the substitution s → (s² + Wo²) / (Bw · s). Order doubles.

Parameters

z	Prototype zeros.
p	Prototype poles.
k	Prototype gain.
Wo	Centre frequency in rad/s.
Bw	Bandwidth in rad/s (Wo_high − Wo_low).
mr	Memory resource (nullptr → process default).

Returns

Tuple (z', p', k').

lp2bs()

std::tuple< Value, Value, Value > nk::signal::lp2bs	(	const Value &	z,
		const Value &	p,
		double	k,
		double	Wo,
		double	Bw,
		std::pmr::memory_resource *	mr = nullptr )

Lowpass → bandstop frequency transformation ([z', p', k'] = lp2bs(z, p, k, Wo, Bw)).

Applies the substitution s → (Bw · s) / (s² + Wo²). Order doubles.

Parameters

z	Prototype zeros.
p	Prototype poles.
k	Prototype gain.
Wo	Centre frequency in rad/s.
Bw	Bandwidth in rad/s.
mr	Memory resource (nullptr → process default).

Returns

Tuple (z', p', k') of the bandstop filter.

See also

lp2bp

lp2hp()

std::tuple< Value, Value, Value > nk::signal::lp2hp	(	const Value &	z,
		const Value &	p,
		double	k,
		double	Wo,
		std::pmr::memory_resource *	mr = nullptr )

Lowpass → highpass frequency transformation.

Applies the substitution s → Wo / s. Result is an analog highpass filter with cutoff Wo rad/s.

Parameters

z	Prototype zeros.
p	Prototype poles.
k	Prototype gain.
Wo	Target cutoff frequency in rad/s.
mr	Memory resource (nullptr → process default).

Returns

Tuple (z', p', k').

lp2lp()

std::tuple< Value, Value, Value > nk::signal::lp2lp	(	const Value &	z,
		const Value &	p,
		double	k,
		double	Wo,
		std::pmr::memory_resource *	mr = nullptr )

Scale an analog lowpass prototype to cutoff Wo.

Applies the substitution s → s / Wo. The result is an analog lowpass filter with cutoff Wo rad/s.

Parameters

z	Prototype zeros (may be empty).
p	Prototype poles.
k	Prototype gain.
Wo	Target cutoff frequency in rad/s.
mr	Memory resource (nullptr → process default).

Returns

Tuple (z', p', k') of the transformed filter.

lpc()

std::tuple< Value, Value > nk::signal::lpc	(	const Value &	x,
		int	p,
		std::pmr::memory_resource *	mr = nullptr )

Linear-prediction coefficients (aryule alias + sqrt-error gain).

Parameters

x	Real 1-D signal.
p	Prediction order.
mr	Memory resource (nullptr → process default).

Returns

Tuple (a, g) — AR poly and sqrt(e) gain factor.

See also

aryule

lsf2poly()

Value nk::signal::lsf2poly	(	const Value &	lsf,
		std::pmr::memory_resource *	mr = nullptr )

Line-spectral frequencies → AR poly.

Parameters

lsf	LSF angles in (0, π).
mr	Memory resource (nullptr → process default).

Returns

AR coefficient vector of length numel(lsf) + 1.

mag2db()

Value nk::signal::mag2db	(	const Value &	x,
		std::pmr::memory_resource *	mr = nullptr )

Magnitude to decibels (voltage form): \( y = 20 \log_{10} x \).

Unlike db("voltage"), does NOT take abs(x) first — mag2db requires the input to be non-negative.

Parameters

x	Non-negative magnitudes. Negative values → nan.
mr	Memory resource (nullptr → process default).

Returns

DOUBLE array of dB values.

See also

db2mag, db

meanfreq()

Value nk::signal::meanfreq	(	const Value &	x,
		const Value &	fs = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Power-weighted mean frequency.

\( \dfrac{\sum f \cdot P}{\sum P} \).

Parameters

x	Real 1-D signal.
fs	Sample rate (Hz) or Value::Empty for rad/sample.
mr	Memory resource (nullptr → process default).

Returns

Scalar mean frequency.

See also

medfreq, powerbw

medfilt1()

Value nk::signal::medfilt1	(	const Value &	x,
		size_t	k = 3,
		bool	zeropad = true,
		std::pmr::memory_resource *	mr = nullptr )

1-D median filter.

Sliding-window median over a window of k samples centered on each output sample. Effective for removing salt-and-pepper noise and short outliers while preserving step-like edges (unlike linear smoothing, which blurs edges).

Boundary handling uses truncation (the 'truncate' mode): the window is shortened at the signal edges rather than zero-padded.

Parameters

x	Real 1-D signal.
k	Window length (samples). Default 3. Typically odd; even k uses the lower-median convention.
mr	Memory resource (nullptr → process default).

Returns

Filtered signal, same shape as x.

// Remove single-sample outliers in a noisy measurement:
Value clean = medfilt1(noisy, 5);

See also

sgolayfilt

Parameters

zeropad

true (MATLAB default): out-of-range samples count as 0 (window always k long). false: 'truncate' — clip the window to the valid range at the signal ends.

medfreq()

Value nk::signal::medfreq	(	const Value &	x,
		const Value &	fs = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Median frequency.

F such that the cumulative PSD below F equals half the total.

Parameters

x	Real 1-D signal.
fs	Sample rate (Hz) or Value::Empty.
mr	Memory resource (nullptr → process default).

Returns

Scalar median frequency.

See also

meanfreq

mergesigroi()

Value nk::signal::mergesigroi	(	const Value &	roi,
		int64_t	sep,
		std::pmr::memory_resource *	mr = nullptr )

Merge near-adjacent ROIs (roi = mergesigroi(roi, sep)).

sep == 0 → only strictly overlapping ROIs merge. sep >= 1 → ROIs within sep samples of each other merge.

Parameters

roi	N × 2 ROI matrix.
sep	Merge gap threshold.
mr	Memory resource (nullptr → process default).

Returns

Merged ROI matrix.

See also

extendsigroi

midcross()

Value nk::signal::midcross	(	const Value &	x,
		const Value &	fs = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Mid-state crossing times.

Returns the (fractional) times at which x crosses the 50% mid-state level, linearly interpolated between adjacent samples.

Parameters

x	Real 1-D signal.
fs	Sample rate in Hz. Value::Empty → fs = 1, output is 1-based fractional sample index.
mr	Memory resource (nullptr → process default).

Returns

Column vector of crossing times. Empty if none.

See also

statelevels

modulate()

Value nk::signal::modulate	(	const Value &	x,
		double	Fc,
		double	Fs,
		const std::string &	method,
		const Value &	opt = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Analog modulation: AM / FM / PM family.

Supported (case-insensitive) method:

• "am" / "amdsb-sc" — double-sideband suppressed carrier.
• "amdsb-tc" — DSB with transmitted carrier; opt is the DC offset (default min(x)).
• "fm" — frequency modulation; opt is deviation factor kf (default Fc/Fs · 2π / max(|x|)).
• "pm" — phase modulation; opt is deviation kp (default π / max(|x|)).

Parameters

x	Message signal.
Fc	Carrier frequency in Hz.
Fs	Sample rate in Hz.
method	Modulation type (case-insensitive).
opt	Method-specific scalar; Value::Empty → defaults above.
mr	Memory resource (nullptr → process default).

Returns

Modulated signal.

Note

KNOWN GAPs: "amssb", "pwm", "ptm", "ppm", "qam" deferred.

See also

demod, vco

mscohere()

std::tuple< Value, Value > nk::signal::mscohere	(	const Value &	x,
		const Value &	y,
		const Value &	window,
		size_t	noverlap,
		size_t	nfft,
		double	fs = 2.0 *3.14159265358979323846,
		std::pmr::memory_resource *	mr = nullptr )

Magnitude-squared coherence via Welch's method.

Computes \( C_{xy}(f) = \frac{|P_{xy}(f)|^2}{P_{xx}(f) \cdot P_{yy}(f)} \), real-valued in [0, 1]. Equals 1 when y is a linear function of x.

Parameters

x	First real 1-D signal.
y	Second real 1-D signal.
window	Window. Value::Empty → Hamming(256).
noverlap	Overlap.
nfft	FFT size.
fs	Sample rate.
mr	Memory resource (nullptr → process default).

Returns

Tuple (Cxy, F) — Cxy is REAL in [0, 1].

See also

cpsd, tfestimate

nextpow2() [1/2]

Value nk::signal::nextpow2	(	const Value &	x,
		std::pmr::memory_resource *	mr = nullptr )

Vectorised nextpow2 — applies elementwise to an array.

Parameters

x	Real input array (any shape).
mr	Memory resource (nullptr → process default).

Returns

DOUBLE array with the same shape as x.

nextpow2() [2/2]

Value nk::signal::nextpow2	(	double	n,
		std::pmr::memory_resource *	mr = nullptr )

Smallest integer p such that \( 2^p \ge n \) (scalar form).

Useful for padding sequences to a length suitable for radix-2 FFT.

Parameters

n	Input scalar. Negative / zero → returns 0.
mr	Memory resource (nullptr → process default).

Returns

Scalar DOUBLE.

size_t pad = 1ull << (size_t)nextpow2(numel(x)).toScalar();  

nuttallwin()

Value nk::signal::nuttallwin	(	size_t	N,
		std::pmr::memory_resource *	mr = nullptr )

Nuttall window of length N — 4-term, continuous-first-derivative.

Coefficients chosen to minimise sidelobe height under a continuous-derivative constraint. Sidelobe attenuation ≈ -98 dB.

Parameters

N	Window length, ≥ 1.
mr	Memory resource (nullptr → process default).

Returns

N×1 DOUBLE column vector.

obw()

std::tuple< Value, Value, Value, Value > nk::signal::obw	(	const Value &	x,
		const Value &	fs = Value::Empty,
		double	p = 0.99,
		std::pmr::memory_resource *	mr = nullptr )

Occupied bandwidth at fraction p of total power ([bw, flo, fhi, power] = obw(x, fs, p)).

Bandwidth (Hz or rad/s) of the contiguous frequency band that holds fraction p (default 0.99) of the total power, centred so that the (1-p)/2 tail lies on each side. Matches MATLAB obw: the PSD is a rectangular-windowed periodogram with nfft = numel(x) (no zero-pad), the cumulative power is the rectangle rule Σ P·df, and a band edge is the frequency (at the bin's upper edge F + df/2) where the cumulative reaches (1∓p)/2 of the total.

Parameters

x	Real 1-D signal.
fs	Sample rate or Value::Empty.
p	Power fraction (default 0.99).
mr	Memory resource (nullptr → process default).

Returns

Tuple (bw, flo, fhi, power): bandwidth, lower/upper band edges, and the in-band power (p · total).

overshoot()

Value nk::signal::overshoot	(	const Value &	x,
		const Value &	fs = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Percent overshoot above the upper state.

One entry per positive-going transition. 5.0 ≡ 5% above the upper state level.

Parameters

x	Real 1-D signal.
fs	Sample rate in Hz. Value::Empty → samples.
mr	Memory resource (nullptr → process default).

Returns

Column vector of percentages, one per transition.

See also

undershoot, settlingtime

parzenwin()

Value nk::signal::parzenwin	(	size_t	N,
		std::pmr::memory_resource *	mr = nullptr )

Parzen (de la Vallée Poussin) window of length N — piecewise cubic.

Smooth (continuous second derivative) → low sidelobes, wider mainlobe than Bartlett.

Parameters

N	Window length, ≥ 1.
mr	Memory resource (nullptr → process default).

Returns

N×1 DOUBLE column vector.

pburg()

std::tuple< Value, Value > nk::signal::pburg	(	const Value &	x,
		int	p,
		size_t	nfft,
		std::pmr::memory_resource *	mr = nullptr )

Burg's AR PSD estimate ([Pxx, F] = pburg(x, p, nfft)).

AR coefficients estimated by minimising the sum of forward and backward prediction-error variances iteratively. More numerically stable than Yule-Walker on short data.

Parameters

x	Real 1-D signal.
p	AR model order.
nfft	Number of frequency points (≥ 2). 0 → nextPow2(numel(x)).
mr	Memory resource (nullptr → process default).

Returns

Tuple (Pxx, F).

See also

pyulear, arburg

peak2peak()

Value nk::signal::peak2peak	(	const Value &	x,
		int	dim = 0,
		std::pmr::memory_resource *	mr = nullptr )

Peak-to-peak amplitude along a dimension.

Computes max(x) - min(x) along dim. NaN propagates (any NaN in the slice yields NaN).

Parameters

x	Real input array.
dim	Reduction axis. 0 → first non-singleton dim.
mr	Memory resource (nullptr → process default).

Returns

Reduced array.

peak2rms()

Value nk::signal::peak2rms	(	const Value &	x,
		int	dim = 0,
		std::pmr::memory_resource *	mr = nullptr )

Peak-to-RMS ratio along a dimension.

Computes \( y = \max|x| / \mathrm{rms}(x) \) along dim. Indicates the crest factor of a signal.

Parameters

x	Real input array.
dim	Reduction axis. 0 → first non-singleton dim.
mr	Memory resource (nullptr → process default).

Returns

Reduced array.

See also

rms, peak2peak

peig()

std::tuple< Value, Value > nk::signal::peig	(	const Value &	x,
		int	p,
		int	nfft = 256,
		double	fs = 2.0 *3.14159265358979323846,
		std::pmr::memory_resource *	mr = nullptr )

Eigenvector pseudospectrum ([P, F] = peig(x, p, nfft, fs)).

As pmusic, but weights each noise term by 1/λ_k: P(ω) = 1 / Σ_{noise} |e(ω)'·v_k|² / λ_k. Same peak-frequency parity caveat.

Parameters

x	Real 1-D signal.
p	Signal-subspace dimension.
nfft	Frequency points (default 256).
fs	Sample rate (default 2π).
mr	Memory resource (nullptr → process default).

Returns

Tuple (P, F) column vectors.

See also

pmusic

periodogram()

std::tuple< Value, Value > nk::signal::periodogram	(	const Value &	x,
		const Value &	window,
		size_t	nfft,
		double	fs = 2.0 *3.14159265358979323846,
		std::pmr::memory_resource *	mr = nullptr )

Single-segment periodogram PSD estimate.

Computes \( \hat{P}_{xx}(f) = \frac{1}{f_s \cdot \sum |w|^2} \big|\sum_n w[n] \, x[n] \, e^{-j 2\pi f n / f_s}\big|^2 \) on a uniform grid of frequencies on [0, fs/2] (one-sided form).

Parameters

x	Real 1-D signal.
window	Window vector (must have numel(window) == numel(x)). Value::Empty → rectangular window (all ones).
nfft	FFT size. 0 → nextPow2(numel(x)).
fs	Sample rate in Hz. Default 2π (the normalised-radian convention).
mr	Memory resource (nullptr → process default).

Returns

Tuple (Pxx, F):

• Pxx — nfft/2+1 × 1 PSD column vector.
• F — nfft/2+1 × 1 frequency vector on [0, fs/2].

See also

pwelch, spectrogram

periodogramConf()

Value nk::signal::periodogramConf	(	const Value &	Pxx,
		double	confidenceLevel,
		bool	realInput,
		bool	nfftEven,
		std::pmr::memory_resource *	mr = nullptr )

Chi-square confidence interval for a periodogram PSD estimate.

Given a one-sided periodogram Pxx (as returned by periodogram), returns the confidenceLevel-coverage interval as an nf × 2 matrix (column 1 = lower bound, column 2 = upper). Each PSD bin is chi-square distributed with v degrees of freedom: the general (folded) interior bins carry v = 2, while the purely-real DC bin and — when nfftEven — the Nyquist bin carry v = 1. The interval is \( \hat{P}_{xx} \cdot v \big/ \chi^2_{v}([1-\alpha/2,\ \alpha/2]) \) with \( \alpha = 1 - \text{confidenceLevel} \), using the closed forms chi2inv(q,2) = -2 ln(1-q) and chi2inv(q,1) = (√2·erfinv(q))².

Parameters

Pxx	One-sided PSD column vector from periodogram.
confidenceLevel	Coverage in (0, 1) (MATLAB default 0.95).
realInput	true if the analysed signal was real (DC/Nyquist bins then carry 1 DOF); false → every bin 2 DOF.
nfftEven	true if the transform length was even (a Nyquist bin then sits at Pxx(end)).
mr	Memory resource (nullptr → process default).

Returns

nf × 2 matrix [lower, upper].

See also

periodogram

phasedelay()

std::tuple< Value, Value > nk::signal::phasedelay	(	const Value &	b,
		const Value &	a,
		size_t	n = 512,
		std::pmr::memory_resource *	mr = nullptr )

Phase delay of a digital filter.

Computes \( \tau_p(\omega) = -\phi(\omega) / \omega \) for ω ∈ [0, π]. Phase is unwrapped before division; the ω=0 sample uses the next-bin value to avoid 0/0.

Parameters

b	Numerator polynomial.
a	Denominator polynomial.
n	Number of frequency points. Default 512.
mr	Memory resource (nullptr → process default).

Returns

Tuple (pd, w) — phase delay (samples) and frequency grid.

See also

grpdelay, phasez

phasez()

std::tuple< Value, Value > nk::signal::phasez	(	const Value &	b,
		const Value &	a,
		size_t	npts = 512,
		std::pmr::memory_resource *	mr = nullptr,
		double	fs = 0.0 )

Unwrapped phase response of a digital filter.

Equivalent to unwrap(angle(freqz(b, a, npts))).

Parameters

b	Numerator polynomial.
a	Denominator polynomial.
npts	Number of frequency points. Default 512.
mr	Memory resource (nullptr → process default).

Returns

Tuple (phi, W) — phase in radians and frequencies.

See also

freqz, grpdelay

fs > 0 (the phasez(b,a,n,fs) form) returns the frequency vector in Hz over [0, fs/2) instead of rad/sample; the phase values are unchanged.

pmusic()

std::tuple< Value, Value > nk::signal::pmusic	(	const Value &	x,
		int	p,
		int	nfft = 256,
		double	fs = 2.0 *3.14159265358979323846,
		std::pmr::memory_resource *	mr = nullptr )

MUSIC pseudospectrum ([P, F] = pmusic(x, p, nfft, fs)).

Builds the correlation matrix R = X'·X (order 2p, via corrmtx), eigendecomposes it, takes the smallest p eigenvectors as the noise subspace, and evaluates P(ω) = 1 / Σ_{noise} |e(ω)'·v_k|² over a one-sided grid of nfft/2+1 frequencies on [0, fs/2].

Matches MATLAB on the peak frequencies (the estimator's purpose). The absolute pseudospectrum is scale-arbitrary and eigendecomposition-sensitive (peaks are 1/near-zero), so it is not bit-matched to MATLAB.

Parameters

x	Real 1-D signal.
p	Signal-subspace dimension (≈ number of complex exponentials).
nfft	Frequency points: nfft/2+1 one-sided (default 256 → 129).
fs	Sample rate; default 2π → frequencies in [0, π] rad/sample.
mr	Memory resource (nullptr → process default).

Returns

Tuple (P, F) column vectors.

See also

peig, corrmtx, pwelch

poly2ac()

Value nk::signal::poly2ac	(	const Value &	a,
		double	e,
		std::pmr::memory_resource *	mr = nullptr )

AR poly + prediction error → autocorrelation.

Parameters

a	AR coefficient vector.
e	Prediction error variance.
mr	Memory resource (nullptr → process default).

Returns

Autocorrelation column of length numel(a).

poly2lsf()

Value nk::signal::poly2lsf	(	const Value &	a,
		std::pmr::memory_resource *	mr = nullptr )

AR poly → line-spectral frequencies (radians).

Parameters

a	AR coefficient vector of length N+1.
mr	Memory resource (nullptr → process default).

Returns

Column vector of N angles in (0, π).

poly2rc()

std::tuple< Value, Value > nk::signal::poly2rc	(	const Value &	a,
		double	efinal = 0.0,
		std::pmr::memory_resource *	mr = nullptr )

AR poly → reflection coefficients (step-down recursion).

Parameters

a	AR coefficient vector.
efinal	Final prediction error (for the second output R0).
mr	Memory resource (nullptr → process default).

Returns

Tuple (k, R0): reflection coefficients of length numel(a) - 1, and the zero-lag autocorrelation R0 = efinal / prod(1 - k.^2).

polyscale()

Value nk::signal::polyscale	(	const Value &	p,
		const Value &	scale,
		std::pmr::memory_resource *	mr = nullptr )

Radial scaling of polynomial roots (y = polyscale(p, scale)).

Computes y[k] = p[k] · scale^k for k = 0..N-1, equivalent to multiplying every root of the polynomial by scale (the z-transform scaling property A(z) ↦ A(z/scale)). Real or complex inputs supported.

Parameters

p	Polynomial coefficients. A vector is one polynomial of length N; an M×N matrix is M polynomials, one per row, each scaled independently.
scale	Scaling factor — a scalar, or a length-N vector whose element k is raised to the power k.
mr	Memory resource (nullptr → process default).

Returns

Scaled polynomial coefficients (row vector for a vector input, M×N matrix for a matrix input).

See also

polystab

polystab()

Value nk::signal::polystab	(	const Value &	a,
		std::pmr::memory_resource *	mr = nullptr )

Stabilise a polynomial (b = polystab(a)).

Reflects any root with |root| > 1 to its conjugate reciprocal 1/conj(root) inside the unit circle, yielding the minimum-phase polynomial. The magnitude-response shape is preserved — the reflection scales |B(e^jω)| by a constant gain relative to |A(e^jω)|. Returns a row vector (real if the input was real).

Parameters

a	Polynomial coefficients, a vector (row or column).
mr	Memory resource (nullptr → process default).

Returns

Stabilised polynomial coefficients (row vector).

Note

Complex-coefficient input is not supported — nk's roots handles real polynomials only.

See also

polyscale

pow2db()

Value nk::signal::pow2db	(	const Value &	p,
		std::pmr::memory_resource *	mr = nullptr )

Power to decibels: \( y = 10 \log_{10} p \).

Parameters

p	Non-negative power values. Negative → nan; zero → -inf.
mr	Memory resource (nullptr → process default).

Returns

DOUBLE array of dB values.

See also

db2pow, mag2db

powerbw()

Value nk::signal::powerbw	(	const Value &	x,
		const Value &	fs = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

3-dB power bandwidth around the dominant peak.

Parameters

x	Real 1-D signal.
fs	Sample rate (Hz) or Value::Empty.
mr	Memory resource (nullptr → process default).

Returns

Scalar bandwidth in Hz / rad/s.

See also

obw, meanfreq

prony()

std::tuple< Value, Value > nk::signal::prony	(	const Value &	h,
		int	nb,
		int	na,
		std::pmr::memory_resource *	mr = nullptr )

Prony IIR identification from impulse response.

Given an impulse response h, identifies the (nb, na) IIR filter b(z)/a(z) whose impulse response matches h in a least-squares sense. Solves the denominator equation by LS, then convolves a with h to recover b.

Parameters

h	Impulse response.
nb	Numerator order.
na	Denominator order.
mr	Memory resource (nullptr → process default).

Returns

Tuple (b, a).

pulseperiod()

Value nk::signal::pulseperiod	(	const Value &	x,
		const Value &	fs = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Period between consecutive same-direction mid-state crossings.

Parameters

x	Real 1-D signal.
fs	Sample rate in Hz. Value::Empty → samples.
mr	Memory resource (nullptr → process default).

Returns

Column vector of periods, one per consecutive pulse pair.

See also

pulsewidth, dutycycle

pulsesep()

Value nk::signal::pulsesep	(	const Value &	x,
		const Value &	fs = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Separation between consecutive pulses (time below mid-state).

Parameters

x	Real 1-D signal.
fs	Sample rate in Hz. Value::Empty → samples.
mr	Memory resource (nullptr → process default).

Returns

Column vector of separations.

See also

pulsewidth, pulseperiod

pulsewidth()

Value nk::signal::pulsewidth	(	const Value &	x,
		const Value &	fs = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Duration each pulse stays above the mid-state.

Parameters

x	Real 1-D signal.
fs	Sample rate in Hz. Value::Empty → samples.
mr	Memory resource (nullptr → process default).

Returns

Column vector, one entry per pulse.

See also

pulseperiod, dutycycle

pulstran()

Value nk::signal::pulstran	(	const Value &	t,
		const Value &	d,
		const std::string &	fnName,
		double	fcOrW = 1.0,
		double	bw = 0.5,
		std::pmr::memory_resource *	mr = nullptr )

Pulse train: Σ_i fn(t - d_i) for a named pulse type.

Parameters

t	Output time grid.
d	Delay vector (one entry per pulse).
fnName	Pulse-generator name: "rectpuls", "tripuls", or "gauspuls".
fcOrW	For rectpuls / tripuls: pulse width w. For gauspuls: centre frequency fc. Default 1.
bw	Gaussian fractional bandwidth (gauspuls only). Default 0.5.
mr	Memory resource (nullptr → process default).

Returns

Same-shape DOUBLE array.

See also

pulstranHandle, rectpuls, tripuls, gauspuls

pulstranHandle()

Value nk::signal::pulstranHandle	(	Span< const double >	t,
		Span< const double >	d,
		FnHandle	fn,
		std::pmr::memory_resource *	mr = nullptr )

Pulse train with a callback-based pulse generator.

The callback is invoked once per delay with a 1-element args holding the shifted time vector t - d_i (as a 1 × n DOUBLE row Value) and writes the corresponding pulse vector into outs[0] (length n).

Parameters

t	Output time grid (length n).
d	Delay vector (length k).
fn	Callback (1 vector in, 1 vector out).
mr	Memory resource (nullptr → process default).

Returns

n × 1 column-vector DOUBLE Value containing Σ_i fn(t - d_i).

See also

pulstran

pwelch()

std::tuple< Value, Value > nk::signal::pwelch	(	const Value &	x,
		const Value &	window,
		size_t	noverlap,
		size_t	nfft,
		double	fs = 2.0 *3.14159265358979323846,
		std::pmr::memory_resource *	mr = nullptr )

Welch's averaged, modified periodogram PSD estimate.

Slides a window over x with noverlap samples of overlap, periodogram-estimates each segment, then averages.

Parameters

x	Real 1-D signal.
window	Window vector. Value::Empty → Hamming of length min(256, numel(x)).
noverlap	Samples of overlap. 0 → numel(window)/2.
nfft	FFT size. 0 → nextPow2(numel(window)).
fs	Sample rate. Default 2π.
mr	Memory resource (nullptr → process default).

Returns

Tuple (Pxx, F) (see periodogram).

See also

periodogram, cpsd, mscohere

pyulear()

std::tuple< Value, Value > nk::signal::pyulear	(	const Value &	x,
		int	p,
		size_t	nfft,
		std::pmr::memory_resource *	mr = nullptr )

Yule-Walker autoregressive PSD estimate.

Solves the normal equations from the biased autocorrelation via Levinson-Durbin recursion, then evaluates the all-pole PSD \( P_{xx}(f) = \sigma^2 \big/ \big|1 + \sum a_k e^{-j\omega k}\big|^2 \) on a one-sided grid.

Parameters

x	Real 1-D signal.
p	AR model order.
nfft	Number of frequency points (≥ 2). 0 → nextPow2(numel(x)).
mr	Memory resource (nullptr → process default).

Returns

Tuple (Pxx, F).

See also

pburg, aryule

rainflow()

Value nk::signal::rainflow	(	const Value &	x,
		std::pmr::memory_resource *	mr = nullptr )

Rainflow cycle counting (ASTM E1049-85).

Standard counting method for fatigue analysis. Identifies full and half cycles in a load-history signal, classifying each by amplitude range and mean.

Parameters

x	Real 1-D load history.
mr	Memory resource (nullptr → process default).

Returns

Nrows × 5 matrix where each row is [count, range, mean, start_idx, end_idx]. count = 1.0 for full cycles, 0.5 for half cycles.

rc2ac()

Value nk::signal::rc2ac	(	const Value &	k,
		double	r0,
		std::pmr::memory_resource *	mr = nullptr )

Reflection coefficients + r[0] → autocorrelation.

Inverse of ac2rc.

Parameters

k	Reflection coefficients.
r0	Zeroth autocorrelation sample.
mr	Memory resource (nullptr → process default).

Returns

Autocorrelation column of length numel(k) + 1.

See also

ac2rc

rc2is()

Value nk::signal::rc2is	(	const Value &	k,
		std::pmr::memory_resource *	mr = nullptr )

Reflection coefficients → inverse-sine parameterisation.

Parameters

k	Reflection-coefficient vector.
mr	Memory resource (nullptr → process default).

Returns

Inverse-sine parameter vector.

See also

is2rc

rc2lar()

Value nk::signal::rc2lar	(	const Value &	k,
		std::pmr::memory_resource *	mr = nullptr )

Reflection coefficients → log-area-ratio.

Parameters

k	Reflection-coefficient vector.
mr	Memory resource (nullptr → process default).

Returns

Log-area-ratio vector.

See also

lar2rc

rc2poly()

std::tuple< Value, Value > nk::signal::rc2poly	(	const Value &	k,
		double	r0 = 1.0,
		std::pmr::memory_resource *	mr = nullptr )

Reflection coefficients → AR poly (step-up recursion).

Parameters

k	Reflection coefficients.
r0	Zero-lag autocorrelation (for the second output efinal).
mr	Memory resource (nullptr → process default).

Returns

Tuple (a, efinal): AR coefficient vector of length numel(k) + 1, and the final prediction error efinal = r0 * prod(1 - k.^2).

rceps()

Value nk::signal::rceps	(	const Value &	x,
		std::pmr::memory_resource *	mr = nullptr )

Real cepstrum: real(ifft(log(abs(fft(x))))).

The real cepstrum is used in homomorphic signal processing for echo detection and pitch estimation.

Parameters

x	Real input vector.
mr	Memory resource (nullptr → process default).

Returns

Same-length DOUBLE vector.

See also

cceps, icceps

rcepsMinPhase()

std::pair< Value, Value > nk::signal::rcepsMinPhase	(	const Value &	x,
		std::pmr::memory_resource *	mr = nullptr )

Real cepstrum and its minimum-phase reconstruction ([y, ym] = rceps(x)).

y is the real cepstrum (as rceps); ym is the minimum-phase signal whose real cepstrum equals y, obtained by folding the cepstrum with the window [1, 2,…,2, (1 if length even), 0,…,0] and running it back through real(ifft(exp(fft(·)))).

Parameters

x	Real input vector.
mr	Memory resource (nullptr → process default).

Returns

(y, ym) pair, each the same length/orientation as x.

See also

rceps, cceps

rectpuls()

Value nk::signal::rectpuls	(	const Value &	t,
		double	w = 1.0,
		std::pmr::memory_resource *	mr = nullptr )

Rectangular pulse of unit amplitude on the open interval (-w/2, w/2).

\( y(t) = 1 \) inside the support, 0 outside; the boundary |t| == w/2 returns 0 (open-interval convention).

Parameters

t	Time samples.
w	Pulse width. Default 1.
mr	Memory resource (nullptr → process default).

Returns

Same-shape DOUBLE array.

rectwin()

Value nk::signal::rectwin	(	size_t	N,
		std::pmr::memory_resource *	mr = nullptr )

Rectangular window of length N — all ones.

Parameters

N	Window length, ≥ 1.
mr	Memory resource (nullptr → process default).

Returns

N×1 DOUBLE column vector of 1.0.

removesigroi()

Value nk::signal::removesigroi	(	const Value &	roi,
		int64_t	maxLen,
		std::pmr::memory_resource *	mr = nullptr )

Drop short ROIs (roi = removesigroi(roi, maxLen)).

Drops ROIs whose length (end - start + 1) is <= maxLen.

Parameters

roi	N × 2 ROI matrix.
maxLen	Length threshold (ROIs <= maxLen are dropped).
mr	Memory resource (nullptr → process default).

Returns

Filtered ROI matrix.

resample()

Value nk::signal::resample	(	const Value &	x,
		size_t	p,
		size_t	q,
		std::pmr::memory_resource *	mr = nullptr )

Rational rate conversion: change rate by factor p/q.

Pipeline: upsample by p with zero-stuffing → anti-alias FIR lowpass at cutoff min(1/p, 1/q) of Nyquist (order 10 · max(p, q)) → downsample by q.

Parameters

x	Input signal.
p	Numerator (target rate).
q	Denominator (source rate).
mr	Memory resource (nullptr → process default).

Returns

Resampled signal of length ceil(nx · p / q).

Value y = resample(x, 3, 2);     // 1.5× speedup

See also

decimate, upsample, downsample

risetime()

Value nk::signal::risetime	(	const Value &	x,
		const Value &	fs = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Rise time of positive-going transitions.

Duration spent crossing from the 10% to the 90% state-boundary during each positive-going transition.

Parameters

x	Real 1-D signal.
fs	Sample rate in Hz. Value::Empty → samples.
mr	Memory resource (nullptr → process default).

Returns

Column vector of rise times; one per detected transition.

See also

falltime, slewrate

rlevinson()

std::tuple< Value, Value > nk::signal::rlevinson	(	const Value &	a,
		double	efinal,
		std::pmr::memory_resource *	mr = nullptr )

Inverse Levinson recursion: recover autocorrelation from AR poly.

Parameters

a	AR coefficient vector (a[0] = 1).
efinal	Final prediction error variance.
mr	Memory resource (nullptr → process default).

Returns

Tuple (R, k) — autocorrelation sequence and reflection coefficients.

See also

levinson

rms()

Value nk::signal::rms	(	const Value &	x,
		int	dim = 0,
		std::pmr::memory_resource *	mr = nullptr )

Root-mean-square along a dimension.

Computes \( y = \sqrt{\frac{1}{N}\sum x^2} \) along the chosen axis.

Parameters

x	Real input array.
dim	Reduction axis (1-based). 0 (default) → first non-singleton dimension.
mr	Memory resource (nullptr → process default).

Returns

Reduced array with dim collapsed to length 1.

See also

rssq, peak2rms

rssq()

Value nk::signal::rssq	(	const Value &	x,
		int	dim = 0,
		std::pmr::memory_resource *	mr = nullptr )

Root-sum-of-squares along a dimension.

Computes \( y = \sqrt{\sum x^2} \) along dim.

Parameters

x	Real input array.
dim	Reduction axis. 0 → first non-singleton dim.
mr	Memory resource (nullptr → process default).

Returns

Reduced array.

See also

rms

sawtooth()

Value nk::signal::sawtooth	(	const Value &	t,
		double	width = 1.0,
		std::pmr::memory_resource *	mr = nullptr )

Sawtooth wave on period 2π.

width (in [0, 1]) controls the rising-portion fraction:

• width = 1 (default) → canonical sawtooth (linear ramp -1 → +1).
• width = 0.5 → symmetric triangle wave.
• width = 0 → reversed sawtooth.

Parameters

t	Time samples.
width	Rising-portion fraction in [0, 1]. Default 1.
mr	Memory resource (nullptr → process default).

Returns

Same-shape DOUBLE array.

scaleFilterSections()

Value nk::signal::scaleFilterSections	(	const Value &	CTFNum,
		const Value &	SV,
		std::pmr::memory_resource *	mr = nullptr )

Scale numerator coefficients of a cascaded transfer function.

Distributes the scale values SV (scalar or K+1 vector) across all sections of the cascade NUM matrix. Magnitude is distributed as |sv|^(1/K) per section; sign is concentrated on the last section.

Parameters

CTFNum	K × (Q+1) numerator matrix.
SV	Scale values.
mr	Memory resource (nullptr → process default).

Returns

Scaled K × (Q+1) numerator matrix.

schurrc()

Value nk::signal::schurrc	(	const Value &	R,
		std::pmr::memory_resource *	mr = nullptr )

Schur reflection coefficients from autocorrelation.

Equivalent to the first output of ac2rc.

Parameters

R	Autocorrelation sequence.
mr	Memory resource (nullptr → process default).

Returns

Column vector of length numel(R) - 1.

seqperiod()

std::pair< Value, Value > nk::signal::seqperiod	(	const Value &	x,
		double	tol = 0.0,
		std::pmr::memory_resource *	mr = nullptr )

Find the smallest repetition period of a signal.

Returns the smallest integer d ≤ N such that |x[i] - x[i mod d]| ≤ tol for every i. Useful for detecting if a captured waveform is periodic.

Parameters

x	Real 1-D signal of length N.
tol	Maximum allowed deviation between equivalent samples. Default 0.0 (exact match).
mr	Memory resource (nullptr → process default).

Returns

Pair (period, numRepetitions) where numRepetitions = N / period (as DOUBLE scalars).

Note

Vector input only in v1. The matrix (column-wise) form is deferred.

settlingtime()

Value nk::signal::settlingtime	(	const Value &	x,
		const Value &	fs = Value::Empty,
		double	tol = 0.02,
		std::pmr::memory_resource *	mr = nullptr )

Settling time of each transition.

Time from the start of each transition until x stays within tol (default 2%) of the destination state.

Parameters

x	Real 1-D signal.
fs	Sample rate in Hz. Value::Empty → samples.
tol	Settling tolerance as a fraction. Default 0.02.
mr	Memory resource (nullptr → process default).

Returns

Column vector, one entry per transition.

See also

risetime

sfdr()

Value nk::signal::sfdr	(	const Value &	x,
		const Value &	fs = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Spurious-free dynamic range in dB.

Distance from the fundamental peak to the next-largest spur.

Parameters

x	Real 1-D signal.
fs	Sample rate or Value::Empty.
mr	Memory resource (nullptr → process default).

Returns

Scalar SFDR in dB.

See also

snr

sgolay()

Value nk::signal::sgolay	(	int	order,
		int	framelen,
		std::pmr::memory_resource *	mr = nullptr )

Savitzky-Golay filter projection matrix.

Returns the framelen × framelen projection matrix B such that row r contains the FIR coefficients producing the polynomial-fit estimate at the r-th sample of a length-framelen window. The central row (r = floor(framelen/2)) is the symmetric filter; the other rows are the asymmetric filters used at the signal edges.

Parameters

order	Polynomial order. Must satisfy 0 ≤ order < framelen.
framelen	Window length. Must be odd and ≥ order + 1.
mr	Memory resource (nullptr → process default).

Returns

framelen × framelen DOUBLE projection matrix.

Exceptions

nk::Error

on invalid order / framelen.

See also

sgolayfilt

sgolayDiff()

Value nk::signal::sgolayDiff	(	int	order,
		int	framelen,
		std::pmr::memory_resource *	mr = nullptr )

Savitzky-Golay differentiation-filter matrix (the second output G of MATLAB's [B,G] = sgolay(order,framelen)).

Returns the framelen × (order+1) matrix G = V·(VᵀV)⁻¹, where V is the centred Vandermonde matrix of the window offsets. Column j (1-based) is the FIR filter that, applied to a length-framelen window, estimates the polynomial coefficient a_j at the central point — so G(:,1) is the smoothing filter (equals the central row of sgolay) and factorial(j-1) · G(:,j) estimates the (j-1)-th derivative.

Parameters

order	Polynomial order. Must satisfy 0 ≤ order < framelen.
framelen	Window length. Must be odd and ≥ order + 1.
mr	Memory resource (nullptr → process default).

Returns

framelen × (order+1) DOUBLE differentiation matrix.

Exceptions

nk::Error

on invalid order / framelen.

See also

sgolay

sgolayfilt() [1/2]

Value nk::signal::sgolayfilt	(	const Value &	x,
		int	order,
		int	framelen,
		const Value &	weights,
		int	dim,
		std::pmr::memory_resource *	mr = nullptr )

Savitzky-Golay smoothing with optional weighting and dimension.

Generalises sgolayfilt to matrices and weighted least-squares:

• If x is a matrix, each 1-D slice along dim is filtered independently (dim = 1 → columns, dim = 2 → rows). dim = 0 selects the first non-singleton dimension (the MATLAB default).
• weights is an empty Value (unweighted) or a framelen-length vector of positive weights for the local least-squares fit.

Parameters

x	Real 1-D or 2-D signal.
order	Polynomial order (0 ≤ order < framelen).
framelen	Window length (odd, ≥ order + 1).
weights	Empty, or framelen positive weights.
dim	Operating dimension (1, 2, or 0 = auto).
mr	Memory resource (nullptr → process default).

Returns

Filtered signal, same shape as x.

See also

sgolay, medfilt1

sgolayfilt() [2/2]

Value nk::signal::sgolayfilt	(	const Value &	x,
		int	order,
		int	framelen,
		std::pmr::memory_resource *	mr = nullptr )

Savitzky-Golay smoothing of a 1-D signal.

Fits a local polynomial of order to a sliding window of framelen samples (via least-squares), then evaluates the polynomial at the centre. Smooths the signal while preserving features up to order-th derivative.

Interior samples use the central row of sgolay's projection matrix; edge samples use the asymmetric rows so no zero-padding artefacts appear.

Parameters

x	Real 1-D signal.
order	Polynomial order (0 ≤ order < framelen).
framelen	Window length (odd, ≥ order + 1).
mr	Memory resource (nullptr → process default).

Returns

Filtered signal, same shape as x.

// Smooth a noisy signal preserving local quadratic features:
Value y = sgolayfilt(noisy, 2, 11);

See also

sgolay, medfilt1

shiftdata()

std::tuple< Value, Value, Value > nk::signal::shiftdata	(	const Value &	x,
		int	dim = 0,
		std::pmr::memory_resource *	mr = nullptr )

Move a chosen dimension to the leading axis for dim-aware processing.

Two operating modes:

• dim == 0 (or unspecified): "auto" mode. Calls shiftdim(x) to drop leading singleton dimensions. perm is returned empty; nshifts contains the number of dimensions rolled up.
• dim > 0: explicit dim mode. Calls permute(x, perm) where perm = [dim, 1..dim-1, dim+1..ndims]. nshifts is empty.

Useful when implementing a function that operates "along the first non-singleton dimension by default, or along an explicit dim if provided".

Parameters

x	Input array.
dim	Dimension to move to the front. 0 (default) = auto.
mr	Memory resource (nullptr → process default).

Returns

Tuple (shifted, perm, nshifts). Use unshiftdata to reverse.

See also

unshiftdata

shortensigroi()

Value nk::signal::shortensigroi	(	const Value &	roi,
		int64_t	Lpre,
		int64_t	Lpost,
		std::pmr::memory_resource *	mr = nullptr )

Shrink each ROI (roi = shortensigroi(roi, Lpre, Lpost)).

Shrinks each ROI by Lpre on the left and Lpost on the right. ROIs that collapse (end < start) are dropped.

Parameters

roi	N × 2 ROI matrix.
Lpre	Left shrink.
Lpost	Right shrink.
mr	Memory resource (nullptr → process default).

Returns

Shrunken ROI matrix.

See also

extendsigroi

sigrangebinmask() [1/2]

Value nk::signal::sigrangebinmask	(	const Value &	x,
		double	lo,
		double	hi,
		std::pmr::memory_resource *	mr = nullptr )

Range-based binary mask, interval form (m = sigrangebinmask(x, [lo, hi]) ≡ lo <= x <= hi).

Parameters

x	Source signal column.
lo	Lower bound (inclusive).
hi	Upper bound (inclusive).
mr	Memory resource (nullptr → process default).

Returns

LOGICAL column, same length as x.

See also

binmask2sigroi

sigrangebinmask() [2/2]

Value nk::signal::sigrangebinmask	(	const Value &	x,
		double	threshold,
		std::pmr::memory_resource *	mr = nullptr )

Range-based binary mask, single-threshold form (m = sigrangebinmask(x, threshold) ≡ x > threshold).

Parameters

x	Source signal column.
threshold	Scalar threshold.
mr	Memory resource (nullptr → process default).

Returns

LOGICAL column, same length as x.

See also

binmask2sigroi

sigroi2binmask()

Value nk::signal::sigroi2binmask	(	const Value &	roi,
		int64_t	len = -1,
		std::pmr::memory_resource *	mr = nullptr )

ROI pairs → binary mask (m = sigroi2binmask(roi, len)).

Parameters

roi	N × 2 ROI matrix.
len	Output length: -1 (default) → max(roi(:, 2)); otherwise pad with zeros (or clamp ROIs) to exact length.
mr	Memory resource (nullptr → process default).

Returns

LOGICAL column.

See also

binmask2sigroi

sinad()

Value nk::signal::sinad	(	const Value &	x,
		const Value &	fs = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Signal-to-noise-and-distortion in dB.

Like snr but treats harmonic distortion as noise.

Parameters

x	Real 1-D signal.
fs	Sample rate or Value::Empty.
mr	Memory resource (nullptr → process default).

Returns

Scalar SINAD in dB.

See also

snr, thd

sinc()

Value nk::signal::sinc	(	const Value &	t,
		std::pmr::memory_resource *	mr = nullptr )

Normalised cardinal sine: sinc(0) = 1, otherwise sin(πt)/(πt).

Parameters

t	Real array.
mr	Memory resource (nullptr → process default).

Returns

Same-shape DOUBLE array.

slewrate()

Value nk::signal::slewrate	(	const Value &	x,
		const Value &	fs = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Slew rate of each transition.

Computed as (upper - lower) / transition_duration; sign matches direction (positive for rising, negative for falling).

Parameters

x	Real 1-D signal.
fs	Sample rate in Hz. Value::Empty → samples.
mr	Memory resource (nullptr → process default).

Returns

Column vector, one entry per transition.

See also

risetime, falltime

snr()

Value nk::signal::snr	(	const Value &	x,
		const Value &	fs = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Signal-to-noise ratio in dB.

Power of the fundamental over the noise floor (everything outside the fundamental and the first 6 harmonic skirts).

Parameters

x	Real 1-D signal.
fs	Sample rate or Value::Empty.
mr	Memory resource (nullptr → process default).

Returns

Scalar SNR in dB.

See also

sinad, thd, sfdr

sos2ss()

std::tuple< Value, Value, Value, Value > nk::signal::sos2ss	(	const Value &	sos,
		double	g = 1.0,
		std::pmr::memory_resource *	mr = nullptr )

Second-order sections to state space (via sos2tf then tf2ss).

Parameters

sos	L × 6 SOS matrix.
g	Optional global gain. Default 1.
mr	Memory resource (nullptr → process default).

Returns

Tuple (A, B, C, D).

sos2tf()

std::tuple< Value, Value > nk::signal::sos2tf	(	const Value &	sos,
		double	g = 1.0,
		std::pmr::memory_resource *	mr = nullptr )

Second-order sections to transfer function.

Convolves every section row [b0 b1 b2 1 a1 a2] across the cascade to recover the global numerator and denominator polynomials.

Parameters

sos	L × 6 second-order-sections matrix.
g	Optional global gain (multiplies b at the end). Default 1.
mr	Memory resource (nullptr → process default).

Returns

Tuple (b, a) — global numerator and denominator.

See also

zp2sos, tf2sos

sos2zp()

std::tuple< Value, Value, double > nk::signal::sos2zp	(	const Value &	sos,
		double	g = 1.0,
		std::pmr::memory_resource *	mr = nullptr )

Second-order sections to zero / pole / gain.

Roots each section and assembles the zero / pole vectors. The per-section gains are accumulated into the returned scalar gain.

Parameters

sos	L × 6 SOS matrix.
g	Optional global gain prefactor. Default 1.
mr	Memory resource (nullptr → process default).

Returns

Tuple (zeros, poles, gain).

See also

sos2tf, zp2sos

sosfilt()

Value nk::signal::sosfilt	(	const Value &	sos,
		const Value &	x,
		std::pmr::memory_resource *	mr = nullptr )

Apply a second-order-sections cascade to a signal.

Each row of sos represents one biquad section [b0 b1 b2 1 a1 a2] (after global-gain normalisation; pass g to sos2tf or build SOS via zp2sos for the gain-distributed form). Sections are evaluated in cascade left-to-right.

For matrix x, columns are filtered independently.

Parameters

sos	L × 6 SOS matrix.
x	Input signal (vector or 2-D matrix).
mr	Memory resource (nullptr → process default).

Returns

Filtered signal, same shape as x.

auto [z, p, k] = ellipap(8, 1.0, 60.0);
Value sos      = zp2sos(z, p, k);
Value y        = sosfilt(sos, x);

See also

sosfiltfilt, filter, zp2sos

sosfiltfilt()

Value nk::signal::sosfiltfilt	(	const Value &	sos,
		const Value &	x,
		std::pmr::memory_resource *	mr = nullptr )

Zero-phase forward + backward SOS cascade.

Equivalent to applying sosfilt once forward and once on the reversed signal (and reversing again), with Gustafsson initial conditions and reflection padding to suppress edge transients. This is the filtfilt(d, x) form where d is a digital-filter SOS object.

Numerically stable for high-order IIR designs where direct (b, a) form is ill-conditioned.

Parameters

sos	L × 6 SOS matrix.
x	Input signal.
mr	Memory resource (nullptr → process default).

Returns

Zero-phase filtered signal.

See also

sosfilt, filtfilt

spectralcrest()

Value nk::signal::spectralcrest	(	const Value &	x,
		const Value &	fs = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Spectral crest: max(P) / mean(P) (peakedness).

Parameters

x	Real 1-D signal.
fs	Sample rate (Hz) or Value::Empty.
mr	Memory resource (nullptr → process default).

Returns

Scalar crest.

See also

spectralflatness

spectralentropy()

Value nk::signal::spectralentropy	(	const Value &	x,
		const Value &	fs = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Shannon entropy of the normalised PSD.

Treats the PSD as a probability distribution over frequency bins.

Parameters

x	Real 1-D signal.
fs	Sample rate (Hz) or Value::Empty.
mr	Memory resource (nullptr → process default).

Returns

Scalar entropy.

spectralflatness()

Value nk::signal::spectralflatness	(	const Value &	x,
		const Value &	fs = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Spectral flatness: geomean(P) / mean(P).

1 = white noise, 0 = tonal.

Parameters

x	Real 1-D signal.
fs	Sample rate (Hz) or Value::Empty.
mr	Memory resource (nullptr → process default).

Returns

Scalar flatness in [0, 1].

See also

spectralcrest

spectralkurtosis()

Value nk::signal::spectralkurtosis	(	const Value &	x,
		const Value &	fs = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Kurtosis of the PSD treated as a frequency distribution.

Parameters

x	Real 1-D signal.
fs	Sample rate (Hz) or Value::Empty.
mr	Memory resource (nullptr → process default).

Returns

Scalar spectral kurtosis.

See also

spectralskewness

spectralskewness()

Value nk::signal::spectralskewness	(	const Value &	x,
		const Value &	fs = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Skewness of the PSD treated as a frequency distribution.

Parameters

x	Real 1-D signal.
fs	Sample rate (Hz) or Value::Empty.
mr	Memory resource (nullptr → process default).

Returns

Scalar spectral skewness.

See also

spectralkurtosis

spectrogram()

std::tuple< Value, Value, Value > nk::signal::spectrogram	(	const Value &	x,
		const Value &	window,
		size_t	noverlap,
		size_t	nfft,
		std::pmr::memory_resource *	mr = nullptr )

Short-time Fourier transform with explicit (S, F, T) outputs.

Slides a window of length winLen across x with noverlap samples of overlap, computes the FFT of each windowed segment, and returns the resulting time–frequency matrix.

Parameters

x	1-D signal (row or column).
window	Window vector. Value::Empty → Hamming of length min(256, numel(x)).
noverlap	Samples of overlap between consecutive segments. 0 → winLen / 2.
nfft	FFT size. 0 → nextPow2(winLen).
mr	Memory resource (nullptr → process default).

Returns

Tuple (S, F, T):

• S — nfft/2+1 × numFrames COMPLEX matrix of per-frame one-sided FFTs.
• F — frequency axis in normalised cycles per sample, nfft/2+1 × 1 column vector.
• T — time axis (centre of each frame in samples), numFrames × 1 column vector.

See also

stft, istft, periodogram

square()

Value nk::signal::square	(	const Value &	t,
		double	duty = 50.0,
		std::pmr::memory_resource *	mr = nullptr )

Square wave with period 2π.

Output is +1 during the high portion and -1 during the low portion of each cycle. The high-portion fraction is duty / 100.

Parameters

t	Time samples.
duty	Duty cycle in percent. Default 50 (symmetric).
mr	Memory resource (nullptr → process default).

Returns

Same-shape DOUBLE array.

ss2sos()

Value nk::signal::ss2sos	(	const Value &	A,
		const Value &	B,
		const Value &	C,
		double	D = 0.0,
		std::pmr::memory_resource *	mr = nullptr )

State space → second-order sections (sos = ss2sos(A, B, C, D)).

Composes ss2tf with tf2sos. SISO only.

Parameters

A	N × N state-transition matrix.
B	N × 1 input vector.
C	1 × N output vector.
D	Direct feed-through scalar (default 0).
mr	Memory resource (nullptr → process default).

Returns

L × 6 SOS matrix.

See also

ss2tf, sos2ss

ss2tf()

std::tuple< Value, Value > nk::signal::ss2tf	(	const Value &	A,
		const Value &	B,
		const Value &	C,
		double	D = 0.0,
		std::pmr::memory_resource *	mr = nullptr )

State space to transfer function (SISO only).

Parameters

A	N × N state-transition matrix.
B	N × 1 input vector.
C	1 × N output vector.
D	Direct feed-through scalar (default 0).
mr	Memory resource (nullptr → process default).

Returns

Tuple (b, a).

See also

tf2ss

ss2zp()

std::tuple< Value, Value, double > nk::signal::ss2zp	(	const Value &	A,
		const Value &	B,
		const Value &	C,
		double	D = 0.0,
		std::pmr::memory_resource *	mr = nullptr )

State space → zero / pole / gain ([z, p, k] = ss2zp(A, B, C, D)).

Composes ss2tf with tf2zpk internally. SISO only.

Parameters

A	N × N state-transition matrix.
B	N × 1 input vector.
C	1 × N output vector.
D	Direct feed-through scalar (default 0).
mr	Memory resource (nullptr → process default).

Returns

Tuple (z, p, k) — zeros, poles, gain.

See also

ss2tf, zp2ss

statelevels()

Value nk::signal::statelevels	(	const Value &	x,
		std::pmr::memory_resource *	mr = nullptr )

Estimate the [low, high] state levels of a step-shaped signal.

Uses a histogram-mode estimator: 100 bins, split at mean(x). The mode bin in each half gives the corresponding state level. For inputs that are too flat for the histogram to separate, returns [min, max].

Parameters

x	Real 1-D signal.
mr	Memory resource (nullptr → process default).

Returns

1 × 2 DOUBLE row vector [low, high].

See also

risetime, falltime, midcross

stepz()

std::tuple< Value, Value > nk::signal::stepz	(	const Value &	b,
		const Value &	a,
		size_t	n = 0,
		std::pmr::memory_resource *	mr = nullptr )

Step response of a digital filter.

Computes s[k] = filter(b, a, ones(n, 1)) — the response to a unit step input.

Parameters

b	Numerator polynomial.
a	Denominator polynomial.
n	Number of output samples. 0 (default) → impzlength.
mr	Memory resource (nullptr → process default).

Returns

Tuple (s, t) — step response and sample indices.

See also

impz

stft()

Value nk::signal::stft	(	const Value &	x,
		const Value &	window,
		std::size_t	overlap,
		std::size_t	fftLength,
		const std::string &	range,
		std::pmr::memory_resource *	mr = nullptr )

Full two-sided / centred / one-sided STFT.

Defaults:

• window = hann(128, 'periodic')
• overlap = 96 (75%)
• fftLength = 128

Parameters

x	1-D signal (row or column).
window	Window vector. Value::Empty → 128-point Hann(periodic).
overlap	Samples shared between consecutive frames. SIZE_MAX sentinel → use default 3·winLen/4.
fftLength	FFT size per frame, ≥ winLen. 0 → use winLen.
range	"twosided" (default), "centered", or "onesided".
mr	Memory resource (nullptr → process default).

Returns

COMPLEX matrix sized [rows × frames] where rows = fftLength for twosided / centered, rows = fftLength/2 + 1 for onesided.

Note

KNOWN GAPS: fs argument and the 3-output [S, F, T] form are deferred. Multi-channel matrix input is also deferred.

See also

istft, spectrogram

stmcb()

std::tuple< Value, Value > nk::signal::stmcb	(	const Value &	h,
		int	nb,
		int	na,
		int	niter = 5,
		std::pmr::memory_resource *	mr = nullptr )

Steiglitz–McBride IIR identification ([b, a] = stmcb(h, nb, na, niter)).

Finds B(z)/A(z) with nb zeros and na poles whose impulse response approximates h. Initialises A via prony, then runs niter (default 5) Steiglitz–McBride iterations: prefilter the unit impulse and h by 1/A, then re-solve the linear least-squares [E | -G]·[b; a] ≈ g.

Parameters

h	Impulse response (real 1-D).
nb	Numerator order (B has nb+1 coefficients).
na	Denominator order (A has na+1 coefficients, a(1)=1).
niter	Iterations (< 1 → MATLAB default 5).
mr	Memory resource (nullptr → process default).

Returns

Tuple (b, a) row vectors.

See also

prony, levinson, lpc

tachorpm()

std::tuple< Value, Value > nk::signal::tachorpm	(	const Value &	x,
		double	fs,
		const Value &	threshold = Value::Empty,
		int	ppr = 1,
		std::pmr::memory_resource *	mr = nullptr )

Convert a tachometer pulse signal to an RPM trace.

Detects rising-edge crossings of threshold, then computes RPM from inter-pulse intervals: rpm = 60 / (Δt · ppr).

Parameters

x	Tachometer pulse signal (real 1-D).
fs	Sample rate of x in Hz.
threshold	Crossing level. Value::Empty (default) → midpoint of min(x) and max(x).
ppr	Pulses per revolution. Default 1.
mr	Memory resource (nullptr → process default).

Returns

Tuple (rpm, t_pulse) — RPM samples and their timestamps in seconds.

See also

tsa

taylorwin()

Value nk::signal::taylorwin	(	size_t	N,
		int	nbar = 4,
		double	sll = -30.0,
		std::pmr::memory_resource *	mr = nullptr )

Taylor window of length N — radar / antenna design.

Distributes sidelobe energy so the first nbar sidelobes are roughly equal in height (at sll dB), with the rest decaying. Used in pattern synthesis where the inner sidelobes matter most.

Parameters

N	Window length, ≥ 1.
nbar	Number of nearly-equal-height sidelobes, ≥ 2. Default 4.
sll	Peak sidelobe level in dB, must be < 0. Default -30.
mr	Memory resource (nullptr → process default).

Returns

N×1 DOUBLE column vector.

Exceptions

nk::Error

if sll ≥ 0 or nbar < 2.

tf2sos()

Value nk::signal::tf2sos	(	const Value &	b,
		const Value &	a,
		std::pmr::memory_resource *	mr = nullptr )

Convert a transfer-function pair (b, a) to an SOS matrix.

Internally: roots(b) → zeros, roots(a) → poles, gain = b[0] / a[0], then dispatches to zp2sos.

Parameters

b	Numerator polynomial.
a	Denominator polynomial.
mr	Memory resource (nullptr → process default).

Returns

SOS matrix (see zp2sos).

See also

tf2sosWithGain, zp2sos

tf2sosWithGain()

std::tuple< Value, double > nk::signal::tf2sosWithGain	(	const Value &	b,
		const Value &	a,
		std::pmr::memory_resource *	mr = nullptr )

Two-output form of tf2sos: returns (sos, g).

Equivalent to tf2sos but returns the residual gain g as the second tuple element instead of folding it into the SOS biquads' numerators.

Parameters

b	Numerator polynomial.
a	Denominator polynomial.
mr	Memory resource (nullptr → process default).

Returns

Tuple (sos, g) — SOS matrix (without gain) and the residual scalar gain.

See also

tf2sos, zp2sosWithGain

tf2ss()

std::tuple< Value, Value, Value, Value > nk::signal::tf2ss	(	const Value &	b,
		const Value &	a,
		std::pmr::memory_resource *	mr = nullptr )

Transfer function to state space (controllable canonical form).

Returns the 4-tuple (A, B, C, D) defining a SISO state-space realisation equivalent to H(z) = B(z) / A(z). The controllable canonical form is always used.

Parameters

b	Numerator polynomial.
a	Denominator polynomial.
mr	Memory resource (nullptr → process default).

Returns

Tuple (A, B, C, D).

See also

ss2tf, tf2zpk

tf2zpk()

std::tuple< Value, Value, double > nk::signal::tf2zpk	(	const Value &	b,
		const Value &	a,
		std::pmr::memory_resource *	mr = nullptr )

Transfer function to zero / pole / gain.

Alias of tf2zp. Roots b for zeros, a for poles, and computes gain = b[0] / a[0].

Parameters

b	Numerator polynomial.
a	Denominator polynomial.
mr	Memory resource (nullptr → process default).

Returns

Tuple (zeros, poles, gain).

tfestimate()

std::tuple< Value, Value > nk::signal::tfestimate	(	const Value &	x,
		const Value &	y,
		const Value &	window,
		size_t	noverlap,
		size_t	nfft,
		double	fs = 2.0 *3.14159265358979323846,
		std::pmr::memory_resource *	mr = nullptr )

Transfer-function estimate via Welch's method.

Estimates \( T_{xy}(f) = P_{yx}(f) / P_{xx}(f) \). For an LTI system y = h * x this recovers H(f) up to finite-Welch bias.

Parameters

x	Input signal.
y	Output signal.
window	Window. Value::Empty → Hamming(256).
noverlap	Overlap.
nfft	FFT size.
fs	Sample rate.
mr	Memory resource (nullptr → process default).

Returns

Tuple (Txy, F) — Txy is COMPLEX.

See also

cpsd, mscohere, freqz

thd()

Value nk::signal::thd	(	const Value &	x,
		const Value &	fs = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Total harmonic distortion in dB.

Power sum of the first 6 harmonics over the fundamental.

Parameters

x	Real 1-D signal.
fs	Sample rate or Value::Empty.
mr	Memory resource (nullptr → process default).

Returns

Scalar THD in dB.

See also

snr, sinad

triang()

Value nk::signal::triang	(	size_t	N,
		std::pmr::memory_resource *	mr = nullptr )

Triangular window of length N — non-zero endpoints variant of Bartlett.

For odd N: \( w(n) = 1 - |2n - (N-1)| / N \). For even N: \( w(n) = 1 - |2n - (N-1)| / (N-1) \).

Differs from bartlett only in that endpoints are non-zero (≈ 1/N).

Parameters

N	Window length, ≥ 1.
mr	Memory resource (nullptr → process default).

Returns

N×1 DOUBLE column vector.

tripuls()

Value nk::signal::tripuls	(	const Value &	t,
		double	w = 1.0,
		std::pmr::memory_resource *	mr = nullptr )

Triangular pulse of unit amplitude on |t| ≤ w/2.

\( y(t) = \max(1 - 2|t|/w,\ 0) \).

Parameters

t	Time samples.
w	Pulse base width. Default 1.
mr	Memory resource (nullptr → process default).

Returns

Same-shape DOUBLE array.

tsa()

std::tuple< Value, Value > nk::signal::tsa	(	const Value &	x,
		double	fs,
		const Value &	rpm,
		double	fs_rpm,
		int	n_per_rev = 1024,
		std::pmr::memory_resource *	mr = nullptr )

Time-synchronous average (TSA).

Resamples x to the angular domain using the rpm time series, then averages across complete revolutions. Reveals periodic features that are coherent with shaft rotation (e.g. gear-mesh tones).

Parameters

x	Vibration signal (real 1-D).
fs	Sample rate of x in Hz.
rpm	RPM trace (real 1-D, sampled at fs_rpm).
fs_rpm	Sample rate of rpm in Hz.
n_per_rev	Samples per revolution in the output. Default 1024.
mr	Memory resource (nullptr → process default).

Returns

Tuple (avg, theta) — averaged signal over one revolution and angle vector [0, 2π · (n_per_rev − 1) / n_per_rev].

See also

tachorpm, envspectrum

tukeywin()

Value nk::signal::tukeywin	(	size_t	N,
		double	r = 0.5,
		std::pmr::memory_resource *	mr = nullptr )

Tukey (cosine-tapered) window of length N.

First and last r*(N-1)/2 samples are a cosine taper; the middle is flat 1.0. r=0 → rectangular, r=1 → Hann.

Parameters

N	Window length, ≥ 1.
r	Cosine-fraction in [0, 1]. Default 0.5.
mr	Memory resource (nullptr → process default).

Returns

N×1 DOUBLE column vector.

udecode()

Value nk::signal::udecode	(	const Value &	u,
		int	N,
		double	V = 1.0,
		bool	wrapOnOverflow = false,
		std::pmr::memory_resource *	mr = nullptr )

Decode integer data back to double with peak ±V (y = udecode(u, N, V, overflow)).

Parameters

u	Input (int8/16/32 or uint8/16/32).
N	Bit width used at encoding time.
V	Peak output level.
wrapOnOverflow	false → saturate; true → wrap modulo 2^N.
mr	Memory resource (nullptr → process default).

Returns

DOUBLE Value, same shape as u.

See also

uencode

uencode()

Value nk::signal::uencode	(	const Value &	u,
		int	N,
		double	V = 1.0,
		bool	signedOutput = false,
		std::pmr::memory_resource *	mr = nullptr )

Quantise and encode u as N-bit integers (y = uencode(u, N, V, type)).

Parameters

u	Real input.
N	Bit width in [2, 32].
V	Peak input level (saturates at ±V).
signedOutput	false → uint8/uint16/uint32; true → int8/int16/int32. Output container type follows the least-bits rule (N≤8 → 8-bit, N≤16 → 16-bit, else 32-bit).
mr	Memory resource (nullptr → process default).

Returns

Integer-typed Value, same shape as u.

See also

udecode

undershoot()

Value nk::signal::undershoot	(	const Value &	x,
		const Value &	fs = Value::Empty,
		std::pmr::memory_resource *	mr = nullptr )

Percent undershoot below the lower state level.

Mirror of overshoot for downward transitions.

Parameters

x	Real 1-D signal.
fs	Sample rate in Hz. Value::Empty → samples.
mr	Memory resource (nullptr → process default).

Returns

Column vector of percentages.

See also

overshoot

unshiftdata()

Value nk::signal::unshiftdata	(	const Value &	x,
		const Value &	perm,
		const Value &	nshifts,
		std::pmr::memory_resource *	mr = nullptr )

Inverse of shiftdata.

If perm is empty: y = shiftdim(x, -nshifts). Otherwise: y = ipermute(x, perm).

Parameters

x	Reshaped array from shiftdata.
perm	Permutation vector from shiftdata (empty → use nshifts).
nshifts	Number of dimensions shiftdata had to roll up.
mr	Memory resource (nullptr → process default).

Returns

Restored array in original layout.

See also

shiftdata

unwrap()

Value nk::signal::unwrap	(	const Value &	phase,
		std::pmr::memory_resource *	mr = nullptr )

Unwrap a wrapped radian phase sequence.

Walks phase from start to end; whenever the jump between consecutive samples exceeds π in magnitude, adds ∓2π to all subsequent samples to restore continuity. This recovers the "true" continuous phase from a sequence that has been wrapped into the principal branch (-π, π].

Parameters

phase	Wrapped phase in radians (real vector or matrix). For matrices: unwraps along the first non-singleton dimension.
mr	Memory resource (nullptr → process default).

Returns

Unwrapped phase, same shape as phase.

auto [H, w] = freqz(b, a);
Value phi   = unwrap(angle(H));   // continuous phase response

upfirdn()

Value nk::signal::upfirdn	(	const Value &	x,
		const Value &	h,
		size_t	p,
		size_t	q = 1,
		std::pmr::memory_resource *	mr = nullptr )

Upsample-FIR-Downsample (polyphase) rational rate conversion.

Pipeline: upsample x by p (zero-stuffing) → FIR-filter with h → downsample by q. The combined operation is implemented via a polyphase decomposition so the actual cost is numel(h)·numel(x)/q rather than the full p·numel(x)·numel(h)/q.

Parameters

x	Input signal.
h	FIR filter coefficients.
p	Upsample factor, ≥ 1.
q	Downsample factor, ≥ 1. Default 1.
mr	Memory resource (nullptr → process default).

Returns

Output signal of length ceil(((nx-1)·p + numel(h)) / q).

See also

resample, interp

upsample()

Value nk::signal::upsample	(	const Value &	x,
		size_t	n,
		std::pmr::memory_resource *	mr = nullptr,
		size_t	phase = 0 )

Integer-rate upsampling — zero-stuff between samples.

y[i · n] = x[i], other positions zero. Output length is nx · n. Orientation preserved. Pair with a lowpass filter for proper band-limited interpolation, or use resample.

Parameters

x	Input signal.
n	Up-sampling factor, ≥ 1.
mr	Memory resource (nullptr → process default).

Returns

Upsampled signal.

See also

downsample, resample, interp

phase (0 ≤ phase < n) places the samples at offset phase: y[phase + i·n] = x[i].

vco() [1/2]

Value nk::signal::vco	(	const Value &	x,
		double	fc,
		double	fs,
		std::pmr::memory_resource *	mr = nullptr )

Voltage-controlled (frequency-modulated) oscillator.

x ∈ [-1, 1] modulates the instantaneous frequency. Centre-form: -1 → 0 Hz, 0 → Fc Hz, +1 → 2·Fc Hz. Frequency modulation via rectangular cumsum integral approximation.

Parameters

x	Control signal in [-1, 1].
fc	Centre frequency in Hz (x = 0 maps to this).
fs	Sample rate in Hz.
mr	Memory resource (nullptr → process default).

Returns

y = cos(...) of the same shape as x.

See also

modulate

vco() [2/2]

Value nk::signal::vco	(	const Value &	x,
		double	fmin,
		double	fmax,
		double	fs,
		std::pmr::memory_resource *	mr = nullptr )

Voltage-controlled oscillator, explicit [Fmin, Fmax] range form (y = vco(x, [fmin fmax], fs)).

x ∈ [-1, 1]: -1 → fmin, +1 → fmax.

Parameters

x	Control signal in [-1, 1].
fmin	Frequency at x == -1, Hz.
fmax	Frequency at x == +1, Hz.
fs	Sample rate in Hz.
mr	Memory resource (nullptr → process default).

Returns

y = cos(...) of the same shape as x.

See also

modulate

xcorr() [1/2]

std::tuple< Value, Value > nk::signal::xcorr	(	const Value &	x,
		const Value &	y,
		std::pmr::memory_resource *	mr = nullptr )

Cross-correlation of two real vectors.

Returns (c, lags) where \( c[k] = \sum_n x[n] \cdot y[n - k] \) for k ∈ [-(maxN-1), maxN-1] (maxN = max(nx, ny)). The lag vector lags is integer-valued and aligns one-to-one with c.

c has length nx + ny - 1.

Parameters

x	First signal (real, row or column).
y	Second signal (real, row or column).
mr	Memory resource (nullptr → process default).

Returns

Tuple (c, lags), both column vectors.

auto [c, lags] = xcorr({1, 2, 3, 4}, {1, 0, 0, 1});
// c has 7 elements, lags = -3..3

See also

xcov, finddelay

xcorr() [2/2]

std::tuple< Value, Value > nk::signal::xcorr ( const Value & x, std::pmr::memory_resource * mr = nullptr )

inline

Auto-correlation — equivalent to xcorr(x, x).

Parameters

x	Signal (real, row or column).
mr	Memory resource (nullptr → process default).

Returns

Tuple (c, lags) — same shape as the two-arg form; c has length 2 · numel(x) - 1.

See also

xcorr(const Value &, const Value &, std::pmr::memory_resource *)

Definition at line 98 of file convolution.hpp.

xcorr2()

Value nk::signal::xcorr2	(	const Value &	A,
		const Value &	B,
		std::pmr::memory_resource *	mr = nullptr )

2-D cross-correlation of two real matrices.

Output size is (rA + rB - 1) × (cA + cB - 1). Equivalent to conv2(A, fliplr(flipud(B)), 'full'). Uses an FFT path for large inputs (when rA·cA·rB·cB > 8192 and output ≥ 8×8) and the direct O(rA·cA·rB·cB) loop otherwise.

Parameters

A	First 2-D matrix.
B	Second 2-D matrix.
mr	Memory resource (nullptr → process default).

Returns

DOUBLE matrix of size (rA+rB-1) × (cA+cB-1).

xcov() [1/3]

std::tuple< Value, Value > nk::signal::xcov	(	const Value &	x,
		const Value &	y,
		int	maxlag,
		const std::string &	scaleopt,
		std::pmr::memory_resource *	mr = nullptr )

Cross-covariance of two real vectors.

Computes xcorr(x - mean(x), y - mean(y)) with MATLAB's scaling and lag handling. The mean is subtracted before correlation, so the result is invariant to DC offsets.

Parameters

x	First signal (real, row or column).
y	Second signal (real, row or column).
maxlag	Maximum lag; < 0 selects the full range N-1 (N = max(numel(x), numel(y))). Result is cropped (or zero-padded) to lags -maxlag..maxlag.
scaleopt	"none" (default), "biased", "unbiased", or "coeff" (a.k.a. "normalized").
mr	Memory resource (nullptr → process default).

Returns

Tuple (c, lags).

See also

xcorr

xcov() [2/3]

std::tuple< Value, Value > nk::signal::xcov ( const Value & x, const Value & y, std::pmr::memory_resource * mr = nullptr )

inline

Cross-covariance with full lags and "none" scaling.

Definition at line 129 of file convolution.hpp.

xcov() [3/3]

std::tuple< Value, Value > nk::signal::xcov ( const Value & x, std::pmr::memory_resource * mr = nullptr )

inline

Auto-covariance — equivalent to xcov(x, x).

Parameters

x	Signal (real, row or column).
mr	Memory resource (nullptr → process default).

Returns

Tuple (c, lags) — DC-removed auto-correlation; same shape as the two-arg form.

See also

xcov(const Value &, const Value &, std::pmr::memory_resource *)

Definition at line 142 of file convolution.hpp.

zerocrossrate()

std::pair< Value, Value > nk::signal::zerocrossrate	(	const Value &	x,
		double	level = 0.0,
		std::pmr::memory_resource *	mr = nullptr )

Zero-crossing rate of a signal.

Counts sign changes of (x - level) over the input and returns the rate per sample. Boundary half-credit +0.5 is applied for the default ZeroPositive = false setting.

Parameters

x	Real 1-D signal.
level	Threshold around which crossings are counted. Default 0.
mr	Memory resource (nullptr → process default).

Returns

Pair (rate, count) where rate = count / numel(x).

Note

Name=Value args ('Threshold', 'TransitionEdge', 'WindowLength') and matrix input deferred.

zerophase()

std::tuple< Value, Value > nk::signal::zerophase	(	const Value &	b,
		const Value &	a,
		size_t	n = 512,
		std::pmr::memory_resource *	mr = nullptr )

Equivalent zero-phase response.

Removes the linear-phase delay component, returning the amplitude function Hr(ω) of the filter. For symmetric or antisymmetric FIR filters this is a real-valued function that may be negative (sign flip ↔ phase jump of π in the original H(e^{jω})).

Parameters

b	Numerator polynomial.
a	Denominator polynomial.
n	Number of frequency points. Default 512.
mr	Memory resource (nullptr → process default).

Returns

Tuple (Hr, w) — amplitude function (real-valued for linear-phase FIR) and frequency grid in [0, π].

See also

freqz, phasez

zp2sos()

Value nk::signal::zp2sos	(	const Value &	zeros,
		const Value &	poles,
		double	gain,
		std::pmr::memory_resource *	mr = nullptr )

Convert zeros / poles / gain to a second-order-sections (SOS) matrix.

Pairs complex-conjugate roots into biquadratic sections, then arranges them into an L × 6 matrix where each row is [b0 b1 b2 1 a1 a2] (numerator + denominator coefficients of one biquad).

1-output form: the global gain is distributed across the sections so the cascade prod_k Hk(z) reproduces the original transfer function.

Parameters

zeros	Zeros of the filter (complex column vector).
poles	Poles of the filter (complex column vector).
gain	Overall scalar gain.
mr	Memory resource (nullptr → process default).

Returns

L × 6 DOUBLE SOS matrix where L = ceil(max(numel(zeros), numel(poles)) / 2).

auto [z, p, k] = ellipap(6, 1.0, 40.0);
Value sos = zp2sos(z, p, k);
Value y   = sosfilt(sos, x);

See also

zp2sosWithGain, sosfilt, tf2sos

zp2sosWithGain()

std::tuple< Value, double > nk::signal::zp2sosWithGain	(	const Value &	zeros,
		const Value &	poles,
		double	gain,
		std::pmr::memory_resource *	mr = nullptr,
		bool	surplusAtOrigin = true )

Convert zeros / poles / gain to (SOS, gain) — the two-output form.

Same biquad structure as zp2sos but the gain is returned separately; the SOS matrix itself has no leading scale (each first-numerator coefficient b0 ≈ 1). This is the [sos, g] = zp2sos(…) form.

Parameters

zeros	Zeros of the filter.
poles	Poles of the filter.
gain	Overall scalar gain.
mr	Memory resource (nullptr → process default).

Returns

Tuple (sos, g). Apply via g * sosfilt(sos, x).

See also

zp2sos

Parameters

surplusAtOrigin

When #zeros < #poles, place the surplus zeros at the ORIGIN (true, MATLAB's zp2sos convention — empty biquad sections become [0 0 g]) or leave them at infinity (false — empty sections stay [g 0 0], used by tf2sos to reproduce the input b).

zp2ss()

std::tuple< Value, Value, Value, Value > nk::signal::zp2ss	(	const Value &	z,
		const Value &	p,
		double	k,
		std::pmr::memory_resource *	mr = nullptr )

Zero / pole / gain to state space (via zp2tf then tf2ss).

Parameters

z	Zeros (complex column vector).
p	Poles (complex column vector).
k	Scalar gain.
mr	Memory resource (nullptr → process default).

Returns

Tuple (A, B, C, D).