islocalmin2
Description
[
also returns the prominence corresponding to each element of TF
,P
] = islocalmin2(A
)A
. For more
information about the prominence calculation, see Algorithms.
___ = islocalmin2(
specifies options for finding local minima using one or more name-value arguments with
either of the output argument combinations in the previous syntaxes. For example,
A
,Name=Value
)TF =
finds no more
than four of the most prominent local minima.islocalmin2
(A,MaxNumExtrema=4)
Examples
Find Locations and Values of Local Minima
Create a matrix, and visualize the matrix using a contour plot.
A = -peaks; contour(A) colorbar
Determine the locations of the local minima.
TF = islocalmin2(A);
Use the local minima indicator to determine the value of each minimum.
minval = A(TF)
minval = 3×1
-3.7573
-8.0752
-3.5823
Plot the local minima on the contour plot.
[X,Y] = meshgrid(1:49,1:49); hold on plot3(X(TF),Y(TF),minval,"red.",MarkerSize=12)
Control Minima Selection from Flat Region
Create and visualize a matrix with a flat region.
data = -peaks; A = clip(data,-5,Inf); contour(A) colorbar
Find the local minima. By default, TF
is 1
(true)
for only the center point of the flat region and TF
is 0
(false)
for all other points on the flat region.
[TF,P] = islocalmin2(A);
To select only the point on the flat region with the smallest linear index as the local minimum, specify the FlatSelection
name-value argument as "first"
.
[TF2,P2] = islocalmin2(A,FlatSelection="first");
To select all points on the flat region as local minima, specify FlatSelection
as "all"
.
[TF3,P3] = islocalmin2(A,FlatSelection="all");
Compare the results of the flat region selections by visualizing the extrema.
[X,Y] = meshgrid(1:49,1:49); tiledlayout(2,2) nexttile contour(A) colorbar hold on plot3(X(TF),Y(TF),A(TF),"red.",MarkerSize=12) title("Center Point on Flat Region") nexttile contour(A) colorbar hold on plot3(X(TF2),Y(TF2),A(TF2),"red.",MarkerSize=12) title("First Point on Flat Region") nexttile contour(A) colorbar hold on plot3(X(TF3),Y(TF3),A(TF3),"red.",MarkerSize=12) title("All Points on Flat Region")
Only the local minima indicator changes when you specify FlatSelection
. The prominence of all data points is the same for all values of FlatSelection
.
isequal(P,P2,P3)
ans = logical
1
Filter Noise
Create a matrix with some noise, and visualize the matrix using a contour plot.
data = peaks; data = -data - randn(49)*0.3; A = clip(data,-5,Inf); contour(A) colorbar
Find the local minima and plot them on the contour plot. By default, islocalmin2
finds all local minima whose prominence is greater than 0.
[TF P] = islocalmin2(A);
To understand the prominence of the local minima, sort the unique prominence values.
maxP = sort(unique(P(:)),"descend")
maxP = 143×1
5.7516
3.9830
3.3811
2.6829
1.7200
1.2871
1.2853
1.1382
1.1128
1.0921
⋮
Ignore the local minima that are a result of noise by finding only the three most prominent local minima. When you specify the MaxNumExtrema
name-value argument, the points in a flat region are jointly considered a single minimum point.
TF2 = islocalmin2(A,MaxNumExtrema=3);
Find local minima whose prominence is greater than 1.
TF3 = islocalmin2(A,MinProminence=1);
Find local minima whose prominence is greater than 3.
TF4 = islocalmin2(A,MinProminence=3);
Compare the results of the prominence filters by visualizing the extrema.
[X,Y] = meshgrid(1:49,1:49); figure tiledlayout(2,2) nexttile contour(A) colorbar hold on plot3(X(TF),Y(TF),A(TF),"r.",MarkerSize=12) title("All Local Minima") nexttile contour(A) colorbar hold on plot3(X(TF2),Y(TF2),A(TF2),"r.",MarkerSize=12) title("Three Most Prominent Minima") nexttile contour(A) colorbar hold on plot3(X(TF3),Y(TF3),A(TF3),"r.",MarkerSize=12) title("Minimum Prominence 1") nexttile contour(A) colorbar hold on plot3(X(TF4),Y(TF4),A(TF4),"r.",MarkerSize=12) title("Minimum Prominence 3")
Alternatively, you can use the smoothdata2
function to remove noise prior to finding the local minima.
Compute Prominence Across Specified Window
Create a matrix of data with one isolated valley and many valleys with high density elsewhere in the data.
rng("default") data = zeros(100); data(30,30) = 1000; data = smoothdata2(data,"gaussian",50); smallPeakLoc = randi(10000,1,400); tempData = zeros(100)+1; tempData(smallPeakLoc) = abs(randn(1,400))*3; tempData(1:50,1:50) = 0; A = -data-tempData; A = smoothdata2(A,"gaussian",5); contour(A) colorbar
Because of the high density of valleys elsewhere in the data, islocalmin2
underestimates the prominence of the valley at (30,30).
TF = islocalmin2(A,MaxNumExtrema=10); [X,Y] = meshgrid(1:100,1:100); contour(A) colorbar hold on plot3(X(TF),Y(TF),A(TF),"r.",MarkerSize=20)
To limit the impact of distant valleys on the prominence calculation, specify a prominence window. The isolated valley at (30,30) is now marked as a local minima.
TF2 = islocalmin2(A,ProminenceWindow=50,MaxNumExtrema=10); contour(A) colorbar hold on plot3(X(TF2),Y(TF2),A(TF2),"r.",MarkerSize=20)
Input Arguments
A
— Input data
vector | matrix | multidimensional array
Input data, specified as a vector, matrix, or multidimensional array.
islocalmin2
ignores missing values when computing the local
minima.
Name-Value Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Example: TF =
islocalmin2
(A,MinProminence=2)
SamplePoints
— Sample points
two-element cell array
Sample points, specified as a two-element cell array of vectors of sample point
values. The sample points in the first vector represent the data locations along the
columns of A
, and the sample points in the second vector represent
the data locations along the rows of A
.
Both vectors must be sorted and must not contain duplicate elements. Sample points
do not need to be uniformly spaced. If A
is an
m
-by-n
matrix, then the
default value of SamplePoints
is
{1:
.n
1:m
}
The prominence window is defined relative to the sample points. When the sample
point vectors have data type datetime
or
duration
, the prominence window size must have type
duration
.
Example: islocalmin2
(A,SamplePoints={1:5,10:2:18})
MinProminence
— Minimum prominence
0
(default) | nonnegative scalar
Minimum prominence, specified as a nonnegative scalar.
islocalmin2
returns only local minima whose prominence is at
least the specified value.
ProminenceWindow
— Prominence window size
positive integer or duration
scalar | two-element cell array of positive integer or duration
values | two-element cell array of two-element vectors of nonnegative integer or
duration
values
Prominence window size, specified as a positive integer or
duration
scalar, two-element cell array of positive integer or
duration
values, or two-element cell array of two-element vectors
of nonnegative integer or duration
values.
islocalmin2
defines the window relative to the sample
points.
If
ProminenceWindow
is a positive integer scalark
, then the window is ak
-by-k
block centered about the current element.If
ProminenceWindow
is a two-element cell array of positive integers{m n}
, then the window is anm
-by-n
block centered about the current element.If
ProminenceWindow
is a two-element cell array of two-element vectors of nonnegative integers{[bRow fRow] [bCol fCol]}
, then the window contains the row and column of the current element, the precedingbRow
and succeedingfRow
rows, and the precedingbCol
and succeedingfCol
columns.
If you specify SamplePoints
using datetime
or duration
values, then ProminenceWindow
must
be of type duration
.
Example: islocalmin2
(A,ProminenceWindow=4)
Example: islocalmin2
(A,ProminenceWindow={2
3})
Example: islocalmin2
(A,ProminenceWindow={[0 2] [3
3]})
FlatSelection
— Flat region indicator
"center"
(default) | "first"
| "all"
Flat region indicator for when a local minimum value is repeated in adjacent elements, specified as one of these values:
"center"
— Select only the center (centroid) element of a flat region as the local minimum."center"
indicates exactly one local minimum per flat section."first"
— Select only the first element of a flat region as the local minimum, where the first element is the element with the smallest linear index."first"
indicates exactly one local minimum per flat section and guarantees that all elements ofTF
with a value of1
(true
) are extrema."all"
— Select all the elements of a flat region as the local minima. The number of elements ofTF
with a value of1
(true
) does not match the number of local minima.
When you specify the MinSeparation
or
MaxNumExtrema
name-value argument, flat region points are jointly
considered a single minimum point.
MinSeparation
— Minimum separation
0
(default) | nonnegative integer or duration
scalar | two-element cell array of positive integer or duration
values
Minimum separation between local minima, specified as 0
, a
nonnegative integer or duration
scalar, or a two-element cell array
of positive integer or duration
values.
If MinSeparation
is a scalar, it is the Euclidean distance
between minima. If MinSeparation
is a cell array, the first element
specifies the minimum distance between minima along the columns of
A
and the second element specifies the minimum distance along the
rows of A
. The separation values are defined in the same units as
the sample points vectors, which are [1 2 3 ...]
by default.
When the separation value is greater than 0
,
islocalmin2
selects the most prominent local minimum and
ignores all other local minima within the specified separation. This process is
repeated until there are no more local minima detected.
If you specify SamplePoints
using datetime
or duration
values, the corresponding element in
MinSeparation
must be of type duration
.
Example: islocalmin2
(A,MinSeparation=3)
Example: islocalmin2
(A,SamplePoints={1:10,hours(1:10)},MinSeparation={3,hours(4)})
MaxNumExtrema
— Maximum number of minima
Inf
(default) | positive integer scalar
Maximum number of minima to detect, specified as a positive integer scalar.
islocalmin2
finds no more than the specified number of the most
prominent minima.
Output Arguments
TF
— Local minima indicator
vector | matrix | multidimensional array
Local minima indicator, returned as a vector, matrix, or multidimensional array.
TF
is the same size as A
.
Data Types: logical
P
— Prominence
vector | matrix | multidimensional array
Prominence, returned as a vector, matrix, or multidimensional array. The prominence of a local minimum (or valley) measures how the valley stands out with respect to its depth and location relative to other valleys. For more information about the prominence calculation, see Algorithms.
P
is the same size as A
. If the input data has
a signed or unsigned integer type, then P
contains unsigned
integers.
Algorithms
islocalmin2
identifies all local minima in the input data and follows
these steps to compute the prominence of each local minimum:
Determine the data to use to compute the prominence.
If the
ProminenceWindow
name-value argument is specified, use its value to draw a rectangular window of data around the current local minimum. Otherwise, use a rectangular window that includes all of the data.
Determine the prominence box.
Move vertical lines left and right from the current minimum until encountering a lower minimum or the edge of the rectangular window.
Move horizontal lines up and down from the current minimum until encountering a lower minimum or the edge of the rectangular window.
Compute the prominence.
Divide the prominence box into four quadrants centered on the current local minimum.
Identify the highest value within each quadrant.
Use the lowest of these quadrant maximum values as the basis value. The prominence is the absolute difference between the height of the current local minimum and the basis value.
Version History
Introduced in R2024a
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)