ismembertol

Members of set within tolerance

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.

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

[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.

[___] = 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.

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
  Columns 1 through 5

    {2x1 double}    {[0]}    {2x1 double}    {[0]}    {3x1 double}

  Columns 6 through 10

    {2x1 double}    {[4]}    {3x1 double}    {3x1 double}    {2x1 double}

  Columns 11 through 15

    {[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 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

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 comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

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 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)

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.

If OutputAllIndices is true, then ismembertol returns 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.

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™.

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).