Документация Engee

findpeaks

Находит локальные максимумы.

Библиотека

EngeeDSP

Синтаксис

Вызов функции

  • pks = findpeaks(y) — возвращает вектор с локальными максимумами (пиками) вектора входного сигнала y. Локальный пик — это отсчеты данных, которые либо больше двух соседних отсчетов, либо равны Inf. Пики выводятся в порядке их появления. Конечные точки сигнала, отличные от Inf, исключаются. Если пик плоский, то функция возвращает только точку с наименьшим индексом.

  • pks, locs = findpeaks(y) — также возвращает индексы locs, при которых возникают пики.

  • pks, locs, w, p = findpeaks(y) — также возвращает ширину пиков в виде вектора w и их возвышение в виде вектора p.

  • ___ = findpeaks(y, x) — использует x в качестве вектора местоположения и возвращает любой из выходных аргументов из предыдущих вариантов синтаксиса. Выходные аргументы locs и w выражаются через x.

  • ___ = findpeaks(y, Fs) — использует частоту дискретизации данных Fs. Предполагается, что первый отсчет y был получен в момент времени ноль. Выходные аргументы locs и w выражаются через единицы времени.

  • ___ = findpeaks(___, Name=Value) — также использует аргументы Name=Value в дополнение к любым входным аргументам, представленным в предыдущих синтаксисах.

  • findpeaks(___) — без выходных аргументов строит график сигнала и накладывает пиковые значения.

Аргументы

Входные аргументы

# y — входные данные
вектор

Details

Входные данные, заданные как вектор с вещественными элементами. Количество элементов в векторе y должно быть не менее трех.

Типы данных

Float32, Float64

# x — местоположения
вектор

Details

Местоположения, заданные как вектор той же длины, что и y. Значения в векторе x должны монотонно возрастать. Если аргумент x не задан, то в качестве местоположений используются индексы y.

Типы данных

Float32, Float64

# Fs — максимальный размер окна корреляции
скаляр

Details

Частота дискретизации, заданная как положительный скаляр. Частота дискретизации — это количество отсчетов в единицу времени. Если единицей времени являются секунды, то частота дискретизации измеряется в Гц.

Типы данных

Float32, Float64

Входные аргументы «имя-значение»

Укажите необязательные пары аргументов в формате Name=Value, где Name — имя аргумента, а Value — соответствующее значение. Аргументы типа Name=Value должны располагаться после других аргументов, но порядок пар не имеет значения.

# Npeaks — максимальное число пиков
скаляр

Details

Максимальное количество пиков для возврата, заданное как положительное целое число. Функция findpeaks работает с первого элемента входных данных и завершает работу, когда количество пиков достигает значения NPeaks.

Типы данных

Float32, Float64

# SortStr — сортировка пиков
"none" (по умолчанию) | "ascend" | "descend"

Details

Сортировка пиков, заданная одним из следующих значений:

  • "none" — возвращает пики в порядке их появления во входных данных;

  • "ascend" — возвращает пики в порядке возрастания, от наименьшего значения к наибольшему;

  • "descend" — возвращает пики в порядке убывания, от наибольшего значения к наименьшему.

# MinPeakHeight — минимальная высота пика
-inf (по умолчанию) | скаляр

Details

Минимальная высота пика, заданная как вещественный скаляр. Используйте этот аргумент, чтобы функция findpeaks возвращала только пики, превышающие MinPeakHeight. Указание минимальной высоты пика может сократить время обработки.

Типы данных

Float32, Float64

# MinPeakProminence — минимальное возвышение пика
0 (по умолчанию) | скаляр

Details

Минимальное возвышение пика, заданное как неотрицательный вещественный скаляр. Используйте этот аргумент, чтобы findpeaks возвращала только те пики, относительное возвышение которых не менее MinPeakProminence. Подробнее см. в разделе Возвышения.

Типы данных

Float32, Float64

# Threshold — минимальная разница высот
0 (по умолчанию) | скаляр

Details

Минимальная разница высот между пиком и его соседями, заданная как неотрицательный вещественный скаляр. Используйте этот аргумент, чтобы findpeaks возвращала только те пики, значения которых превышают значения ближайших соседних пиков как минимум на значение Threshold.

Типы данных

Float32, Float64

# MinPeakDistance — минимальное расстояние между пиками
0 (по умолчанию) | скаляр

Details

Минимальное расстояние между пиками, заданное как положительный вещественный скаляр. При указании значения MinPeakDistance алгоритм выбирает самый высокий пик сигнала и игнорирует все пики в пределах расстояния MinPeakDistance от него. Затем функция повторяет процедуру для самого высокого оставшегося пика и выполняет итерации до тех пор, пока не закончатся пики для рассмотрения.

  • Если указан вектор местоположения x, то MinPeakDistance должно быть выражено через x.

  • Если указана частота дискретизации Fs, то MinPeakDistance должно быть выражено в единицах времени.

  • Если не указан ни x, ни Fs, то MinPeakDistance должно быть выражено в единицах отсчетов.

Используйте этот аргумент, чтобы findpeaks игнорировала небольшие пики, возникающие поблизости от большего пика.

Типы данных

Float32, Float64

# WidthReference — опорная высота для измерений ширины
"halfprom" (по умолчанию) | "halfheight"

Details

Опорная высота для измерений ширины, заданная как "halfprom" или "halfheight". Функция findpeaks оценивает ширину пика как расстояние между точками пересечения нисходящего сигнала с горизонтальной опорной линией. Высота линии выбирается с использованием критерия, заданного в аргументе WidthReference:

  • "halfprom" — размещает опорную линию под пиком на вертикальном расстоянии, равном половине возвышения пика. Подробнее см. в разделе Возвышения;

  • "halfheight" — размещает опорную линию на половине высоты пика. Линия усекается, если какая-либо из ее точек пересечения лежит за границами пиков, выбранных аргументами MinPeakHeight, MinPeakProminence и Threshold. Граница между пиками определяется горизонтальным положением самой низкой впадины между ними. Пики с высотой меньше нуля отбрасываются.

Положение точек пересечения вычисляется линейной интерполяцией.

# MinPeakWidth — максимальная ширина пика
0 (по умолчанию) | скаляр

Details

Минимальная ширина пика, заданная как положительный вещественный скаляр. Используйте этот аргумент, чтобы выбрать только пики с шириной не менее MinPeakWidth.

  • Если указан вектор местоположения x, то MinPeakWidth должно быть выражено через x.

  • Если указана частота дискретизации Fs, то MinPeakWidth должно быть выражено в единицах времени.

  • Если не указан ни x, ни Fs, то MinPeakWidth должно быть выражено в единицах отсчетов.

Типы данных

Float32, Float64

# MaxPeakWidth — максимальная ширина пика
Inf (по умолчанию) | скаляр

Details

Максимальная ширина пика, заданная как положительный вещественный скаляр. Используйте этот аргумент, чтобы выбрать только пики с шириной не более MaxPeakWidth.

  • Если указан вектор местоположения x, то MaxPeakWidth должно быть выражено через x.

  • Если указана частота дискретизации Fs, то MaxPeakWidth должно быть выражено в единицах времени.

  • Если не указан ни x, ни Fs, то MaxPeakWidth должно быть выражено в единицах отсчетов.

Типы данных

Float32, Float64

# Annotate — стиль графика
"peaks" (по умолчанию) | "extents"

Details

Стиль графика, заданный как:

  • "peaks" — строит график сигнала и аннотирует местоположение и значение каждого пика;

  • "extents" — строит график сигнала и аннотирует местоположение, значение, ширину и выраженность каждого пика.

Этот аргумент игнорируется при вызове findpeaks с выходными аргументами.

# out — тип выходных данных
:plot (по умолчанию) | :data

Details

Тип выходных данных:

  • :plot — функция возвращает график;

  • :data — функция возвращает данные.

Выходные аргументы

# pks — локальные максимумы
вектор

Details

Локальные максимумы, возвращаемые в виде вектора значений сигнала. Если локальных максимумов нет, то pks пуст.

# locs — местоположения пиков
вектор

Details

Положения пиков, возвращаемые в виде вектора.

  • Если указан вектор местоположения x, то locs содержит значения x в индексах пиков.

  • Если указана частота дискретизации Fs, то locs представляет собой числовой вектор моментов времени с разницей во времени 1/Fs между последовательными отсчетами.

  • Если не указан ни x, ни Fs, то locs представляет собой вектор целочисленных индексов.

# w — ширина пиков
вектор

Details

Положения пиков, возвращаемые в виде вектора вещественных чисел. Ширина каждого пика вычисляется как расстояние между точками слева и справа от пика, где сигнал пересекает опорную линию, высота которой задается аргументом WidthReference. Сами точки находятся путем линейной интерполяции.

  • Если указан вектор местоположения x, то w выражается через x.

  • Если указана частота дискретизации Fs, то w выражается в единицах времени.

  • Если не указан ни x, ни Fs, то w выражается в единицах отсчетов.

# p — возвышения пиков
вектор

Details

Возвышения пиков, возвращаемые в виде вектора вещественных чисел. Возвышение пика — это минимальное вертикальное расстояние, на которое сигнал должен опуститься по обе стороны от пика, прежде чем снова подняться на уровень выше пика или достичь конечной точки. Подробнее см. в разделе Возвышения.

Примеры

Нахождение пиков в векторе значений

Details

Создадим вектор значений и найдем в нем пики, построим график и укажем на нем пиковые значения.

import EngeeDSP.Functions: findpeaks

data = [25, 8, 15, 5, 6, 10, 10, 3, 1, 20, 7]

findpeaks(data)

findpeaks 2

Добавим на график местоположение, значение, ширину и выраженность каждого пика.

import EngeeDSP.Functions: findpeaks

data = [25, 8, 15, 5, 6, 10, 10, 3, 1, 20, 7]

findpeaks(data, Annotate="extents")

findpeaks 3

Будем учитывать только пики с минимальной шириной 1.5.

import EngeeDSP.Functions: findpeaks

data = [25, 8, 15, 5, 6, 10, 10, 3, 1, 20, 7]

findpeaks(data, Annotate="extents", MinPeakWidth=1.5)

findpeaks 4

Дополнительно

Возвышения

Details

Возвышение пика измеряет, насколько он выделяется благодаря своей высоте и расположению относительно других пиков. Низкий изолированный пик может быть более выраженным, чем тот, который выше, но в остальном ничем не выделяется в диапазоне высоких пиков.

Чтобы измерить возвышение пика:

  1. Поместите маркер на пик.

  2. Проведите горизонтальную линию от пика влево и вправо, пока линия не выполнит одно из следующих условий:

    • Пересечет сигнал, поскольку есть более высокий пик;

    • Достигнет левого или правого конца сигнала.

  3. Найдите минимум сигнала в каждом из двух интервалов, определенных на шаге 2. Эта точка является либо впадиной, либо одной из конечных точек сигнала.

  4. Более высокий из двух минимумов интервала определяет опорный уровень. Высота пика над этим уровнем является его возвышением.

Функция findpeaks не делает никаких предположений о поведении сигнала за пределами его конечных точек, независимо от их высоты. В результате шаги 2 и 4 не учитывают поведение сигнала за пределами конечных точек, что часто влияет на значение референтного уровня. Рассмотрим, например, пики этого сигнала:

findpeaks 1

Номер пика Левый интервал лежит между пиком и …​ Правый интервал лежит между пиком и …​ Самая низкая точка на левом интервале Самая низкая точка на правом интервале Уровень начала отсчета (максимальный минимум)

1

Левый конец

Пересечение из-за пика 2

Левая конечная точка

a

a

2

Левый конец

Правый конец

Левая конечная точка

h

Левая конечная точка

3

Пересечение из-за пика 2

Пересечение из-за пика 4

b

c

c

4

Пересечение из-за пика 2

Пересечение из-за пика 6

b

d

b

5

Пересечение из-за пика 4

Пересечение из-за пика 6

d

e

e

6

Пересечение из-за пика 2

Правый конец

d

h

d

7

Пересечение из-за пика 6

Пересечение из-за пика 8

f

g

g

8

Пересечение из-за пика 6

Правый конец

f

h

f

9

Пересечение из-за пика 6

Пересечение из-за правой конечной точки

h

i

i