periodogram — Estimate power spectral density using a periodogram.
periodogram(x) estimates the power spectral density of a signal by windowing the full input and evaluating its DFT. Optional arguments select the analysis window, DFT length or explicit frequency grid, sampling frequency, frequency range, and spectrum scale.
Syntax
pxx = periodogram(x, window, nfft, fs, freqrange)
[pxx, f] = periodogram(x, window, nfft, fs, freqrange)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
x | NumericArray | Yes | — | Input signal vector or matrix with one signal per column. |
window | NumericArray | No | [] | Window vector. [] uses a rectangular window matching the signal length. |
nfft | NumericArray | No | [] | DFT length or explicit frequency vector. |
fs | NumericScalar | No | — | Sampling frequency in Hz. |
freqrange | StringScalar | No | — | Frequency range selector (`onesided`, `twosided`, or `centered`) and spectrum type (`psd` or `power`). |
Returns
| Name | Type | Description |
|---|---|---|
pxx | NumericArray | Power spectral density or power spectrum estimate. |
f | NumericArray | Frequency vector in radians/sample or Hz when fs is supplied. |
Returned values from periodogram depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:periodogram:ArgCount | The argument count is outside supported forms. | periodogram: expected periodogram(x, [window, [nfft_or_f, [fs, [freqrange_or_scale]]]]) |
RunMat:periodogram:InvalidSignal | Input signal is not a numeric vector or matrix. | periodogram: x must be a nonempty numeric vector or 2-D matrix |
RunMat:periodogram:InvalidWindow | Window input is invalid. | periodogram: window must be a finite real vector matching the signal length |
RunMat:periodogram:InvalidNfft | DFT length or frequency vector is invalid. | periodogram: nfft must be a positive integer or finite real frequency vector |
RunMat:periodogram:InvalidFs | Sampling frequency is invalid. | periodogram: fs must be a positive finite scalar |
RunMat:periodogram:InvalidRange | Frequency range selector or spectrum type is invalid. | periodogram: freqrange must be 'onesided', 'twosided', or 'centered'; spectrum type must be 'psd' or 'power' |
RunMat:periodogram:Internal | Output tensor construction fails internally. | periodogram: internal error |
How periodogram works
pxx = periodogram(x)returns a one-sided PSD estimate for real inputs and a two-sided estimate for complex inputs.- Matrix inputs are processed column-wise;
pxxhas one output column per input column. [pxx, f] = periodogram(...)also returns the frequency grid. Withoutfs, frequencies are in radians/sample; withfs, frequencies are in Hz. Passingfsas[]uses 1 Hz units.windowmust be a finite real vector matching the signal length.[]uses a rectangular window.nfftdefaults tomax(256, 2^nextpow2(length(x)))and controls the DFT grid. Ifnfftis shorter than the window, windowed samples are summed modulonfftbefore the DFT. A real frequency vector may be supplied in the same position to evaluate explicit frequencies.- The optional range selector accepts
'onesided','twosided', or'centered';'onesided'is valid only for real-valued signals. - The optional spectrum type accepts
'psd'(default) or'power';'power'reports power spectrum values using coherent-gain normalization. - Typed-integer signals and typed-integer numeric controls are separate RunMat extensions. Structural DFT lengths are decoded exactly; signals, windows, frequency grids, and sample rates must be exactly representable before entering the floating spectral domain.
Examples
PSD of a sine wave
fs = 1000;
t = (0:999) / fs;
x = sin(2*pi*100*t);
[pxx, f] = periodogram(x, [], 1024, fs);Use a Hamming window and power spectrum scaling
x = 1.8*cos(2*pi*(0:127)/16);
[pxx, f] = periodogram(x, hamming(128), 128, 'power');Two-sided complex spectrum
x = exp(1i*2*pi*(0:127)/16);
[pxx, w] = periodogram(x, [], 128, 'twosided');Column-wise spectra for a matrix
x = [sin(2*pi*(0:255)'/16), cos(2*pi*(0:255)'/32)];
[pxx, f] = periodogram(x, [], 256, 1000);Evaluate at explicit normalized frequencies
w = linspace(0, pi, 64);
[pxx, wout] = periodogram(randn(1,512), [], w);Using periodogram with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how periodogram changes the result.
Run a small periodogram example, explain the result, then change one input and compare the output.
FAQ
How is periodogram different from pwelch?⌄
periodogram estimates a spectrum from one windowed full-signal segment. pwelch splits the signal into overlapped segments and averages the modified periodograms.
Does periodogram include the Nyquist bin?⌄
For one-sided output and even nfft, yes. The output length is nfft/2 + 1, with DC first and the Nyquist bin last.
Does periodogram plot when no outputs are requested?⌄
RunMat currently returns values using normal output-count semantics instead of opening a plot. Use the returned pxx and frequency vector with plotting functions explicitly.
Related Math functions
Signal
blackman · butter · buttord · cheb2ord · conv · conv2 · deconv · downsample · envelope · filter · filtfilt · fir1 · freqz · gauspuls · hamming · hann · hilbert · pulstran · pwelch · rectpuls · resample · sawtooth · sinc · spectrogram · square · tripuls · unwrap · upsample · zplane
Elementwise
abs · angle · bsxfun · complex · conj · double · erf · erfcinv · exp · expm1 · factorial · flintmax · gamma · gammaln · heaviside · hypot · idivide · imag · intmax · intmin · ldivide · log · log10 · log1p · log2 · minus · nextpow2 · plus · pow2 · power · rdivide · real · realmax · realmin · realsqrt · rescale · sign · single · sqrt · swapbytes · times · typecast · uint16 · uint32 · uint8
Trigonometry
acos · acosh · asin · asinh · atan · atan2 · atanh · cos · cosd · cosh · cospi · deg2rad · pol2cart · rad2deg · sin · sind · sinh · sinpi · tan · tand · tanh
Reduction
all · any · bounds · cummax · cummin · cumprod · cumsum · cumtrapz · diff · gradient · max · maxk · mean · median · min · mink · movmax · movmean · movmedian · movmin · movprod · movstd · movsum · movvar · nnz · prod · rms · std · sum · trapz · var
Structure
bandwidth · isdiag · ishermitian · issymmetric · istril · istriu · symrcm
Optim
coneprog · fminbnd · fminunc · fsolve · fzero · integral · linprog · lsqcurvefit · lsqnonlin · optimoptions · optimset · quad · secondordercone
Ops
cross · ctranspose · dot · mldivide · mpower · mrdivide · mtimes · pagemtimes · pagetranspose · trace · transpose
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how periodogram is executed, line by line, in Rust.
- View the source for periodogram in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.