{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Strategy to compute a peak's prominence:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": true, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Extend a horizontal line from the current peak to the left and right until the line either reaches the window border (see " }, { "__type": "ParamRef", "__tag": 4071, "name": "wlen" }, { "__type": "Text", "__tag": 4046, "value": ") or intersects the signal again at the slope of a higher peak. An intersection with a peak of the same height is ignored." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "On each side find the minimal signal value within the interval defined above. These points are the peak's bases." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The higher one of the two bases marks the peak's lowest contour line. The prominence can then be calculated as the vertical difference between the peaks height itself and its lowest contour line." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Searching for the peak's bases can be slow for large " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": " with periodic behavior because large chunks or even the full signal need to be evaluated for the first algorithmic step. This evaluation area can be limited with the parameter " }, { "__type": "ParamRef", "__tag": 4071, "name": "wlen" }, { "__type": "Text", "__tag": 4046, "value": " which restricts the algorithm to a window around the current peak and can shorten the calculation time if the window length is short in relation to " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": ". However, this may stop the algorithm from finding the true global contour line if the peak's true bases are outside this window. Instead, a higher contour line is found within the restricted window leading to a smaller calculated prominence. In practice, this is only relevant for the highest set of peaks in " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": ". This behavior may even be used intentionally to calculate \"local\" prominences." } ] }, { "__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_prominences", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._peak_finding:peak_prominences" }, "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": "For indices in " }, { "__type": "ParamRef", "__tag": 4071, "name": "peaks" }, { "__type": "Text", "__tag": 4046, "value": " that don't point to valid local maxima in " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": ", the returned prominence will be 0 and this warning is raised. This also happens if " }, { "__type": "ParamRef", "__tag": 4071, "name": "wlen" }, { "__type": "Text", "__tag": 4046, "value": " is smaller than the plateau size of a peak." } ] } ] } ] } ], "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 a value in " }, { "__type": "ParamRef", "__tag": 4071, "name": "peaks" }, { "__type": "Text", "__tag": 4046, "value": " is an invalid index for " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] } ], "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": "prominences", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The calculated prominences for each peak in " }, { "__type": "ParamRef", "__tag": 4071, "name": "peaks" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "left_bases, right_bases", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The peaks' bases as indices in " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": " to the left and right of each peak. The higher base of each pair is a peak's lowest contour line." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Calculate the prominence 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": "wlen", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A window length in samples that optionally limits the evaluated area for each peak to a subset of " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": ". The peak is always placed in the middle of the window therefore the given length is rounded up to the next odd integer. This parameter can speed up the calculation (see Notes)." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The prominence of a peak measures how much a peak stands out from the surrounding baseline of the signal and is defined as the vertical distance between the peak and its lowest contour line." } ] } ], "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": 323, "item_type": "function", "aliases": [ "scipy.signal.peak_prominences" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy.signal import find_peaks, peak_prominences\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 prominences\n\n" }, { "__type": "Code", "__tag": 4050, "value": "peaks, _ = find_peaks(x)\nprominences = peak_prominences(x, peaks)[0]\nprominences\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nCalculate the height of each peak's contour line and plot the results\n\n" }, { "__type": "Code", "__tag": 4050, "value": "contour_heights = x[peaks] - prominences\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "plt.plot(x)\nplt.plot(peaks, x[peaks], \"x\")\nplt.vlines(x=peaks, ymin=contour_heights, ymax=x[peaks])\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-63d9933a7a2887b7.png" } }, { "__type": "Text", "__tag": 4046, "value": "\nLet's evaluate a second example that demonstrates several edge cases for\none peak at index 5.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "x = np.array([0, 1, 0, 3, 1, 3, 0, 4, 0])\npeaks = np.array([5])\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "plt.plot(x)\nplt.plot(peaks, x[peaks], \"x\")\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-cb4eff94c7fd326d.png" } }, { "__type": "Code", "__tag": 4050, "value": "peak_prominences(x, peaks) # -> (prominences, left_bases, right_bases)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nNote how the peak at index 3 of the same height is not considered as a\nborder while searching for the left base. Instead, two minima at 0 and 2\nare found in which case the one closer to the evaluated peak is always\nchosen. On the right side, however, the base must be placed at 6 because the\nhigher peak represents the right border to the evaluated area.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "peak_prominences(x, peaks, wlen=3.1)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nHere, we restricted the algorithm to a window from 3 to 7 (the length is 5\nsamples because `wlen` was rounded up to the next odd integer). Thus, the\nonly two candidates in the evaluated area are the two neighboring samples\nand a smaller prominence is calculated." } ], "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_widths", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._peak_finding:peak_widths" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Calculate the width 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": "wlen", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "peak_prominences" }, "references": [ ".. [1] Wikipedia Article for Topographic Prominence:", " https://en.wikipedia.org/wiki/Topographic_prominence" ], "qa": "scipy.signal._peak_finding:peak_prominences", "arbitrary": [], "local_refs": [ "left_bases", "peaks", "prominences", "right_bases", "wlen", "x" ] }