ismembertol
Find set members of data within tolerance
Syntax
Description
returns
an array containing logical LIA
= ismembertol(A
,B
,tol
)1
(true
)
where the elements of A
are within tolerance of
the elements in B
. Otherwise, the array contains
logical 0
(false
). Two values, u
and v
,
are within tolerance if
abs(u-v) <= tol*max(abs([A(:);B(:)]))
That is, ismembertol
scales the tol
input
based on the magnitude of the data.
ismembertol
is similar to ismember
.
Whereas ismember
performs exact comparisons, ismembertol
performs
comparisons using a tolerance.
[___] = ismembertol(___,
uses
additional options specified by one or more Name-Value pair arguments
using any of the input or output argument combinations in previous
syntaxes. For example, Name,Value
)ismembertol(A,B,'ByRows',true)
compares
the rows of A
and B
and returns
a logical column vector.
Examples
Set Members in Presence of Numerical Error
Create a vector x
. Obtain a second vector y
by transforming and untransforming x
. This transformation introduces round-off differences in y
.
x = (1:6)'*pi; y = 10.^log10(x);
Verify that x
and y
are not identical by taking the difference.
x-y
ans = 6×1
10-14 ×
0.0444
0
0
0
0
-0.3553
Use ismember
to find the elements of x
that are in y
. The ismember
function performs exact comparisons and determines that some of the matrix elements in x
are not members of y
.
lia = ismember(x,y)
lia = 6x1 logical array
0
1
1
1
1
0
Use ismembertol
to perform the comparison using a small tolerance. ismembertol
treats elements that are within tolerance as equal and determines that all of the elements in x
are members of y
.
LIA = ismembertol(x,y)
LIA = 6x1 logical array
1
1
1
1
1
1
Determine Set Members by Rows
By default, ismembertol
looks for elements that are within tolerance, but it also can find rows of a matrix that are within tolerance.
Create a numeric matrix, A
. Obtain a second matrix, B
, by transforming and untransforming A
. This transformation introduces round-off differences to B
.
A = [0.05 0.11 0.18; 0.18 0.21 0.29; 0.34 0.36 0.41; ...
0.46 0.52 0.76; 0.82 0.91 1.00];
B = log10(10.^A);
Use ismember
to find the rows of A
that are in B
. ismember
performs exact comparisons and thus determines that most of the rows in A
are not members of B
, even though some of the rows differ by only a small amount.
lia = ismember(A,B,'rows')
lia = 5x1 logical array
0
0
0
0
1
Use ismembertol
to perform the row comparison using a small tolerance. ismembertol
treats rows that are within tolerance as equal and thus determines that all of the rows in A
are members of B
.
LIA = ismembertol(A,B,'ByRows',true)
LIA = 5x1 logical array
1
1
1
1
1
Average Similar Values in Vectors
Create two vectors of random numbers and determine which values in A
are also members of B
, using a tolerance. Specify OutputAllIndices
as true
to return all of the indices for the elements in B
that are within tolerance of the corresponding elements in A
.
rng(5)
A = rand(1,15);
B = rand(1,5);
[LIA,LocAllB] = ismembertol(A,B,0.2,'OutputAllIndices',true)
LIA = 1x15 logical array
1 0 1 0 1 1 1 1 1 1 0 1 1 1 0
LocAllB=1×15 cell array
{2x1 double} {[0]} {2x1 double} {[0]} {3x1 double} {2x1 double} {[4]} {3x1 double} {3x1 double} {2x1 double} {[0]} {2x1 double} {4x1 double} {2x1 double} {[0]}
Find the average value of the elements in B
that are within tolerance of the value A(13)
. The cell LocAllB{13}
contains all the indices for elements in B
that are within tolerance of A(13)
.
A(13)
ans = 0.4413
allB = B(LocAllB{13})
allB = 1×4
0.2741 0.4142 0.2961 0.5798
aveB = mean(allB)
aveB = 0.3911
Specify Absolute Tolerance
By default, ismembertol
uses a tolerance test of the form abs(u-v) <= tol*DS
, where DS
automatically scales based on the magnitude of the input data. You can specify a different DS
value to use with the DataScale
option. However, absolute tolerances (where DS
is a scalar) do not scale based on the magnitude of the input data.
First, compare two small values that are a distance eps
apart. Specify tol
and DS
to make the within tolerance equation abs(u-v) <= 10^-6
.
x = 0.1;
ismembertol(x, exp(log(x)), 10^-6, 'DataScale', 1)
ans = logical
1
Next, increase the magnitude of the values. The round-off error in the calculation exp(log(x))
is proportional to the magnitude of the values, specifically to eps(x)
. Even though the two large values are a distance eps
from one another, eps(x)
is now much larger. Therefore, 10^-6
is no longer a suitable tolerance.
x = 10^10;
ismembertol(x, exp(log(x)), 10^-6, 'DataScale', 1)
ans = logical
0
Correct this issue by using the default (scaled) value of DS
.
Y = [0.1 10^10]; ismembertol(Y, exp(log(Y)))
ans = 1x2 logical array
1 1
Specify DataScale by Column
Create a set of random 2-D points, and then use ismembertol
to group the points into vertical bands that have a similar (within-tolerance) x-coordinate to a small set of query points, B
. Use these options with ismembertol
:
Specify
ByRows
astrue
, since the point coordinates are in the rows ofA
andB
.Specify
OutputAllIndices
astrue
to return the indices for all points inA
that have an x-coordinate within tolerance of the query points inB
.Specify DataScale as
[1 Inf]
to use an absolute tolerance for the x-coordinate, while ignoring the y-coordinate.
A = rand(1000,2); B = [(0:.2:1)',0.5*ones(6,1)]; [LIA,LocAllB] = ismembertol(B, A, 0.1, 'ByRows', true, ... 'OutputAllIndices', true, 'DataScale', [1,Inf])
LIA = 6x1 logical array
1
1
1
1
1
1
LocAllB=6×1 cell array
{ 94x1 double}
{223x1 double}
{195x1 double}
{212x1 double}
{187x1 double}
{ 89x1 double}
Plot the points in A
that are within tolerance of each query point in B
.
hold on plot(B(:,1),B(:,2),'x') for k = 1:length(LocAllB) plot(A(LocAllB{k},1), A(LocAllB{k},2),'.') end
Input Arguments
A
— Query array
scalar | vector | matrix | multidimensional array
Query array, specified as a scalar, vector, matrix, or multidimensional
array. Inputs A
and B
must be
full.
If you specify the ByRows
option, then A
and B
must
have the same number of columns.
Data Types: single
| double
B
— Query array
scalar | vector | matrix | multidimensional array
Query array, specified as a scalar, vector, matrix, or multidimensional
array. Inputs A
and B
must be
full.
If you specify the ByRows
option, then A
and B
must
have the same number of columns.
Data Types: single
| double
tol
— Comparison tolerance
positive real scalar
Comparison tolerance, specified as a positive real scalar. ismembertol
scales
the tol
input using the maximum absolute values
in the input arrays A
and B
.
Then ismembertol
uses the resulting scaled comparison
tolerance to determine which elements in A
are
also a member of B
. If two elements are within
tolerance of each other, then ismembertol
considers
them to be equal.
Two values, u
and v
, are
within tolerance if abs(u-v) <= tol*max(abs([A(:);B(:)]))
.
To specify an absolute tolerance, specify both tol
and
the 'DataScale'
Name-Value pair.
Example: tol = 0.05
Example: tol
= 1e-8
Example: tol = eps
Data Types: single
| double
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.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: LIA = ismembertol(A,B,'ByRows',true)
OutputAllIndices
— Output index type
false
(default) | true
| 0
| 1
Output index type, specified as the comma-separated pair consisting
of 'OutputAllIndices'
and either false
(default), true
, 0
,
or 1
. ismembertol
interprets
numeric 0
as false
and numeric 1
as true
.
When OutputAllIndices
is true
,
the ismembertol
function returns the second output, LocB
,
as a cell array. The cell array contains the indices for all elements
in B
that are within tolerance of the corresponding
value in A
. That is, each cell in LocB
corresponds
to a value in A
, and the values in each cell correspond
to locations in B
.
Example: [LIA,LocAllB] = ismembertol(A,B,tol,'OutputAllIndices',true)
ByRows
— Row comparison toggle
false
(default) | true
| 0
| 1
Row comparison toggle, specified as the comma-separated pair
consisting of 'ByRows'
and either false
(default), true
, 0
,
or 1
. ismembertol
interprets
numeric 0
as false
and numeric 1
as true
.
Use this option to find rows in A
and B
that
are within tolerance.
When ByRows
is true
:
ismembertol
compares the rows ofA
andB
by considering each column separately. Thus,A
andB
must be 2-D arrays with the same number of columns.If the corresponding row in
A
is within tolerance of a row inB
, thenLIA
contains logical1
(true
). Otherwise, it contains logical0
(false
).
Two rows, u
and v
, are
within tolerance if all(abs(u-v) <= tol*max(abs([A;B])))
.
Example: LIA = ismembertol(A,B,tol,'ByRows',true)
DataScale
— Scale of data
scalar | vector
Scale of data, specified as the comma-separated pair consisting
of 'DataScale'
and either a scalar or vector. Specify DataScale
as
a numeric scalar, DS
, to change the tolerance test
to be, abs(u-v) <= tol*DS
.
When used together with the ByRows
option,
the DataScale
value also can be a vector. In this
case, each element of the vector specifies DS
for
a corresponding column in A
. If a value in the DataScale
vector
is Inf
, then ismembertol
ignores
the corresponding column in A
.
Example: LIA = ismembertol(A,B,'DataScale',1)
Example: [LIA,LocB] = ismembertol(A,B,'ByRows',true,'DataScale',[eps(1)
eps(10) eps(100)])
Data Types: single
| double
Output Arguments
LIA
— Logical index to A
vector | matrix
Logical index to A
, returned as a vector
or matrix containing logical 1
(true
)
wherever the elements (or rows) in A
are members
of B
(within tolerance). Elsewhere, LIA
contains
logical 0
(false
).
LIA
is the same size as A
,
unless you specify the ByRows
option. In that case, LIA
is
a column vector with the same number of rows as A
.
LocB
— Locations in B
vector | matrix | cell array
Locations in B
, returned as a vector, matrix,
or cell array. LocB
contains the indices to the
elements (or rows) in B
that are found in A
(within
tolerance). LocB
contains 0
wherever
an element in A
is not a member of B
.
By default, each element in LocB
is the index of the first element in
B
that is within tolerance of the corresponding
element in A
. Specify OutputAllIndices
as true
to instead return LocB
as a
cell array containing the indices for all elements in
B
that are within tolerance of the corresponding
value in A
. That is, each cell in LocB
corresponds to a value in A
, and the values in each cell
are indices into B
to elements that are within
tolerance.
LocB
is the same size as A
,
unless you specify the ByRows
option. In that case, LocB
is
a column vector with the same number of rows as A
.
Extended Capabilities
Thread-Based Environment
Run code in the background using MATLAB® backgroundPool
or accelerate code with Parallel Computing Toolbox™ ThreadPool
.
This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.
GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.
The ismembertol
function
supports GPU array input with these usage notes and limitations:
The
'ByRows'
and'OutputAllIndices'
arguments are not supported.64-bit integers are not supported.
For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).
Version History
Introduced in R2015a
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)