Main Content

table

Table array with named variables that can contain different types

expand all in page

Description

table arrays store column-oriented or tabular data, such as columns from a text file or spreadsheet. Tables store each piece of column-oriented data in a variable. 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. Use the summary function to get information about a table.

To index into a table, use one of these syntaxes. For more information, see Access Data in Tables.

  • Dot notation, as in T.varname, extracts one variable.

  • Curly braces, as in T{rows,vars}, extracts an array from specified rows and variables.

  • Parentheses, as in T(rows,vars), returns a table.

You can perform mathematical operations, such as +, .*, and mean, directly on tables. For more information, see Direct Calculations on Tables and Timetables. (since R2023a)

If your data includes timestamps, consider using a timetable instead.

Creation

You can read data from a file into a table using either the Import Tool or the readtable function. Alternatively, use the table function described below to create a table from input data arrays.

You also can create a table that allows space for variables whose values are filled in later. To create a table with preallocated space for variables, use the table function with 'Size' as the first input argument, as described below.

Syntax

T = table(var1,...,varN)
T = table('Size',sz,'VariableTypes',varTypes)
T = table(___,Name,Value)
T = table

Description

T = table(var1,...,varN) creates a table from the input variables var1,...,varN. The variables can have different sizes and data types, but all variables must have the same number of rows.

If the inputs are workspace variables, then table assigns their names as the variable names in the output table. Otherwise, table assigns variable names of the form 'Var1',...,'VarN', where N is the number of variables.

example

T = table('Size',sz,'VariableTypes',varTypes) creates a table and preallocates space for the variables that have data types you specify. sz is a two-element numeric array, where sz(1) specifies the number of rows and sz(2) specifies the number of variables. varTypes specifies the data types of the variables.

example

T = table(___,Name,Value) specifies additional input arguments using one or more name-value pair arguments. For example, you can specify variable names using the 'VariableNames' name-value pair. You can use this syntax with any of the input arguments of the previous syntaxes.

example

T = table creates an empty 0-by-0 table.

example

Input Arguments

expand all

Input variables, specified as arrays with the same number of rows. The input variables can have different sizes and different data types.

Common input variables are numeric arrays, logical arrays, character arrays, structure arrays, or cell arrays. Input variables also can be objects that are arrays. Such an array must support indexing of the form var(index1,...,indexN), where index1 is a numeric or logical vector that corresponds to rows of the variable var. In addition, the array must implement both a vertcat method and a size method with a dim argument.

Example: table([1:4]',ones(4,3,2),eye(4,2)) creates a table from variables with four rows, but different sizes.

Example: table([1:3]',{'one';'two';'three'},categorical({'A';'B';'C'})) creates a table from variables with three rows, but different data types.

Size of the preallocated table, specified as a two-element numeric vector. The first element of sz specifies the number of rows, and the second element specifies the number of table variables.

To create variables only, without any rows, specify 0 as the first element of sz.

Example: T = table('Size',[50 3],'VariableTypes',{'string','double','datetime'}) preallocates 50 rows for a table that contains a string array, a double array, and a datetime array.

Example: T = table('Size',[0 4],'VariableTypes',varTypes) specifies zero rows and four variables.

Data types of the preallocated variables, specified as a cell array of character vectors or a string array. The number of types specified by varTypes must equal the number of variables specified by the second element of sz.

varTypes can contain the names of any data types, including the names shown in the table.

Data Type Name

Initial Value in Each Element

'double', 'single'

Double- or single-precision 0

'doublenan', 'doubleNaN', 'singlenan', 'singleNaN'

Double- or single-precision NaN

'int8', 'int16', 'int32', 'int64'

Signed 8-, 16-, 32-, or 64-bit integer 0

'uint8', 'uint16', 'uint32', 'uint64'

Unsigned 8-, 16-, 32-, or 64-bit integer 0

'logical'

0 (false)

'categorical'

<undefined> categorical value

'datetime'

NaT datetime value

'duration'

0 seconds, as a duration value

'calendarDuration'

0 days, as a calendarDuration value

'string'

<missing> (missing string)

'cellstr'

{''} (cell with 0-by-0 character array)

'cell'

{[]} (cell with 0-by-0 double array)

'struct'

Scalar structure with no fields

'table'

Table with no variables

'timetable'

Timetable with no variables and NaT for row times

For any other data type, the initial value is the value used by that type or class to "in-fill" unassigned elements of an array.

If you specify 'char' as a data type, then table preallocates the corresponding variable as a cell array of character vectors, not as a character array. Best practice is to avoid creating table or timetable variables that are character arrays. When working with text data in a table or a timetable, consider using a string array or a categorical array.

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: T = table(Age,Height,Weight,'RowNames',LastName) creates a table with row names that are specified by the variable LastName.

Variable names, specified as a cell array of character vectors or a string array whose elements are nonempty and distinct.

  • The number of names in the array must equal the number of table variables.

  • The table function also stores the variable names in the VariableNames property of the table.

  • Variable names can have any Unicode® characters, including spaces and non-ASCII characters.

Example: T = table(lat,lon,'VariableNames',["Latitude","Longitude"]) creates a table from input arrays lat and lon, and names the corresponding table variables Latitude and Longitude.

Row names, specified as a cell array of character vectors or a string array whose elements are nonempty and distinct.

  • The number of names in the array must equal the number of rows.

  • The table function also stores the row names in the RowNames property of the table.

  • Row names can have any Unicode characters, including spaces and non-ASCII characters.

  • The table function removes any leading or trailing whitespace characters from the row names.

Example: T = table(Age,Height,Weight,'RowNames',LastName) creates a table with row names that are specified by the variable LastName.

Since R2021a

Dimension names, specified as a two-element cell array of character vectors or two-element string array whose elements are nonempty and distinct.

  • The table function also stores the dimension names in the DimensionNames property of the table.

  • Dimension names can have any Unicode characters, including spaces and non-ASCII characters.

Before R2021a, you can specify dimension names only by setting the DimensionNames property.

Example: T = table(Age,Height,Weight,'RowNames',LastName,'DimensionNames',["PatientName","PatientData"]) creates a table where the name of the first dimension is "PatientName" and the name of the second dimension is "PatientData".

Properties

expand all

Access Table Metadata Properties

A table contains metadata properties that describe the table and its variables. Access these properties using the syntax tableName.Properties.PropertyName, where PropertyName is the name of a property. For example, you can access the names of the variables in table T using the syntax T.Properties.VariableNames.

You can return a summary of all the metadata properties using the syntax tableName.Properties.

Tables provide metadata access through the Properties property because you can access table data directly using dot syntax. For example, if table T has a variable named Var1, then you can access the values in the variable by using the syntax T.Var1.

Table Metadata

Dimension names, specified as a two-element cell array of character vectors or a two-element string array.

  • Dimension names can have any Unicode characters, including spaces and non-ASCII characters.

  • If you specify this property using a string array, then it is converted and stored as a cell array of character vectors.

You can access table data using the two dimension names.

  • If the table has row names, and you use dot syntax and the first dimension name, then you can access the row names as a vector.

  • If you use dot syntax and the second dimension name, then the data from all the variables are concatenated together in one array, as though you had indexed into the table using {:,:} syntax.

Example

Create a table and display its dimension names. You can access row names and data using dimension names with dot syntax.

load patients
T = table(Age,Height,Weight,Systolic,Diastolic, ...
          'RowNames',LastName);
T.Properties.DimensionNames
ans = 1x2 cell
    {'Row'}    {'Variables'}

Access the row names using the first dimension name. Display the first five names.

T.Row(1:5)
ans = 5x1 cell
    {'Smith'   }
    {'Johnson' }
    {'Williams'}
    {'Jones'   }
    {'Brown'   }

Access the data using the second dimension name. This syntax is equivalent to T{:,:}.

T.Variables
ans = 100×5

    38    71   176   124    93
    43    69   163   109    77
    38    64   131   125    83
    40    67   133   117    75
    49    64   119   122    80
    46    68   142   121    70
    33    64   142   130    88
    40    68   180   115    82
    28    68   183   115    78
    31    66   132   118    86
      ⋮

Modify the names of its dimensions using the Properties.DimensionNames property. Having changed the dimension names, you can access the row names and data using the syntaxes T.Patient and T.Data respectively.

T.Properties.DimensionNames = ["Patient","Data"];
T.Properties
ans = 
  TableProperties with properties:

             Description: ''
                UserData: []
          DimensionNames: {'Patient'  'Data'}
           VariableNames: {'Age'  'Height'  'Weight'  'Systolic'  'Diastolic'}
           VariableTypes: ["double"    "double"    "double"    "double"    "double"]
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowNames: {100x1 cell}
        CustomProperties: No custom properties are set.
      Use addprop and rmprop to modify CustomProperties.

Row names, specified as a cell array of character vectors or a string array whose elements are nonempty and distinct. If RowNames is not empty, then the number of row names must equal the number of rows in the table.

  • Row names can have any Unicode characters, including spaces and non-ASCII characters.

  • If you assign row names with leading or trailing whitespace characters, then MATLAB® removes them from the row names.

  • The row names are visible when you view the table. Furthermore, you can use the row names within parentheses or curly braces to access the table data.

  • Another way to access the row names is to use dot syntax and the name of the first dimension of the table.

  • If you specify this property using a string array, then it is converted and stored as a cell array of character vectors.

Example

Create a table. Then add row names and access rows by their names.

load patients
T = table(Age,Height,Weight,Smoker,Systolic,Diastolic,SelfAssessedHealthStatus);
T.SelfAssessedHealthStatus = string(SelfAssessedHealthStatus);

Add row names using the Properties.RowNames property. By default, tables do not have row names, but you can add them at any time.

T.Properties.RowNames = string(LastName);
head(T,5)
                Age    Height    Weight    Smoker    Systolic    Diastolic    SelfAssessedHealthStatus
                ___    ______    ______    ______    ________    _________    ________________________

    Smith       38       71       176      true        124          93              "Excellent"       
    Johnson     43       69       163      false       109          77              "Fair"            
    Williams    38       64       131      false       125          83              "Good"            
    Jones       40       67       133      false       117          75              "Fair"            
    Brown       49       64       119      false       122          80              "Good"

Another way to access the row names is by using dot syntax with the name of the first dimension of the table. Display the first five row names.

T.Properties.DimensionNames
ans = 1x2 cell
    {'Row'}    {'Variables'}


T.Row(1:5)
ans = 5x1 cell
    {'Smith'   }
    {'Johnson' }
    {'Williams'}
    {'Jones'   }
    {'Brown'   }

Index into the table by row names.

T(["Smith","Brown"],:)
ans=2×7 table
             Age    Height    Weight    Smoker    Systolic    Diastolic    SelfAssessedHealthStatus
             ___    ______    ______    ______    ________    _________    ________________________

    Smith    38       71       176      true        124          93              "Excellent"       
    Brown    49       64       119      false       122          80              "Good"

Table description, specified as a character vector or string scalar. This description is visible when using the summary function.

If you specify this property using a string scalar, then it is converted and stored as a character vector.

Example

Create a table. Modify the description of the table. Display a summary of the result.

load patients
T = table(LastName,Age,Height,Weight);
T.LastName = string(T.LastName);
T.Properties.Description = "Simulated patient data";
summary(T)
T: 100x4 table

Description: Simulated patient data

Variables:

    LastName: string
    Age: double
    Height: double
    Weight: double

Statistics for applicable variables:

                NumMissing      Min         Median         Max         Mean            Std    

    LastName        0                                                                         
    Age             0            25              39         50        38.2800         7.2154  
    Height          0            60              67         72        67.0700         2.8365  
    Weight          0           111        142.5000        202            154        26.5714

Additional table information, specified as an array. You can attach data of any kind to a table using this property.

Example

Create a table. Attach an anonymous function as a piece of user data that is associated with the table.

load patients
T = table(LastName,Age,Height,Weight,Smoker,Systolic,Diastolic);
formula = @(x) x.^2;
T.Properties.UserData = formula;
T.Properties
ans = 
  TableProperties with properties:

             Description: ''
                UserData: @(x)x.^2
          DimensionNames: {'Row'  'Variables'}
           VariableNames: {'LastName'  'Age'  'Height'  'Weight'  'Smoker'  'Systolic'  'Diastolic'}
           VariableTypes: ["cell"    "double"    "double"    "double"    "logical"    "double"    "double"]
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowNames: {}
        CustomProperties: No custom properties are set.
      Use addprop and rmprop to modify CustomProperties.

Variable Metadata

Variable names, specified as a cell array of character vectors or a string array whose elements are nonempty and distinct. The number of names must equal the number of variables.

  • Variable names can have any Unicode characters, including spaces and non-ASCII characters.

  • The variable names are visible when viewing the table and when using the summary function. Furthermore, you can use the variable names within parentheses, within curly braces, or with dot indexing to access table data.

  • If you specify this property using a string array, then it is converted and stored as a cell array of character vectors.

Example

Create a table with default variable names. Then modify the names using the Properties.VariableNames property.

T = table(["Smith";"Nguyen";"Williams";"Fernandez";"Brown"],[38;43;38;40;49], ...
          [71;69;64;67;64],[176;163;131;133;119])
T=5×4 table
       Var1        Var2    Var3    Var4
    ___________    ____    ____    ____

    "Smith"         38      71     176 
    "Nguyen"        43      69     163 
    "Williams"      38      64     131 
    "Fernandez"     40      67     133 
    "Brown"         49      64     119 


T.Properties.VariableNames = ["LastName","Age","Height","Weight"]
T=5×4 table
     LastName      Age    Height    Weight
    ___________    ___    ______    ______

    "Smith"        38       71       176  
    "Nguyen"       43       69       163  
    "Williams"     38       64       131  
    "Fernandez"    40       67       133  
    "Brown"        49       64       119

A fundamental way to display and modify variables is to access them by name using dot syntax.

T.Age
ans = 5×1

    38
    43
    38
    40
    49


T.Age(1) = 53
T=5×4 table
     LastName      Age    Height    Weight
    ___________    ___    ______    ______

    "Smith"        53       71       176  
    "Nguyen"       43       69       163  
    "Williams"     38       64       131  
    "Fernandez"    40       67       133  
    "Brown"        49       64       119

Since R2024b

Variable data types, specified as a string array or a cell array of character vectors.

Example

Create a table.

load patients
T = table(LastName,Age,Height,Weight,Smoker,SelfAssessedHealthStatus)
T=100×6 table
      LastName      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'     }      
      ⋮

Display the data types of the table variables.

T.Properties.VariableTypes
ans = 1x6 string
    "cell"    "double"    "double"    "double"    "logical"    "cell"

You can also use the property to convert table variables to other data types. For example, convert the first variable to a string array and the last variable to a categorical array.

T.Properties.VariableTypes = ["string" "double" "double" "double" "logical" "categorical"]
T=100×6 table
     LastName     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             
      ⋮

Variable descriptions, specified as a cell array of character vectors or a string array This property can be an empty cell array, which is the default. If the array is not empty, then it must contain as many elements as there are variables. You can specify an individual empty character vector or empty string for a variable that does not have a description.

  • The variable descriptions are visible when using the summary function.

  • If you specify this property using a string array, then it is converted and stored as a cell array of character vectors.

Example

Create a table. Modify the variable descriptions. Display a summary of the result.

load patients
T = table(LastName,Age,Height,Weight,Smoker,Systolic,Diastolic);
T.LastName = string(T.LastName);
T.Properties.VariableDescriptions = ["","","","", ...
                                     "Has the patient ever been a smoker", ...
                                     "Systolic Pressure","Diastolic Pressure"];
summary(T)
T: 100x7 table

Variables:

    LastName: string
    Age: double
    Height: double
    Weight: double
    Smoker: logical (34 true, Has the patient ever been a smoker)
    Systolic: double (Systolic Pressure)
    Diastolic: double (Diastolic Pressure)

Statistics for applicable variables:

                 NumMissing      Min         Median         Max          Mean            Std    

    LastName         0                                                                          
    Age              0            25              39         50         38.2800         7.2154  
    Height           0            60              67         72         67.0700         2.8365  
    Weight           0           111        142.5000        202             154        26.5714  
    Systolic         0           109             122        138        122.7800         6.7128  
    Diastolic        0            68         81.5000         99         82.9600         6.9325

Variable units, specified as a cell array of character vectors or a string array. This property can be an empty cell array, which is the default. If the array is not empty, then it must contain as many elements as there are variables. You can specify an individual empty character vector or empty string for a variable that does not have units.

  • The variable units are visible when using the summary function.

  • If you specify this property using a string array, then it is converted and stored as a cell array of character vectors.

Example

Create a table. Modify the variable units. Display a summary of the result.

load patients
T = table(LastName,Age,Height,Weight,Smoker,Systolic,Diastolic);
T.LastName = string(T.LastName);
T.Properties.VariableUnits = ["","Yrs","In","Lbs","","mm Hg","mm Hg"];
summary(T)
T: 100x7 table

Variables:

    LastName: string
    Age: double (Yrs)
    Height: double (In)
    Weight: double (Lbs)
    Smoker: logical (34 true)
    Systolic: double (mm Hg)
    Diastolic: double (mm Hg)

Statistics for applicable variables:

                 NumMissing      Min         Median         Max          Mean            Std    

    LastName         0                                                                          
    Age              0            25              39         50         38.2800         7.2154  
    Height           0            60              67         72         67.0700         2.8365  
    Weight           0           111        142.5000        202             154        26.5714  
    Systolic         0           109             122        138        122.7800         6.7128  
    Diastolic        0            68         81.5000         99         82.9600         6.9325

Status as continuous or discrete variables, specified as a cell array of character vectors or a string array.

While tables and timetables both have this property, only timetables use it. For more information, see the VariableContinuity property of timetable.

Custom Metadata

Customized metadata of a table and its variables, specified as a CustomProperties object.

The CustomProperties object is a container for customized metadata that you can add to a table. By default, CustomProperties has zero properties. Each property you add to CustomProperties can contain either table metadata or variable metadata. If a property contains variable metadata, then its value must be an array, and the number of elements in the array must equal the number of table variables.

  • To add properties for customized metadata to a table, use the addprop function.

  • To access or modify customized metadata, use the syntax tableName.Properties.CustomProperties.PropertyName. In this syntax, PropertyName is the name you chose when you added that property using addprop.

  • To remove properties, use the rmprop function.

Note: You can add or remove only properties for customized metadata using addprop and rmprop. You cannot add or remove properties of the tableName.Properties object.

Example

Create a table.

load patients
T = table(LastName,Age,Height,Weight,Smoker,Systolic,Diastolic);

Add properties that can hold customized metadata about the table and its variables. In this example, the metadata are names of instruments, true and false values indicating whether variables are to be plotted, and the name of an output file. To add properties, use the addprop function.

T = addprop(T,["Instrument","ToPlot","OutputFile"],["variable","variable","table"]);
T.Properties
ans = 
  TableProperties with properties:

             Description: ''
                UserData: []
          DimensionNames: {'Row'  'Variables'}
           VariableNames: {'LastName'  'Age'  'Height'  'Weight'  'Smoker'  'Systolic'  'Diastolic'}
           VariableTypes: ["cell"    "double"    "double"    "double"    "logical"    "double"    "double"]
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowNames: {}

   Custom Properties (access using t.Properties.CustomProperties.<name>):
              OutputFile: []
              Instrument: []
                  ToPlot: []

Assign values to the customized metadata using dot syntax. When you assign an array of text values to customized metadata, the best practice is to use a string array, not a cell array of character vectors. If a property of CustomProperties is a cell array of character vectors, then there is no mechanism to prevent you from later assigning nontext values as elements of the cell array.

T.Properties.CustomProperties.Instrument = ["","","height rod","scale","","blood pressure cuff","blood pressure cuff"];
T.Properties.CustomProperties.ToPlot = [false false true true false true true];
T.Properties.CustomProperties.OutputFile = 'patientData.csv';
T.Properties
ans = 
  TableProperties with properties:

             Description: ''
                UserData: []
          DimensionNames: {'Row'  'Variables'}
           VariableNames: {'LastName'  'Age'  'Height'  'Weight'  'Smoker'  'Systolic'  'Diastolic'}
           VariableTypes: ["cell"    "double"    "double"    "double"    "logical"    "double"    "double"]
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowNames: {}

   Custom Properties (access using t.Properties.CustomProperties.<name>):
              OutputFile: 'patientData.csv'
              Instrument: [""    ""    "height rod"    "scale"    ""    "blood pressure cuff"    "blood pressure cuff"]
                  ToPlot: [0 0 1 1 0 1 1]

Remove the OutputFile property from T.

T = rmprop(T,"OutputFile");
T.Properties
ans = 
  TableProperties with properties:

             Description: ''
                UserData: []
          DimensionNames: {'Row'  'Variables'}
           VariableNames: {'LastName'  'Age'  'Height'  'Weight'  'Smoker'  'Systolic'  'Diastolic'}
           VariableTypes: ["cell"    "double"    "double"    "double"    "logical"    "double"    "double"]
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowNames: {}

   Custom Properties (access using t.Properties.CustomProperties.<name>):
              Instrument: [""    ""    "height rod"    "scale"    ""    "blood pressure cuff"    "blood pressure cuff"]
                  ToPlot: [0 0 1 1 0 1 1]

Examples

collapse all

Open Live Script

Store data about a group of patients in a table. You can perform calculations and store results in the same table. Also, you can annotate the table to describe your work and the variables of the table.

First, create workspace variables that have the patient data. The variables can have any data types but must have the same number of rows.

LastName = {'Sanchez';'Johnson';'Li';'Diaz';'Brown'};
Age = [38;43;38;40;49];
Smoker = logical([1;0;1;0;1]);
Height = [71;69;64;67;64];
Weight = [176;163;131;133;119];
BloodPressure = [124 93; 109 77; 125 83; 117 75; 122 80];

Create a table, T, as a container for the workspace variables. The table function uses the workspace variable names as the names of the table variables in T. A table variable can have multiple columns. For example, the BloodPressure variable in T is a 5-by-2 array.

T = table(LastName,Age,Smoker,Height,Weight,BloodPressure)
T=5×6 table
     LastName      Age    Smoker    Height    Weight    BloodPressure
    ___________    ___    ______    ______    ______    _____________

    {'Sanchez'}    38     true        71       176       124     93  
    {'Johnson'}    43     false       69       163       109     77  
    {'Li'     }    38     true        64       131       125     83  
    {'Diaz'   }    40     false       67       133       117     75  
    {'Brown'  }    49     true        64       119       122     80

You can use dot indexing to access table variables. For example, calculate the mean height of the patients using the values in T.Height.

meanHeight = mean(T.Height)
meanHeight = 
67

Calculate body mass index (BMI), and add it as a new table variable. You also can add and name table variables in one step, using dot syntax.

T.BMI = (T.Weight*0.453592)./(T.Height*0.0254).^2
T=5×7 table
     LastName      Age    Smoker    Height    Weight    BloodPressure     BMI  
    ___________    ___    ______    ______    ______    _____________    ______

    {'Sanchez'}    38     true        71       176       124     93      24.547
    {'Johnson'}    43     false       69       163       109     77      24.071
    {'Li'     }    38     true        64       131       125     83      22.486
    {'Diaz'   }    40     false       67       133       117     75      20.831
    {'Brown'  }    49     true        64       119       122     80      20.426

Annotate the table with a description of the BMI calculation. You can annotate T and its variables using metadata accessed through T.Properties.

T.Properties.Description = 'Patient data, including body mass index (BMI) calculated using Height and Weight';
T.Properties
ans = 
  TableProperties with properties:

             Description: 'Patient data, including body mass index (BMI) calculated using Height and Weight'
                UserData: []
          DimensionNames: {'Row'  'Variables'}
           VariableNames: {'LastName'  'Age'  'Smoker'  'Height'  'Weight'  'BloodPressure'  'BMI'}
           VariableTypes: ["cell"    "double"    "logical"    "double"    "double"    "double"    "double"]
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowNames: {}
        CustomProperties: No custom properties are set.
      Use addprop and rmprop to modify CustomProperties.
Open Live Script

Access all the data from a table as a matrix, using the name of the second dimension of the table.

Create a table that has five rows of data about a set of patients.

Age = [38;43;38;40;49];
Smoker = logical([1;0;1;0;1]);
Height = [71;69;64;67;64];
Weight = [176;163;131;133;119];
BloodPressure = [124 93; 109 77; 125 83; 117 75; 122 80];

T = table(Age,Smoker,Height,Weight,BloodPressure)
T=5×5 table
    Age    Smoker    Height    Weight    BloodPressure
    ___    ______    ______    ______    _____________

    38     true        71       176       124     93  
    43     false       69       163       109     77  
    38     true        64       131       125     83  
    40     false       67       133       117     75  
    49     true        64       119       122     80

Display the names of the table dimensions using the DimensionNames property. The default name of the second dimension is Variables.

T.Properties.DimensionNames
ans = 1x2 cell
    {'Row'}    {'Variables'}

Access the table data as a matrix using the syntax T.Variables. This syntax is equivalent to accessing all the contents using curly brace syntax, T{:,:}. If the table data cannot be concatenated into a matrix, then an error message is raised.

T.Variables
ans = 5×6

    38     1    71   176   124    93
    43     0    69   163   109    77
    38     1    64   131   125    83
    40     0    67   133   117    75
    49     1    64   119   122    80

Rename the second dimension. If you change the name, then you can use the new name to access the data.

T.Properties.DimensionNames{2} = 'PatientData';
T.PatientData
ans = 5×6

    38     1    71   176   124    93
    43     0    69   163   109    77
    38     1    64   131   125    83
    40     0    67   133   117    75
    49     1    64   119   122    80
Open Live Script

Preallocate a table by specifying its size and the data types of the variables. The table function fills the variables with default values that are appropriate for the data types you specify. It also gives the variables default names, but you also can assign variable names of your own. Preallocation provides room for data you add to the table later.

sz = [4 3];
varTypes = {'double','datetime','string'};
T = table('Size',sz,'VariableTypes',varTypes)
T=4×3 table
    Var1    Var2      Var3   
    ____    ____    _________

     0      NaT     <missing>
     0      NaT     <missing>
     0      NaT     <missing>
     0      NaT     <missing>

To specify names for the variables, use the 'VariableNames' name-value pair argument.

varNames = {'Temperature','Time','Station'};
T2 = table('Size',sz,'VariableTypes',varTypes,'VariableNames',varNames)
T2=4×3 table
    Temperature    Time     Station 
    ___________    ____    _________

         0         NaT     <missing>
         0         NaT     <missing>
         0         NaT     <missing>
         0         NaT     <missing>

Add rows of data to the first two rows of T2. Preallocation can be a useful technique when your code adds one row of data, or a few rows of data, at a time. Instead of growing the table every time you add a row, you can fill in table variables that already have room for your data.

T2(1,:) = {75,datetime('now'),"S1"};
T2(2,:) = {68,datetime('now')+1,"S2"}
T2=4×3 table
    Temperature            Time             Station 
    ___________    ____________________    _________

        75         05-Sep-2024 14:54:21    "S1"     
        68         06-Sep-2024 14:54:21    "S2"     
         0                          NaT    <missing>
         0                          NaT    <missing>

You can encapsulate a row of data values in a cell array. When you assign a row from a cell array, elements from the cell array are assigned to the row in the table.

Open Live Script

Create a table from arrays. To specify table variable names, use the 'VariableNames' name-value pair argument. For example, you can use 'VariableNames' to specify names when the other input arguments are not workspace variables.

T = table(categorical({'M';'F';'M'}),[45;32;34],...
          {'NY';'CA';'MA'},logical([1;0;0]),...
          'VariableNames',{'Gender','Age','State','Vote'})
T=3×4 table
    Gender    Age    State     Vote 
    ______    ___    ______    _____

      M       45     {'NY'}    true 
      F       32     {'CA'}    false
      M       34     {'MA'}    false

Create a table with the state names as row names. You can specify both the 'VariableNames' and 'RowNames' name-value pairs when using the table function.

T = table(categorical({'M';'F';'M'}),[45;32;34],logical([1;0;0]),...
          'VariableNames',{'Gender','Age','Vote'},...
          'RowNames',{'NY';'CA';'MA'})
T=3×3 table
          Gender    Age    Vote 
          ______    ___    _____

    NY      M       45     true 
    CA      F       32     false
    MA      M       34     false
Open Live Script

Specify row names for a table. Tables do not have to have row names, but if you specify them, then you can index into a table by row name. You also can access the set of row names using the name of the first dimension of a table.

Create arrays containing patient data.

LastName = {'Sanchez';'Johnson';'Lee';'Diaz';'Brown'};
Age = [38;43;38;40;49];
Height = [71;69;64;67;64];
Weight = [176;163;131;133;119];

Create a table containing the arrays. Specify LastName as the source of row names for the table. The table has only three variables. The row names are not a table variable, but instead a property of the table.

T = table(Age,Weight,Height,'RowNames',LastName)
T=5×3 table
               Age    Weight    Height
               ___    ______    ______

    Sanchez    38      176        71  
    Johnson    43      163        69  
    Lee        38      131        64  
    Diaz       40      133        67  
    Brown      49      119        64

Since the rows have row names, you can index into the rows of T by name.

T('Lee',:)
ans=1×3 table
           Age    Weight    Height
           ___    ______    ______

    Lee    38      131        64

To specify multiple rows, use a cell array.

T({'Lee','Brown'},:)
ans=2×3 table
             Age    Weight    Height
             ___    ______    ______

    Lee      38      131        64  
    Brown    49      119        64

To access all the row names of T as a cell array, use the syntax T.Row. By default, Row is the name of the first dimension of a table.

T.Row
ans = 5x1 cell
    {'Sanchez'}
    {'Johnson'}
    {'Lee'    }
    {'Diaz'   }
    {'Brown'  }

Change the name of the first dimension. If you change the name, then you can access the row names using the new name.

T.Properties.DimensionNames{1} = 'LastNames';
T.LastNames
ans = 5x1 cell
    {'Sanchez'}
    {'Johnson'}
    {'Lee'    }
    {'Diaz'   }
    {'Brown'  }
Open Live Script

Starting in R2017a, you can create strings using double quotes, and add string arrays as table variables.

FlightNum = [1261;547;3489];
Customer = ["Jones";"Brown";"Smith"];
Date = datetime(2016,12,20:22)';
Rating = categorical(["Good";"Poor";"Fair"]);
Comment = ["Flight left on time, not crowded";...
           "Late departure, ran out of dinner options";...
           "Late, but only by half an hour. Otherwise fine."];
T = table(FlightNum,Customer,Date,Rating,Comment)
T=3×5 table
    FlightNum    Customer       Date        Rating                         Comment                     
    _________    ________    ___________    ______    _________________________________________________

      1261       "Jones"     20-Dec-2016     Good     "Flight left on time, not crowded"               
       547       "Brown"     21-Dec-2016     Poor     "Late departure, ran out of dinner options"      
      3489       "Smith"     22-Dec-2016     Fair     "Late, but only by half an hour. Otherwise fine."

To use the text in a string array as row names, convert the string array to a cell array of character vectors. Then create a table with row names.

Customer = cellstr(Customer);
T = table(FlightNum,Date,Rating,Comment,'RowNames',Customer)
T=3×4 table
             FlightNum       Date        Rating                         Comment                     
             _________    ___________    ______    _________________________________________________

    Jones      1261       20-Dec-2016     Good     "Flight left on time, not crowded"               
    Brown       547       21-Dec-2016     Poor     "Late departure, ran out of dinner options"      
    Smith      3489       22-Dec-2016     Fair     "Late, but only by half an hour. Otherwise fine."
Open Live Script

Create workspace variables containing snowfall totals on different dates at three locations. These variables are row vectors.

Date = {'12/25/11','1/2/12','1/23/12','2/7/12','2/15/12'};
location1 = [20 5 13 0 17];
location2 = [18 9 21 5 12];
location3 = [26 10 16 3 15];

One way to create a table from these variables is to call the table function with the syntax T = table(Date',location1',location2',location3'). Because the workspace variables are row vectors, you must transpose them to put them into the table as column-oriented data. Therefore, the input arguments are expressions, not simple variables. As a result, table creates T with the default variable names Var1, Var2, Var3, and Var4. You can assign more meaningful names to T.Properties.VariableNames after you create T. But, it might be more convenient to create an empty table, and then add variables one at a time with new names.

Create an empty table. Transpose the workspace variables and add them to the table as column vectors. As part of assigning each workspace variable into T, provide a meaningful name for the table variable.

T = table;
T.Date = Date';
T.Natick = location1';
T.Boston = location2';
T.Worcester = location3'
T=5×4 table
        Date        Natick    Boston    Worcester
    ____________    ______    ______    _________

    {'12/25/11'}      20        18         26    
    {'1/2/12'  }       5         9         10    
    {'1/23/12' }      13        21         16    
    {'2/7/12'  }       0         5          3    
    {'2/15/12' }      17        12         15
Open Live Script

Starting in R2019b, you can specify table variable names that are not valid MATLAB® identifiers. Such variable names can include spaces, non-ASCII characters, and can have any character as the leading character. When you access such a variable name, enclose it quotation marks.

Create a table that stores data about a set of patients. Start with their ages and status as smokers.

Age = [38;43;38;40;49];
Smoker = logical([1;0;1;0;1]);
Height = [71;69;64;67;64];
Weight = [176;163;131;133;119];
BloodPressure = [124 93; 109 77; 125 83; 117 75; 122 80];
T = table(Age,Smoker)
T=5×2 table
    Age    Smoker
    ___    ______

    38     true  
    43     false 
    38     true  
    40     false 
    49     true

Add the blood pressure readings with the variable name '29-May-2019 Blood Pressure Reading'. You can use dot syntax to add or access the variable. Since its name is not a valid MATLAB identifier, use parentheses and quotation marks with dot syntax.

T.('29-May-2019 Blood Pressure Reading') = BloodPressure
T=5×3 table
    Age    Smoker    29-May-2019 Blood Pressure Reading
    ___    ______    __________________________________

    38     true                  124     93            
    43     false                 109     77            
    38     true                  125     83            
    40     false                 117     75            
    49     true                  122     80

When table variable names are valid MATLAB identifiers, you can use dot syntax without parentheses and quotation marks.

T.Height = Height;
T.Weight = Weight
T=5×5 table
    Age    Smoker    29-May-2019 Blood Pressure Reading    Height    Weight
    ___    ______    __________________________________    ______    ______

    38     true                  124     93                  71       176  
    43     false                 109     77                  69       163  
    38     true                  125     83                  64       131  
    40     false                 117     75                  67       133  
    49     true                  122     80                  64       119

Index into T using variable names.

T(:,{'Age','Smoker','29-May-2019 Blood Pressure Reading'})
ans=5×3 table
    Age    Smoker    29-May-2019 Blood Pressure Reading
    ___    ______    __________________________________

    38     true                  124     93            
    43     false                 109     77            
    38     true                  125     83            
    40     false                 117     75            
    49     true                  122     80

Limitations

  • Use single quotes for these input names:

    • 'DimensionNames' (since R2021a)

    • 'RowNames'

    • 'Size'

    • 'VariableTypes'

    • 'VariableNames'

    To avoid confusion with variable inputs, do not use double-quoted string scalars (such as "RowNames") for these names.

Tips

  • For a list of functions that accept or return tables, see Tables.

Extended Capabilities

Thread-Based Environment
Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

Version History

Introduced in R2013b

expand all

See Also

| | | | | | |

Topics