table
datatypes: table
Array of tabular data containing multiple columnar variables.
A table is a 2-dimensional data structure that collects heterogeneous data and metadata into a single container. Tables are suitable for storing columnar data much like spreadsheets but they can also be used for storing more complex data including multicolumnar variables and nested tables.
Tables can be subscripted using parentheses like ordinary numeric arrays,
but in addition to indexing with numeric and logical vectors, you can also
use the table’s variable or row names much like indexing a structure field
as well as using a vartype class object to make a selection of
variable types. While these methods will return a subset of the original
table, you can also use curly brackets much like cell arrays to retrieve
the contents of the table. In this case, the original data types of the
selected variables are returned.
Besides the table constructor, you can also use array2table,
cell2table, and struct2table to create tables from the
respective data types.
Besides all numeric data types, other supported data types that can be
stored in a table array are logical, categorical,
cell, (including cellstr), calendarDuration,
duration, datetime, string, and struct
arrays, as well as table itself.
See also: vartype, array2table, cell2table, struct2table
Source Code: table
The table class contains the following properties:
Table description specified as a character vector or a string scalar.
If specified as a string scalar, it is converted and stored internally
as a character vector. You can access the Description property
of a table tbl with tbl.Properties.Description.
Additional table information, specified as an array. Any type of data
can be attached using this property. You can access the UserData
property of a table tbl with tbl.Properties.UserData.
Dimension names specified as a two-element cell array of character
vectors or a two-element string array. If specified as a string array,
it is converted and stored internally as a cell array of character
vectors. You can access the DimensionNames property of a table
tbl with tbl.Properties.DimensionNames.
By default, DimensionNames is specified as
'Row', 'Variables'. You can access table data per rows or per
columns by using either one of the two dimension names, respectively.
However, if the table contains row names, then the first element of the
DimensionNames corresponds to the row names.
Create a table and display its dimension names. You can access row names and data using dimension names with dot syntax.
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];
T = table (Age, Smoker, Height, Weight, BloodPressure, 'RowNames', LastName)
T =
5x5 table
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
T.Properties.DimensionNames
ans =
1x2 cell array
{'Row'} {'Variables'}
Access the row names using the first dimension name.
T.Row
ans =
5x1 cell array
{'Sanchez'}
{'Johnson'}
{'Li' }
{'Diaz' }
{'Brown' }
Access the data using the second dimension name.
T.Variables
ans =
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
Modify the names of its dimensions using the Properties
T.Properties.DimensionNames = {'Patient', 'Data'};
T.Properties
ans =
scalar structure containing the fields:
Description =
UserData = [](0x0)
DimensionNames =
{
[1,1] = Patient
[1,2] = Data
}
VariableTypes =
{
[1,1] = double
[1,2] = logical
[1,3] = double
[1,4] = double
[1,5] = double
}
VariableNames =
{
[1,1] = Age
[1,2] = Smoker
[1,3] = Height
[1,4] = Weight
[1,5] = BloodPressure
}
VariableDescriptions =
{
[1,1] =
[1,2] =
[1,3] =
[1,4] =
[1,5] =
}
VariableUnits =
{
[1,1] =
[1,2] =
[1,3] =
[1,4] =
[1,5] =
}
VariableValues =
{
[1,1] =
38
43
38
40
49
[1,2] =
1
0
1
0
1
[1,3] =
71
69
64
67
64
[1,4] =
176
163
131
133
119
[1,5] =
124 93
109 77
125 83
117 75
122 80
}
RowNames =
{
[1,1] = Sanchez
[2,1] = Johnson
[3,1] = Li
[4,1] = Diaz
[5,1] = Brown
}
CustomProperties = [](0x0)
Change a single dimension name
T.Properties.DimensionNames(1) = 'Patients'
T =
5x5 table
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
T.Properties
ans =
scalar structure containing the fields:
Description =
UserData = [](0x0)
DimensionNames =
{
[1,1] = Patients
[1,2] = Data
}
VariableTypes =
{
[1,1] = double
[1,2] = logical
[1,3] = double
[1,4] = double
[1,5] = double
}
VariableNames =
{
[1,1] = Age
[1,2] = Smoker
[1,3] = Height
[1,4] = Weight
[1,5] = BloodPressure
}
VariableDescriptions =
{
[1,1] =
[1,2] =
[1,3] =
[1,4] =
[1,5] =
}
VariableUnits =
{
[1,1] =
[1,2] =
[1,3] =
[1,4] =
[1,5] =
}
VariableValues =
{
[1,1] =
38
43
38
40
49
[1,2] =
1
0
1
0
1
[1,3] =
71
69
64
67
64
[1,4] =
176
163
131
133
119
[1,5] =
124 93
109 77
125 83
117 75
122 80
}
RowNames =
{
[1,1] = Sanchez
[2,1] = Johnson
[3,1] = Li
[4,1] = Diaz
[5,1] = Brown
}
CustomProperties = [](0x0)
T.Patients
ans =
5x1 cell array
{'Sanchez'}
{'Johnson'}
{'Li' }
{'Diaz' }
{'Brown' }
Variable names, specified as a cell array of character vectors or a
string array. If specified as a string array, it is converted and stored
internally as a cell array of character vectors. All elements must be
nonempty and distinct, and their number must equal the number of
variables. You can access the data type of a specific variable by using
dot name assignment, as in tbl.varname, where
varname is the name of the variable in table tbl. If the
variable name does not exist, a new one is created.
Store patient data in a table
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];
T = table (LastName, Age, Smoker, Height, Weight, BloodPressure)
T =
5x6 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
Use indexing to access variables
meanHeight = mean (T.Height)
meanHeight = 67
Calculate body mass index (BMI), and add it as a new table variable.
pounds2kg = 0.4535924; inch2meter = 0.0254; T.BMI = (T.Weight * pounds2kg) ./ (T.Height * inch2meter) .^ 2
T =
5x7 table
LastName Age Smoker Height Weight BloodPressure BMI
___________ ___ ______ ______ ______ _____________ _______
{'Sanchez'} 38 true 71 176 124 93 24.5468
{'Johnson'} 43 false 69 163 109 77 24.0706
{'Li' } 38 true 64 131 125 83 22.4859
{'Diaz' } 40 false 67 133 117 75 20.8305
{'Brown' } 49 true 64 119 122 80 20.4261
The class of the data of each variable, defined as a cell array of
character vectors or a string array with the same number of elements as
the number of variables in the table. If specified as a string array,
it is converted and stored internally as a cell array of character
vectors. You can access the VariableTypes property of a table
tbl with tbl.Properties.VariableTypes. You can
further index specific variables to access their data type. Modifying
the elements of the VariableTypes property automatically converts
the underlying data of the corresponding variable into the specified
data types provided that a valid conversion is requested.
Variable descriptions, specified as a cell array of character vectors or
a string array. If specified as a string array, it is converted and
stored internally as a cell array of character vectors. If not empty
(default), it must contain the same number of elements as the number of
variables. If a specific variable does not have a description, this can
be specified with an individual empty character vector or an empty
string. You can access the VariableDescriptions property of a
table tbl with tbl.Properties.VariableDescriptions.
You can further index specific variables to access their description.
Variable units, specified as a cell array of character vectors or a
string array. If specified as a string array, it is converted and stored
internally as a cell array of character vectors. If not empty (default),
it must contain the same number of elements as the number of variables.
If a specific variable does not have a unit, this can be specified with
an individual empty character vector or an empty string. You can access
the VariableUnits property of a table tbl with
tbl.Properties.VariableUnits. You can further index
specific variables to access their unit.
Row names, specified as a cell array of character vectors or a string
array. If specified as a string array, it is converted and stored
internally as a cell array of character vectors. If not empty (default),
it must contain the same number of elements as the number of rows in the
table. All elements must be nonempty and distinct. You can access the
rows of the table tbl by specifying one or more row names within
parentheses or curly braces. You can also set RowNames by
dot name assignment to an existing variable.
Access rows by selecting row names
LastName = {'Sanchez'; 'Johnson'; 'Lee'; 'Diaz'; 'Brown'};
Age = [38;43;38;40;49];
Height = [71;69;64;67;64];
Weight = [176;163;131;133;119];
T = table (Age, Weight, Height, 'RowNames', LastName)
T =
5x3 table
Age Weight Height
___ ______ ______
Sanchez 38 176 71
Johnson 43 163 69
Lee 38 131 64
Diaz 40 133 67
Brown 49 119 64
T('Lee',:)
ans =
1x3 table
Age Weight Height
___ ______ ______
Lee 38 131 64
T{'Lee',:}
ans =
38 131 64
T({'Lee', 'Diaz'},:)
ans =
2x3 table
Age Weight Height
___ ______ ______
Lee 38 131 64
Diaz 40 133 67
T{{'Lee', 'Diaz'},:}
ans =
38 131 64
40 133 67
Set row names by assigning a new variable
LastName = {'Sanchez'; 'Johnson'; 'Lee'; 'Diaz'; 'Brown'};
Age = [38;43;38;40;49];
Height = [71;69;64;67;64];
Weight = [176;163;131;133;119];
T = table (Age, Weight, Height)
T =
5x3 table
Age Weight Height
___ ______ ______
38 176 71
43 163 69
38 131 64
40 133 67
49 119 64
T.Properties.RowNames = LastName
T =
5x3 table
Age Weight Height
___ ______ ______
Sanchez 38 176 71
Johnson 43 163 69
Lee 38 131 64
Diaz 40 133 67
Brown 49 119 64
Set row names by assigning an existing variable
LastName = {'Sanchez'; 'Johnson'; 'Lee'; 'Diaz'; 'Brown'};
Age = [38;43;38;40;49];
Height = [71;69;64;67;64];
Weight = [176;163;131;133;119];
T = table (Age, Weight, Height, LastName)
T =
5x4 table
Age Weight Height LastName
___ ______ ______ ___________
38 176 71 {'Sanchez'}
43 163 69 {'Johnson'}
38 131 64 {'Lee' }
40 133 67 {'Diaz' }
49 119 64 {'Brown' }
In this case the variable persists in the table
T.Properties.RowNames = T.LastName
T =
5x4 table
Age Weight Height LastName
___ ______ ______ ___________
Sanchez 38 176 71 {'Sanchez'}
Johnson 43 163 69 {'Johnson'}
Lee 38 131 64 {'Lee' }
Diaz 40 133 67 {'Diaz' }
Brown 49 119 64 {'Brown' }
In this case the variable is removed from the table
T.Properties.RowNames = 'LastName'
T =
5x3 table
Age Weight Height
___ ______ ______
Sanchez 38 176 71
Johnson 43 163 69
Lee 38 131 64
Diaz 40 133 67
Brown 49 119 64
Custom properties that contain metadata of a table and its variables.
By default, this is an empty container. Each custom property holds
either table metadata or per-variable metadata, according to the property
type ('table' or 'variable') specified when the property
is created with the addprop method. A variable-scoped property
holds one element per variable.
You can add custom properties only by using the addprop method and
you can only remove a custom property with the rmprop method. To
access existing custom properties use dot name structure assignment as in
tbl.Properties.CustomProperties.PropertyName, where
PropertyName is the name used with the addprop method.
The table class offers the following public methods:
table |
Create a new table. |
table2array |
Converts a table to a homogeneous array. |
table2cell |
Converts a table to a cell array. |
table2struct |
Converts a table to a scalar structure or structure array. |
table2csv |
Write a table to a comma-separated-value (CSV) file. |
table2ods |
Write a table to an OpenDocument spreadsheet file. |
writetable |
Write a table to a file in a MATLAB-compatible format. |
sortrows |
Sort the rows of a table. |
unique |
Unique rows in a table. |
issortedrows |
Check if table rows are sorted accordingly. |
topkrows |
Return the top rows of a table. |
addvars |
Add new variables to a table. |
renamevars |
Rename variables in a table. |
movevars |
Move variables in a table. |
removevars |
Remove variables from a table. |
splitvars |
Split multicolumn variables in a table. |
mergevars |
Merge table variables into a single multicolumn variable. |
convertvars |
Convert table variables to specified data type. |
rows2vars |
Reorient table by swapping rows into variables. |
stack |
Stack multiple table variables into a single table variable. |
unstack |
Unstack a single table variable into multiple table variables. |
inner2outer |
Invert the nested hierarchy of nested tables in a table. |
addprop |
Add custom properties to a table. |
rmprop |
Remove custom properties from a table. |
join |
Combine two tables by rows using key variables. |
innerjoin |
Inner join between two tables by rows using key variables. |
outerjoin |
Outer join between two tables by rows using key variables. |
union |
Union of two tables by rows. |
intersect |
Intersection of two tables by rows. |
ismember |
Find set members between two tables by rows. |
setdiff |
Difference between two tables by rows. |
setxor |
Exclusive OR of two tables by rows. |
anymissing |
Determine if any table element is missing. |
ismissing |
Find missing values in table. |
rmmissing |
Remove missing table elements by rows. |
fillmissing |
Fill missing entries of a table, variable by variable. |
standardizeMissing |
Insert standard missing values into a table. |
findgroups |
Find groups defined by the variables of a table. |
splitapply |
Split table data into groups and apply a function to each group. |
varfun |
Apply a function to each variable of a table. |
rowfun |
Apply a function to each row of a table. |
groupsummary |
Compute summary statistics by group for the variables of a table. |
groupcounts |
Count the number of rows in each group of a table. |
groupfilter |
Filter the rows of a table by a per-group condition. |
grouptransform |
Transform the data variables of a table group by group. |
pivot |
Summarize tabular data in a pivoted table. |
horzcat |
Horizontal concatenation for tables. |
iscolumn |
Test input table for being a column vector. |
isempty |
Test input table for being empty. |
ismatrix |
Test input table for being a matrix. |
isrow |
Test input table for being a row vector. |
isscalar |
Test input table for being a scalar. |
istable |
Return true if input is a table. |
isvector |
Test input table for being a vector. |
length |
Length along longest dimension. |
ndims |
Number of table dimensions. |
numel |
Total number of elements in table. |
repelem |
Replicate elements of a table. |
repmat |
Repeat copies of a table. |
size |
Return the size of a table. |
squeeze |
Remove singleton dimensions. |
vertcat |
Vertical concatenation for tables. |