{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The cross-spectrogram may be interpreted as the time-frequency analogon of the cross-spectral density (consult " }, { "__type": "CrossRef", "__tag": 4002, "value": "csd", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._spectral_py:csd" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": "). The absolute square " }, { "__type": "InlineRole", "__tag": 4003, "value": "|Sxy|²", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " of a cross-spectrogram " }, { "__type": "InlineRole", "__tag": 4003, "value": "Sxy", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " divided by the spectrograms " }, { "__type": "InlineRole", "__tag": 4003, "value": "Sxx", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineRole", "__tag": 4003, "value": "Syy", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " can be interpreted as a coherence spectrogram " }, { "__type": "InlineCode", "__tag": 4051, "value": "Cxy := abs(Sxy)**2 / (Sxx*Syy)" }, { "__type": "Text", "__tag": 4046, "value": ", which is the time-frequency analogon to " }, { "__type": "CrossRef", "__tag": 4002, "value": "coherence", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._spectral_py:coherence" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If the STFT is parametrized to be a unitary transform, i.e., utilitzing " }, { "__type": "CrossRef", "__tag": 4002, "value": "from_win_equals_dual", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._short_time_fft:ShortTimeFFT.from_win_equals_dual" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ", then the value of the scalar product, hence also the energy, is preserved." } ] } ], "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": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "S_xy", "annotation": "np.ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A real-valued array with non-negative values is returned, if " }, { "__type": "InlineCode", "__tag": 4051, "value": "x is y" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "ParamRef", "__tag": 4071, "name": "y" }, { "__type": "Text", "__tag": 4046, "value": " is " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": ". The dimension is always by one larger than of " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": ". The last axis always represents the time slices of the spectrogram. " }, { "__type": "ParamRef", "__tag": 4071, "name": "axis" }, { "__type": "Text", "__tag": 4046, "value": " defines the frequency axis (default second to last). E.g., for a one-dimensional " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": ", a complex 2d array is returned, with axis 0 representing frequency and axis 1 the time slices." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Calculate spectrogram or cross-spectrogram." } ] } ], "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": "x", "annotation": "np.ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The input signal as real or complex valued array. For complex values, the property " }, { "__type": "InlineRole", "__tag": 4003, "value": "fft_mode", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " must be set to 'twosided' or 'centered'." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "y", "annotation": "np.ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The second input signal of the same shape as " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": ". If " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": ", it is assumed to be " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": ". For complex values, the property " }, { "__type": "InlineRole", "__tag": 4003, "value": "fft_mode", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " must be set to 'twosided' or 'centered'." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "detr", "annotation": "'linear' | 'constant' | Callable[[np.ndarray], np.ndarray] | None", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If 'constant', the mean is subtracted, if set to \"linear\", the linear trend is removed from each segment. This is achieved by calling " }, { "__type": "CrossRef", "__tag": 4002, "value": "detrend", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.signal._signaltools:detrend" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ". If " }, { "__type": "ParamRef", "__tag": 4071, "name": "detr" }, { "__type": "Text", "__tag": 4046, "value": " is a function with one parameter, " }, { "__type": "ParamRef", "__tag": 4071, "name": "detr" }, { "__type": "Text", "__tag": 4046, "value": " is applied to each segment. For " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": " (default), no trends are removed." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "p0", "annotation": "int | None", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The first element of the range of slices to calculate. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": " then it is set to " }, { "__type": "InlineRole", "__tag": 4003, "value": "p_min", "domain": null, "role": "attr", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", which is the smallest possible slice." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "p1", "annotation": "int | None", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The end of the array. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": " then " }, { "__type": "InlineRole", "__tag": 4003, "value": "p_max(n)", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " is used." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "k_offset", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Index of first sample (t = 0) in " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "padding", "annotation": "'zeros' | 'edge' | 'even' | 'odd'", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Kind of values which are added, when the sliding window sticks out on either the lower or upper end of the input " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": ". Zeros are added if the default 'zeros' is set. For 'edge' either the first or the last value of " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": " is used. 'even' pads by reflecting the signal on the first or last sample and 'odd' additionally multiplies it with -1." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "axis", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The axis of " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": " over which to compute the STFT. If not given, the last axis is used." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The spectrogram is the absolute square of the STFT, i.e., it is " }, { "__type": "InlineCode", "__tag": 4051, "value": "abs(S[q,p])**2" }, { "__type": "Text", "__tag": 4046, "value": " for given " }, { "__type": "InlineCode", "__tag": 4051, "value": "S[q,p]" }, { "__type": "Text", "__tag": 4046, "value": " and thus is always non-negative. For two STFTs " }, { "__type": "InlineCode", "__tag": 4051, "value": "Sx[q,p], Sy[q,p]" }, { "__type": "Text", "__tag": 4046, "value": ", the cross-spectrogram is defined as " }, { "__type": "InlineCode", "__tag": 4051, "value": "Sx[q,p] * np.conj(Sy[q,p])" }, { "__type": "Text", "__tag": 4046, "value": " and is complex-valued. This is a convenience function for calling " }, { "__type": "InlineRole", "__tag": 4003, "value": "~ShortTimeFFT.stft", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " / " }, { "__type": "CrossRef", "__tag": 4002, "value": "stft_detrend", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._short_time_fft:ShortTimeFFT.stft_detrend" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ", hence all parameters are discussed there." } ] } ], "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": 1256, "item_type": "function", "aliases": [ "scipy.signal.ShortTimeFFT.spectrogram" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "The following example shows the spectrogram of a square wave with varying\nfrequency :math:`f_i(t)` (marked by a green dashed line in the plot) sampled\nwith 20 Hz. The utilized Gaussian window is 50 samples or 2.5 s long. For the\n`ShortTimeFFT`, the parameter ``mfft=800`` (oversampling factor 16) and the\n`hop` interval of 2 in was chosen to produce a sufficient number of points.\n\nThe plot's colormap is logarithmically scaled as the power spectral\ndensity is in dB. The time extent of the signal `x` is marked by\nvertical dashed lines, and the shaded areas mark the presence of border\neffects.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import matplotlib.pyplot as plt\nimport numpy as np\nfrom scipy.signal import square, 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 = 5e-3*(t_x - t_x[N // 3])**2 + 1 # varying frequency\nx = square(2*np.pi*np.cumsum(f_i)*T_x) # the signal\ng_std = 12 # standard deviation for Gaussian window in samples\nwin = gaussian(50, std=g_std, sym=True) # symmetric Gaussian wind.\nSFT = ShortTimeFFT(win, hop=2, fs=1/T_x, mfft=800, scale_to='psd')\nSx2 = SFT.spectrogram(x) # calculate absolute square of STFT\nfig1, 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\"Spectrogram ({SFT.m_num*SFT.T:g}$\\,s$ Gaussian \" +\n rf\"window, $\\sigma_t={g_std*SFT.T:g}\\,$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": "Sx_dB = 10 * np.log10(np.fmax(Sx2, 1e-4)) # limit range to -40 dB\nim1 = ax1.imshow(Sx_dB, origin='lower', aspect='auto',\n extent=SFT.extent(N), cmap='magma')\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "ax1.plot(t_x, f_i, 'g--', alpha=.5, label='$f_i(t)$')\nfig1.colorbar(im1, label='Power Spectral Density ' +\n r\"$20\\,\\log_{10}|S_x(t, f)|$ in dB\")\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=.3)\nfor t_ in [0, N * SFT.T]: # mark signal borders with vertical line\n ax1.axvline(t_, color='c', 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-ae728c1c83128318.png" } }, { "__type": "Text", "__tag": 4046, "value": "\nThe logarithmic scaling reveals the odd harmonics of the square wave,\nwhich are reflected at the Nyquist frequency of 10 Hz. This aliasing\nis also the main source of the noise artifacts in the plot." } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "scipy.signal.ShortTimeFFT", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._short_time_fft:ShortTimeFFT" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Class this method belongs to." } ] } ], "type": "class" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "stft_detrend", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._short_time_fft:ShortTimeFFT.stft_detrend" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "STFT with a trend subtracted from each segment." } ] } ], "type": null }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "~ShortTimeFFT.stft", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "~ShortTimeFFT.stft" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Perform the short-time Fourier transform." } ] } ], "type": "meth" } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "self", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "x", "annotation": "np.ndarray", "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "y", "annotation": "np.ndarray | None", "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "detr", "annotation": "Callable[[np.ndarray], np.ndarray] | Literal['linear', 'constant'] | None", "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "p0", "annotation": "int | None", "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "p1", "annotation": "int | None", "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "k_offset", "annotation": "int", "kind": "KEYWORD_ONLY", "default": "0" }, { "__type": "SigParam", "__tag": 4030, "name": "padding", "annotation": "PAD_TYPE", "kind": "KEYWORD_ONLY", "default": "zeros" }, { "__type": "SigParam", "__tag": 4030, "name": "axis", "annotation": "int", "kind": "KEYWORD_ONLY", "default": "-1" } ], "return_annotation": "np.ndarray", "target_name": "spectrogram" }, "references": null, "qa": "scipy.signal._short_time_fft:ShortTimeFFT.spectrogram", "arbitrary": [], "local_refs": [ "S_xy", "axis", "detr", "k_offset", "p0", "p1", "padding", "x", "y" ] }