stft

function of dascore.transform.fourier

stft(
    patch: Patch ,
    taper_window: str | numpy.ndarray | tuple[str, ndarray, tuple[str, Any, …]] = hann,
    overlap: pint.registry.Quantity | int | None[Quantity, int, None] = 50 %,
    samples: bool = False,
    detrend: bool = False,
    **kwargs ,
)

Perform a short-time fourier transform.

Parameters

Parameter	Description
patch	The patch to transform.
taper_window	Parameter controlling the tapering of each time window before fourier transform. Can either be the name of the window to use, or an array, or a tuple of name and parameters passed to scipy.signal’s get_window function.
overlap	The overlap between windows. Can be a number (assumed to be in units of the transformed dimension if `samples`==False), a percent, or None for 0 overlap.
samples	If True, the window length (provided in kwargs) and overlap parameters are in samples (or explicit units).
detrend	If True, detrend each time window before performing fourier transform. This can lead to nicer looking spectrograms, but means the istft is no longer possible.
**kwargs	Used to specify window length in data units, percent, or samples.

Examples

from scipy.signal import get_window
import dascore as dc
from dascore.units import second, percent
patch = dc.get_example_patch("chirp", channel_count=2)

# Simple stft with 10 second window and 4 seconds overlap
pa1 = patch.stft(time=10*second, overlap=4*second)

# Same as above, but using a boxcar window and 10% overlap.
pa2 = patch.stft(time=10*second, taper_window="boxcar", overlap=10*percent)

# Using a custom window array and specifying window/overlap in samples.
window = get_window(("tukey", 0.1), 1000)
pa2 = patch.stft(time=1000, taper_window=window, overlap=100, samples=True)

Note

The output is scaled the same as Patch.dft. For a given sliding window, Parseval’s theorem doesn’t hold exactly (unless a boxcar window is used) because the taper window changes the time series signal before the transformation.
If an array is passed for taper_window that has a different length than specified in kwargs, artificial enriching of frequency resolution (equivalent to zero padding in time domain) can occur.

See Also

Patch.dft, Patch.istft