Fft Utility

Fourier-transform utility helpers.

This module provides reusable FFT helpers for one-dimensional signals used by analysis tasks and workflows. It handles common preprocessing choices such as detrending and windowing, and returns frequency-domain arrays ready for plotting or downstream feature extraction.

Function: detrend_signal

Remove low-order trends from a 1D signal.

Applies one of the supported detrending modes to prepare signal data for frequency-domain analysis.

Parameters:

Name	Type	Description	Default
signal	array - like	Input 1D signal.	required
mode	('none', 'mean', 'linear')	Detrending mode: - 'none': no detrending - 'mean': remove mean value - 'linear': remove best-fit linear trend	'none'

Returns:

Type	Description
ndarray	Detrended signal.

Examples:

>>> detrend_signal([1.0, 2.0, 3.0], mode="mean")
array([-1.,  0.,  1.])

Function: window_function

Build a 1D window function.

Constructs standard tapering windows used before FFT computation and also supports an optional Kaiser window path.

Parameters:

Name	Type	Description	Default
n	int	Number of samples.	required
name	('none', 'hann', 'hamming', 'blackman', 'bartlett')	Window type.	'none'
kaiser_beta	float	If provided and name == 'none', uses a Kaiser window with this beta. This allows optional tunable windowing without expanding the enum.	None

Returns:

Type	Description
ndarray	Window values with shape (n,).

Examples:

>>> window_function(8, name="hann")
array([...])

Function: fft_spectrum

Compute FFT spectrum for a uniformly sampled 1D signal.

Performs detrending, applies the selected window, computes FFT values, and returns common spectrum components for downstream analysis and plotting.

Parameters:

Name	Type	Description	Default
signal	array - like	Input time-domain signal.	required
dt	float	Sampling interval in time units.	required
detrend	('none', 'mean', 'linear')	Detrending mode before FFT.	'none'
window	('none', 'hann', 'hamming', 'blackman', 'bartlett')	Window function to apply before FFT.	'none'
kaiser_beta	float	Optional Kaiser beta parameter (used when window='none').	None
one_sided	bool	If True, return non-negative frequency part only.	True

Returns:

Type	Description
dict[str, ndarray]	Dictionary with keys: - 'freq': frequency axis - 'amplitude': amplitude spectrum - 'power': power spectrum (amplitude squared) - 'phase': phase angle (radians) - 'real': real FFT component - 'imag': imaginary FFT component

Notes

• For help, see numpy's documentation on numpy.fft and scipy.signal for windowing and detrending, which can be found at https://numpy.org/doc/2.2/reference/generated/numpy.fft.rfft.html
• An example can be found at https://hackmd.io/@cccccccc/S1DE042eO

Examples:

>>> fft_spectrum([0.0, 1.0, 0.0, -1.0], dt=0.1)
{'freq': array([...]), 'amplitude': array([...]), ...}

Function: dominant_frequency

Return dominant positive frequency of a 1D signal.

Computes a one-sided spectrum and selects the frequency with maximum amplitude among frequencies that satisfy freq >= min_freq.

Parameters:

Name	Type	Description	Default
signal	array - like	Input time-domain signal.	required
dt	float	Sampling interval in time units.	required
detrend	('none', 'mean', 'linear')	Detrending mode before FFT.	'none'
window	('none', 'hann', 'hamming', 'blackman', 'bartlett')	Window function to apply before FFT.	'none'
kaiser_beta	float	Optional Kaiser beta parameter (used when window='none').	None
min_freq	float	Minimum frequency threshold for candidate dominant frequency.	0.0

Returns:

Type	Description
float	Dominant frequency value.

Examples:

>>> dominant_frequency([0.0, 1.0, 0.0, -1.0], dt=0.1)
2.5