table
Table array with named variables that can contain different types
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., extracts one variable.varnameCurly braces, as in
T{, extracts an array from specified rows and variables.rows,vars}Parentheses, as in
T(, returns a table.rows,vars)
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
Description
T = table( creates a
table from the input variables var1,...,varN)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',...,'Var, where
N'N
T = table('Size',
creates a table and preallocates space for the variables that have data types
you specify. sz,'VariableTypes',varTypes)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.
T = table(___,
specifies additional input arguments using one or more name-value pair
arguments. For example, you can specify variable names using the
Name,Value)'VariableNames' name-value pair. You can use this syntax
with any of the input arguments of the previous syntaxes.
T = table creates an empty 0-by-0 table.
Input Arguments
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- or single-precision |
| Double- or single-precision
|
| Signed 8-, 16-, 32-, or 64-bit integer |
| Unsigned 8-, 16-, 32-, or 64-bit integer |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Scalar structure with no fields |
| Table with no variables |
| Timetable with no variables and |
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
tablefunction also stores the variable names in theVariableNamesproperty 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
tablefunction also stores the row names in theRowNamesproperty of the table.Row names can have any Unicode characters, including spaces and non-ASCII characters.
The
tablefunction 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
tablefunction also stores the dimension names in theDimensionNamesproperty 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
Access Table Metadata Properties
A table contains metadata properties that describe the table and its variables. Access
these properties using the syntax
tableName.Properties.PropertyNamePropertyNameT 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 = 1×2 cell
{'Row'} {'Variables'}
Access the row names using the first dimension name. Display the first five names.
T.Row(1:5)
ans = 5×1 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
45 68 128 114 77
42 66 137 115 68
25 71 174 127 74
39 72 202 130 95
36 65 129 114 79
⋮
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: {100×1 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 = 1×2 cell
{'Row'} {'Variables'}
T.Row(1:5)
ans = 5×1 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: 100×4 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.Propertiesans =
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
summaryfunction. 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 = 1×6 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
summaryfunction.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: 100×7 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
summaryfunction.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: 100×7 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
addpropfunction.To access or modify customized metadata, use the syntax
tableName.Properties.CustomProperties.PropertyNamePropertyNameaddprop.To remove properties, use the
rmpropfunction.
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
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.Propertiesans =
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
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.Propertiesans =
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.
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 = 1×2 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.PatientDataans = 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
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 09-Aug-2025 11:48:05 "S1"
68 10-Aug-2025 11:48:05 "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.
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
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 = 5×1 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.LastNamesans = 5×1 cell
{'Sanchez'}
{'Johnson'}
{'Lee' }
{'Diaz' }
{'Brown' }
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."
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
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') = BloodPressureT=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
The
table function supports tall arrays with the following usage
notes and limitations:
The syntax
TT = table(T1,T2,...)constructs a tall table from several tall arrays(T1,T2,...). You can use theVariableNamesname-value argument to specify variable names.The
VariableTypesproperty is not supported.
For more information, see Tall Arrays.
Usage notes and limitations:
Starting in R2019b, you can use tables in MATLAB code intended for code generation. For more information, see Code Generation for Tables (MATLAB Coder) and Table Limitations for Code Generation (MATLAB Coder).
Thread-Based Environment
Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.
Usage notes and limitations:
The input arrays must be distributed and have the same number of rows.
The result is distributed, using a 1D distribution scheme over the first dimension.
For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).
Version History
Introduced in R2013bIn tables and timetables, the maximum allowed length of dimension and variable
names has increased to 2048 characters. This length matches the updated maximum
identifier length, which you can query by using the namelengthmax function.
Using longer dimension and variable names in tables and timetables might negatively impact performance and memory.
Previously, the maximum length of dimension and variable names in tables and timetables was 63 characters. Code that depends on dimension and variable names being no longer than 63 characters might not run as expected.
If you save a table or timetable with long dimension or variable names to a MAT file, then you can load it into a MATLAB release before R2025a. However, the earlier MATLAB release truncates the long dimension and variable names in the table or timetable to 63 characters.
The VariableTypes property of tables and timetables specifies the data
types of their variables.
You can now perform calculations directly on tables and timetables without extracting their data. All the variables in your tables and timetables must have data types that support calculations. You can also perform operations where one operand is a table or timetable and the other is a numeric or logical array. Previously, all calculations required you to extract data from your tables and timetables by indexing into them.
For more information, see Direct Calculations on Tables and Timetables and Rules for Table and Timetable Mathematics.
Subscripting when using dot notation is significantly faster in R2022a than in R2021b. Also, subscripting with multiple levels of indexing is faster.
For example, when you use dot notation to refer to a table variable with 106 elements, performance in R2022a is more than 4x faster than in R2021b.
function timingTest() t = table(zeros(1e6,1), ones(1e6,1), nan(1e6,1)); indices = 1:10000; tic; % Refer to variable using dot notation for i = indices x = t.Var1; end toc end
The approximate execution times are:
R2021b: 0.15 s
R2022a: 0.035 s
Similarly, when you use dot notation to assign an array to a table variable with 106 elements, performance in R2022a is about 3.6x faster than in R2021b.
function timingTest() t = table(zeros(1e6,1), ones(1e6,1), nan(1e6,1)); indices = 1:10000; x = randi(1e6,1e6,1); tic; % Assign to variable using dot notation for i = indices t.Var1 = x; end toc end
The approximate execution times are:
R2021b: 0.23 s
R2022a: 0.063 s
Also, when you use dot notation and parentheses to assign individual values to elements of a table variable, performance in R2022a is more than 4x faster than in R2021b.
function timingTest() t = table(zeros(1e6,1), ones(1e6,1), nan(1e6,1)); indices = randi(1e6,1,10000); tic; % Assign to elements using dot notation and parentheses for i = indices t.Var1(i) = rand; end toc end
The approximate execution times are:
R2021b: 0.53 s
R2022a: 0.12 s
The code was timed on a Windows® 10, Intel® Xeon CPU W-2133 @ 3.60 GHz test system by calling each version of the
timingTest function.
Subscripted assignment using curly braces is significantly faster in R2021b than in R2021a.
For example, when you assign into three table variables with 106 elements, performance in R2021b is approximately 4.4x faster, as shown below.
function timingTest() t = table(zeros(1e6,1), ones(1e6,1), nan(1e6,1)); indices = randi(1e6,1,10000); tic; % Assign row vector of random values to randomly chosen row for i = indices t{i,:} = rand(1,3); end toc end
The approximate execution times are:
R2021a: 7.4 s
R2021b: 1.7 s
The code was timed on a Windows 10 system with a 3.6 GHz Intel Xeon W-2133 CPU by calling the timingTest function
in R2021a and R2021b.
MATLAB raises an error if you assign a dimension name that matches one of
these reserved names: 'Properties',
'RowNames', 'VariableNames', or
':'. In previous releases, MATLAB raised a warning and modified the dimension names so that they were
different from the reserved names.
Subscripted assignment into table variables is significantly faster. Performance is essentially constant with the number of elements in each table variable.
For example, when you use dot indexing to assign elements to a variable with 106 elements, performance in R2020a is approximately 2x faster than in R2019b, as shown below.
function timingTest() t = table(zeros(1e6,1)); indices = randi(1e6,1,10000); tic; for i = indices t.Var1(i) = rand; end toc end
The approximate execution times are:
R2019b: 1.20 s
R2020a: 0.59 s
Similarly, assignment using curly braces is faster. When you assign into three table variables with 106 elements, performance in R2020a is approximately 1.2x faster than in R2019b, as shown below.
function timingTest() t = table(zeros(1e6,1), ones(1e6,1), nan(1e6,1)); indices = randi(1e6,1,10000); tic; for i = indices t{i,:} = rand; end toc end
The approximate execution times are:
R2019b: 8.04 s
R2020a: 6.68 s
The code was timed on a Windows 10, Intel
Xeon® W-2133 @ 3.60 GHz test system by calling the function
timingTest.
The performance improvement occurs only when you make table subscripted
assignments within a function. There is no improvement when subscripting into tables
at the command line, or within try-catch blocks.
Table and timetable variable names with leading or trailing whitespace characters are not modified.
In previous releases, leading and trailing whitespace characters were deleted from variable names when you specified them using the 'VariableNames' name-value pair argument, or assigned them to the VariableNames property.
To manually remove such characters, first use the strtrim function on the names,
then assign them as variable names to the table or timetable.
MATLAB raises an error if you assign a table variable name that matches a dimension name, or a dimension name that matches a variable name. In previous releases, MATLAB raised a warning and modified the names so they were unique.
Subscripted assignment into large table variables is significantly faster. Performance is now essentially constant with the number of elements in each table variable.
For example, when you use dot indexing to assign elements to a variable with 106 elements, performance in R2019b is approximately 40x times faster, as shown below.
function timingTest() t = table(zeros(1e6,1)); indices = randi(1e6,1,10000); tic; for i = indices t.Var1(i) = rand; end toc end
The approximate execution times are:
R2019a: 47.83 s
R2019b: 1.20 s
Similarly, assignment using curly braces is faster. For example, when you assign into three table variables with 106 elements, performance in R2019b is approximately 18x faster.
function timingTest() t = table(zeros(1e6,1), ones(1e6,1), nan(1e6,1)); indices = randi(1e6,1,10000); tic; for i = indices t{i,:} = rand; end toc end
The approximate execution times are:
R2019a: 156.39 s
R2019b: 8.51 s
The code was timed on a Windows 10 system with a 3.6 GHz Intel Xeon W-2133 CPU by calling each version of the
timingTest function.
The larger the table variables are, the greater the performance improvement becomes. However, the performance improvement occurs only when you make table subscripted assignments within a function. There is no improvement when subscripting into tables at the command line, or within try-catch blocks.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)