Written and maintained by CASRAI Editorial Board
Published
On this page
scipy.signal.welch estimates the power spectral density (PSD) of a sampled signal with Welch’s method: it divides the data into overlapping segments, computes a modified periodogram for each segment and averages them. You call f, Pxx = signal.welch(x, fs, nperseg=1024) and get back the sample frequencies f and the power estimate Pxx, in squared signal units per hertz by default.
What scipy.signal.welch is used for in research
Researchers use Welch’s method whenever a recording has to be summarised by how its power is spread across frequency: EEG and other physiological traces, accelerometer and vibration data, instrument noise, oscillating sensor readings. A single periodogram of a long, noisy record is a high-variance estimate. Averaging the periodograms of many overlapping segments trades some frequency resolution for a smoother, more stable estimate, which is the central design choice you make with nperseg. The SciPy reference cites P. Welch, IEEE Transactions on Audio and Electroacoustics, vol. 15, pp. 70-73, 1967, and M.S. Bartlett, Biometrika, vol. 37, pp. 1-16, 1950, for the method.
The function was added in SciPy 0.12.0. The same page lists csd (cross spectral density), periodogram and lombscargle (for unevenly sampled data) as related functions; the alternatives section below places them. For the wider scipy.signal module (filters, convolution, peak finding) see the scipy.signal guide; for the underlying transform see NumPy Fourier transforms.
How to install or access scipy.signal.welch
The function ships inside SciPy, so there is nothing separate to install. The official installation page gives two routes: python -m pip install scipy, or conda install scipy from conda-forge (the page recommends Miniforge for conda users). It also notes that system package managers often provide older versions, so check the version you have before relying on parameters described here.
- Install SciPy and NumPy with one of the commands above, ideally inside a virtual environment.
- Import the module:
from scipy import signal. - Confirm the call is available:
signal.welch. The signature in the SciPy 1.18.0 manual iswelch(x, fs=1.0, window='hann_periodic', nperseg=None, noverlap=None, nfft=None, detrend='constant', return_onesided=True, scaling='density', axis=-1, average='mean').
Older SciPy releases differ in details (the average argument was added in version 1.2.0, and the SciPy documentation versions its defaults), so read the manual that matches your installed version.
How to estimate a power spectral density with scipy.signal.welch step by step
The steps below use a worked example built on the one in the SciPy manual: a 1234 Hz sine wave of amplitude 2√2 V (RMS 2 V) plus Gaussian white noise, sampled at 10 kHz for 100,000 samples, with a known noise density of 0.001 V²/Hz. Because the true answer is known, you can check that the estimate is right.
- Generate or load the signal as a one-dimensional array and note the sampling frequency in hertz. The example uses
rng = np.random.default_rng(1234),fs = 10e3,N = 100000,time = np.arange(N) / fsandx = amp * np.sin(2*np.pi*freq*time) + rng.normal(scale=np.sqrt(noise_power), size=time.shape), wherenoise_power = 0.001 * fs / 2. - Call Welch’s method with the sampling rate and a segment length:
f, Pxx_den = signal.welch(x, fs, nperseg=1024). If you omitfsit defaults to 1.0 and the frequency axis is in cycles per sample. - Check the frequency grid. With
nperseg=1024the function returns 513 frequencies spaced 9.765625 Hz apart (fs / nperseg). The peak ofPxx_denfalls in the bin at 1230.47 Hz, the bin nearest the true 1234 Hz tone. - Check the noise floor. The mean of
Pxx_den[256:](the bins above about 2.5 kHz, away from the tone) is 0.0009998 V²/Hz in this run, which recovers the noise density of 0.001 V²/Hz that was put in. - For the amplitude of a tone, switch to a power spectrum with a flat-top window:
f, Pxx_spec = signal.welch(x, fs, 'flattop', 1024, scaling='spectrum'). The square root ofPxx_spec.max()is 2.0095 V in this run, close to the true RMS amplitude of 2 V (the SciPy manual’s own run reports 2.0077 V; the small difference is the random noise draw). - Plot with a logarithmic power axis, for example
plt.semilogy(f, Pxx_den)with matplotlib, and label the axes with units (V²/Hz for density, V² for spectrum).
What each parameter changes
The following table is taken from the SciPy 1.18.0 documentation of welch.
| Parameter | Default | Effect |
|---|---|---|
x |
required | The time series to analyse; the function works along axis (default -1). |
fs |
1.0 | Sampling frequency; sets the units of the returned frequencies. |
window |
‘hann_periodic’ | Taper applied to each segment; a string or tuple names a window, an array must have length nperseg. |
nperseg |
None | Samples per segment. If None and the window is a string or tuple it is 256; if the window is an array it is the window length. |
noverlap |
None | Samples shared between neighbouring segments. None means nperseg // 2; 0 gives Bartlett’s method. |
nfft |
None | Length of the FFT per segment. None means nperseg; a larger value zero-pads. |
detrend |
‘constant’ | Removes the mean of each segment; False disables it, and a callable can be supplied. |
return_onesided |
True | Returns the one-sided spectrum for real data; complex data always return a two-sided spectrum. |
scaling |
‘density’ | ‘density’ returns V²/Hz, ‘spectrum’ returns V². |
average |
‘mean’ | ‘mean’ or ‘median’ across segments; the median option was added in version 1.2.0. |
The documentation adds that for the default Hann window a 50% overlap is reasonable, while narrower windows may need more. The ratio between the ‘spectrum’ and ‘density’ scalings is sum(abs(window)**2) * fs / abs(sum(window))**2, which is why the two outputs of one call differ by a window-dependent constant rather than by a free choice of units.
Choosing nperseg
The frequency spacing of the output is fs / nperseg, so a longer segment gives finer resolution but fewer segments to average. The data table below shows this trade-off for the worked example: at nperseg=256 the spacing is 39.06 Hz and 780 segments are averaged; at 4096 it is 2.44 Hz and 47 segments are averaged. The noise-floor estimate stays near 0.001 V²/Hz throughout, but the more segments averaged, the smoother the curve you would plot.
How to read the output
f is a one-dimensional array of frequencies from 0 up to fs/2 (for real input with the default one-sided output), and Pxx has the same length along the frequency axis. With scaling='density', Pxx is a power spectral density: integrating it over a frequency band gives the power in that band, and white noise shows up as a flat floor whose height is the noise density. With scaling='spectrum', each bin is a power in V², so the square root of a peak height is the RMS amplitude of a tone that sits at the bin centre.
Two reading rules follow from the example. First, the peak frequency is only as exact as the grid: the tone at 1234 Hz is reported at 1230.47 Hz when the spacing is 9.77 Hz, and at 1235.35 Hz when nperseg=2048 (spacing 4.88 Hz). Second, use the density for broadband noise and the spectrum for narrow tones; reading a tone height off a density plot confuses the two units. For several channels, pass a 2-D array and set axis to the time axis rather than looping.
Troubleshooting scipy.signal.welch
The signal is shorter than 256 samples
With the default nperseg the segment length is 256, but when the data are shorter SciPy lowers it and issues a warning. Running signal.welch(x[:100], fs) on the example data returns 51 frequencies and the message “nperseg=256 is greater than signal length max(len(x), len(y)) = 100, using nperseg = 100” (SciPy 1.18.1). With one segment the call reduces to a single periodogram, so set nperseg explicitly and expect high variance.
A discontinuity or spike inflates the spectrum
The SciPy manual notes that a discontinuity can corrupt the mean average and that average='median' estimates the normal spectrum better. In a test that multiplies ten consecutive samples by 50, the mean-averaged noise floor above 2.5 kHz rises from 0.0010 to 0.00116 V²/Hz, while the median-averaged one stays at 0.00101 V²/Hz.
The spectrum looks smeared or the peak is in the wrong place
Check fs first: forgetting it leaves the default 1.0 and the axis in cycles per sample. Then check resolution (fs / nperseg). Raising nfft above nperseg only zero-pads each segment and interpolates the plot; it does not add resolving power.
The amplitude is not what you expected
The two scalings differ by the window-dependent ratio given above, and a tone that falls between bins loses height with some windows. The documentation’s amplitude example uses the flat-top window for that reason. Match the scaling to the question: PSD for noise, spectrum for tone amplitude.
The window array has the wrong length
When window is an array its length must equal nperseg. Passing a named window (‘hann’, ‘flattop’) avoids the mismatch.
Free alternatives to scipy.signal.welch
SciPy offers three neighbouring functions, described in its own documentation. MATLAB users will find the equivalent pwelch covered in the MATLAB signal analysis guide; time-resolved spectra are covered in short-time Fourier transform.
| Function | What it does | Choose it when |
|---|---|---|
scipy.signal.periodogram |
Computes a simple periodogram of the whole record. | You want the raw, single-window estimate without segment averaging. |
scipy.signal.csd |
Estimates the cross power spectral density Pxy of two signals using Welch’s method. | You need the frequency-domain relationship between two channels. |
scipy.signal.lombscargle |
Listed under ‘See also’ for unevenly sampled data. | Your samples are not evenly spaced in time. |
All three ship with SciPy, so no further install is needed. The SciPy User Guide’s spectral-analysis section explains the windowing trade-off underlying all of them: multiplying by a window suppresses side lobes at the cost of a wider main lobe.
Sources
- SciPy v1.18.0 Manual: scipy.signal.welch, checked 2026-11-17
- SciPy v1.18.0 Manual: scipy.signal.periodogram, checked 2026-11-17
- SciPy v1.18.0 Manual: scipy.signal.csd, checked 2026-11-17
- SciPy v1.18.0 Manual: Signal Processing (scipy.signal) user guide, checked 2026-11-17
- SciPy: Installation, checked 2026-11-17
- NumPy Manual: Random Generator (numpy.random.default_rng), checked 2026-11-17
Data: Welch segment length vs frequency resolution, segments averaged and noise-floor estimate (worked example)
Computed by running scipy.signal.welch (SciPy 1.18.1, Hann window, default 50% overlap) on a 10 kHz, 100,000-sample test signal: a 1234 Hz sine (RMS 2 V) plus white noise of density 0.001 V^2/Hz, generated with numpy default_rng(1234). Frequency spacing is fs/nperseg per the SciPy documentation; the other columns are measured outputs of the run. The mean noise floor uses bins above 2.5 kHz.
| nperseg | Frequency spacing (Hz) | Frequency bins returned | Segments averaged | Peak bin frequency (Hz) | Mean noise density above 2.5 kHz (V^2/Hz) |
|---|---|---|---|---|---|
| 256 | 39.0625 | 129 | 780 | 1250 | 0.000995 |
| 512 | 19.53125 | 257 | 389 | 1230.469 | 0.000999 |
| 1024 | 9.765625 | 513 | 194 | 1230.469 | 0.001 |
| 2048 | 4.8828125 | 1025 | 96 | 1235.352 | 0.001005 |
| 4096 | 2.44140625 | 2049 | 47 | 1232.91 | 0.000999 |
Sources
- SciPy v1.18.0 Manual: scipy.signal.welch (accessed 2026-11-17)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







