{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This computation uses the tridiagonal eigenvector formulation given in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The default normalization for " }, { "__type": "InlineCode", "__tag": 4051, "value": "Kmax=None" }, { "__type": "Text", "__tag": 4046, "value": ", i.e. window-generation mode, simply using the l-infinity norm would create a window with two unity values, which creates slight normalization differences between even and odd orders. The approximate correction of " }, { "__type": "InlineCode", "__tag": 4051, "value": "M**2/float(M**2+NW)" }, { "__type": "Text", "__tag": 4046, "value": " for even sample numbers is used to counteract this effect (see Examples below)." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For very long signals (e.g., 1e6 elements), it can be useful to compute windows orders of magnitude shorter and use interpolation (e.g., " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.interpolate.interp1d", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.interpolate._interpolate:interp1d" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ") to obtain tapers of length " }, { "__type": "ParamRef", "__tag": 4071, "name": "M" }, { "__type": "Text", "__tag": 4046, "value": ", but this in general will not preserve orthogonality between the tapers." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 1.1" } ] } ] }, { "__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": "dpss", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal.windows._windows:dpss" }, "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": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "v", "annotation": "ndarray, shape (Kmax, M) or (M,)", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The DPSS windows. Will be 1D if " }, { "__type": "ParamRef", "__tag": 4071, "name": "Kmax" }, { "__type": "Text", "__tag": 4046, "value": " is None." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "r", "annotation": "ndarray, shape (Kmax,) or float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The concentration ratios for the windows. Only returned if " }, { "__type": "ParamRef", "__tag": 4071, "name": "return_ratios" }, { "__type": "Text", "__tag": 4046, "value": " evaluates to True. Will be 0D if " }, { "__type": "ParamRef", "__tag": 4071, "name": "Kmax" }, { "__type": "Text", "__tag": 4046, "value": " is None." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Compute the Discrete Prolate Spheroidal Sequences (DPSS)." } ] } ], "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": "M", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Window length." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "NW", "annotation": "float", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Standardized half bandwidth corresponding to " }, { "__type": "InlineCode", "__tag": 4051, "value": "2*NW = BW/f0 = BW*M*dt" }, { "__type": "Text", "__tag": 4046, "value": " where " }, { "__type": "InlineCode", "__tag": 4051, "value": "dt" }, { "__type": "Text", "__tag": 4046, "value": " is taken as 1." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "Kmax", "annotation": "int | None, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Number of DPSS windows to return (orders " }, { "__type": "InlineCode", "__tag": 4051, "value": "0" }, { "__type": "Text", "__tag": 4046, "value": " through " }, { "__type": "InlineCode", "__tag": 4051, "value": "Kmax-1" }, { "__type": "Text", "__tag": 4046, "value": "). If None (default), return only a single window of shape " }, { "__type": "InlineCode", "__tag": 4051, "value": "(M,)" }, { "__type": "Text", "__tag": 4046, "value": " instead of an array of windows of shape " }, { "__type": "InlineCode", "__tag": 4051, "value": "(Kmax, M)" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "sym", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When True (default), generates a symmetric window, for use in filter design. When False, generates a periodic window, for use in spectral analysis." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "norm", "annotation": "{2, 'approximate', 'subsample'} | None, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If 'approximate' or 'subsample', then the windows are normalized by the maximum, and a correction scale-factor for even-length windows is applied either using " }, { "__type": "InlineCode", "__tag": 4051, "value": "M**2/(M**2+NW)" }, { "__type": "Text", "__tag": 4046, "value": " (\"approximate\") or a FFT-based subsample shift (\"subsample\"), see Notes for details. If None, then \"approximate\" is used when " }, { "__type": "InlineCode", "__tag": 4051, "value": "Kmax=None" }, { "__type": "Text", "__tag": 4046, "value": " and 2 otherwise (which uses the l2 norm)." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "return_ratios", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If True, also return the concentration ratios in addition to the windows." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "xp", "annotation": "array_namespace, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Optional array namespace. Should be compatible with the array API standard, or supported by array-api-compat. Default: " }, { "__type": "InlineCode", "__tag": 4051, "value": "numpy" } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "device: any", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "optional device specification for output. Should match one of the supported device specification in " }, { "__type": "InlineCode", "__tag": 4051, "value": "xp" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "DPSS (or Slepian sequences) are often used in multitaper power spectral density estimation (see " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": "). The first window in the sequence can be used to maximize the energy concentration in the main lobe, and is also called the Slepian window." } ] } ], "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/windows/_windows.py", "item_line": 1970, "item_type": "function", "aliases": [ "scipy.signal.windows.dpss" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "We can compare the window to `kaiser`, which was invented as an alternative\nthat was easier to calculate [3]_ (example adapted from\n`here `_):\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nimport matplotlib.pyplot as plt\nfrom scipy.signal import windows, freqz\nM = 51\nfig, axes = plt.subplots(3, 2, figsize=(5, 7))\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "for ai, alpha in enumerate((1, 3, 5)):\n win_dpss = windows.dpss(M, alpha)\n beta = alpha*np.pi\n win_kaiser = windows.kaiser(M, beta)\n for win, c in ((win_dpss, 'k'), (win_kaiser, 'r')):\n win /= win.sum()\n axes[ai, 0].plot(win, color=c, lw=1.)\n axes[ai, 0].set(xlim=[0, M-1], title=rf'$\\alpha$ = {alpha}',\n ylabel='Amplitude')\n w, h = freqz(win)\n axes[ai, 1].plot(w, 20 * np.log10(np.abs(h)), color=c, lw=1.)\n axes[ai, 1].set(xlim=[0, np.pi],\n title=rf'$\\beta$ = {beta:0.2f}',\n ylabel='Magnitude (dB)')\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "for ax in axes.ravel():\n ax.grid(True)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "axes[2, 1].legend(['DPSS', 'Kaiser'])\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "fig.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-50f320e542e85649.png" } }, { "__type": "Text", "__tag": 4046, "value": "\nAnd here are examples of the first four windows, along with their\nconcentration ratios:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "M = 512\nNW = 2.5\nwin, eigvals = windows.dpss(M, NW, 4, return_ratios=True)\nfig, ax = plt.subplots(1)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "ax.plot(win.T, linewidth=1.)\nax.set(xlim=[0, M-1], ylim=[-0.1, 0.1], xlabel='Samples',\n title=f'DPSS, {M:d}, {NW:0.1f}')\nax.legend([f'win[{ii}] ({ratio:0.4f})'\n for ii, ratio in enumerate(eigvals)])\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "fig.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-3000607ea3eb8ca8.png" } }, { "__type": "Text", "__tag": 4046, "value": "\nUsing a standard :math:`l_{\\infty}` norm would produce two unity values\nfor even `M`, but only one unity value for odd `M`. This produces uneven\nwindow power that can be counteracted by the approximate correction\n``M**2/float(M**2+NW)``, which can be selected by using\n``norm='approximate'`` (which is the same as ``norm=None`` when\n``Kmax=None``, as is the case here). Alternatively, the slower\n``norm='subsample'`` can be used, which uses subsample shifting in the\nfrequency domain (FFT) to compute the correction:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "Ms = np.arange(1, 41)\nfactors = (50, 20, 10, 5, 2.0001)\nenergy = np.empty((3, len(Ms), len(factors)))\nfor mi, M in enumerate(Ms):\n for fi, factor in enumerate(factors):\n NW = M / float(factor)\n # Corrected using empirical approximation (default)\n win = windows.dpss(M, NW)\n energy[0, mi, fi] = np.sum(win ** 2) / np.sqrt(M)\n # Corrected using subsample shifting\n win = windows.dpss(M, NW, norm='subsample')\n energy[1, mi, fi] = np.sum(win ** 2) / np.sqrt(M)\n # Uncorrected (using l-infinity norm)\n win /= win.max()\n energy[2, mi, fi] = np.sum(win ** 2) / np.sqrt(M)\nfig, ax = plt.subplots(1)\nhs = ax.plot(Ms, energy[2], '-o', markersize=4,\n markeredgecolor='none')\nleg = [hs[-1]]\nfor hi, hh in enumerate(hs):\n h1 = ax.plot(Ms, energy[0, :, hi], '-o', markersize=4,\n color=hh.get_color(), markeredgecolor='none',\n alpha=0.66)\n h2 = ax.plot(Ms, energy[1, :, hi], '-o', markersize=4,\n color=hh.get_color(), markeredgecolor='none',\n alpha=0.33)\n if hi == len(hs) - 1:\n leg.insert(0, h1[0])\n leg.insert(0, h2[0])\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "ax.set(xlabel='M (samples)', ylabel=r'Power / $\\sqrt{M}$')\nax.legend(leg, ['Uncorrected', r'Corrected: $\\frac{M^2}{M^2+NW}$',\n 'Corrected (subsample)'])\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "fig.tight_layout()\n", "execution_status": "success" } ], "title": [], "level": 0, "target": null }, "see_also": [], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "M", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "NW", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "Kmax", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "sym", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "True" }, { "__type": "SigParam", "__tag": 4030, "name": "norm", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "return_ratios", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "False" }, { "__type": "SigParam", "__tag": 4030, "name": "xp", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "device", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "dpss" }, "references": [ ".. [1] Percival DB, Walden WT. Spectral Analysis for Physical Applications:", " Multitaper and Conventional Univariate Techniques.", " Cambridge University Press; 1993.", ".. [2] Slepian, D. Prolate spheroidal wave functions, Fourier analysis, and", " uncertainty V: The discrete case. Bell System Technical Journal,", " Volume 57 (1978), 1371430.", ".. [3] Kaiser, JF, Schafer RW. On the Use of the I0-Sinh Window for", " Spectrum Analysis. IEEE Transactions on Acoustics, Speech and", " Signal Processing. ASSP-28 (1): 105-107; 1980." ], "qa": "scipy.signal.windows._windows:dpss", "arbitrary": [], "local_refs": [ "Kmax", "M", "NW", "device: any", "norm", "r", "return_ratios", "sym", "v", "xp" ] }