ismember

Array elements that are members of set array

Syntax

Lia = ismember(A,B)

Lia = ismember(A,B,'rows')

[Lia,Locb] = ismember(___)

[Lia,Locb] = ismember(___,'legacy')

Description

Lia = ismember(A,B) returns an array containing logical 1 (true) where the data in A is found in B. Elsewhere, the array contains logical 0 (false).

• If A and B are tables or timetables, then ismember returns a logical value for each row. For timetables, ismember takes row times into account to determine equality. The output, Lia, is a column vector.

Lia = ismember(A,B,'rows') treats each row of A and each row of B as single entities and returns a column vector containing logical 1 (true) where the rows of A are also rows of B. Elsewhere, the array contains logical 0 (false).

The 'rows' option does not support cell arrays, unless one of the inputs is either a categorical array or a datetime array.

[Lia,Locb] = ismember(___) also returns an array, Locb, using any of the previous syntaxes.

• Generally, Locb contains the lowest index in B for each value in A that is a member of B. Values of 0 indicate where A is not a member of B.

• If the 'rows' option is specified, then Locb contains the lowest index in B for each row in A that is also a row in B. Values of 0 indicate where A is not a row of B.

• If A and B are tables or timetables, then Locb contains the lowest index in B for each row in A that is also a row in B. Values of 0 indicate where A is not a row of B.

[Lia,Locb] = ismember(___,'legacy') preserves the behavior of the ismember function from R2012b and prior releases using any of the input arguments in previous syntaxes.

The 'legacy' option does not support categorical arrays, datetime arrays, duration arrays, tables, or timetables.

Examples

Values That Are Members of Set

Create two vectors with values in common.

A = [5 3 4 2]; 
B = [2 4 4 4 6 8];

Determine which elements of A are also in B.

Lia = ismember(A,B)

Lia = 1x4 logical array

   0   0   1   1

A(3) and A(4) are found in B.

Table Rows Found in Another Table

Create two tables with rows in common.

A = table([1:5]',['A';'B';'C';'D';'E'],logical([0;1;0;1;0]))

A=5×3 table
    Var1    Var2    Var3 
    ____    ____    _____

     1       A      false
     2       B      true 
     3       C      false
     4       D      true 
     5       E      false

B = table([1:2:10]',['A';'C';'E';'G';'I'],logical(zeros(5,1)))

B=5×3 table
    Var1    Var2    Var3 
    ____    ____    _____

     1       A      false
     3       C      false
     5       E      false
     7       G      false
     9       I      false

Determine which rows of A are also in B.

Lia = ismember(A,B)

Lia = 5x1 logical array

   1
   0
   1
   0
   1

A(1,:), A(3,:), and A(5,:) are found in B.

Members of Set and Indices to Values

Create two vectors with values in common.

A = [5 3 4 2]; 
B = [2 4 4 4 6 8];

Determine which elements of A are also in B as well as their corresponding locations in B.

[Lia,Locb] = ismember(A,B)

Lia = 1x4 logical array

   0   0   1   1

Locb = 1×4

     0     0     2     1

The lowest index to A(3) is B(2), and A(4) is found in B(1).

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

Rows of Another Table and Their Location

Create a table, A, of gender, age, and height for five people.

A = table(['M';'M';'F';'M';'F'],[27;52;31;46;35],[74;68;64;61;64],...
'VariableNames',{'Gender' 'Age' 'Height'},...
'RowNames',{'Ted' 'Fred' 'Betty' 'Bob' 'Judy'})

A=5×3 table
             Gender    Age    Height
             ______    ___    ______

    Ted        M       27       74  
    Fred       M       52       68  
    Betty      F       31       64  
    Bob        M       46       61  
    Judy       F       35       64  

Create another table, B, with rows in common with A.

B = table(['M';'F';'F';'F'],[47;31;35;23],[68;64;62;58],...
'VariableNames',{'Gender' 'Age' 'Height'},...
'RowNames',{'Joe' 'Meg' 'Beth' 'Amy'})

B=4×3 table
            Gender    Age    Height
            ______    ___    ______

    Joe       M       47       68  
    Meg       F       31       64  
    Beth      F       35       62  
    Amy       F       23       58  

Determine which rows of A are also in B, as well as their corresponding locations in B.

[Lia,Locb] = ismember(A,B)

Lia = 5x1 logical array

   0
   0
   1
   0
   0

Locb = 5×1

     0
     0
     2
     0
     0

Two rows that have the same values, but different names, are considered equal. The same data for Betty is found in B(2,:), which corresponds to Meg.

Rows That Belong to a Set

Create two matrices with a row in common.

A = [1 3 5 6; 2 4 6 8];
B = [2 4 6 8; 1 3 5 7; 2 4 6 8];

Determine which rows of A are also in B as well as their corresponding locations in B.

[Lia, Locb] = ismember(A,B, 'rows')

Lia = 2x1 logical array

   0
   1

Locb = 2×1

     0
     1

The lowest index to A(2,:) is B(1,:).

Members of Set Containing NaN Values

Create two vectors containing NaN.

A = [5 NaN NaN]; 
B = [5 NaN NaN];

Determine which elements of A are also in B, as well as their corresponding locations in B.

[Lia,Locb] = ismember(A,B)

Lia = 1x3 logical array

   1   0   0

Locb = 1×3

     1     0     0

ismember treats NaN values as distinct.

Cell Array of Character Vectors with Trailing White Space

Create a cell array of character vectors, A.

A = {'dog','cat','fish','horse'};

Create a cell array of character vectors, B, where some of the vectors have trailing white space.

B = {'dog ','cat','fish ','horse'};

Determine which character vectors of A are also in B.

[Lia,Locb] = ismember(A,B)

Lia = 1x4 logical array

   0   1   0   1

Locb = 1×4

     0     2     0     4

ismember treats trailing white space in cell arrays of character vectors as distinct characters.

Members of Char and Cell Array of Character Vectors

Create a character vector, A, and a cell array of character vectors, B.

A = ['cat';'dog';'fox';'pig'];
B = {'dog','cat','fish','horse'};

Determine which character vectors of A are also in B.

[Lia,Locb] = ismember(A,B)

Lia = 4x1 logical array

   1
   1
   0
   0

Locb = 4×1

     2
     1
     0
     0

Preserve Legacy Behavior of ismember

Use the 'legacy' flag to preserve the behavior of ismember from R2012b and prior releases in your code.

Find the members of B with the current behavior.

A = [5 3 4 2]; 
B = [2 4 4 4 6 8];
[Lia1,Locb1] = ismember(A,B)

Lia1 = 1x4 logical array

   0   0   1   1

Locb1 = 1×4

     0     0     2     1

Find the members of B, and preserve the legacy behavior.

[Lia2,Locb2] = ismember(A,B,'legacy')

Lia2 = 1x4 logical array

   0   0   1   1

Locb2 = 1×4

     0     0     4     1

Input Arguments

A — Query array

numeric arrays | logical arrays | character arrays | string arrays | categorical arrays | datetime arrays | duration arrays | cell arrays of character vectors | tables | timetables

Query array, specified as a numeric array, logical array, character array, string array, categorical array, datetime array, duration array, cell array of character vectors, table, or timetable. If you specify the 'rows' option, A and B must have the same number of columns.

A must belong to the same class as B with the following exceptions:

• logical, char, and all numeric classes can combine with double arrays.

• Cell arrays of character vectors can combine with character arrays or string arrays.

• Categorical arrays can combine with character arrays, cell arrays of character vectors, or string arrays.

• Datetime arrays can combine with cell arrays of date character vectors or single date character vectors.

There are additional requirements for A and B based on data type:

• If A and B are both ordinal categorical arrays, they must have the same sets of categories, including their order. If neither A nor B are ordinal, they need not have the same sets of categories, and the comparison is performed using the category names.

• If A is a table or timetable, it must have the same variable names as B (except for order). For tables, row names are ignored, so that two rows that have the same values, but different names, are considered equal. For timetables, row times are taken into account, so that two rows that have the same values, but different times, are not considered equal.

• If A and B are datetime arrays, they must be consistent with each other in whether they specify a time zone.

For textual inputs, ismember generally does not ignore trailing spaces in character vectors, cell arrays of character vectors, and string arrays. However, there are a few cases when ismember does ignore trailing spaces:

• If A is a character array and B is a cell array of character vectors, then ismember ignores trailing spaces in the character array.

• When the 'rows' option is specified, ismember ignores trailing spaces in character vectors and character arrays.

A also can be an object with the following class methods:

• sort (or sortrows for the 'rows' option)

• eq

• ne

The object class methods must be consistent with each other. These objects include heterogeneous arrays derived from the same root class. For example, A can be an array of handles to graphics objects.

B — Set array

numeric arrays | logical arrays | character arrays | string arrays | categorical arrays | datetime arrays | duration arrays | cell arrays of character vectors | tables | timetables

Set array, specified as a numeric array, logical array, character array, string array, categorical array, datetime array, duration array, cell array of character vectors, table, or timetable. If you specify the 'rows' option, A and B must have the same number of columns.

B must belong to the same class as A with the following exceptions:

• logical, char, and all numeric classes can combine with double arrays.

• Cell arrays of character vectors can combine with character arrays or string arrays.

• Categorical arrays can combine with character arrays, cell arrays of character vectors, or string arrays.

• Datetime arrays can combine with cell arrays of date character vectors or single date character vectors.

There are additional requirements for A and B based on data type:

• If A and B are both ordinal categorical arrays, they must have the same sets of categories, including their order. If neither A nor B are ordinal, they need not have the same sets of categories, and the comparison is performed using the category names.

• If B is a table or timetable, it must have the same variable names as A (except for order). For tables, row names are ignored, so that two rows that have the same values, but different names, are considered equal. For timetables, row times are taken into account, so that two rows that have the same values, but different times, are not considered equal.

• If A and B are datetime arrays, they must be consistent with each other in whether they specify a time zone.

For textual inputs, ismember generally does not ignore trailing spaces in character vectors, cell arrays of character vectors, and string arrays. However, there are a few cases when ismember does ignore trailing spaces:

• If A is a character array and B is a cell array of character vectors, then ismember ignores trailing spaces in the character array.

• When the 'rows' option is specified, ismember ignores trailing spaces in character vectors and character arrays.

B also can be an object with the following class methods:

• sort (or sortrows for the 'rows' option)

• eq

• ne

The object class methods must be consistent with each other. These objects include heterogeneous arrays derived from the same root class. For example, B can be an array of handles to graphics objects.

Output Arguments

Lia — Logical index to A

vector | matrix | N-D array

Logical index to A, returned as a vector, matrix or N-D array containing logical 1 (true) wherever the values (or rows) in A are members of B. Elsewhere, it contains logical 0 (false).

Lia is an array of the same size as A, unless you specify the 'rows' flag.

If the 'rows' flag is specified or if A is a table or timetable, Lia is a column vector with the same number of rows as A.

Locb — Locations in B

vector | matrix | N-D array

Locations in B, returned as a vector, matrix, or N-D array. If the 'legacy' flag is not specified, Locb contains the lowest indices to the values (or rows) in B that are found in A. Values of 0 indicate where A is not a member of B.

Locb is an array of the same size as A unless you specify the 'rows' flag.

If the 'rows' flag is specified or if A is a table or timetable, Locb is a column vector with the same number of rows as A.

Tips

• Use ismembertol to perform comparisons between floating-point numbers using a tolerance.

• To find the rows from table or timetable A that are found in B with respect to a subset of variables, you can use column subscripting. For example, you can use ismember(A(:,vars),B(:,vars)), where vars is a positive integer, a vector of positive integers, a variable name, a cell array of variable names, or a logical vector. Alternatively, you can use vartype to create a subscript that selects variables of a specified type.

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

Usage notes and limitations:

• If both A and B are tall arrays, then one must be the result of a reduction operation applied in the first dimension (such as sum, prod, max, and so on).

For more information, see Tall Arrays.

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• Code generation does not support cell arrays for the first or second arguments.

• Complex inputs must be single or double.

• See Code Generation for Complex Data with Zero-Valued Imaginary Parts (MATLAB Coder).

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Usage notes and limitations:

• The 'legacy' flag is not supported.

• 64-bit integers are not supported.

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).