# ismembertol

Members of set within tolerance

## Syntax

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

## Description

example

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

## Examples

collapse all

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

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

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} {} {2x1 double} {} {3x1 double} Columns 6 through 10 {2x1 double} {} {3x1 double} {3x1 double} {2x1 double} Columns 11 through 15 {} {2x1 double} {4x1 double} {2x1 double} {} ```

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

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

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

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

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

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