psd
Builtin index · Signal processing
result = psd(x, [fs], [window="hann"], [nfft=min(256,len(x))], [overlap=0.5])
Input: x, fs, window, nfft, overlap · Output: result
What it is
x: a length-N real vector or Signal; fs (number, Hz) — required, or carried by a Signal. nfft (optional number): the segment length — the same meaning spectrogram/stft give nfft in this engine, *not* SciPy's zero-padded transform length. overlap (optional number): segment overlap as a fraction in [0, 1) — 0.5 is 50%, where welch's noverlap= is an absolute sample count. window (optional string, as for welch).
Overloads
One call shape — this function is not overloaded.
| Code | Input | Output | Description |
result = psd(x, [fs], [window="hann"], [nfft=min(256,len(x))], [overlap=0.5]) | x vector or Signalx: a length-N real vector or Signal.fs number or Signal, optionalfs (number, Hz) — required, or carried by a Signal.window string, optional (default "hann")window (optional string, as for welch).nfft number, optional (default min(256,len(x)))nfft (optional number): the segment length — the same meaning spectrogram/stft give nfft in this engine, *not* SciPy's zero-padded transform length.overlap number, optional (default 0.5)overlap (optional number): segment overlap as a fraction in [0, 1) — 0.5 is 50%, where welch's noverlap= is an absolute sample count. | result vector or string | Returns a spectrum of nfft/2 + 1 one-sided bins stamped norm = "density", the Welch PSD in SciPy's "density" scaling, exactly as welch does — literally the same code path, so psd(x, fs) and welch(x, fs) stay bit-identical and the defaults are chosen to keep that true. Changed in v0.2.4 from a bare vector, back-compatibly: it now carries its own frequency axis (P.freq, P.df), which is what toolkit-signal.md §2 asks for. The scaling is a typed tag, not a unit string. §2 sketches a P.unit of V^2/Hz; the engine still has no derived/compound unit algebra to propagate a per-hertz density through arithmetic, so what is recorded is the *convention* (norm = "density"), which the engine does enforce — ifft and spectrum_unnormalize refuse a density, and band_power integrates it correctly — rather than a label it could not. |
Examples
No documentation example calls this form yet. The Signal processing chapter is where one belongs.
How it works
psd(x, [fs], [window="hann"], [nfft=min(256,len(x))], [overlap=0.5]) — toolkit-signal.md §2's Welch PSD, which is welch above under the spec's own parameter spelling. Deliberately the SAME code path (numeric::transforms::welch called directly, not the welch builtin re-dispatched), so the two cannot drift: psd(x, fs) and welch(x, fs) return bit-identical vectors, and the defaults below are chosen to keep that true (nfft defaults to welch's own nperseg default, and overlap=0.5 lands exactly on its nperseg/2). overlap is a FRACTION (0.5 = 50%), where welch's noverlap is an absolute sample count. Both spellings stay: welch is SciPy's, and a reader porting a SciPy script should not have to convert; overlap is the spec's, and is the one that does not silently change meaning when nfft changes. nfft means the segment length, matching spectrogram/stft's own nfft in this codebase (NOT a zero-padded transform length, which is what the name means in SciPy — flagged here because the collision is real and a reader who assumes SciPy's meaning gets a resolution they did not ask for). NO UNITS ON THE RESULT, despite toolkit-signal.md §2 claiming "P.unit really is V^2/Hz". Returns a plain Value::Vec, exactly as welch does. The units feature this repo actually has is simple named scalars (unit ppm = 1e-6); there is no derived/compound unit algebra for a per-hertz density, and Value::Spectrum is not it either — its SpectrumNorm enumerates the three conventions that make sense for a scaled DFT bin, not a density. Stamping a unit the engine cannot then propagate would be a label, not a guarantee. The scaling is documented instead, and the axis is linspace(0, fs/2, length(p)) as for welch.
From the note above this builtin in the interpreter, where the reasoning was written down as it was built.