{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The basic algorithm to calculate a peak's width is as follows:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Calculate the evaluation height " }, { "__type": "InlineMath", "__tag": 4057, "value": "h_{eval}" }, { "__type": "Text", "__tag": 4046, "value": " with the formula " }, { "__type": "InlineMath", "__tag": 4057, "value": "h_{eval} = h_{Peak} - P \\cdot R" }, { "__type": "Text", "__tag": 4046, "value": ", where " }, { "__type": "InlineMath", "__tag": 4057, "value": "h_{Peak}" }, { "__type": "Text", "__tag": 4046, "value": " is the height of the peak itself, " }, { "__type": "InlineMath", "__tag": 4057, "value": "P" }, { "__type": "Text", "__tag": 4046, "value": " is the peak's prominence and " }, { "__type": "InlineMath", "__tag": 4057, "value": "R" }, { "__type": "Text", "__tag": 4046, "value": " a positive ratio specified with the argument " }, { "__type": "ParamRef", "__tag": 4071, "name": "rel_height" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Draw a horizontal line at the evaluation height to both sides, starting at the peak's current vertical position until the lines either intersect a slope, the signal border or cross the vertical position of the peak's base (see " }, { "__type": "CrossRef", "__tag": 4002, "value": "peak_prominences", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._peak_finding:peak_prominences" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " for an definition). For the first case, intersection with the signal, the true intersection point is estimated with linear interpolation." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Calculate the width as the horizontal distance between the chosen endpoints on both sides. As a consequence of this the maximal possible width for each peak is the horizontal distance between its bases." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "As shown above to calculate a peak's width its prominence and bases must be known. You can supply these yourself with the argument " }, { "__type": "ParamRef", "__tag": 4071, "name": "prominence_data" }, { "__type": "Text", "__tag": 4046, "value": ". Otherwise, they are internally calculated (see " }, { "__type": "CrossRef", "__tag": 4002, "value": "peak_prominences", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._peak_finding:peak_prominences" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ")." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 1.1.0" } ] } ] }, { "__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": "peak_widths", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._peak_finding:peak_widths" }, "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": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "", "annotation": "PeakPropertyWarning", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Raised if any calculated width is 0. This may stem from the supplied " }, { "__type": "ParamRef", "__tag": 4071, "name": "prominence_data" }, { "__type": "Text", "__tag": 4046, "value": " or if " }, { "__type": "ParamRef", "__tag": 4071, "name": "rel_height" }, { "__type": "Text", "__tag": 4046, "value": " is set to 0." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Raises": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "", "annotation": "ValueError", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "prominence_data" }, { "__type": "Text", "__tag": 4046, "value": " is supplied but doesn't satisfy the condition " }, { "__type": "InlineCode", "__tag": 4051, "value": "0 <= left_base <= peak <= right_base < x.shape[0]" }, { "__type": "Text", "__tag": 4046, "value": " for each peak, has the wrong dtype, is not C-contiguous or does not have the same shape." } ] } ] } ] } ], "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": "widths", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The widths for each peak in samples." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "width_heights", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The height of the contour lines at which the " }, { "__type": "CrossRef", "__tag": 4002, "value": "widths", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "widths" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " where evaluated." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "left_ips, right_ips", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Interpolated positions of left and right intersection points of a horizontal line at the respective evaluation height." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Calculate the width of each peak in a signal." } ] } ], "title": [], "level": 0, "target": null }, "Receives": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Warnings": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function may return unexpected results for data containing NaNs. To avoid this, NaNs should either be removed or replaced." } ] } ], "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": "sequence", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A signal with peaks." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "peaks", "annotation": "sequence", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Indices of peaks in " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "rel_height", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Chooses the relative height at which the peak width is measured as a percentage of its prominence. 1.0 calculates the width of the peak at its lowest contour line while 0.5 evaluates at half the prominence height. Must be at least 0. See notes for further explanation." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "prominence_data", "annotation": "tuple, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A tuple of three arrays matching the output of " }, { "__type": "CrossRef", "__tag": 4002, "value": "peak_prominences", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._peak_finding:peak_prominences" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " when called with the same arguments " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "ParamRef", "__tag": 4071, "name": "peaks" }, { "__type": "Text", "__tag": 4046, "value": ". This data are calculated internally if not provided." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "wlen", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A window length in samples passed to " }, { "__type": "CrossRef", "__tag": 4002, "value": "peak_prominences", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._peak_finding:peak_prominences" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " as an optional argument for internal calculation of " }, { "__type": "ParamRef", "__tag": 4071, "name": "prominence_data" }, { "__type": "Text", "__tag": 4046, "value": ". This argument is ignored if " }, { "__type": "ParamRef", "__tag": 4071, "name": "prominence_data" }, { "__type": "Text", "__tag": 4046, "value": " is given." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function calculates the width of a peak in samples at a relative distance to the peak's height and prominence." } ] } ], "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/_peak_finding.py", "item_line": 467, "item_type": "function", "aliases": [ "scipy.signal.peak_widths" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy.signal import chirp, find_peaks, peak_widths\nimport matplotlib.pyplot as plt\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nCreate a test signal with two overlaid harmonics\n\n" }, { "__type": "Code", "__tag": 4050, "value": "x = np.linspace(0, 6 * np.pi, 1000)\nx = np.sin(x) + 0.6 * np.sin(2.6 * x)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nFind all peaks and calculate their widths at the relative height of 0.5\n(contour line at half the prominence height) and 1 (at the lowest contour\nline at full prominence height).\n\n" }, { "__type": "Code", "__tag": 4050, "value": "peaks, _ = find_peaks(x)\nresults_half = peak_widths(x, peaks, rel_height=0.5)\nresults_half[0] # widths\nresults_full = peak_widths(x, peaks, rel_height=1)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "results_full[0] # widths\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nPlot signal, peaks and contour lines at which the widths where calculated\n\n" }, { "__type": "Code", "__tag": 4050, "value": "plt.plot(x)\nplt.plot(peaks, x[peaks], \"x\")\nplt.hlines(*results_half[1:], color=\"C2\")\nplt.hlines(*results_full[1:], color=\"C3\")\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "plt.show()\n", "execution_status": "success" }, { "__type": "Figure", "__tag": 4024, "value": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "1.17.1", "kind": "assets", "path": "fig-21c9e85b51df6ef1.png" } } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "find_peaks", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._peak_finding:find_peaks" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Find peaks inside a signal based on peak properties." } ] } ], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "peak_prominences", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._peak_finding:peak_prominences" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Calculate the prominence of peaks." } ] } ], "type": "func" } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "x", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "peaks", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "rel_height", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "0.5" }, { "__type": "SigParam", "__tag": 4030, "name": "prominence_data", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "wlen", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "peak_widths" }, "references": null, "qa": "scipy.signal._peak_finding:peak_widths", "arbitrary": [], "local_refs": [ "left_ips", "peaks", "prominence_data", "rel_height", "right_ips", "width_heights", "widths", "wlen", "x" ] }