Access Data in Tables

A table is a container that stores column-oriented data in variables. Table variables can have different data types and sizes as long as all variables have the same number of rows. Table variables have names, just as the fields of a structure have names. The rows of a table can have names, but row names are not required. To access table data, index into the rows and variables using either their names or numeric indices.

Typical reasons for indexing into tables include:

Reordering or removing rows and variables.
Adding arrays as new rows or variables.
Extracting arrays of data to use as input arguments to functions.

Summary of Table Indexing Syntaxes

Depending on the type of indexing you use, you can access either a subtable or an array extracted from the table. Indexing with:

Smooth parentheses, (), returns a table that has selected rows and variables.
Dot notation returns the contents of a variable as an array.
Curly braces, {}, returns an array concatenated from the contents of selected rows and variables.

You can specify rows and variables by name, numeric index, or data type. Starting in R2019b, variable names and row names can include any characters, including spaces and non-ASCII characters. Also, they can start with any characters, not just letters. Variable and row names do not have to be valid MATLAB^® identifiers (as determined by the isvarname function).

Type of Output	Syntax	Rows	Variables	Examples
Table, containing specified rows and variables	`T(rows,vars)`	Specified as: Row numbers (between `1` and `m`) Names, if `T` has row names Times, if `T` is a timetable Colon (`:`), meaning all rows	Specified as: Variable numbers (between `1` and `n`) Names Colon (`:`), meaning all variables	`T(1:5,[1 4 5])` Table having the first five rows and the first, fourth, and fifth variables of `T` `T(:,{'A','B'})` Table having all rows and the variables named `'A'` and `'B'` from `T`
Table, containing variables that have specified data type	`S = vartype(type);` `T(rows,S)`	Specified as: Row numbers (between `1` and `m`) Names, if `T` has row names Times, if `T` is a timetable Colon (`:`), meaning all rows	Specified as a data type, such as `'numeric'`, `'categorical'`, or `'datetime'`	`S = vartype('numeric');` `T(1:5,S)` Table having the first five rows and the numeric variables of `T`
Array, extracting data from one variable	`T.var` `T.(expression)`	Not specified	Specified as: A variable name (without quotation marks) An expression inside parentheses that returns a variable name or number	`T.Date` Array extracted from table variable named `'Date'` `T.('2019/06/30')` Array extracted from table variable named `'2019/06/30'` `T.(1)` Array extracted from the first table variable
Array, extracting data from one variable and specified rows	`T.var(rows)` `T.(expression)(rows)`	Specified as numeric or logical indices of the array	Specified as: A variable name (without quotation marks) An expression inside parentheses that returns a variable name or number	`T.Date(1:5)` First five rows of array extracted from table variable named `'Date'` `T.('2019/06/30')(1:5)` First five rows of array extracted from table variable named `'2019/06/30'` `T.(1)(1:5)` First five rows of array extracted from the first table variable
Array, concatenating data from specified rows and variables	`T{rows,vars}`	Specified as: Row numbers (between `1` and `m`) Names, if `T` has row names Times, if `T` is a timetable Colon (`:`), meaning all rows	Specified as: Variable numbers (between `1` and `n`) Names Colon (`:`), meaning all variables	`T{1:5,[1 4 5]}` Array concatenated from the first five rows and the first, fourth, and fifth variables of `T` `T{:,{'A','B'}}` Array concatenated from all rows and the variables named `'A'` and `'B'` from `T`
Array, concatenating data from specified rows and variables with specified data type	`S = vartype(type);` `T{rows,S}`	Specified as: Row numbers (between `1` and `m`) Names, if `T` has row names Times, if `T` is a timetable Colon (`:`), meaning all rows	Specified as a data type, such as `'numeric'`, `'categorical'`, or `'datetime'`	`S = vartype('numeric');` `T{1:5,S}` Array concatenated from the first five rows and the numeric variables of `T`
Array, concatenating data from all rows and variables	`T.Variables`	Not specified	Not specified	`T.Variables` Identical to array returned by `T{:,:}`

Tables Containing Specified Rows and Variables

Open Live Script

Load sample data for 100 patients from the patients MAT-file to workspace variables.

load patients
whos

  Name                            Size            Bytes  Class      Attributes

  Age                           100x1               800  double               
  Diastolic                     100x1               800  double               
  Gender                        100x1             11412  cell                 
  Height                        100x1               800  double               
  LastName                      100x1             11616  cell                 
  Location                      100x1             14208  cell                 
  SelfAssessedHealthStatus      100x1             11540  cell                 
  Smoker                        100x1               100  logical              
  Systolic                      100x1               800  double               
  Weight                        100x1               800  double

Create a table and populate it with the Age, Gender, Height, Weight, and Smoker workspace variables. Use the unique identifiers in LastName as row names. T is a 100-by-5 table. (When you specify row names, they do not count as a table variable).

T = table(Age,Gender,Height,Weight,Smoker,...
    'RowNames',LastName)

T=100×5 table
                Age      Gender      Height    Weight    Smoker
                ___    __________    ______    ______    ______

    Smith       38     {'Male'  }      71       176      true  
    Johnson     43     {'Male'  }      69       163      false 
    Williams    38     {'Female'}      64       131      false 
    Jones       40     {'Female'}      67       133      false 
    Brown       49     {'Female'}      64       119      false 
    Davis       46     {'Female'}      68       142      false 
    Miller      33     {'Female'}      64       142      true  
    Wilson      40     {'Male'  }      68       180      false 
    Moore       28     {'Male'  }      68       183      false 
    Taylor      31     {'Female'}      66       132      false 
    Anderson    45     {'Female'}      68       128      false 
    Thomas      42     {'Female'}      66       137      false 
    Jackson     25     {'Male'  }      71       174      false 
    White       39     {'Male'  }      72       202      true  
    Harris      36     {'Female'}      65       129      false 
    Martin      48     {'Male'  }      71       181      true  
      ⋮

Index Using Numeric Indices

Create a subtable containing the first five rows and all the variables from T. To specify the desired rows and variables, use numeric indices within parentheses. This type of indexing is similar to indexing into numeric arrays.

T1 = T(1:5,:)

T1=5×5 table
                Age      Gender      Height    Weight    Smoker
                ___    __________    ______    ______    ______

    Smith       38     {'Male'  }      71       176      true  
    Johnson     43     {'Male'  }      69       163      false 
    Williams    38     {'Female'}      64       131      false 
    Jones       40     {'Female'}      67       133      false 
    Brown       49     {'Female'}      64       119      false

T1 is a 5-by-5 table.

In addition to numeric indices, you can use row or variable names inside the parentheses. (In this case, using row indices and a colon is more compact than using row or variable names.)

Index Using Names

Select all the data for the patients with the last names 'Williams' and 'Brown'. Since T has row names that are the last names of patients, index into T using row names.

T2 = T({'Williams','Brown'},:)

T2=2×5 table
                Age      Gender      Height    Weight    Smoker
                ___    __________    ______    ______    ______

    Williams    38     {'Female'}      64       131      false 
    Brown       49     {'Female'}      64       119      false

T2 is a 2-by-5 table.

You also can select variables by name. Create a table that has only the first five rows of T and the Height and Weight variables. Display it.

T3 = T(1:5,{'Height','Weight'})

T3=5×2 table
                Height    Weight
                ______    ______

    Smith         71       176  
    Johnson       69       163  
    Williams      64       131  
    Jones         67       133  
    Brown         64       119

Table variable names do not have to be valid MATLAB identifiers. They can include spaces and non-ASCII characters, and can start with any character.

Add a variable name with spaces and a dash to T. Then index into T using variable names.

T = addvars(T,SelfAssessedHealthStatus,'NewVariableNames','Self-Assessed Health Status');
T(1:5,{'Age','Smoker','Self-Assessed Health Status'})

ans=5×3 table
                Age    Smoker    Self-Assessed Health Status
                ___    ______    ___________________________

    Smith       38     true             {'Excellent'}       
    Johnson     43     false            {'Fair'     }       
    Williams    38     false            {'Good'     }       
    Jones       40     false            {'Fair'     }       
    Brown       49     false            {'Good'     }

Specify Data Type Subscript

Instead of specifying variables using names or numbers, you can create a data type subscript that matches all variables having the same data type.

First, create a data type subscript to match numeric table variables.

S = vartype('numeric')

S = 
	table vartype subscript:

		Select table variables matching the type 'numeric'

	See Access Data in a Table.

Create a table that has only the numeric variables, and only the first five rows, from T.

T4 = T(1:5,S)

T4=5×3 table
                Age    Height    Weight
                ___    ______    ______

    Smith       38       71       176  
    Johnson     43       69       163  
    Williams    38       64       131  
    Jones       40       67       133  
    Brown       49       64       119

Extract Data Using Dot Notation and Logical Values

Open Live Script

Create a table from the patients MAT-file. Then use dot notation to extract data from table variables. You can also index using logical indices generated from values in a table variable that meet a condition.

load patients

T = table(Age,Gender,Height,Weight,Smoker,...
    'RowNames',LastName);

Extract Data from Variable

To extract data from one variable, use dot notation. Extract numeric values from the variable Weight. Then plot a histogram of those values.

histogram(T.Weight)
title('Patient Weight')

Figure contains an axes object. The axes object with title Patient Weight contains an object of type histogram.

T.Weight is a double-precision column vector with 100 rows.

Select Rows with Logical Indexing

You can index into an array or a table using an array of logical indices. Typically, you use a logical expression that determines which values in a table variable meet a condition. The result of the expression is an array of logical indices.

For example, create logical indices matching patients whose age is less than 40.

rows = T.Age < 40

rows = 100x1 logical array

   1
   0
   1
   0
   0
   0
   1
   0
   1
   1
      ⋮

To extract heights for patients whose age is less than 40, index into the Height variable using rows. There are 56 patients younger than 40.

T.Height(rows)

You can index into a table with logical indices. Display the rows of T for the patients who are younger than 40.

T(rows,:)

ans=56×5 table
                 Age      Gender      Height    Weight    Smoker
                 ___    __________    ______    ______    ______

    Smith        38     {'Male'  }      71       176      true  
    Williams     38     {'Female'}      64       131      false 
    Miller       33     {'Female'}      64       142      true  
    Moore        28     {'Male'  }      68       183      false 
    Taylor       31     {'Female'}      66       132      false 
    Jackson      25     {'Male'  }      71       174      false 
    White        39     {'Male'  }      72       202      true  
    Harris       36     {'Female'}      65       129      false 
    Thompson     32     {'Male'  }      69       191      true  
    Garcia       27     {'Female'}      69       131      true  
    Martinez     37     {'Male'  }      70       179      false 
    Rodriguez    39     {'Female'}      64       117      false 
    Walker       28     {'Female'}      65       123      true  
    Hall         25     {'Male'  }      70       189      false 
    Allen        39     {'Female'}      63       143      false 
    Young        25     {'Female'}      63       114      false 
      ⋮

You can match multiple conditions with one logical expression. Display the rows for smoking patients younger than 40.

rows = (T.Smoker==true & T.Age<40);
T(rows,:)

ans=18×5 table
                 Age      Gender      Height    Weight    Smoker
                 ___    __________    ______    ______    ______

    Smith        38     {'Male'  }      71       176      true  
    Miller       33     {'Female'}      64       142      true  
    White        39     {'Male'  }      72       202      true  
    Thompson     32     {'Male'  }      69       191      true  
    Garcia       27     {'Female'}      69       131      true  
    Walker       28     {'Female'}      65       123      true  
    King         30     {'Male'  }      67       186      true  
    Nelson       33     {'Male'  }      66       180      true  
    Mitchell     39     {'Male'  }      71       164      true  
    Turner       37     {'Male'  }      70       194      true  
    Sanders      33     {'Female'}      67       115      true  
    Price        31     {'Male'  }      72       178      true  
    Jenkins      28     {'Male'  }      69       189      true  
    Long         39     {'Male'  }      68       182      true  
    Patterson    37     {'Female'}      65       120      true  
    Flores       31     {'Female'}      66       141      true  
      ⋮

Dot Notation with Any Variable Name or Expression

Open Live Script

When you index using dot notation, there are two ways to specify a variable.

By name, without quotation marks. For example, T.Date specifies a variable named 'Date'.
By an expression, where the expression is enclosed by parentheses after the dot. For example, T.('Start Date') specifies a variable named 'Start Date'.

Use the first syntax when a table variable name also happens to be a valid MATLAB® identifier. (A valid identifier starts with a letter and includes only letters, digits, and underscores.)

Use the second syntax when you specify:

A number that indicates the position of the variable in the table.
A variable name that isn't a valid MATLAB identifier.
A function whose output is the name of a variable in the table, or a variable you add to the table. The output of the function must be a character vector or a string scalar.

For example, create a table from the patients MAT-file. Then use dot notation to access the contents of table variables.

load patients

T = table(Age,Gender,Height,Weight,Smoker,...
    'RowNames',LastName);

To specify a variable by position in the table, use a number. Age is the first variable in T, so use the number 1 to specify its position.

T.(1)

ans = 100×1

    38
    43
    38
    40
    49
    46
    33
    40
    28
    31
      ⋮

To specify a variable by name, you can enclose it in quotation marks. Since 'Age' is a valid identifier, you can specify it using either T.Age or T.('Age').

T.('Age')

ans = 100×1

    38
    43
    38
    40
    49
    46
    33
    40
    28
    31
      ⋮

You can specify table variable names that are not valid MATLAB identifiers. Variable names can include spaces and non-ASCII characters, and can start with any character. However, when you use dot notation to access a table variable with such a name, you must specify it using parentheses.

Add a variable name with spaces and a hyphen to T.

T = addvars(T,SelfAssessedHealthStatus,'NewVariableNames','Self-Assessed Health Status');
T(1:5,:)

ans=5×6 table
                Age      Gender      Height    Weight    Smoker    Self-Assessed Health Status
                ___    __________    ______    ______    ______    ___________________________

    Smith       38     {'Male'  }      71       176      true             {'Excellent'}       
    Johnson     43     {'Male'  }      69       163      false            {'Fair'     }       
    Williams    38     {'Female'}      64       131      false            {'Good'     }       
    Jones       40     {'Female'}      67       133      false            {'Fair'     }       
    Brown       49     {'Female'}      64       119      false            {'Good'     }

Access the new table variable using dot notation. Display the first five elements.

C = T.('Self-Assessed Health Status');
C(1:5)

ans = 5x1 cell
    {'Excellent'}
    {'Fair'     }
    {'Good'     }
    {'Fair'     }
    {'Good'     }

You also can use the output of a function as a variable name. Delete the T.('Self-Assessed Health Status') variable. Then replace it with a variable whose name includes today's date.

T.('Self-Assessed Health Status') = [];
T.(string(datetime('today')) + ' Self Report') = SelfAssessedHealthStatus;
T(1:5,:)

ans=5×6 table
                Age      Gender      Height    Weight    Smoker    01-Sep-2021 Self Report
                ___    __________    ______    ______    ______    _______________________

    Smith       38     {'Male'  }      71       176      true           {'Excellent'}     
    Johnson     43     {'Male'  }      69       163      false          {'Fair'     }     
    Williams    38     {'Female'}      64       131      false          {'Good'     }     
    Jones       40     {'Female'}      67       133      false          {'Fair'     }     
    Brown       49     {'Female'}      64       119      false          {'Good'     }

Extract Data from Specified Rows and Variables

Open Live Script

Indexing with curly braces extracts data from a table and results in an array, not a subtable. But other than that difference, you can specify rows and variables using numbers, names, and data type subscripts, just as you can when you index using smooth parentheses. To extract values from a table, use curly braces. If you extract values from multiple table variables, then the variables must have data types that allow them to be concatenated together.

Specify Rows and Variables

Create a table from numeric and logical arrays from the patients file.

load patients

T = table(Age,Height,Weight,Smoker,...
    'RowNames',LastName);

Extract data from multiple variables in T. Unlike dot notation, indexing with curly braces can extract values from multiple table variables and concatenate them into one array.

Extract the height and weight for the first five patients. Use numeric indices to select the first five rows, and variable names to select the variables Height and Weight.

A = T{1:5,{'Height','Weight'}}

A is a 5-by-2 numeric array, not a table.

If you specify one variable name, then curly brace indexing results in the same array you can get with dot notation. However, you must specify both rows and variables when you use curly brace indexing. For example, this syntaxes T.Height and T{:,'Height'} return the same array.

Extract Data from All Rows and Variables

If all the table variables have data types that allow them to be concatenated together, then you can use the T.Variables syntax to put all the table data into an array. This syntax is equivalent to T{:,:} where the colons indicate all rows and all variables.

A2 = T.Variables

A2 = 100×4

    38    71   176     1
    43    69   163     0
    38    64   131     0
    40    67   133     0
    49    64   119     0
    46    68   142     0
    33    64   142     1
    40    68   180     0
    28    68   183     0
    31    66   132     0
      ⋮