# 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×110^{-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`

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

.

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)