{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A typical STFT application is the creation of various types of time-frequency plots, often subsumed under the term \"spectrogram\". Note that this term is also used to explecitly refer to the absolute square of a STFT " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "11" }, { "__type": "Text", "__tag": 4046, "value": ", as done in " }, { "__type": "InlineRole", "__tag": 4003, "value": "spectrogram", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The STFT can also be used for filtering and filter banks as discussed in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "12" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Array API Standard Support" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "ShortTimeFFT", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._short_time_fft:ShortTimeFFT" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " has experimental support for Python Array API Standard compatible backends in addition to NumPy. Please consider testing these features by setting an environment variable " }, { "__type": "InlineCode", "__tag": 4051, "value": "SCIPY_ARRAY_API=1" }, { "__type": "Text", "__tag": 4046, "value": " and providing CuPy, PyTorch, JAX, or Dask arrays as array arguments. The following combinations of backend and device (or other capability) are supported." } ] }, { "__type": "Code", "__tag": 4050, "value": "==================== ==================== ====================\nLibrary CPU GPU\n==================== ==================== ====================\nNumPy ✅ n/a \nCuPy n/a ⛔ \nPyTorch ⛔ ⛔ \nJAX ⛔ ⛔ \nDask ⛔ n/a \n==================== ==================== ====================", "execution_status": null }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "See " }, { "__type": "InlineRole", "__tag": 4003, "value": "dev-arrayapi", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " for more information." } ] } ] } ], "title": [], "level": 0, "target": null }, "Warns": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Raises": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Yields": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Methods": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Returns": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Provide a parametrized discrete Short-time Fourier transform (stft) and its inverse (istft)." } ] } ], "title": [], "level": 0, "target": null }, "Receives": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Warnings": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Attributes": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Parameters": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "win", "annotation": "np.ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The window must be a real- or complex-valued 1d array." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "hop", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The increment in samples, by which the window is shifted in each step." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "fs", "annotation": "float", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Sampling frequency of input signal and window. Its relation to the sampling interval " }, { "__type": "InlineRole", "__tag": 4003, "value": "T", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " is " }, { "__type": "InlineCode", "__tag": 4051, "value": "T = 1 / fs" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "fft_mode", "annotation": "'twosided', 'centered', 'onesided', 'onesided2X'", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Mode of FFT to be used (default 'onesided'). See property " }, { "__type": "ParamRef", "__tag": 4071, "name": "fft_mode" }, { "__type": "Text", "__tag": 4046, "value": " for details." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "mfft: int | None", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Length of the FFT used, if a zero padded FFT is desired. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": " (default), the length of the window " }, { "__type": "ParamRef", "__tag": 4071, "name": "win" }, { "__type": "Text", "__tag": 4046, "value": " is used." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "dual_win", "annotation": "np.ndarray | None", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The dual window of " }, { "__type": "ParamRef", "__tag": 4071, "name": "win" }, { "__type": "Text", "__tag": 4046, "value": ". If set to " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": ", it is calculated if needed." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "scale_to", "annotation": "'magnitude', 'psd' | None", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If not " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": " (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 " }, { "__type": "InlineRole", "__tag": 4003, "value": "scaling", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " to the same value. See method " }, { "__type": "ParamRef", "__tag": 4071, "name": "scale_to" }, { "__type": "Text", "__tag": 4046, "value": " for details." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "phase_shift", "annotation": "int | None", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If set, add a linear phase " }, { "__type": "ParamRef", "__tag": 4071, "name": "phase_shift" }, { "__type": "Text", "__tag": 4046, "value": " / " }, { "__type": "ParamRef", "__tag": 4071, "name": "mfft" }, { "__type": "Text", "__tag": 4046, "value": " * " }, { "__type": "InlineRole", "__tag": 4003, "value": "f", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " to each frequency " }, { "__type": "InlineRole", "__tag": 4003, "value": "f", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ". The default value of 0 ensures that there is no phase shift on the zeroth slice (in which t=0 is centered). See property " }, { "__type": "ParamRef", "__tag": 4071, "name": "phase_shift" }, { "__type": "Text", "__tag": 4046, "value": " for more details." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "InlineRole", "__tag": 4003, "value": "~ShortTimeFFT.stft", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " calculates sequential FFTs by sliding a window (" }, { "__type": "ParamRef", "__tag": 4071, "name": "win" }, { "__type": "Text", "__tag": 4046, "value": ") over an input signal by " }, { "__type": "ParamRef", "__tag": 4071, "name": "hop" }, { "__type": "Text", "__tag": 4046, "value": " increments. It can be used to quantify the change of the spectrum over time." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "InlineRole", "__tag": 4003, "value": "~ShortTimeFFT.stft", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " 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 * " }, { "__type": "InlineRole", "__tag": 4003, "value": "delta_t", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " = p * " }, { "__type": "ParamRef", "__tag": 4071, "name": "hop" }, { "__type": "Text", "__tag": 4046, "value": " * " }, { "__type": "InlineRole", "__tag": 4003, "value": "T", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " where " }, { "__type": "InlineRole", "__tag": 4003, "value": "T", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " is the sampling interval of the input signal. The q-th row represents the values at the frequency f[q] = q * " }, { "__type": "InlineRole", "__tag": 4003, "value": "delta_f", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " with " }, { "__type": "InlineRole", "__tag": 4003, "value": "delta_f", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " = 1 / (" }, { "__type": "ParamRef", "__tag": 4071, "name": "mfft" }, { "__type": "Text", "__tag": 4046, "value": " * " }, { "__type": "InlineRole", "__tag": 4003, "value": "T", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ") being the bin width of the FFT." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The inverse STFT " }, { "__type": "InlineRole", "__tag": 4003, "value": "~ShortTimeFFT.istft", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " 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 " }, { "__type": "ParamRef", "__tag": 4071, "name": "dual_win" }, { "__type": "Text", "__tag": 4046, "value": "). Shift the result by p * " }, { "__type": "InlineRole", "__tag": 4003, "value": "delta_t", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " and add the result to previous shifted results to reconstruct the signal. If only the dual window is known and the STFT is invertible, " }, { "__type": "InlineRole", "__tag": 4003, "value": "from_dual", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " can be used to instantiate this class." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "By default, the so-called canonical dual window is used. It is the window with minimal energy among all possible dual windows. " }, { "__type": "InlineRole", "__tag": 4003, "value": "from_win_equals_dual", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "CrossRef", "__tag": 4002, "value": "closest_STFT_dual_window", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.signal._short_time_fft:closest_STFT_dual_window" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " provide means for utilizing alterantive dual windows. Note that " }, { "__type": "ParamRef", "__tag": 4071, "name": "win" }, { "__type": "Text", "__tag": 4046, "value": " is also always a dual window of " }, { "__type": "ParamRef", "__tag": 4071, "name": "dual_win" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "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 " }, { "__type": "InlineRole", "__tag": 4003, "value": "p_min", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineRole", "__tag": 4003, "value": "k_min", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " do not indicate counting backwards from an array's end like in standard Python indexing but being left of t = 0." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "More detailed information can be found in the " }, { "__type": "InlineRole", "__tag": 4003, "value": "tutorial_stft", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " section of the " }, { "__type": "InlineRole", "__tag": 4003, "value": "user_guide", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Note that all parameters of the initializer, except " }, { "__type": "ParamRef", "__tag": 4071, "name": "scale_to" }, { "__type": "Text", "__tag": 4046, "value": " (which uses " }, { "__type": "InlineRole", "__tag": 4003, "value": "scaling", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ") have identical named attributes." } ] } ], "title": [], "level": 0, "target": null }, "Other Parameters": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null } }, "_ordered_sections": [ "Summary", "Extended Summary", "Parameters", "Attributes", "Methods", "Returns", "Yields", "Receives", "Other Parameters", "Raises", "Warns", "Warnings", "Notes" ], "item_file": "/scipy/signal/_short_time_fft.py", "item_line": 225, "item_type": "class", "aliases": [ "scipy.signal.ShortTimeFFT" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "The following example shows the magnitude of the STFT of a sine with\nvarying frequency :math:`f_i(t)` (marked by a red dashed line in the plot):\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nimport matplotlib.pyplot as plt\nfrom scipy.signal import ShortTimeFFT\nfrom scipy.signal.windows import gaussian\nT_x, N = 1 / 20, 1000 # 20 Hz sampling rate for 50 s signal\nt_x = np.arange(N) * T_x # time indexes for signal\nf_i = 1 * np.arctan((t_x - t_x[N // 2]) / 2) + 5 # varying frequency\nx = np.sin(2*np.pi*np.cumsum(f_i)*T_x) # the signal\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe utilized Gaussian window is 50 samples or 2.5 s long. The parameter\n``mfft=200`` in `ShortTimeFFT` causes the spectrum to be oversampled\nby a factor of 4:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "g_std = 8 # standard deviation for Gaussian window in samples\nw = gaussian(50, std=g_std, sym=True) # symmetric Gaussian window\nSFT = ShortTimeFFT(w, hop=10, fs=1/T_x, mfft=200, scale_to='magnitude')\nSx = SFT.stft(x) # perform the STFT\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nIn the plot, the time extent of the signal `x` is marked by vertical dashed\nlines. Note that the SFT produces values outside the time range of `x`. The\nshaded areas on the left and the right indicate border effects caused\nby the window slices in that area not fully being inside time range of\n`x`:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "fig1, ax1 = plt.subplots(figsize=(6., 4.)) # enlarge plot a bit\nt_lo, t_hi = SFT.extent(N)[:2] # time range of plot\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "ax1.set_title(rf\"STFT ({SFT.m_num*SFT.T:g}$\\,s$ Gaussian window, \" +\n rf\"$\\sigma_t={g_std*SFT.T}\\,$s)\")\nax1.set(xlabel=f\"Time $t$ in seconds ({SFT.p_num(N)} slices, \" +\n rf\"$\\Delta t = {SFT.delta_t:g}\\,$s)\",\n ylabel=f\"Freq. $f$ in Hz ({SFT.f_pts} bins, \" +\n rf\"$\\Delta f = {SFT.delta_f:g}\\,$Hz)\",\n xlim=(t_lo, t_hi))\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "im1 = ax1.imshow(abs(Sx), origin='lower', aspect='auto',\n extent=SFT.extent(N), cmap='viridis')\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "ax1.plot(t_x, f_i, 'r--', alpha=.5, label='$f_i(t)$')\nfig1.colorbar(im1, label=\"Magnitude $|S_x(t, f)|$\")\nfor t0_, t1_ in [(t_lo, SFT.lower_border_end[0] * SFT.T),\n (SFT.upper_border_begin(N)[0] * SFT.T, t_hi)]:\n ax1.axvspan(t0_, t1_, color='w', linewidth=0, alpha=.2)\nfor t_ in [0, N * SFT.T]: # mark signal borders with vertical line:\n ax1.axvline(t_, color='y', linestyle='--', alpha=0.5)\nax1.legend()\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "fig1.tight_layout()\nplt.show()\n", "execution_status": "success" }, { "__type": "Figure", "__tag": 4024, "value": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "1.17.1", "kind": "assets", "path": "fig-73462285eae23f2e.png" } }, { "__type": "Text", "__tag": 4046, "value": "\nReconstructing the signal with the `~ShortTimeFFT.istft` is\nstraightforward, but note that the length of `x1` should be specified,\nsince the STFT length increases in `hop` steps:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "SFT.invertible # check if invertible\nx1 = SFT.istft(Sx, k1=N)\nnp.allclose(x, x1)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nIt is possible to calculate the STFT of signal parts:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "N2 = SFT.nearest_k_p(N // 2)\nSx0 = SFT.stft(x[:N2])\nSx1 = SFT.stft(x[N2:])\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nWhen assembling sequential STFT parts together, the overlap needs to be\nconsidered:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "p0_ub = SFT.upper_border_begin(N2)[1] - SFT.p_min\np1_le = SFT.lower_border_end[1] - SFT.p_min\nSx01 = np.hstack((Sx0[:, :p0_ub],\n Sx0[:, p0_ub:] + Sx1[:, :p1_le],\n Sx1[:, p1_le:]))\nnp.allclose(Sx01, Sx) # Compare with SFT of complete signal\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nIt is also possible to calculate the `itsft` for signal parts:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "y_p = SFT.istft(Sx, N//3, N//2)\nnp.allclose(y_p, x[N//3:N//2])\n", "execution_status": "success" } ], "title": [], "level": 0, "target": null }, "see_also": [], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "win", "annotation": "np.ndarray", "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "hop", "annotation": "int", "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "fs", "annotation": "float", "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "fft_mode", "annotation": "FFT_MODE_TYPE", "kind": "KEYWORD_ONLY", "default": "onesided" }, { "__type": "SigParam", "__tag": 4030, "name": "mfft", "annotation": "int | None", "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "dual_win", "annotation": "np.ndarray | None", "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "scale_to", "annotation": "Literal['magnitude', 'psd'] | None", "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "phase_shift", "annotation": "int | None", "kind": "KEYWORD_ONLY", "default": "0" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "ShortTimeFFT" }, "references": [ ".. [11] Karlheinz Gröchenig: \"Foundations of Time-Frequency Analysis\",", " Birkhäuser Boston 2001, `10.1007/978-1-4612-0003-1`", ".. [12] Julius O. Smith III, \"Spectral Audio Signal Processing\", online book, 2011,", " https://www.dsprelated.com/freebooks/sasp/" ], "qa": "scipy.signal._short_time_fft:ShortTimeFFT", "arbitrary": [], "local_refs": [ "dual_win", "fft_mode", "fs", "hop", "mfft: int | None", "phase_shift", "scale_to", "win" ] }