学习笔记: `scipy.signal.find_peaks` 寻峰函数

scipy.signal.find_peaks 寻峰函数

''' 寻峰
find_peaks: Find peaks inside a signal based on peak properties.
(function) def find_peaks(
    x: Any,
    height: Any | None = None,
    threshold: Any | None = None,
    distance: Any | None = None,
    prominence: Any | None = None,
    width: Any | None = None,
    wlen: Any | None = None,
    rel_height: float = 0.5,
    plateau_size: Any | None = None
) -> tuple[Any, dict]
在具有峰属性的信号中寻找峰值。

该函数接受一个1-D数组，并通过简单比较相邻值来找到所有局部最大值。可选地，可以通过指定峰值属性的条件来选择这些峰值的子集。

参数

    x: 峰信号 序列
        一个带有峰值的信号。
    height: 高 数字或ndarray或序列, 可选
        峰值的所需高度。一个数字，None，一个匹配x的数组或前者的2元序列(第一个元素总是被解释为最小值，第二个元素（如果提供）被解释为最大所需高度)。
    threshold: 阈值 数字或ndarray或序列, 可选
        峰值所需的阈值，即其相邻样本的垂直距离。一个数字，None，一个匹配x的数组或前者的2元序列(第一个元素总是被解释为最小值，第二个元素（如果提供）被解释为最大所需阈值)。
    distance: 距离 数字, 可选
        相邻峰值之间的所需最小水平距离(>= 1)。较小的峰值首先被删除，直到所有剩余的峰值都满足该条件。
    prominence: 显著性 数字或ndarray或序列, 可选
        峰值的所需显著性，即其相邻样本的垂直距离。一个数字，None，一个匹配x的数组或前者的2元序列(第一个元素总是被解释为最小值，第二个元素（如果提供）被解释为最大所需显著性)。
    width: 宽度 数字或ndarray或序列, 可选
        峰值的所需宽度，即其相邻样本的水平距离。一个数字，None，一个匹配x的数组或前者的2元序列(第一个元素总是被解释为最小值，第二个元素（如果提供）被解释为最大所需宽度)。
    wlen: 窗口长度 数字, 可选
        用于计算峰值宽度的窗口长度。默认值为宽度的1/10。
    rel_height: 相对高度 数字, 可选
        用于计算峰值宽度的相对高度。默认值为0.5。
    plateau_size: 平台大小 数字, 可选
        用于计算峰值宽度的平台大小。默认值为1。

返回

    peaks: 峰值序列 ndarray
        满足所有给定条件的x中的峰值的索引。
    properties: 属性 字典
        包含返回的峰值的属性的字典，这些属性在计算指定条件的评估过程中作为中间结果计算出来:
            'peak_heights' 如果给出了height，则为x中每个峰值的高度。
            'left_thresholds', 'right_thresholds' 如果给出了threshold，则可以访问这些键，它们包含峰值到其相邻样本的垂直距离。
            'prominences', 'right_bases', 'left_bases' 如果给出了prominence，则可以访问这些键。请参阅peak_prominences以获取其内容的描述。
            'width_heights', 'left_ips', 'right_ips' 如果给出了width，则可以访问这些键。请参阅peak_widths以获取其内容的描述。
            'plateau_sizes', left_edges', 'right_edges' 如果给出了plateau_size，则可以访问这些键，并包含峰值边缘的索引(边缘仍然是平台的一部分)和计算出的平台大小。
Warns
PeakPropertyWarning
    若一个或多个峰值属性的条件无法满足，则会发出警告。(见`prominence`height`width`的警告)

Warning
    该函数对于包含NaN的数据，可能会返回意外的结果。为了避免这种情况，应该删除或替换NaN。

其他参见
    `find_peaks_cwt`
        使用小波变换查找峰值。
    `peak_prominences`
        直接计算峰值的显著性。
    `peak_widths`
        直接计算峰值的宽度。

注意
    在这个函数的上下文中，峰值或局部最大值被定义为任何两个直接邻居的样本都具有较小振幅的样本。对于平坦的峰值(宽度大于一个样本的等幅)，返回中间样本的索引(如果样本数是偶数，则向下取整)。对于噪声信号，峰值位置可能会偏离，因为噪声可能会改变局部最大值的位置。在这些情况下，考虑在搜索峰值之前对信号进行平滑，或者使用其他峰值查找和拟合方法(如find_peaks_cwt)。

关于指定条件的一些附加说明:

    几乎所有的条件(不包括距离)都可以给出半开或闭区间，例如，1或(1，None)定义了半开区间[1，\infty]，而(None，1)定义了区间[-\infty，1]。 也可以指定开放间隔（None，None），它返回匹配属性而不排除峰值。
    边界总是包含在用于选择有效峰值的区间中的。
    对于几个条件，区间边界可以用与x匹配的形状数组指定，这样就可以根据样本位置动态地约束。
    条件是按以下方式计算的: plateau_size、height、threshold、distance、prominence、width。在大多数情况下，这个顺序是最快的，因为优先级高的条件可以用来排除峰值，从而减少计算量。
    虽然峰值中的索引保证至少相距distance个样本，但平坦峰的边缘可能比允许的距离更近。
    如果x很大或有很多个局部最大值(参见`prominence`)，使用wlen来减少计算显著性或宽度的时间。

Examples

#%% 为了演示这个函数的用法，我们使用SciPy提供的一个信号x(参见scipy.datasets.electrocardiogram)。
# (这个信号包含一个心电图，我们将使用它来演示如何找到峰值。)
import numpy as np
import matplotlib.pyplot as plt
from scipy.datasets import electrocardiogram
from scipy.signal import find_peaks
#%% 让我们找到x中所有振幅高于0的峰值(局部最大值)。
x = electrocardiogram()[2000:4000]
peaks, _ = find_peaks(x, height=0)
plt.plot(x)
plt.plot(peaks, x[peaks], "x") # 画出峰值
plt.plot(np.zeros_like(x), "--", color="gray") # 画出基线0
plt.show()
#%% 使用`height`参数。

```python
# 设height=(None, 0)，这样就可以选择所有峰值, 或者使用array(如👇)匹配x的大小来反映不同部分的变化条件。
border = np.sin(np.linspace(0, 3 * np.pi, x.size))
peaks, _ = find_peaks(x, height=(-border, border))
plt.plot(x)
plt.plot(-border, "--", color="gray")
plt.plot(border, ":", color="gray")
plt.plot(peaks, x[peaks], "x")
plt.show()

#%% 对于周期信号另一个有用的选择是`distance`参数.
# 在这个案例中，我们可以很容易地从心电图 (ECG) 中的 QRS 复合波要求距离至少为150选择样本的位置 。
peaks, _ = find_peaks(x, distance=150)
np.diff(peaks) # 差分
# array([186, 180, 177, 171, 177, 169, 167, 164, 158, 162, 172])
plt.plot(x)
plt.plot(peaks, x[peaks], "x")
plt.show()
# peaks array([ 49, 302, 515, 691, 909])

#%% `prominences`特别是对于噪声信号峰值可以很容易地按其分组
# （见peak_prominences）例如，我们可以选择除 对于上述 QRS 波群，将允许的突出度限制为 0.6。
peaks, properties = find_peaks(x, prominence=(None, 0.6))
properties["prominences"].max()
# 0.5049999999999999
plt.plot(x)
plt.plot(peaks, x[peaks], "x")
plt.show()

#%% 最后， `prominence=1, width=20`
# 让我们检查一下心电图的不同部分，其中包含不同形状的节拍形式。
# 为了仅选择非典型心跳，我们结合👆🏻两个条件
x = electrocardiogram()[17000:18000]
peaks, properties = find_peaks(x, prominence=1, width=20)
properties["prominences"], properties["widths"]
#   # array([1.495, 2.3  ]), array([36.93773946, 39.32723577]))
plt.plot(x)
plt.plot(peaks, x[peaks], "x")
plt.vlines(x=peaks, ymin=x[peaks] - properties["prominences"],
           ymax = x[peaks], color = "C1")
plt.hlines(y=properties["width_heights"], xmin=properties["left_ips"],
           xmax=properties["right_ips"], color = "C1")
plt.show()

翻译: scipy自带的文档