sgdZddlmZddlmZddlmZmZmZddl m Z m Z m Z ddl ZddlmZddlmZddlmZd gZe d Ze d Zdd ZGd d Zy)z=Implementation of an FFT-based Short-time Fourier Transform. ) annotations) Generator)cache lru_cachepartial)Callableget_argsLiteralN)detrend get_window ShortTimeFFTzerosedgeevenodd)twosidedcenteredonesided onesided2Xc|t|kDrtd|dt|dzt|jjt j rtdd|jdz|jdz|jdzz}|j}t|t||D]&}||dxxx|d| z ccc|d| xxx||dz ccc(t j|jjt|z}t j||k\s td||z S) aCalculate canonical dual window for 1d window `win` and a time step of `hop` samples. A ``ValueError`` is raised, if the inversion fails. This is a separate function not a method, since it is also used in the class method ``ShortTimeFFT.from_dual()``. zhop=z! is larger than window length of z => STFT not invertible!z/Parameter 'win' cannot be of integer type, but z win.dtype=Nz,Short-time Fourier Transform not invertible!)len ValueError issubclassdtypetypenpintegerrealimagcopyrangefinfo resolutionmaxall)winhopw2DDk_relative_resolutions O/var/www/html/venv/lib/python3.12/site-packages/scipy/signal/_short_time_fft.py_calc_dual_canonical_windowr0+s5 SX~DC6!B3s8*M345 5#)).."**-J&CII<'?@AB B 1sxx{ "B BCS3' 232ds8 4RCBrsG ((399-883r7B 66"++ ,GHH 8OceZdZUdZded<dZded<ded<d ed <d Zd ed <ded<dZded<ded<dZded<dZ ded<dZ ded<d ddddd dVdZ e d dddd dWdZ e dd dddd dXdZedYd ZedZd!Zed[d"Zej&d\d#Zed[d$Zej&d\d%Zed]d&Zej&d^d'ZedZd(Zej&d_d)Zed`d*Zdad+Zedbd,Zej&dcd-Z ddd.Z dedd/d0d1 dfd2Z dedd/d0d1 dgd3Z dedddd/d0d4 dhd5ZedYd6Zedid7Zdjd8d0d9 dkd:Z ed[d;Z!ed[d<Z"edZd=Z#edZd>Z$e%dld?Z&edZd@Z'edZdAZ(e)dBCdmdDZ*dndEZ+dndFZ,dndGZ-edldHZ.e)dBCdmdIZ/ed[dJZ0 de dodKZ1e)dLC dp dqdMZ2drdsdNZ3ed[dOZ4edZdPZ5edidQZ6edYdRZ7dtdSZ8dudTZ9 dv dwdUZ:y)xraProvide a parametrized discrete Short-time Fourier transform (stft) and its inverse (istft). .. currentmodule:: scipy.signal.ShortTimeFFT The `~ShortTimeFFT.stft` calculates sequential FFTs by sliding a window (`win`) over an input signal by `hop` increments. It can be used to quantify the change of the spectrum over time. The `~ShortTimeFFT.stft` is represented by a complex-valued matrix S[q,p] where the p-th column represents an FFT with the window centered at the time t[p] = p * `delta_t` = p * `hop` * `T` where `T` is the sampling interval of the input signal. The q-th row represents the values at the frequency f[q] = q * `delta_f` with `delta_f` = 1 / (`mfft` * `T`) being the bin width of the FFT. The inverse STFT `~ShortTimeFFT.istft` is calculated by reversing the steps of the STFT: Take the IFFT of the p-th slice of S[q,p] and multiply the result with the so-called dual window (see `dual_win`). Shift the result by p * `delta_t` and add the result to previous shifted results to reconstruct the signal. If only the dual window is known and the STFT is invertible, `from_dual` can be used to instantiate this class. Due to the convention of time t = 0 being at the first sample of the input signal, the STFT values typically have negative time slots. Hence, negative indexes like `p_min` or `k_min` do not indicate counting backwards from an array's end like in standard Python indexing but being left of t = 0. More detailed information can be found in the :ref:`tutorial_stft` section of the :ref:`user_guide`. Note that all parameters of the initializer, except `scale_to` (which uses `scaling`) have identical named attributes. Parameters ---------- win : np.ndarray The window must be a real- or complex-valued 1d array. hop : int The increment in samples, by which the window is shifted in each step. fs : float Sampling frequency of input signal and window. Its relation to the sampling interval `T` is ``T = 1 / fs``. fft_mode : 'twosided', 'centered', 'onesided', 'onesided2X' Mode of FFT to be used (default 'onesided'). See property `fft_mode` for details. mfft: int | None Length of the FFT used, if a zero padded FFT is desired. If ``None`` (default), the length of the window `win` is used. dual_win : np.ndarray | None The dual window of `win`. If set to ``None``, it is calculated if needed. scale_to : 'magnitude', 'psd' | None If not ``None`` (default) the window function is scaled, so each STFT column represents either a 'magnitude' or a power spectral density ('psd') spectrum. This parameter sets the property `scaling` to the same value. See method `scale_to` for details. phase_shift : int | None If set, add a linear phase `phase_shift` / `mfft` * `f` to each frequency `f`. The default value 0 ensures that there is no phase shift on the zeroth slice (in which t=0 is centered). See property `phase_shift` for more details. Examples -------- The following example shows the magnitude of the STFT of a sine with varying frequency :math:`f_i(t)` (marked by a red dashed line in the plot): >>> import numpy as np >>> import matplotlib.pyplot as plt >>> from scipy.signal import ShortTimeFFT >>> from scipy.signal.windows import gaussian ... >>> T_x, N = 1 / 20, 1000 # 20 Hz sampling rate for 50 s signal >>> t_x = np.arange(N) * T_x # time indexes for signal >>> f_i = 1 * np.arctan((t_x - t_x[N // 2]) / 2) + 5 # varying frequency >>> x = np.sin(2*np.pi*np.cumsum(f_i)*T_x) # the signal The utilized Gaussian window is 50 samples or 2.5 s long. The parameter ``mfft=200`` in `ShortTimeFFT` causes the spectrum to be oversampled by a factor of 4: >>> g_std = 8 # standard deviation for Gaussian window in samples >>> w = gaussian(50, std=g_std, sym=True) # symmetric Gaussian window >>> SFT = ShortTimeFFT(w, hop=10, fs=1/T_x, mfft=200, scale_to='magnitude') >>> Sx = SFT.stft(x) # perform the STFT In the plot, the time extent of the signal `x` is marked by vertical dashed lines. Note that the SFT produces values outside the time range of `x`. The shaded areas on the left and the right indicate border effects caused by the window slices in that area not fully being inside time range of `x`: >>> fig1, ax1 = plt.subplots(figsize=(6., 4.)) # enlarge plot a bit >>> t_lo, t_hi = SFT.extent(N)[:2] # time range of plot >>> ax1.set_title(rf"STFT ({SFT.m_num*SFT.T:g}$\,s$ Gaussian window, " + ... rf"$\sigma_t={g_std*SFT.T}\,$s)") >>> ax1.set(xlabel=f"Time $t$ in seconds ({SFT.p_num(N)} slices, " + ... rf"$\Delta t = {SFT.delta_t:g}\,$s)", ... ylabel=f"Freq. $f$ in Hz ({SFT.f_pts} bins, " + ... rf"$\Delta f = {SFT.delta_f:g}\,$Hz)", ... xlim=(t_lo, t_hi)) ... >>> im1 = ax1.imshow(abs(Sx), origin='lower', aspect='auto', ... extent=SFT.extent(N), cmap='viridis') >>> ax1.plot(t_x, f_i, 'r--', alpha=.5, label='$f_i(t)$') >>> fig1.colorbar(im1, label="Magnitude $|S_x(t, f)|$") ... >>> # Shade areas where window slices stick out to the side: >>> for t0_, t1_ in [(t_lo, SFT.lower_border_end[0] * SFT.T), ... (SFT.upper_border_begin(N)[0] * SFT.T, t_hi)]: ... ax1.axvspan(t0_, t1_, color='w', linewidth=0, alpha=.2) >>> for t_ in [0, N * SFT.T]: # mark signal borders with vertical line: ... ax1.axvline(t_, color='y', linestyle='--', alpha=0.5) >>> ax1.legend() >>> fig1.tight_layout() >>> plt.show() Reconstructing the signal with the `~ShortTimeFFT.istft` is straightforward, but note that the length of `x1` should be specified, since the SFT length increases in `hop` steps: >>> SFT.invertible # check if invertible True >>> x1 = SFT.istft(Sx, k1=N) >>> np.allclose(x, x1) True It is possible to calculate the SFT of signal parts: >>> p_q = SFT.nearest_k_p(N // 2) >>> Sx0 = SFT.stft(x[:p_q]) >>> Sx1 = SFT.stft(x[p_q:]) When assembling sequential STFT parts together, the overlap needs to be considered: >>> p0_ub = SFT.upper_border_begin(p_q)[1] - SFT.p_min >>> p1_le = SFT.lower_border_end[1] - SFT.p_min >>> Sx01 = np.hstack((Sx0[:, :p0_ub], ... Sx0[:, p0_ub:] + Sx1[:, :p1_le], ... Sx1[:, p1_le:])) >>> np.allclose(Sx01, Sx) # Compare with SFT of complete signal True It is also possible to calculate the `itsft` for signal parts: >>> y_p = SFT.istft(Sx, N//3, N//2) >>> np.allclose(y_p, x[N//3:N//2]) True np.ndarray_winNnp.ndarray | None _dual_winint_hopfloat_fsr FFT_MODE_TYPE _fft_mode_mfft"Literal['magnitude', 'psd'] | None_scaling int | None _phase_shiftz float | None_fac_mag_fac_psdztuple[int, int] | None_lower_border_endr)fft_modemfftdual_winscale_to phase_shiftc|jdk(r|jdkDstd|jdt t j |s td|dk\rt|tstd|d|||c|_ |_ |_ | t|n||_ |h|j|jk7r&td|jd |jdt t j |s td ||_||j|||c|_|_y) Nrz(Parameter win must be 1d, but win.shape=!z'Parameter win must have finite entries!zParameter hop=z is not an integer >= 1!zdual_win.shape=z must equal win.shape=z*Parameter dual_win must be a finite array!)ndimsizershaper(risfinite isinstancer7r4r8fsrrFr6rHrErI) selfr)r*rRrErFrGrHrIs r/__init__zShortTimeFFT.__init__s A #((Q,Hcii\KL L2;;s#$FG GqZS1#/GHI I(+S"% 49dg $ CH$  ~~* OHNN#44K A!NOOr{{8,- !MNN!   MM( #*2K' t'r1)rErFrHrIc :t||}|||||||||S)a Instantiate a `ShortTimeFFT` by only providing a dual window. If an STFT is invertible, it is possible to calculate the window `win` from a given dual window `dual_win`. All other parameters have the same meaning as in the initializer of `ShortTimeFFT`. As explained in the :ref:`tutorial_stft` section of the :ref:`user_guide`, an invertible STFT can be interpreted as series expansion of time-shifted and frequency modulated dual windows. E.g., the series coefficient S[q,p] belongs to the term, which shifted `dual_win` by p * `delta_t` and multiplied it by exp( 2 * j * pi * t * q * `delta_f`). Examples -------- The following example discusses decomposing a signal into time- and frequency-shifted Gaussians. A Gaussian with standard deviation of one made up of 51 samples will be used: >>> import numpy as np >>> import matplotlib.pyplot as plt >>> from scipy.signal import ShortTimeFFT >>> from scipy.signal.windows import gaussian ... >>> T, N = 0.1, 51 >>> d_win = gaussian(N, std=1/T, sym=True) # symmetric Gaussian window >>> t = T * (np.arange(N) - N//2) ... >>> fg1, ax1 = plt.subplots() >>> ax1.set_title(r"Dual Window: Gaussian with $\sigma_t=1$") >>> ax1.set(xlabel=f"Time $t$ in seconds ({N} samples, $T={T}$ s)", ... xlim=(t[0], t[-1]), ylim=(0, 1.1*max(d_win))) >>> ax1.plot(t, d_win, 'C0-') The following plot with the overlap of 41, 11 and 2 samples show how the `hop` interval affects the shape of the window `win`: >>> fig2, axx = plt.subplots(3, 1, sharex='all') ... >>> axx[0].set_title(r"Windows for hop$\in\{10, 40, 49\}$") >>> for c_, h_ in enumerate([10, 40, 49]): ... SFT = ShortTimeFFT.from_dual(d_win, h_, 1/T) ... axx[c_].plot(t + h_ * T, SFT.win, 'k--', alpha=.3, label=None) ... axx[c_].plot(t - h_ * T, SFT.win, 'k:', alpha=.3, label=None) ... axx[c_].plot(t, SFT.win, f'C{c_+1}', ... label=r"$\Delta t=%0.1f\,$s" % SFT.delta_t) ... axx[c_].set_ylim(0, 1.1*max(SFT.win)) ... axx[c_].legend(loc='center') >>> axx[-1].set(xlabel=f"Time $t$ in seconds ({N} samples, $T={T}$ s)", ... xlim=(t[0], t[-1])) >>> plt.show() Beside the window `win` centered at t = 0 the previous (t = -`delta_t`) and following window (t = `delta_t`) are depicted. It can be seen that for small `hop` intervals, the window is compact and smooth, having a good time-frequency concentration in the STFT. For the large `hop` interval of 4.9 s, the window has small values around t = 0, which are not covered by the overlap of the adjacent windows, which could lead to numeric inaccuracies. Furthermore, the peaky shape at the beginning and the end of the window points to a higher bandwidth, resulting in a poorer time-frequency resolution of the STFT. Hence, the choice of the `hop` interval will be a compromise between a time-frequency resolution and memory requirements demanded by small `hop` sizes. See Also -------- from_window: Create instance by wrapping `get_window`. ShortTimeFFT: Create instance using standard initializer. )r)r*rRrErFrGrHrI)r0) clsrGr*rRrErFrHrIr)s r/ from_dualzShortTimeFFT.from_duals0Z*(C8sXD$x*, ,r1F) symmetric_winrErFrHrIc Dt||| } || ||z ||||| S)a Instantiate `ShortTimeFFT` by using `get_window`. The method `get_window` is used to create a window of length `nperseg`. The parameter names `noverlap`, and `nperseg` are used here, since they more inline with other classical STFT libraries. Parameters ---------- win_param: Union[str, tuple, float], Parameters passed to `get_window`. For windows with no parameters, it may be a string (e.g., ``'hann'``), for parametrized windows a tuple, (e.g., ``('gaussian', 2.)``) or a single float specifying the shape parameter of a kaiser window (i.e. ``4.`` and ``('kaiser', 4.)`` are equal. See `get_window` for more details. fs : float Sampling frequency of input signal. Its relation to the sampling interval `T` is ``T = 1 / fs``. nperseg: int Window length in samples, which corresponds to the `m_num`. noverlap: int Window overlap in samples. It relates to the `hop` increment by ``hop = npsereg - noverlap``. symmetric_win: bool If ``True`` then a symmetric window is generated, else a periodic window is generated (default). Though symmetric windows seem for most applications to be more sensible, the default of a periodic windows was chosen to correspond to the default of `get_window`. fft_mode : 'twosided', 'centered', 'onesided', 'onesided2X' Mode of FFT to be used (default 'onesided'). See property `fft_mode` for details. mfft: int | None Length of the FFT used, if a zero padded FFT is desired. If ``None`` (default), the length of the window `win` is used. scale_to : 'magnitude', 'psd' | None If not ``None`` (default) the window function is scaled, so each STFT column represents either a 'magnitude' or a power spectral density ('psd') spectrum. This parameter sets the property `scaling` to the same value. See method `scale_to` for details. phase_shift : int | None If set, add a linear phase `phase_shift` / `mfft` * `f` to each frequency `f`. The default value 0 ensures that there is no phase shift on the zeroth slice (in which t=0 is centered). See property `phase_shift` for more details. Examples -------- The following instances ``SFT0`` and ``SFT1`` are equivalent: >>> from scipy.signal import ShortTimeFFT, get_window >>> nperseg = 9 # window length >>> w = get_window(('gaussian', 2.), nperseg) >>> fs = 128 # sampling frequency >>> hop = 3 # increment of STFT time slice >>> SFT0 = ShortTimeFFT(w, hop, fs=fs) >>> SFT1 = ShortTimeFFT.from_window(('gaussian', 2.), fs, nperseg, ... noverlap=nperseg-hop) See Also -------- scipy.signal.get_window: Return a window of a given length and type. from_dual: Create instance using dual window. ShortTimeFFT: Create instance using standard initializer. )fftbins)r*rRrErFrHrIr ) rV win_paramrRnpersegnoverlaprXrErFrHrIr)s r/ from_windowzShortTimeFFT.from_windowgs9NG5FG3GH,hx[J Jr1c|jS)a8Window function as real- or complex-valued 1d array. This attribute is read only, since `dual_win` depends on it. See Also -------- dual_win: Canonical dual window. m_num: Number of samples in window `win`. m_num_mid: Center index of window `win`. mfft: Length of input for the FFT used - may be larger than `m_num`. hop: ime increment in signal samples for sliding window. win: Window function as real- or complex-valued 1d array. ShortTimeFFT: Class this property belongs to. )r4rSs r/r)zShortTimeFFT.win yyr1c|jS)aBTime increment in signal samples for sliding window. This attribute is read only, since `dual_win` depends on it. See Also -------- delta_t: Time increment of STFT (``hop*T``) m_num: Number of samples in window `win`. m_num_mid: Center index of window `win`. mfft: Length of input for the FFT used - may be larger than `m_num`. T: Sampling interval of input signal and of the window. win: Window function as real- or complex-valued 1d array. ShortTimeFFT: Class this property belongs to. )r8r`s r/r*zShortTimeFFT.hoprar1c d|jz S)aSampling interval of input signal and of the window. A ``ValueError`` is raised if it is set to a non-positive value. See Also -------- delta_t: Time increment of STFT (``hop*T``) hop: Time increment in signal samples for sliding window. fs: Sampling frequency (being ``1/T``) t: Times of STFT for an input signal with `n` samples. ShortTimeFFT: Class this property belongs to. rKr:r`s r/TzShortTimeFFT.Ts488|r1c@|dkDstd|dd|z |_y)zSampling interval of input signal and of the window. A ``ValueError`` is raised if it is set to a non-positive value. rzSampling interval T= must be positive!rKNrr:rSvs r/rezShortTimeFFT.Ts, A3A36HIJ Jq5r1c|jS)aSampling frequency of input signal and of the window. The sampling frequency is the inverse of the sampling interval `T`. A ``ValueError`` is raised if it is set to a non-positive value. See Also -------- delta_t: Time increment of STFT (``hop*T``) hop: Time increment in signal samples for sliding window. T: Sampling interval of input signal and of the window (``1/fs``). ShortTimeFFT: Class this property belongs to. rdr`s r/rRzShortTimeFFT.fss xxr1c:|dkDstd|d||_y)zSampling frequency of input signal and of the window. The sampling frequency is the inverse of the sampling interval `T`. A ``ValueError`` is raised if it is set to a non-positive value. rzSampling frequency fs=rgNrhris r/rRzShortTimeFFT.fss(A5aS8JKL Lr1c|jS)aMode of utilized FFT ('twosided', 'centered', 'onesided' or 'onesided2X'). It can have the following values: 'twosided': Two-sided FFT, where values for the negative frequencies are in upper half of the array. Corresponds to :func:`~scipy.fft.fft()`. 'centered': Two-sided FFT with the values being ordered along monotonically increasing frequencies. Corresponds to applying :func:`~scipy.fft.fftshift()` to :func:`~scipy.fft.fft()`. 'onesided': Calculates only values for non-negative frequency values. Corresponds to :func:`~scipy.fft.rfft()`. 'onesided2X': Like `onesided`, but the non-zero frequencies are doubled if `scaling` is set to 'magnitude' or multiplied by ``sqrt(2)`` if set to 'psd'. If `scaling` is ``None``, setting `fft_mode` to `onesided2X` is not allowed. If the FFT length `mfft` is even, the last FFT value is not paired, and thus it is not scaled. Note that `onesided` and `onesided2X` do not work for complex-valued signals or complex-valued windows. Furthermore, the frequency values can be obtained by reading the `f` property, and the number of samples by accessing the `f_pts` property. See Also -------- delta_f: Width of the frequency bins of the STFT. f: Frequencies values of the STFT. f_pts: Width of the frequency bins of the STFT. onesided_fft: True if a one-sided FFT is used. scaling: Normalization applied to the window function ShortTimeFFT: Class this property belongs to. )r<r`s r/rEzShortTimeFFT.fft_mode sN~~r1c|ttx}vrtd|d|d|dvr1tj|j rtd|ddz|dk(r|j td |d ||_y ) zSet mode of FFT. Allowed values are 'twosided', 'centered', 'onesided', 'onesided2X'. See the property `fft_mode` for more details. z fft_mode='z ' not in rLrrz#One-sided spectra, i.e., fft_mode='z', z+are not allowed for complex-valued windows!rNzFor scaling is None, fft_mode='z9' is invalid!Do scale_to('psd') or scale_to('magnitude')!)r r;rr iscomplexobjr)scalingr<)rStfft_mode_typess r/rEzShortTimeFFT.fft_mode4s x '>>^ ?z!In5EQGH H * *rtxx/HB1#SIJKL L !5>qcBLLM Mr1c|jS)aLength of input for the FFT used - may be larger than window length `m_num`. If not set, `mfft` defaults to the window length `m_num`. See Also -------- f_pts: Number of points along the frequency axis. f: Frequencies values of the STFT. m_num: Number of samples in window `win`. ShortTimeFFT: Class this property belongs to. )r=r`s r/rFzShortTimeFFT.mfftGszzr1cp||jk\s td|dd|jdz||_y)zeSetter for the length of FFT utilized. See the property `mfft` for further details. zAttribute mfft=z needs to be at least the zwindow length m_num=rLN)m_numrr=)rSn_s r/rFzShortTimeFFT.mfftWsH djj rd2LM3DJJ Bz.1ACD D ==G #  '5 0 d6H6HII% >> %!^^e3DN'1$ t} r1c|jS)aIf set, add linear phase `phase_shift` / `mfft` * `f` to each FFT slice of frequency `f`. Shifting (more precisely `rolling`) an `mfft`-point FFT input by `phase_shift` samples results in a multiplication of the output by ``np.exp(2j*np.pi*q*phase_shift/mfft)`` at the frequency q * `delta_f`. The default value 0 ensures that there is no phase shift on the zeroth slice (in which t=0 is centered). No phase shift (``phase_shift is None``) is equivalent to ``phase_shift = -mfft//2``. In this case slices are not shifted before calculating the FFT. The absolute value of `phase_shift` is limited to be less than `mfft`. See Also -------- delta_f: Width of the frequency bins of the STFT. f: Frequencies values of the STFT. mfft: Length of input for the FFT used ShortTimeFFT: Class this property belongs to. )rAr`s r/rIzShortTimeFFT.phase_shifts0   r1c|||_yt|tstd|ddz|j |cxkr|jks!ntdd|jd|dz||_y) zThe absolute value of the phase shift needs to be less than mfft samples. See the `phase_shift` getter method for more details. Nz phase_shift=z has the unit samples. Hence z(it needs to be an int or it may be None!z)-mfft < phase_shift < mfft does not hold z for mfft=z, phase_shift=rL)rArQr7rrFris r/rIzShortTimeFFT.phase_shifts 9 !D  !S!|A3.KLGHI I Q**H( >!AFGH Hr1c#K|ttx}vrtd|d|dtddtdtd d td d d }|jd||z |j z} }||j z|j z |z} | | z|jz} t| dt| |} } dg|jdz zt| d t| |z dfgz}tj|d| | f|fi||}td| |j D]}|d|||jzfyw)zGenerate signal slices along last axis of `x`. This method is only used by `stft_detrend`. The parameters are described in `~ShortTimeFFT.stft`. zParameter padding=r|rLconstantrr)modeconstant_valuesr)rreflectr)r reflect_typerrrrK.N)r PAD_TYPErdictrOr* m_num_midrvr'minrMrpadr$)rSxk_offp0p1padding padding_typespad_kwsnn1k0k1i0i1 pad_widthx1r-s r/ _x_sliceszShortTimeFFT._x_slicessV HX,>>= ?2'8M?!LM Mz6Bf%if=YU; $  b2g12 $((]T^^ +e 3 "Wtzz !RSQZBHq)s2qzk3rAvq>-J,KK VVAc2b5jM9 A0@ A2txx( .BS"R$**_,,- - .sE E rrk_offsetraxisc 2|j|d|||||S)a{ Perform the short-time Fourier transform. A two-dimensional matrix with ``p1-p0`` columns is calculated. The `f_pts` rows represent value at the frequencies `f`. The q-th column of the windowed FFT with the window `win` is centered at t[q]. The columns represent the values at the frequencies `f`. Parameters ---------- x The input signal as real or complex valued array. For complex values, the property `fft_mode` must be set to 'twosided' or 'centered'. p0 The first element of the range of slices to calculate. If ``None`` then it is set to :attr:`p_min`, which is the smallest possible slice. p1 The end of the array. If ``None`` then `p_max(n)` is used. k_offset Index of first sample (t = 0) in `x`. padding Kind of values which are added, when the sliding window sticks out on either the lower or upper end of the input `x`. Zeros are added if the default 'zeros' is set. For 'edge' either the first or the last value of `x` is used. 'even' pads by reflecting the signal on the first or last sample and 'odd' additionally multiplies it with -1. axis The axis of `x` over which to compute the STFT. If not given, the last axis is used. Returns ------- S A complex array is returned with the dimension always being larger by one than of `x`. The last axis always represent the time slices of the STFT. `axis` defines the frequency axis (default second to last). E.g., for a one-dimensional `x`, a complex 2d array is returned, with axis 0 representing frequency and axis 1 the time slices. See Also -------- delta_f: Width of the frequency bins of the STFT. delta_t: Time increment of STFT f: Frequencies values of the STFT. invertible: Check if STFT is invertible. :meth:`~ShortTimeFFT.istft`: Inverse short-time Fourier transform. p_range: Determine and validate slice index range. stft_detrend: STFT with detrended segments. t: Times of STFT for an input signal with `n` samples. :class:`scipy.signal.ShortTimeFFT`: Class this method belongs to. Nr) stft_detrend)rSrrrrrrs r/stftzShortTimeFFT.stfts,r  D"b8)0t!= =r1c |jr.tj|rtd|jdt |t rtt|}n|t|std|ddz|j|}||j|jz x} k\s@|jdk(rd t|nd |d |j} t| d | d |jdkDrtj||d}|j!|||\}}|j"||z f} |jdkDr|jdd| zn| } tj$| t&} t)|j+|||||D]C\}}|||}|j-||j.j1z| ddd|f<E|jdkDr%tj| d|dk\r|S|dz S| S)aShort-time Fourier transform with a trend being subtracted from each segment beforehand. If `detr` is set to 'constant', the mean is subtracted, if set to "linear", the linear trend is removed. This is achieved by calling :func:`scipy.signal.detrend`. If `detr` is a function, `detr` is applied to each segment. All other parameters have the same meaning as in `~ShortTimeFFT.stft`. Note that due to the detrending, the original signal cannot be reconstructed by the `~ShortTimeFFT.istft`. See Also -------- invertible: Check if STFT is invertible. :meth:`~ShortTimeFFT.istft`: Inverse short-time Fourier transform. :meth:`~ShortTimeFFT.stft`: Short-time Fourier transform (without detrending). :class:`scipy.signal.ShortTimeFFT`: Class this method belongs to. z1Complex-valued `x` not allowed for self.fft_mode=z7'! Set property `fft_mode` to 'twosided' or 'centered'.)rNzParameter detr=z is not a str, function or zNone!rKzlen(x)=zof axis=z of z must be >= ceil(m_num/2) = rLrr.r) onesided_fftrrprrErQstrrr callablerOrvrrMrmoveaxisp_rangef_ptsrcomplex enumerater _fft_funcr)conj)rSrdetrrrrrrrm2pe_str S_shape_1dS_shapeSp_x_s r/rzShortTimeFFT.stft_detrend!s4   !3Q4==BRSTTU U dC 7.D,(4./$0KL$%& & GGDMTZZ66c7$%FFaKws1viLy4'aggY5OEw&B3%qIJ J 66A: AtR(AaR(Bjj"r'* /0vvz!''#2,+z HHWG ,q(BG LM AFB"X NN2 +?@Ac1bjM A 66A:;;q"daidD DT!VD Dr1)rrrrrc |j|||||||} |||ur| jdz| jdzzS|j|||||||} | | jzS)aCalculate spectrogram or cross-spectrogram. The spectrogram is the absolute square of the STFT, i.e, it is ``abs(S[q,p])**2`` for given ``S[q,p]`` and thus is always non-negative. For two STFTs ``Sx[q,p], Sy[q,p]``, the cross-spectrogram is defined as ``Sx[q,p] * np.conj(Sx[q,p])`` and is complex-valued. This is a convenience function for calling `~ShortTimeFFT.stft` / `stft_detrend`, hence all parameters are discussed there. If `y` is not ``None`` it needs to have the same shape as `x`. Examples -------- The following example shows the spectrogram of a square wave with varying frequency :math:`f_i(t)` (marked by a green dashed line in the plot) sampled with 20 Hz: >>> import matplotlib.pyplot as plt >>> import numpy as np >>> from scipy.signal import square, ShortTimeFFT >>> from scipy.signal.windows import gaussian ... >>> T_x, N = 1 / 20, 1000 # 20 Hz sampling rate for 50 s signal >>> t_x = np.arange(N) * T_x # time indexes for signal >>> f_i = 5e-3*(t_x - t_x[N // 3])**2 + 1 # varying frequency >>> x = square(2*np.pi*np.cumsum(f_i)*T_x) # the signal The utitlized Gaussian window is 50 samples or 2.5 s long. The parameter ``mfft=800`` (oversampling factor 16) and the `hop` interval of 2 in `ShortTimeFFT` was chosen to produce a sufficient number of points: >>> g_std = 12 # standard deviation for Gaussian window in samples >>> win = gaussian(50, std=g_std, sym=True) # symmetric Gaussian wind. >>> SFT = ShortTimeFFT(win, hop=2, fs=1/T_x, mfft=800, scale_to='psd') >>> Sx2 = SFT.spectrogram(x) # calculate absolute square of STFT The plot's colormap is logarithmically scaled as the power spectral density is in dB. The time extent of the signal `x` is marked by vertical dashed lines and the shaded areas mark the presence of border effects: >>> fig1, ax1 = plt.subplots(figsize=(6., 4.)) # enlarge plot a bit >>> t_lo, t_hi = SFT.extent(N)[:2] # time range of plot >>> ax1.set_title(rf"Spectrogram ({SFT.m_num*SFT.T:g}$\,s$ Gaussian " + ... rf"window, $\sigma_t={g_std*SFT.T:g}\,$s)") >>> ax1.set(xlabel=f"Time $t$ in seconds ({SFT.p_num(N)} slices, " + ... rf"$\Delta t = {SFT.delta_t:g}\,$s)", ... ylabel=f"Freq. $f$ in Hz ({SFT.f_pts} bins, " + ... rf"$\Delta f = {SFT.delta_f:g}\,$Hz)", ... xlim=(t_lo, t_hi)) >>> Sx_dB = 10 * np.log10(np.fmax(Sx2, 1e-4)) # limit range to -40 dB >>> im1 = ax1.imshow(Sx_dB, origin='lower', aspect='auto', ... extent=SFT.extent(N), cmap='magma') >>> ax1.plot(t_x, f_i, 'g--', alpha=.5, label='$f_i(t)$') >>> fig1.colorbar(im1, label='Power Spectral Density ' + ... r"$20\,\log_{10}|S_x(t, f)|$ in dB") ... >>> # Shade areas where window slices stick out to the side: >>> for t0_, t1_ in [(t_lo, SFT.lower_border_end[0] * SFT.T), ... (SFT.upper_border_begin(N)[0] * SFT.T, t_hi)]: ... ax1.axvspan(t0_, t1_, color='w', linewidth=0, alpha=.3) >>> for t_ in [0, N * SFT.T]: # mark signal borders with vertical line ... ax1.axvline(t_, color='c', linestyle='--', alpha=0.5) >>> ax1.legend() >>> fig1.tight_layout() >>> plt.show() The logarithmic scaling reveals the odd harmonics of the square wave, which are reflected at the Nyquist frequency of 10 Hz. This aliasing is also the main source of the noise artifacts in the plot. See Also -------- :meth:`~ShortTimeFFT.stft`: Perform the short-time Fourier transform. stft_detrend: STFT with a trend subtracted from each segment. :class:`scipy.signal.ShortTimeFFT`: Class this method belongs to. rr)rr!r"r) rSryrrrrrrSxSys r/ spectrogramzShortTimeFFT.spectrogramWsl  q$B'.T; 9Q77A: * *   q$B'.T;BGGI~r1c||j%t|j|j|_|jS)aCanonical dual window. A STFT can be interpreted as the input signal being expressed as a weighted sum of modulated and time-shifted dual windows. Note that for a given window there exist many dual windows. The canonical window is the one with the minimal energy (i.e., :math:`L_2` norm). `dual_win` has same length as `win`, namely `m_num` samples. If the dual window cannot be calculated a ``ValueError`` is raised. This attribute is read only and calculated lazily. See Also -------- dual_win: Canonical dual window. m_num: Number of samples in window `win`. win: Window function as real- or complex-valued 1d array. ShortTimeFFT: Class this property belongs to. )r6r0r)r*r`s r/rGzShortTimeFFT.dual_wins.* >> !8488LDN~~r1cR t|jdkDS#t$rYywxYw)aCheck if STFT is invertible. This is achieved by trying to calculate the canonical dual window. See Also -------- :meth:`~ShortTimeFFT.istft`: Inverse short-time Fourier transform. m_num: Number of samples in window `win` and `dual_win`. dual_win: Canonical dual window. win: Window for STFT. ShortTimeFFT: Class this property belongs to. rF)rrGrr`s r/ invertiblezShortTimeFFT.invertibles- t}}%) )  s  &&r)f_axist_axisc t||k(rtd|d|d|j||jk7r:td|j|dd|jd|jdz|j|jz }|j||j |x}k\s/td |j|d |d |jdz||j d z k7s||j d z k7rE|dkr|j |zn|}|dkr|j |zn|}tj|||fd}|jd|jz}|d z |jz|jz|jz } || n|}|j|cxkr |cxkr| ks(ntd|jd|d|dd| dz||z x} |k\std|d|d| dd|dz|dk\r||jz|jzn||jz} t|j||} |j||j|d}} || z |jz|jz }tj|jdd|fz|j rt"nt$ }t'| | D]}|j)|d!dd||jz f|j*z}||jz|jz }t||jz||z}d||z }}||kr |||z z }|}|d!||z ||z fxx|d!||fz cc<|d!d||z f}|j d kDr(tj|d||j kr|n|}|S)"aInverse short-time Fourier transform. It returns an array of dimension ``S.ndim - 1`` which is real if `onesided_fft` is set, else complex. If the STFT is not `invertible`, or the parameters are out of bounds a ``ValueError`` is raised. Parameters ---------- S A complex valued array where `f_axis` denotes the frequency values and the `t-axis` dimension the temporal values of the STFT values. k0, k1 The start and the end index of the reconstructed signal. The default (``k0 = 0``, ``k1 = None``) assumes that the maximum length signal should be reconstructed. f_axis, t_axis The axes in `S` denoting the frequency and the time dimension. Notes ----- It is required that `S` has `f_pts` entries along the `f_axis`. For the `t_axis` it is assumed that the first entry corresponds to `p_min` * `delta_t` (being <= 0). The length of `t_axis` needs to be compatible with `k1`. I.e., ``S.shape[t_axis] >= self.p_max(k1)`` must hold, if `k1` is not ``None``. Else `k1` is set to `k_max` with:: q_max = S.shape[t_range] + self.p_min k_max = (q_max - 1) * self.hop + self.m_num - self.m_num_mid The :ref:`tutorial_stft` section of the :ref:`user_guide` discussed the slicing behavior by means of an example. See Also -------- invertible: Check if STFT is invertible. :meth:`~ShortTimeFFT.stft`: Perform Short-time Fourier transform. :class:`scipy.signal.ShortTimeFFT`: Class this method belongs to. zf_axis=z may not be equal to t_axis=rLzS.shape[f_axis]=z must be equal to z self.f_pts=z (S.shape=z)!zS.shape[t_axis]=z needs to have at least z slices (S.shape=rKrr)rrrNz (self.k_min=z ) <= (k0=z) < (k1=z) <= z(k_max=z ) is false!z(k1=z) - (k0=z) = z has to be at z!least the half the window length F)leftrr.)rrOrrvrp_numrMrrp_minr*k_minrp_max nearest_k_prrr9rr$ _ifft_funcrG)rSrrrrrn_minq_numq_maxk_maxnum_ptsq0q1k_q0k_q1n_ptsrq_xsrrj0j1s r/istftzShortTimeFFT.istftsV V y(EfYaHI I 776?djj ( 011CD + }Kqwwj;<= = 4>>)TZZ->$>E? 011IJ %w&8z<=> > QVVaZ 6QVVaZ#7(. QVVf_F(. QVVf_F A/:A djj(dhh&3dnnDjUb b.2..} ZB5 bU%H' 456 67"u,uY2%tG9NK@qIJK K.01WbDHHntzz)DHHn B '%%b)4+;+;BU+;+Kdt djj(4>>9 HHQWWSb\UH,$($5$557 DB- 2B32 ?#:!; 1  2 c6BrE6kN 66A: ArVaff_6&IAr1c|jdk(ry|j&dtt|jz |_|jS)a1Factor to multiply the STFT values by to scale each frequency slice to a magnitude spectrum. It is 1 if attribute ``scaling == 'magnitude'``. The window can be scaled to a magnitude spectrum by using the method `scale_to`. See Also -------- fac_psd: Scaling factor for to a power spectral density spectrum. scale_to: Scale window to obtain 'magnitude' or 'psd' scaling. scaling: Normalization applied to the window function. ShortTimeFFT: Class this property belongs to. rzrK)rqrBabssumr)r`s r/rzShortTimeFFT.fac_magnitude;s@ <<; & == CM 22DM}}r1c|jdk(ry|jddtjt |j j dz|j jdzz|jz z |_|jS)a(Factor to multiply the STFT values by to scale each frequency slice to a power spectral density (PSD). It is 1 if attribute ``scaling == 'psd'``. The window can be scaled to a psd spectrum by using the method `scale_to`. See Also -------- fac_magnitude: Scaling factor for to a magnitude spectrum. scale_to: Scale window to obtain 'magnitude' or 'psd' scaling. scaling: Normalization applied to the window function. ShortTimeFFT: Class this property belongs to. r{rKr) rqrCrsqrtrr)r!r"rer`s r/r~zShortTimeFFT.fac_psdQsp <<5  == DHHMM1$TXX]]A%556?!AADM}}r1c,t|jS)aNumber of samples in window `win`. Note that the FFT can be oversampled by zero-padding. This is achieved by setting the `mfft` property. See Also -------- m_num_mid: Center index of window `win`. mfft: Length of input for the FFT used - may be larger than `m_num`. hop: Time increment in signal samples for sliding window. win: Window function as real- or complex-valued 1d array. ShortTimeFFT: Class this property belongs to. )rr)r`s r/rvzShortTimeFFT.m_numhs488}r1c |jdzS)aCenter index of window `win`. For odd `m_num`, ``(m_num - 1) / 2`` is returned and for even `m_num` (per definition) ``m_num / 2`` is returned. See Also -------- m_num: Number of samples in window `win`. mfft: Length of input for the FFT used - may be larger than `m_num`. hop: ime increment in signal samples for sliding window. win: Window function as real- or complex-valued 1d array. ShortTimeFFT: Class this property belongs to. r)rvr`s r/rzShortTimeFFT.m_num_midyszzQr1c||jjdz|jjdzz}|j }t t |||j z dz |j D]>\}}||jz }||j zdkst||ddk(s9|| fcStd)zSmallest signal index and slice index due to padding. Since, per convention, for time t=0, n,q is zero, the returned values are negative or zero. rrKrN/This is code line should not have been reached!) r)r!r"rrr$rvr*r( RuntimeError)rSr+n0rrwn_nexts r/ _pre_paddingzShortTimeFFT._pre_paddingsXX]]A  q 0 0nn_b"TZZ-/DHH9 EF FB$((]F "a'3r&'{a/?+@B3w LMMr1c(|jdS)aThe smallest possible signal index of the STFT. `k_min` is the index of the left-most non-zero value of the lowest slice `p_min`. Since the zeroth slice is centered over the zeroth sample of the input signal, `k_min` is never positive. A detailed example is provided in the :ref:`tutorial_stft_sliding_win` section of the :ref:`user_guide`. See Also -------- k_max: First sample index after signal end not touched by a time slice. lower_border_end: Where pre-padding effects end. p_min: The smallest possible slice index. p_max: Index of first non-overlapping upper time slice. p_num: Number of time slices, i.e., `p_max` - `p_min`. p_range: Determine and validate slice index range. upper_border_begin: Where post-padding effects start. ShortTimeFFT: Class this property belongs to. rrr`s r/rzShortTimeFFT.k_mins*  "1%%r1c(|jdS)aThe smallest possible slice index. `p_min` is the index of the left-most slice, where the window still sticks into the signal, i.e., has non-zero part for t >= 0. `k_min` is the smallest index where the window function of the slice `p_min` is non-zero. Since, per convention the zeroth slice is centered at t=0, `p_min` <= 0 always holds. A detailed example is provided in the :ref:`tutorial_stft_sliding_win` section of the :ref:`user_guide`. See Also -------- k_min: The smallest possible signal index. k_max: First sample index after signal end not touched by a time slice. p_max: Index of first non-overlapping upper time slice. p_num: Number of time slices, i.e., `p_max` - `p_min`. p_range: Determine and validate slice index range. ShortTimeFFT: Class this property belongs to. rKrr`s r/rzShortTimeFFT.p_mins.  "1%%r1)maxsizec|jjdz|jjdzz}||jz}||jz|jz }t t |||jz|j|D]C\}}||jz}||k\st|d||z dk(s/||jz|dzfcStd)z4Largest signal index and slice index due to padding.r)startNrrKr) r)r!r"r*rrr$rvr(r)rSrr+rrrr-rs r/ _post_paddingzShortTimeFFT._post_paddingsXX]]A  q 0 0 $((] $((]T^^ +b!DJJ, AL /FB$((]F{c"Yah-1"45DJJQ.. /LMMr1c*|j|dS)aFirst sample index after signal end not touched by a time slice. `k_max` - 1 is the largest sample index of the slice `p_max` for a given input signal of `n` samples. A detailed example is provided in the :ref:`tutorial_stft_sliding_win` section of the :ref:`user_guide`. See Also -------- k_min: The smallest possible signal index. p_min: The smallest possible slice index. p_max: Index of first non-overlapping upper time slice. p_num: Number of time slices, i.e., `p_max` - `p_min`. p_range: Determine and validate slice index range. ShortTimeFFT: Class this method belongs to. rrrSrs r/rzShortTimeFFT.k_maxs"!!!$Q''r1c*|j|dS)aIndex of first non-overlapping upper time slice for `n` sample input. Note that center point t[p_max] = (p_max(n)-1) * `delta_t` is typically larger than last time index t[n-1] == (`n`-1) * `T`. The upper border of samples indexes covered by the window slices is given by `k_max`. Furthermore, `p_max` does not denote the number of slices `p_num` since `p_min` is typically less than zero. A detailed example is provided in the :ref:`tutorial_stft_sliding_win` section of the :ref:`user_guide`. See Also -------- k_min: The smallest possible signal index. k_max: First sample index after signal end not touched by a time slice. p_min: The smallest possible slice index. p_num: Number of time slices, i.e., `p_max` - `p_min`. p_range: Determine and validate slice index range. ShortTimeFFT: Class this method belongs to. rKrrs r/rzShortTimeFFT.p_maxs*!!!$Q''r1c>|j||jz S)aNumber of time slices for an input signal with `n` samples. It is given by `p_num` = `p_max` - `p_min` with `p_min` typically being negative. A detailed example is provided in the :ref:`tutorial_stft_sliding_win` section of the :ref:`user_guide`. See Also -------- k_min: The smallest possible signal index. k_max: First sample index after signal end not touched by a time slice. lower_border_end: Where pre-padding effects end. p_min: The smallest possible slice index. p_max: Index of first non-overlapping upper time slice. p_range: Determine and validate slice index range. upper_border_begin: Where post-padding effects start. ShortTimeFFT: Class this method belongs to. )rrrs r/rzShortTimeFFT.p_nums&zz!}tzz))r1c|j |jStj|jjdz|jj dzzd}|j |z}tt||jdz|jD]>\}}||jzdk\s||jz|dzf|_|jcSdt|jdf|_|jS)aoFirst signal index and first slice index unaffected by pre-padding. Describes the point where the window does not stick out to the left of the signal domain. A detailed example is provided in the :ref:`tutorial_stft_sliding_win` section of the :ref:`user_guide`. See Also -------- k_min: The smallest possible signal index. k_max: First sample index after signal end not touched by a time slice. lower_border_end: Where pre-padding effects end. p_min: The smallest possible slice index. p_max: Index of first non-overlapping upper time slice. p_num: Number of time slices, i.e., `p_max` - `p_min`. p_range: Determine and validate slice index range. upper_border_begin: Where post-padding effects start. ShortTimeFFT: Class this property belongs to. rrrK) rDr flatnonzeror)r!r"rrr$r*rvr'r)rSm0rrr-s r/lower_border_endzShortTimeFFT.lower_border_ends,  ! ! -)) )^^DHHMM1,txx}}a/?? @ Cnn_r !b$((Q, AB .FBDHH}!*,tzz/26)B&--- .#$SQ%7!8%%%r1c|jjdz|jjdzz}||jzdz}t ||j z |jzdz d}t ||dD]j}||jz|j |jz z}||kst|||z ddk(sF|dz|jz|jz |dzfcSy)a'First signal index and first slice index affected by post-padding. Describes the point where the window does begin stick out to the right of the signal domain. A detailed example is given :ref:`tutorial_stft_sliding_win` section of the :ref:`user_guide`. See Also -------- k_min: The smallest possible signal index. k_max: First sample index after signal end not touched by a time slice. lower_border_end: Where pre-padding effects end. p_min: The smallest possible slice index. p_max: Index of first non-overlapping upper time slice. p_num: Number of time slices, i.e., `p_max` - `p_min`. p_range: Determine and validate slice index range. ShortTimeFFT: Class this method belongs to. rrKrNrr) r)r!r"r*r'rvr$rr()rSrr+q2rrr-s r/upper_border_beginzShortTimeFFT.upper_border_begin?s(XX]]A  q 0 0 $((]Q  !DJJ,488+a/ 4B# DBdhh$**t~~"=>BAvR"Y!^,Q$((*T^^;R!VCC Dr1c4|j|jzS)aTime increment of STFT. The time increment `delta_t` = `T` * `hop` represents the sample increment `hop` converted to time based on the sampling interval `T`. See Also -------- delta_f: Width of the frequency bins of the STFT. hop: Hop size in signal samples for sliding window. t: Times of STFT for an input signal with `n` samples. T: Sampling interval of input signal and window `win`. ShortTimeFFT: Class this property belongs to )rer*r`s r/delta_tzShortTimeFFT.delta_t]svv  r1c|j|}| |jn|}||n|}|j|cxkr |cxkr|ks/ntd|d|dd|jd|dzd|dz||fS) aDetermine and validate slice index range. Parameters ---------- n : int Number of samples of input signal, assuming t[0] = 0. p0 : int | None First slice index. If 0 then the first slice is centered at t = 0. If ``None`` then `p_min` is used. Note that p0 may be < 0 if slices are left of t = 0. p1 : int | None End of interval (last value is p1-1). If ``None`` then `p_max(n)` is used. Returns ------- p0_ : int The fist slice index p1_ : int End of interval (last value is p1-1). Notes ----- A ``ValueError`` is raised if ``p_min <= p0 < p1 <= p_max(n)`` does not hold. See Also -------- k_min: The smallest possible signal index. k_max: First sample index after signal end not touched by a time slice. lower_border_end: Where pre-padding effects end. p_min: The smallest possible slice index. p_max: Index of first non-overlapping upper time slice. p_num: Number of time slices, i.e., `p_max` - `p_min`. upper_border_begin: Where post-padding effects start. ShortTimeFFT: Class this property belongs to. zInvalid Parameter p0=z, p1=z, i.e., z self.p_min=z <= p0 < p1 <= p_max= z"does not hold for signal length n=rL)rrr)rSrrrrp0_p1_s r/rzShortTimeFFT.p_rangensP 1 JdjjBzer c0C0505"fXF + },BE81EFBt1EFG GCxr1rKc|j|||\}}tj|||jz||jzzS)a?Times of STFT for an input signal with `n` samples. Returns a 1d array with times of the `~ShortTimeFFT.stft` values with the same parametrization. Note that the slices are ``delta_t = hop * T`` time units apart. Parameters ---------- n Number of sample of the input signal. p0 The first element of the range of slices to calculate. If ``None`` then it is set to :attr:`p_min`, which is the smallest possible slice. p1 The end of the array. If ``None`` then `p_max(n)` is used. k_offset Index of first sample (t = 0) in `x`. See Also -------- delta_t: Time increment of STFT (``hop*T``) hop: Time increment in signal samples for sliding window. nearest_k_p: Nearest sample index k_p for which t[k_p] == t[p] holds. T: Sampling interval of input signal and of the window (``1/fs``). fs: Sampling frequency (being ``1/T``) ShortTimeFFT: Class this method belongs to. )rrarangerre)rSrrrrs r/rrzShortTimeFFT.tsC@aR(ByyR 4<</(TVV2CCCr1ct||j\}}|dk(r|S|r||jzS|dz|jzS)afReturn nearest sample index k_p for which t[k_p] == t[p] holds. The nearest next smaller time sample p (where t[p] is the center position of the window of the p-th slice) is p_k = k // `hop`. If `hop` is a divisor of `k` than `k` is returned. If `left` is set than p_k * `hop` is returned else (p_k+1) * `hop`. This method can be used to slice an input signal into chunks for calculating the STFT and iSTFT incrementally. See Also -------- delta_t: Time increment of STFT (``hop*T``) hop: Time increment in signal samples for sliding window. T: Sampling interval of input signal and of the window (``1/fs``). fs: Sampling frequency (being ``1/T``) t: Times of STFT for an input signal with `n` samples. ShortTimeFFT: Class this method belongs to. rrK)divmodr*)rSkrp_q remainders r/rzShortTimeFFT.nearest_k_psF( 488,Y >H!%sTXX~?C!Gtxx+??r1c:d|j|jzz S)aWidth of the frequency bins of the STFT. Return the frequency interval `delta_f` = 1 / (`mfft` * `T`). See Also -------- delta_t: Time increment of STFT. f_pts: Number of points along the frequency axis. f: Frequencies values of the STFT. mfft: Length of the input for FFT used. T: Sampling interval. t: Times of STFT for an input signal with `n` samples. ShortTimeFFT: Class this property belongs to. rK)rFrer`s r/delta_fzShortTimeFFT.delta_fs DII&''r1cV|jr|jdzdzS|jS)a!Number of points along the frequency axis. See Also -------- delta_f: Width of the frequency bins of the STFT. f: Frequencies values of the STFT. mfft: Length of the input for FFT used. ShortTimeFFT: Class this property belongs to. rrK)rrFr`s r/rzShortTimeFFT.f_ptss(&*%6%6tyyA~!EDIIEr1c|jdvS)a<Return True if a one-sided FFT is used. Returns ``True`` if `fft_mode` is either 'onesided' or 'onesided2X'. See Also -------- fft_mode: Utilized FFT ('twosided', 'centered', 'onesided' or 'onesided2X') ShortTimeFFT: Class this property belongs to. ro)rEr`s r/rzShortTimeFFT.onesided_ffts}} :::r1c|jdvr*tj|j|jS|jdk(r*tj |j|jS|jdk(r=tj tj |j|jStt}td|jd|d)avFrequencies values of the STFT. A 1d array of length `f_pts` with `delta_f` spaced entries is returned. See Also -------- delta_f: Width of the frequency bins of the STFT. f_pts: Number of points along the frequency axis. mfft: Length of the input for FFT used. ShortTimeFFT: Class this property belongs to. rorrself.fft_mode=r|rL) rEfft_librfftfreqrFrefftfreqfftshiftr r;r)rS fft_modess r/fzShortTimeFFT.fs ==6 6##DIItvv6 6 ]]j (??499dff5 5 ]]j (##GOODIItvv$FG G]+ ndmm-Xi[BCCr1cF|j|jd|jkrjt|j}|j|jdz |d<t j |t j ||jf}|j|jz|jz}t j|| d}|jdk(r"tj||jdS|jdk(r7tjtj||jddS|jd k(r"tj||jdS|jd k(rotj||jd}|j d k(rt j"d nd }|d d|jd zdk(rdndfxx|zcc<|St%t&}t)d|jd|d)zFFT based on the `fft_mode`, `mfft`, `scaling` and `phase_shift` attributes. For multidimensional arrays the transformation is carried out on the last axis. Nrrrrrrraxesrrr{r.rKrrr|rL)rIrOrFlistrhstackrrrrvrollrErfftrrfftrqrr r;r)rSrz_shapep_sXfacrs r/rzShortTimeFFT._fft_funcs    'wwr{TYY&qww-"ii!''"+5 IIq"((7!''"BCD##dnn4 BCC4b)A ==J &;;qDIIB7 7 ==J &##GKK4992$FRP P ==J &<<TYYR8 8 ==L ( Q$))"5A $  5"''!*1C c1DIIMQ.bD88 9S @ 9H]+ ndmm-Xi[BCCr1c|jdk(r$tj||jd}n3|jdk(r8tjtj|d|jd}n|jdk(r#tj ||jd}n|jdk(r|j }|jdk(rtjd nd }|jd zd k(rdnd }|d d |fxx|zcc<tj ||jd}n+d|jdttd}t||j|d |jS|j|jz|jz}tj ||dd |jS)aInverse to `_fft_func`. Returned is an array of length `m_num`. If the FFT is `onesided` then a float array is returned else a complex array is returned. For multidimensional arrays the transformation is carried out on the last axis. rrrrrrrr{rrN.rKrr|rLr)rErifftrF ifftshiftirfftr#rqrrr r;rrIrvrr)rSr#rXcr$r error_strr"s r/rzShortTimeFFT._ifft_func?sm ==J & Q$))"5A ]]j ( W..qr:diibQA ]]j ( a49926A ]]l *B $  5"''!*1Cyy1})tB sAbDyMS M bDIIB7A)4==*(8M3J2K1MIy) )    #[djj> !$..0DJJ>wwq#B' 44r1c|dvrtd|d|jrd|j}}no|jdk(rD|j dz}|jdzdk(r|jdzdz n|jdz}ntd|jd d z|j |j |}}|rI|j|d z z|j|d z z} }|j|d z z|j|d z z} } n<|j|z|j|z} }|j|z|j|z} } |d k(r|| | | fS| | || fS) a(Return minimum and maximum values time-frequency values. A tuple with four floats ``(t0, t1, f0, f1)`` for 'tf' and ``(f0, f1, t0, t1)`` for 'ft' is returned describing the corners of the time-frequency domain of the `~ShortTimeFFT.stft`. That tuple can be passed to `matplotlib.pyplot.imshow` as a parameter with the same name. Parameters ---------- n : int Number of samples in input signal. axes_seq : {'tf', 'ft'} Return time extent first and then frequency extent or vice-versa. center_bins: bool If set (default ``False``), the values of the time slots and frequency bins are moved from the side the middle. This is useful, when plotting the `~ShortTimeFFT.stft` values as step functions, i.e., with no interpolation. See Also -------- :func:`matplotlib.pyplot.imshow`: Display data as an image. :class:`scipy.signal.ShortTimeFFT`: Class this method belongs to. )tfftzParameter axes_seq=z not in ['tf', 'ft']!rrrrKzAttribute fft_mode=z must be z)in ['centered', 'onesided', 'onesided2X']g?r,) rrrrErFrrrr ) rSraxes_seq center_binsrrrrt0t1f0f1s r/extentzShortTimeFFT.extent^s`6 < '3(4IJK K    B ]]j ())qB'+yy1}'9a!#tyyA~B24==/KHIJ JTZZ]B \\R#X. S0IB\\R#X. S0IB\\B& r(9B\\B& r(9B#+t#3BBI"b"b9IIr1)r)r3r*r7rRr9rEr;rFr@rGr5rHr>rIr@)rGr3r*r7rRr9rEr;rFr@rHr>rIr@)r[zstr | tuple | floatrRr9r\r7r]r7rXboolrEr;rFr@rHr>rIr@)returnr3)r6r7)r6r9)rjr9)r6r;)rrr;)rwr7)r6r>)rqzLiteral['magnitude', 'psd'])r6r@)rjr@) rr3rr7rr7rr7rrr6z!Generator[np.ndarray, None, None]r})rr3rr@rr@rr7rrrr7r6r3)rr3rICallable[[np.ndarray], np.ndarray] | Literal['linear', 'constant'] | Nonerr@rr@rr7rrrr7r6r3)rr3rr5rr7rr@rr@rr7rrrr7r6r3)r6r5)rN) rr3rr7rr@rr7rr7r6r3)r6tuple[int, int])rr7r6r8)rr7r6r7)rr7rr@rr@r6r8)NNr) rr7rr@rr@rr7r6r3)T)rr7rr5r6r7)rr3r6r3)r#r3r6r3)r,F)rr7r.zLiteral['tf', 'ft']r/r5r6z!tuple[float, float, float, float]);__name__ __module__ __qualname____doc____annotations__r6r<r?rBrCrDrT classmethodrWr^propertyr)r*resetterrRrErFrqrHrIrrrrrGrrrr~rvrrrrrrrrrrrrrrrrrr rrrrrr4r1r/rrNsXt #'I ' I J)I}) J37H07"Hl!!Hl!04-4,6$(/3@D+, @(@!@-@> @ ) @8,6%)AE,- O,)O,"O,?O, * O,O,b+0.8'+CG./ HJHJ(+HJ7:HJ#'HJ,HJ% HJ A HJ ", HJHJT""  XX  YY&&P__$   [[($ L!!2".#.(I.848":=78!(b:=:=14:=:=03:=:=|>B4&'G!# 4d4#40:4 #42:4 4  4lAEfj]&*D$%7 " ]c]#]0:]" ]19 ]  ]  ]~0$WbWW(+WWr*,    N  N"&&,&&0s N N(&(.**"&"&Hs:!! 04!%//*9/bq@D D D * D DD@2((" F F ; ;DD,D@5>>B#(.J .J-N.Jr1)r)r3r*r7r6r3)r< __future__rcollections.abcr functoolsrrrtypingrr r numpyr scipy.fftrr scipy.signalr scipy.signal.windowsr __all__rr;r0rrAr1r/rKs^C(#%//.. +   1 2HI F~J~Jr1