What is the mechanism or math behind the function islocalmax(A)?

42 views (last 30 days)
What is the mechanism or math behind the function islocalmax(A)?
I just refer to the the basic islocalmax(A) function, without any additional input or option.
An example:
x = 1:100;
A = (1-cos(2*pi*0.01*x)).*sin(2*pi*0.15*x);
TF = islocalmax(A);
plot(x,A,x(TF),A(TF),'r*')
Also, if I open islocalmax in Matlab
>> open islocalmax
I just get the following code (so not additional information):
% Copyright 2017-2022 The MathWorks, Inc.
if nargout > 1
[tf, P] = matlab.internal.math.isLocalExtrema(A, true, varargin{:});
else
tf = matlab.internal.math.isLocalExtrema(A, true, varargin{:});
end
  4 Comments

Sign in to comment.

Accepted Answer

John D'Errico
John D'Errico on 8 Nov 2023
Edited: John D'Errico on 8 Nov 2023
Someone who is not an employee of TMW cannot see the code. (I can't, as I am not an employee.) And if someone is an employee, they generally do not give specifics of code that is not an m-file. But, this is one of those simple codes that are mainly simple heuristics, an ad hoc algorithm that gets the job done. Nothing more is needed. And a basic rule when writing code is that if a simple code is sufficient, then just write the simple code. Get the job done, and move onto more difficult problems.
help islocalmax
ISLOCALMAX Detect local maxima in data. TF = ISLOCALMAX(A) returns a logical array whose elements are true when a local maximum is detected in the corresponding element of A. If A is a matrix or a table, ISLOCALMAX operates on each column separately. If A is an N-D array, ISLOCALMAX operates along the first array dimension whose size does not equal 1. TF = ISLOCALMAX(A,DIM) specifies the dimension to operate along. TF = ISLOCALMAX(...,'MinProminence',P) returns only those local maxima whose prominence is at least P. The prominence of a local maximum is the smaller of the largest decrease in value on the left side and on the right side of the local maximum before encountering a larger local maximum. For a vector X, the largest prominence is at most MAX(X)-MIN(X). TF = ISLOCALMAX(...,'FlatSelection',F) specifies how local maxima are indicated for flat regions containing repeated local maxima values. F must be: 'center' - (default) middle index of a flat region marked as true. 'first' - first index of a flat region marked as true. 'last' - last index of a flat region marked as true. 'all' - all flat region indices marked as true. TF = ISLOCALMAX(...,'MinSeparation',S) specifies S as the minimum separation between local maxima. S is defined in units of the sample points. When S > 0, ISLOCALMAX selects the largest local maximum and ignores all other local maximum within S units of it. The process is repeated until there are no more local maxima detected. By default, S = 0. TF = ISLOCALMAX(...,'MaxNumExtrema',N) detects no more than the N most prominent local maxima. By default, N is equal to SIZE(A,DIM). TF = ISLOCALMAX(...,'SamplePoints',X) specifies the sample points X representing the location of the data in A. X must be a numeric or datetime vector, and must be sorted with unique elements. If the first input is a table, X can also specify a table variable. For example, X can specify time stamps for the data in A. By default, ISLOCALMAX uses data sampled uniformly at points X = [1 2 3 ... ]. TF = ISLOCALMAX(...,'ProminenceWindow',K) for a positive scalar K computes the prominence of each local maxima only within a window of width K centered around the maxima. For flat regions, the window extends K/2 units before the first point in the region and K/2 units after the last point in the region. TF = ISLOCALMAX(...,'ProminenceWindow',[NB NF]) for non-negative scalars NB and NF computes the prominence of each local maxima only within a window from NB units before the local maxima to NF units after it. For flat regions, the window extends NB units before the first point in the region and NF units after the last point in the region. If 'SamplePoints' are specified, the units of the prominence window are relative to the sample points. [TF,P] = ISLOCALMAX(A,...) also returns the prominence for each value of A. Points that are not local maxima have a prominence of 0. Arguments supported only when first input is table or timetable: TF = ISLOCALMAX(...,'DataVariables',DV) finds local maxima only in the table variables specified by DV. The default is all table variables in A. DV must be a table variable name, a cell array of table variable names, a vector of table variable indices, a logical vector, a function handle that returns a logical scalar (such as @isnumeric), or a table vartype subscript. TF has the same size as A. DV cannot be specified if A is not a table or a timetable. Only numeric or logical data variables should be specified. TF = ISLOCALMAX(...,'OutputFormat',FORMAT) specifies the format for the output TF with respect to the table variables. FORMAT must be: 'logical'- (default) TF is a logical array matching the size of A. 'tabular' - TF is a table or timetable that is the same height as A with logical variables corresponding to specified table variables EXAMPLE: Find local maxima in a vector of data. x = 1:100; A = (1-cos(2*pi*0.01*x)).*sin(2*pi*0.15*x); tf = islocalmax(A); EXAMPLE: Filter out less prominent local maxima. A = peaks(256); A = A(:, 150); tf = islocalmax(A, 'MinProminence', 1); EXAMPLE: Filter out local maxima too close to each other in time. t = hours(linspace(0, 3, 15)); A = [2 4 6 4 3 7 5 6 5 10 4 -1 -3 -2 0]; S = minutes(45); tf = islocalmax(A, 'MinSeparation', S, 'SamplePoints', t); EXAMPLE: Detect center points of flat maxima regions. x = 0:0.1:10; A = min(0.75, sin(pi*x)); tf = islocalmax(A, 'FlatSelection', 'center'); See also islocalmin, ischange, isoutlier, max, maxk Documentation for islocalmax doc islocalmax Other uses of islocalmax gpuArray/islocalmax tall/islocalmax
As such, the islocalmax function detects if both immediate neighbors of an element are less than the element in the middle. So, without any parameters set, all that is required should be a tiny amount of excess.
A little experimentation should be sufficient to determine the basic rules the code will follow.
V = [4 2 2 3 1 2];
islocalmax(V)
ans = 1×6 logical array
0 0 0 1 0 0
So only the number 3 was flagged. An element at the end can not be a local max, by that definition, since the immediate elements on either side are not less than it.
This next test shows that an inequality is required. All elements of a constant vector are not local maxima.
V = [1 1 1 1 1 1 1];
islocalmax(V)
ans = 1×7 logical array
0 0 0 0 0 0 0
How about a case where there is an internal region that is greater than the neightbors, but is constant? We should see three local maxima in this next test. Only the third maximum is a true extremum in my eyes, because the first two cases are not distiinct from the immediate neighbors. But the other two cases still would seem to qualify, depending on how the inequality test is structured.
V = [1 2 2 1 3 3 3 1 3 4 3 1];
islocalmax(V)
ans = 1×12 logical array
0 1 0 0 0 1 0 0 0 1 0 0
Next, remember that we cannot have a local maximum at either end of a vector.
V = [0 0 0 1 1 1];
islocalmax(V)
ans = 1×6 logical array
0 0 0 0 0 0
A perturbation by eps is all that is required to introduce a max though.
V(5) = 1 + eps
V = 1×6
0 0 0 1.0000 1.0000 1.0000
islocalmax(V)
ans = 1×6 logical array
0 0 0 0 1 0
Unless, of course, one has decided to adjust the tolerance for a peak, using the "minprominence" property.
islocalmax(V,'minprominence',2*eps)
ans = 1×6 logical array
0 0 0 0 0 0
So all that does is adjust the test for inequality that is applied, using a tolerance.
Anyway, I would argue there is surely no serious mathematics behind this code, beyond a set of simple tests of inequality. There are several options in the code that will make those tests more complex, but still nothing sophisticated, just more complicated. Yes, I might apply diff to the vector to perform some of those tests, but diff is just a simple forward difference engine.
  1 Comment
Sim
Sim on 8 Nov 2023
Edited: Sim on 8 Nov 2023
A great answer, that, added to your previous one in Find (local?) maxima when two maxima are adjacent to each other (maybe using islocalmax or findpeaks?), makes thing clearer :-) Many thanks :-)
I understood that the key point here is just about the prominence (i.e. the difference between an element - that is supposed to be a local maxima - and its two nearest neighbours) used by islocalmax.
Without any additional option (e.g. "minprominence"), so just with the input data, you just need a very tiny difference between an element and the two nearest neighbours, to classify that element as a local maxima. For example, here following, V(3) is a local maxima, since there is a very tiny "eps" difference between element 3 and the two nearest neighbours, i.e. elements 2 and 4:
V = [0 0 eps 0 0];
islocalmax(V)
ans = 1×5 logical array
0 0 1 0 0

Sign in to comment.

More Answers (1)

Collin Pecora
Collin Pecora on 8 Nov 2023
edit matlab.internal.math.isLocalExtrema

Categories

Find more on Structures in Help Center and File Exchange

Tags

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!