Main Content

ismembertol

Find set members of data within tolerance

collapse all in page

Syntax

LIA = ismembertol(A,B,tol)
LIA = ismembertol(A,B)
[LIA,LocB] = ismembertol(___)
[___] = ismembertol(___,Name,Value)

Description

LIA = ismembertol(A,B,tol) returns an array containing logical 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.

example

LIA = ismembertol(A,B) uses a default tolerance of 1e-6 for single-precision inputs and 1e-12 for double-precision inputs.

example

[LIA,LocB] = ismembertol(___) also returns an array, LocB, that contains the index location in B for each element in A that is a member of B. You can use any of the input arguments in previous syntaxes.

example

[___] = ismembertol(___,Name,Value) 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, ismembertol(A,B,'ByRows',true) compares the rows of A and B and returns a logical column vector.

example

Examples

collapse all

Open Live Script

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
Open Live Script

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
Open Live Script

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
Open Live Script

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
Open Live Script

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 as true, since the point coordinates are in the rows of A and B.

  • Specify OutputAllIndices as true to return the indices for all points in A that have an x-coordinate within tolerance of the query points in B.

  • 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

Figure contains an axes object. The axes object contains 7 objects of type line. One or more of the lines displays its values using only markers

Input Arguments

collapse all

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

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

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)

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)

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 of A and B by considering each column separately. Thus, A and B must be 2-D arrays with the same number of columns.

  • If the corresponding row in A is within tolerance of a row in B, then LIA contains logical 1 (true). Otherwise, it contains logical 0 (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)

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

collapse all

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.

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

Version History

Introduced in R2015a

See Also

| | | |

Topics