Main Content

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 or modify 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.

Another way to access or modify table data is to open it in the Variables editor for graphical editing. To open a table, double-click it in the Workspace browser or use the openvar function.

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

  • Starting in R2022a, when you specify rows and variables by name, you can use a pattern object to specify names. For example, "Var" + digitsPattern matches all names that start with Var and end with any number of digits.

Type of Output

Syntax

Rows

Variables

Examples

Table, containing specified rows and variables

T(rows,vars)

Specified as:

  • Row numbers (between 1 and m)

  • Logical array having m elements

  • Names, if T has row names

  • Times, if T is a timetable

  • Colon (:), meaning all rows

Specified as:

  • Variable numbers (between 1 and n)

  • Logical array having n elements

  • 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(1:5,[true false false true true])

    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

  • T(:,"A" + wildcardPattern)

    Table having all rows and variables whose names start with A

Table, containing variables that have specified data type

S = vartype(type);

T(rows,S)

Specified as:

  • Row numbers (between 1 and m)

  • Logical array having m elements

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

  • Logical array having m elements

  • Names, if T has row names

  • Times, if T is a timetable

  • Colon (:), meaning all rows

Specified as:

  • Variable numbers (between 1 and n)

  • Logical array having n elements

  • 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{1:5,[true false false true true]}

    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

  • T{:,"A" + wildcardPattern}

    Array concatenated from all rows and variables whose names start with A

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)

  • Logical array having m elements

  • 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{:,:}

Table Indexing with 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, Height, Weight, Smoker, and SelfAssessedHealthStatus workspace variables. Use the unique identifiers in LastName as row names. T is a 100-by-5 table, with 100 rows and five variables. (When you specify a vector of row names, it does not count as a table variable). Also, convert SelfAssessedHealthStatus to a categorical variable because it contains only the unique values Excellent, Good, Fair, and Poor. It can be useful to treat a variable as a categorical array when it has a fixed set of values that you can think of as categories.

SelfAssessedHealthStatus = categorical(SelfAssessedHealthStatus);
T = table(Age,Height,Weight,Smoker,SelfAssessedHealthStatus,...
    'RowNames',LastName)
T=100×5 table
                Age    Height    Weight    Smoker    SelfAssessedHealthStatus
                ___    ______    ______    ______    ________________________

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

Index Using Numeric Indices or end Keyword

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.

firstRows = T(1:5,:)
firstRows=5×5 table
                Age    Height    Weight    Smoker    SelfAssessedHealthStatus
                ___    ______    ______    ______    ________________________

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

You can also use the end keyword to mean the last row or variable. Use the end keyword to index into the last five rows of the table.

lastRows = T(end-4:end,:)
lastRows=5×5 table
                 Age    Height    Weight    Smoker    SelfAssessedHealthStatus
                 ___    ______    ______    ______    ________________________

    Alexander    25       69       171      true                Good          
    Russell      44       69       188      true                Good          
    Griffin      49       70       186      false               Fair          
    Diaz         45       68       172      true                Good          
    Hayes        48       66       177      false               Fair

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 Griffin, Diaz, and Hayes. Since T has row names that are the last names of patients, index into T using row names.

rowsByName = T(["Griffin","Diaz","Hayes"],:)
rowsByName=3×5 table
               Age    Height    Weight    Smoker    SelfAssessedHealthStatus
               ___    ______    ______    ______    ________________________

    Griffin    49       70       186      false               Fair          
    Diaz       45       68       172      true                Good          
    Hayes      48       66       177      false               Fair

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.

variablesByName = T(1:5,["Height","Weight"])
variablesByName=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.

For example, rename the SelfAssessedHealthStatus variable by using the renamevars function. Add spaces and a dash to make that variable name more readable. Then index into T using variable names.

T = renamevars(T,"SelfAssessedHealthStatus","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 Row or Variable Names Using Patterns

When you specify table row or variable names, you can use a pattern that defines a rule for matching text. For example, you can match variable names that start with "Var" followed by any digits. You can build pattern expressions using pattern objects, strings, and operators.

For example, index into T by row name to find all rows where the last name of the patient begins with the letter G. To match any letters after G use the wildcardPattern function.

beginsWithG = "G" + wildcardPattern
beginsWithG = pattern
  Matching:

    "G" + wildcardPattern


T(beginsWithG,:)
ans=6×5 table
                Age    Height    Weight    Smoker    Self-Assessed Health Status
                ___    ______    ______    ______    ___________________________

    Garcia      27       69       131      true               Fair              
    Green       44       71       193      false              Good              
    Gonzalez    35       66       118      false              Fair              
    Gray        31       64       130      false              Excellent         
    Gonzales    48       71       174      false              Good              
    Griffin     49       70       186      false              Fair

Index into T by variable name to find any name that contains Status as part of the name.

containsStatus = wildcardPattern + "Status" + wildcardPattern;
T(1:5,containsStatus)
ans=5×1 table
                Self-Assessed Health Status
                ___________________________

    Smith                Excellent         
    Johnson              Fair              
    Williams             Good              
    Jones                Fair              
    Brown                Good

Index by Data Type of Variables

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 by using the vartype function.

subscriptObject = vartype("numeric")
subscriptObject = 
	table vartype subscript:

		Select table variables matching the type 'numeric'

Create a table that has only the numeric variables from T. The Smoker variable is a logical variable and Self-Assessed Health Status is a categorical variable so they are excluded.

onlyNumericVariables = T(:,subscriptObject)
onlyNumericVariables=100×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  
    Davis       46       68       142  
    Miller      33       64       142  
    Wilson      40       68       180  
    Moore       28       68       183  
    Taylor      31       66       132  
    Anderson    45       68       128  
    Thomas      42       66       137  
    Jackson     25       71       174  
    White       39       72       202  
    Harris      36       65       129  
    Martin      48       71       181  
      ⋮

Find Rows Where Values Meet Logical Conditions

Open Live Script

Create another, smaller table from the data in the patients MAT-file.

load patients.mat
T = table(Age,Height,Weight,Smoker);

To find the rows of a table where values meet a logical condition, use logical indexing. First use dot notation to access table variables. Then you can create an array of logical indices where values in the variables meet a condition that you specify. Index into the table using the logical indices.

Extract Data from Table Variable Using Dot Notation

To extract data from a table variable, use dot notation.

For example, plot a histogram of numeric values from the table variable Weight. With dot notation, you can treat T.Weight as a numeric array. T.Weight is a double-precision column vector with 100 rows.

histogram(T.Weight)
title("Patient Weights")

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

Index into Rows That Meet Logical Conditions

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 logical 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)
ans = 56×1

    71
    64
    64
    68
    66
    71
    72
    65
    69
    69
      ⋮

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×4 table
    Age    Height    Weight    Smoker
    ___    ______    ______    ______

    38       71       176      true  
    38       64       131      false 
    33       64       142      true  
    28       68       183      false 
    31       66       132      false 
    25       71       174      false 
    39       72       202      true  
    36       65       129      false 
    32       69       191      true  
    27       69       131      true  
    37       70       179      false 
    39       64       117      false 
    28       65       123      true  
    25       70       189      false 
    39       63       143      false 
    25       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×4 table
    Age    Height    Weight    Smoker
    ___    ______    ______    ______

    38       71       176      true  
    33       64       142      true  
    39       72       202      true  
    32       69       191      true  
    27       69       131      true  
    28       65       123      true  
    30       67       186      true  
    33       66       180      true  
    39       71       164      true  
    37       70       194      true  
    33       67       115      true  
    31       72       178      true  
    28       69       189      true  
    39       68       182      true  
    37       65       120      true  
    31       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,Height,Weight,Smoker);

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, either specify it after the dot or enclose it in quotation marks and parentheses. 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 quotation marks and parentheses.

For example, add a variable name with spaces and a hyphen to T.

SelfAssessedHealthStatus = categorical(SelfAssessedHealthStatus);
T = addvars(T,SelfAssessedHealthStatus,'NewVariableNames',"Self-Assessed Health Status");
T(1:5,:)
ans=5×5 table
    Age    Height    Weight    Smoker    Self-Assessed Health Status
    ___    ______    ______    ______    ___________________________

    38       71       176      true               Excellent         
    43       69       163      false              Fair              
    38       64       131      false              Good              
    40       67       133      false              Fair              
    49       64       119      false              Good

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

healthStatus = T.("Self-Assessed Health Status");
healthStatus(1:5)
ans = 5x1 categorical
     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 the current date.

T.("Self-Assessed Health Status") = [];
T.(string(datetime("today")) + " Self Report") = SelfAssessedHealthStatus;
T(1:5,:)
ans=5×5 table
    Age    Height    Weight    Smoker    19-Aug-2023 Self Report
    ___    ______    ______    ______    _______________________

    38       71       176      true             Excellent       
    43       69       163      false            Fair            
    38       64       131      false            Good            
    40       67       133      false            Fair            
    49       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 = 5×2

    71   176
    69   163
    64   131
    67   133
    64   119

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, the 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. If the table has row names, they are not included in the output from T.Variables. Row names are not stored in a table variable. Row names are part of the metadata that describes a table.

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
      ⋮

See Also

| | | |

Related Topics