{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For a given window and " }, { "__type": "ParamRef", "__tag": 4071, "name": "hop" }, { "__type": "Text", "__tag": 4046, "value": " interval, all possible dual windows are expressed by the " }, { "__type": "ParamRef", "__tag": 4071, "name": "hop" }, { "__type": "Text", "__tag": 4046, "value": " linear conditions of Eq. " }, { "__type": "InlineRole", "__tag": 4003, "value": "eq_STFT_AllDualWinsCond", "domain": "math", "role": "numref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " 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": ". Hence, decreasing " }, { "__type": "ParamRef", "__tag": 4071, "name": "hop" }, { "__type": "Text", "__tag": 4046, "value": ", increases the number of degrees of freedom of the set of all possible dual windows, improving the ability to better approximate a " }, { "__type": "ParamRef", "__tag": 4071, "name": "desired_dual" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function can also be used to determine windows which fulfill the so-called \"Constant OverLap Add\" (COLA) condition " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": ". It states that summing all touching window values at any given sample position results in the same constant " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\alpha" }, { "__type": "Text", "__tag": 4046, "value": ". Eq. " }, { "__type": "InlineRole", "__tag": 4003, "value": "eq_STFT_AllDualWinsCond", "domain": "math", "role": "numref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " shows that this is equal to having a rectangular dual window, i.e., the dual being " }, { "__type": "InlineCode", "__tag": 4051, "value": "alpha*np.ones(m)" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Some examples of windows that satisfy COLA (taken from " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": "):" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Rectangular window at overlap of 0, 1/2, 2/3, 3/4, ..." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Bartlett window at overlap of 1/2, 3/4, 5/6, ..." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Hann window at 1/2, 2/3, 3/4, ..." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Any Blackman family window at 2/3 overlap" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Any window with " }, { "__type": "InlineCode", "__tag": 4051, "value": "hop=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": "closest_STFT_dual_window", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._short_time_fft:closest_STFT_dual_window" }, "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": "dual_win", "annotation": "np.ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A dual window of " }, { "__type": "InlineCode", "__tag": 4051, "value": "alpha*win" }, { "__type": "Text", "__tag": 4046, "value": " (with hop interval " }, { "__type": "ParamRef", "__tag": 4071, "name": "hop" }, { "__type": "Text", "__tag": 4046, "value": "), which is closest to " }, { "__type": "ParamRef", "__tag": 4071, "name": "desired_dual" }, { "__type": "Text", "__tag": 4046, "value": ". Note that the dual window of " }, { "__type": "ParamRef", "__tag": 4071, "name": "win" }, { "__type": "Text", "__tag": 4046, "value": " is " }, { "__type": "InlineRole", "__tag": 4003, "value": "dual_win/alpha", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " and that the dual window of " }, { "__type": "CrossRef", "__tag": 4002, "value": "dual_win", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "dual_win" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " is " }, { "__type": "InlineRole", "__tag": 4003, "value": "alpha*win", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ". " }, { "__type": "CrossRef", "__tag": 4002, "value": "dual_win", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "dual_win" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " has the same shape as " }, { "__type": "ParamRef", "__tag": 4071, "name": "win" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineRole", "__tag": 4003, "value": "desired_win", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "alpha", "annotation": "float | complex", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Scale factor for " }, { "__type": "ParamRef", "__tag": 4071, "name": "win" }, { "__type": "Text", "__tag": 4046, "value": ". It is always one if " }, { "__type": "ParamRef", "__tag": 4071, "name": "scaled" }, { "__type": "Text", "__tag": 4046, "value": " is set to " }, { "__type": "InlineCode", "__tag": 4051, "value": "False" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Calculate the STFT dual window of a given window closest to a desired dual window." } ] } ], "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": "desired_dual: np.ndarray | None", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The desired dual window must be a 1d array of the same length as " }, { "__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": " (default), then " }, { "__type": "ParamRef", "__tag": 4071, "name": "desired_dual" }, { "__type": "Text", "__tag": 4046, "value": " is assumed to be the rectangular window, i.e., " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.ones_like(win)" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "scaled", "annotation": "bool", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If set (default), the closest scaled version instead of closest dual window is calculated." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For a given short-time Fourier transform window " }, { "__type": "ParamRef", "__tag": 4071, "name": "win" }, { "__type": "Text", "__tag": 4046, "value": " incremented by " }, { "__type": "ParamRef", "__tag": 4071, "name": "hop" }, { "__type": "Text", "__tag": 4046, "value": " samples, the dual window is calculated, which minimizes " }, { "__type": "InlineCode", "__tag": 4051, "value": "abs(dual_win - desired_dual)**2" }, { "__type": "Text", "__tag": 4046, "value": " when " }, { "__type": "ParamRef", "__tag": 4071, "name": "scaled" }, { "__type": "Text", "__tag": 4046, "value": " is " }, { "__type": "InlineCode", "__tag": 4051, "value": "False" }, { "__type": "Text", "__tag": 4046, "value": ". For " }, { "__type": "ParamRef", "__tag": 4071, "name": "scaled" }, { "__type": "Text", "__tag": 4046, "value": " set to " }, { "__type": "InlineCode", "__tag": 4051, "value": "True" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "abs(alpha*dual_win - desired_dual)**2" }, { "__type": "Text", "__tag": 4046, "value": " is minimized with " }, { "__type": "CrossRef", "__tag": 4002, "value": "alpha", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "alpha" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " being the optimal scaling factor. A " }, { "__type": "InlineCode", "__tag": 4051, "value": "ValueError" }, { "__type": "Text", "__tag": 4046, "value": " is raised if no valid dual window can be determined." } ] } ], "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": 72, "item_type": "function", "aliases": [ "scipy.signal.closest_STFT_dual_window" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "Let's show that a Bartlett window with 75% overlap fulfills the COLA condition:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import matplotlib.pyplot as plt\nimport numpy as np\nfrom scipy.signal import closest_STFT_dual_window, windows\nm = 24\nwin, w_rect = windows.bartlett(m, sym=False), np.ones(m)\nd_win, alpha = closest_STFT_dual_window(win, m//4, w_rect, scaled=True)\nprint(f\"COLA: {np.allclose(d_win, w_rect*alpha)}, {alpha = :g}\")\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nWe can also determine for which hop intervals the COLA condition is fulfilled:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "hops, deviations, alphas = np.arange(1, 16, dtype=int), [], []\nfor h_ in hops:\n w_cola, alpha = closest_STFT_dual_window(w_rect, h_, win, scaled=True)\n deviations.append(np.linalg.norm(w_cola - win*alpha))\n alphas.append(alpha)\nfg0, (ax0, ax1) = plt.subplots(2, 1, sharex='all', tight_layout=True)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "ax0.set_title(f\"COLA Window closest to a {m}-Sample Bartlett Window\")\nax0.set(ylabel=r\"$||w_\\text{cola}-\\alpha w||$\", xlim=(0, hops[-1]-.5))\nax1.set(xlabel=\"Hop Interval\", ylabel=r\"Scaling factor $\\alpha$\",\n ylim=(0, 1.25))\nax0.plot(hops, deviations, 'C0.-')\nax1.plot(hops, alphas, 'C1.-')\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "for ax_ in (ax0, ax1):\n ax_.grid()\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-f6868e851f8596cd.png" } }, { "__type": "Text", "__tag": 4046, "value": "\nThe lower plot shows the calculated scaling factor :math:`\\alpha` for different\n`hops` whereas the upper displays the :math:`L^2`-norm of the difference\nbetween the scaled Bartlett window and the calculated window. Since for `hops`\n1 to 4 as well as for 6 and 12 the :math:`L^2`-norm of the difference is\npractically zero, the COLA condition is fulfilled for those." } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "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": "Short-time Fourier transform which is able to utilize a dual window for calculating the inverse." } ] } ], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "ShortTimeFFT.from_win_equals_dual", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "ShortTimeFFT.from_win_equals_dual" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Create instance where the window and its dual are equal." } ] } ], "type": "func" } ], "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": "desired_dual", "annotation": "np.ndarray | None", "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "scaled", "annotation": "bool", "kind": "KEYWORD_ONLY", "default": "True" } ], "return_annotation": "tuple[np.ndarray, float | complex]", "target_name": "closest_STFT_dual_window" }, "references": [ ".. [1] Julius O. Smith III, \"Spectral Audio Signal Processing\",", " online book, 2011, https://www.dsprelated.com/freebooks/sasp/", ".. [2] G. Heinzel, A. Ruediger and R. Schilling, \"Spectrum and spectral density", " estimation by the Discrete Fourier transform (DFT), including a", " comprehensive list of window functions and some new at-top windows\",", " 2002, http://hdl.handle.net/11858/00-001M-0000-0013-557A-5" ], "qa": "scipy.signal._short_time_fft:closest_STFT_dual_window", "arbitrary": [], "local_refs": [ "alpha", "desired_dual: np.ndarray | None", "dual_win", "hop", "scaled", "win" ] }