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 singe 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 used curly brackets much like cell arrays to retrieve
the contents of the table. In this case, the original data type 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
Custom properties that contain metadata of a table and its variables. By default, this is an empty container. Each custom property can contain either table metadata or variable metadata. Any custom property which is an array with the same number of elements as the number of variables is considered as variable metadata, otherwise is considered table metadata.
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.
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.
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. Leading and trailing white space character are automatically removed.
Additional table information, specified as an array. Any type of data can be attached using this property.
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.
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.
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 description, this can be specified with an individual empty character vector or an empty string.
The values of the variables, defined as a cell vector of arbitrary types.
You can access the values of a specific variable of a table tbl by
using the dot notation, as in tbl.VarName.
'Size', sz, 'VariableTypes', varTypes)'VariableNames', varNames)'RowNames', rowNames)'DimensionNames', dimNames)Create a new table.
tbl = table (var1, var2, …, varN)
created a new table with the given variables. The variables passed as
input arguments become the variables of the table. Their names are
automatically detected from the input variable names that you used.
tbl = table ( creates a new table of the given size, sz, and
with the given variable types, varTypes. sz must be a two-
element numeric array, where 'Size', sz, 'VariableTypes',
varTypes)sz(1) specifies the number of
rows and sz(2) specifies the number of variables. The
variables will contain the default value for elements of that type.
tbl = table (…,
specifies the variable names to use in the constructed table.
varNames must be either a cell array of character vectors of string
array with the same number of nonempty and unique elements as the number
of table variables.
'VariableNames', varNames)
tbl = table (…,
specifies the row names to use in the constructed table. dimNames
must be either a cell array of character vectors of string array with the
same number of nonempty and unique elements as the number of rows in the
table.
'RowNames', rowNames)
tbl = table (…,
specifies the dimension names to use in the constructed table.
dimNames must be either a two-element cell array of character
vectors or a two-element string array with nonempty and unique elements.
'DimensionNames', dimNames)
tbl = table () returns an empty table with 0 rows and 0
variables.
See also: array2table, cell2table, struct2table, table, istable
Print a summary of a table.
summary (tbl prints the description from
tbl.Properties.Description (not implemented yet) followed
by a summary of each table variable’s values and their properties as
defined in tbl.Properties.VariableUnits and
tbl.Properties.VariableDescriptions (not implemented yet).
s = summary (tbl returns a structure, s, that
contains a summary of the input table, tbl. Each field of s
is a structure that summarizes the values in the corresponding variable
of tbl.
double, single or any
int type, it prints the minimum, median, and maximum values. For
multicolumnar numerical variables it prints the minimum, median, and
maximum values for each column separately.
logical type, it prints the occurences
of True and False.
datetime, duration, and
calendarDuration it prints the minimum, median, and maximum
values along with the TimeStep, which is only calculated for fixed
intervals present in the data, otherwise NaN is returned.
cellstr, cell, string
and struct it prints the size and the type of variable.
Number of rows in table.
H = height (tbl) returns the number of rows in the
table, tbl. It is the equivalent of size (tbl, 1).
Number of variables in table.
W = width (tbl) returns the number of variables in the
table, tbl. It is the equivalent of size (tbl, 2).
Note that this is not the sum of the number of columns in each variable. It is just the number of variables.
Display or return the first K rows of table.
head (tbl) displays the first eight rows of the table
tbl. If there are less rows in tbl, head displays all
rows available. k must be a positive integer scalar value.
head (tbl, k) displays the first k rows of the
table tbl. If there are less than k rows in tbl,
head displays all rows available.
out = head (tbl, k) returns the first k
rows in a new table out. If k is omitted or empty, then it
defaults to eight. If there are less than k rows in tbl,
all rows available are returned.
Display or return the last K rows of table.
tail (tbl) displays the last eight rows of the table
tbl. If there are less rows in tbl, tail displays all
rows available. k must be a positive integer scalar value.
tail (tbl, k) displays the last k rows of the
table tbl. If there are less than k rows in tbl,
tail displays all rows available.
out = tail (tbl, k) returns the last k
rows in a new table out. If k is omitted or empty, then it
defaults to eight. If there are less than k rows in tbl,
all rows available are returned.
'RowNames')Sort the rows of a table.
tblB = sortrows (tblA) sorts the rows in tblA in
asceding order based on the values in the first variable. If elements
in the first variable are repeated, then sortrows sorts by the
elements in the second variable, and so on.
tblB = sortrows (tblA, 'RowNames') sorts the
table tblA according to its row names. If tblA does not
have row names, i.e. tblA.Properties.RowNames is empty, then it
returns tblA.
tblB = sortrows (tblA, rowDimName) also sorts
the table tblA along the first dimension, rowDimName, which
is the equivalent to the previous syntax, i.e. according to its row
names. If tblA does not have row names, that is
tblA.Properties.RowNames is empty, then it returns tblA.
For this syntax to work, rowDimName must match the first element in
tblA.Properties.DimensionNames, otherwise rowDimName is
considered a variable name, as in the following syntax.
tblB = sortrows (tblA, vars) sorts the rows in
table tblA by the elements in the variables specified by
vars, which can be a character vector (for a single variable) or a
cell array of character vectors or a string array (specifying a single or
multiple variables). If tblA has row names, then vars can
include the row names. Alternatively, vars can be a logical vector
or a numeric vector of real integers indexing the desired variables.
Positive integers specify an ascending order, whereas negative integers
specify a descending order for the referenced variables. You can also
index all available variables in tblA by passing a semicolon
character argument. This Octave specific syntax, facilitates the use of
direction input argument, when no particular variable needs to be
selected for sorting upon. Additionally, vars can be a
vartype object used to create a subscript that selects variables
of a specified type.
tblB = sortrows (tblA, …, direction) sorts
the rows in table tblA in the order specified by direction
for any of the previous syntaxes. direction can be
'ascend' or 'descend', which is applied to all specified
variables or row names that sortrows operates on. direction
can also be a cell array of character vectors, whose elements are
'ascend' and 'descend', where each element corresponds to
the specified variables and/or, row names used for sorting the table.
The order specified by direction always takes precedence over the
order defined by a numerical vector of integers in vars.
direction must always be the 3rd inpnut argument. If you want to
omit passing selected variables and allow sortrows to work on
consequtive variables until all ties are resolved, then you can leave the
second input argument empty, as in
sortrows (tblA, {[]}, direction) or pass a
colon argument for vars as in
sortrows (tblA, {':'}, direction).
tblB = sortrows (…, Name, Value) specifies
additional parameters for sorting rows of a table with the following
Name-Value paired arguments.
'MissingPlacement' specifies the placement of missing
values with one of the following options: 'auto' places the
missing elements at the bottom for ascending order and at the top for
descending order; 'first' places missing elements at the top;
'last' places missing elements at the bottom.
'ComparisonMethod' specifies the element comparison method
with one of the following options: 'auto' sorts rows using the
real part for real numbers and the magnitude for complex numbers;
'real' sorts rows using the real part for both real and complex
numbers; 'abs' sorts rows using the magnitude for both real and
complex numbers. For complex numbers with equal magnitude, the phase
angle in the interval is further used to break ties.
[tblB, index] = sortrows (…) also returns an
index vector such that tblB = tblA(index,:).
Unique rows in a table.
tblB = unique (tblA) returns the unique rows of table
tblA in sorted order.
tblB = unique (tblA, setOrder) returns the
unique rows of table tblA in a specified order. setOrder can
be either "sorted" (default) or "stable".
'sorted' returns the unique rows sorted in ascending order.
'stable' returns the unique rows according to their order
of occurence.
tblB = unique (tblA, occurence) returns the
unique rows of table tblA according to their order of occurence.
occurence cen be either 'first' (default) or 'last'.
'first' returns the first occurence of each unique row,
i.e. the lowest possible indices are returned.
'last' returns the last occurence of each unique row, i.e.
the highest possible indices are returned.
[tblB, ixA, ixB] = unique (…) also returns
index vectors ixA and ixB using any of the previous syntaxes.
ixA and ixB map the tables tblA and tblB to one
another such that tblB = tblA(ixA,:) and
tblA = tblB(ixB,:).
'RowNames')Check if table rows are sorted accordingly.
TF = issortedrows (tblA) determines if the rows in
tblA are sorted in asceding order based on the values in the first
variable or subsequent variables if elements of the former are repeated.
TF is a logical scalar and it is true when
tblA == sortrows (tblA) or false otherwise.
TF = issortedrows (tblA, 'RowNames')
determines if the rows in tblA are sorted according to its row
names. TF is true when tblA == sortrows
(tblA, 'RowNames') or false otherwise. If
tblA does not have row names, i.e. tblA.Properties.RowNames
is empty, then TF is true.
TF = issortedrows (tblA, rowDimName) determines
if the rows in table tblA are sorted along the first dimension,
rowDimName, which is the equivalent to the previous syntax, i.e.
according to its row names. For this syntax to work, rowDimName
must match the first element in tblA.Properties.DimensionNames,
otherwise rowDimName is considered a variable name, as in the
following syntax. TF is true when tblA ==
sortrows (tblA, rowDimName) or false otherwise. If
tblA does not have row names, i.e. tblA.Properties.RowNames
is empty, then TF is true.
TF = issortedrows (tblA, vars) determines if the
rowns in tblA are sorted by the elements in the variables specified
by vars, which can be a character vector (for a single variable) or
a cell array of character vectors or a string array (specifying a single
or multiple variables). If tblA has row names, then vars can
include the row names. Alternatively, vars can be a logical vector
or a numeric vector of real integers indexing the desired variables.
Positive integers specify an ascending order, whereas negative integers
specify a descending order for the referenced variables. You can also
index all available variables in tblA by passing a semicolon
character argument. This Octave specific syntax, facilitates the use of
direction input argument, when no particular variable needs to be
selected for sorting upon. Additionally, vars can be a
vartype object used to create a subscript that selects variables
of a specified type.
TF = issortedrows (tblA, …, direction)
determines if the rows in tblA are sorted in the order specified by
direction for any of the previous syntaxes. direction can be
'ascend' or 'descend', which is applied to all specified
variables or row names that sortrows operates on. direction
can also be a cell array of character vectors, whose elements are
'ascend' and 'descend', where each element corresponds to
the specified variables and/or, row names used for sorting the table.
The order specified by direction always takes precedence over the
order defined by a numerical vector of integers in vars.
direction must always be the 3rd inpnut argument. If you want to
omit passing selected variables and allow sortrows to work on
consequtive variables until all ties are resolved, then you can leave the
second input argument empty, as in
sortrows (tblA, {[]}, direction) or pass a
colon argument for vars as in
sortrows (tblA, {':'}, direction).
TF = issortedrows (…, Name, Value)
determines if the rows in tblA are sorted accoring the additional
parameters specifying the sorting of rows of a table with the following
Name-Value paired arguments.
'MissingPlacement' specifies the placement of missing
values with one of the following options: 'auto' places the
missing elements at the bottom for ascending order and at the top for
descending order; 'first' places missing elements at the top;
'last' places missing elements at the bottom.
'ComparisonMethod' specifies the element comparison method
with one of the following options: 'auto' sorts rows using the
real part for real numbers and the magnitude for complex numbers;
'real' sorts rows using the real part for both real and complex
numbers; 'abs' sorts rows using the magnitude for both real and
complex numbers. For complex numbers with equal magnitude, the phase
angle in the interval is further used to break ties.
'RowNames')Sort the rows of a table.
tblB = topkrows (tblA, k) returns the top
k rows from table tblA sorted in asceding order based on the
values in the first variable. If elements in the first variable are
repeated, then topkrows sorts by the elements in the second
variable, and so on.
tblB = topkrows (tblA, k, 'RowNames') returns
the top k rows from table tblA sorted according to its row
names. If tblA does not have row names, i.e.
tblA.Properties.RowNames is empty, then it returns tblA.
tblB = topkrows (tblA, k, rowDimName) also
returns the top k rows from table tblA sorted along its first
dimension, rowDimName, which is the equivalent to the previous
syntax, i.e. according to its row names. If tblA does not have row
names, i.e. tblA.Properties.RowNames is empty, then it returns
tblA. For this syntax to work, rowDimName must match the
first element in tblA.Properties.DimensionNames, otherwise
rowDimName is considered a variable name, as in the following
syntax.
tblB = topkrows (tblA, k, vars) returns
the top k rows from table tblA sorted by the elements in the
variables specified by vars, which can be a character vector (for a
single variable) or a cell array of character vectors or a string array
(specifying a single or multiple variables). If tblA has row
names, then vars can include the row names. Alternatively,
vars can be a logical vector or a numeric vector of real integers
indexing the desired variables. Positive integers specify an ascending
order, whereas negative integers specify a descending order for the
referenced variables. You can also index all available variables in
tblA by passing a semicolon character argument. This Octave
specific syntax, facilitates the use of direction input argument,
when no particular variable needs to be selected for sorting upon.
Additionally, vars can be a vartype object used to create a
subscript that selects variables of a specified type.
tblB = topkrows (tblA, k, …,
direction) returns the top k rows from table tblA
sorted in the order specified by direction for any of the previous
syntaxes. direction can be 'ascend' or 'descend',
which is applied to all specified variables or row names that
sortrows operates on. direction can also be a cell array of
character vectors, whose elements are 'ascend' and
'descend', where each element corresponds to the specified
variables and/or, row names used for sorting the table. The order
specified by direction always takes precedence over the order
defined by a numerical vector of integers in vars. direction
must always be the 3rd inpnut argument. If you want to omit passing
selected variables and allow sortrows to work on consequtive
variables until all ties are resolved, then you can leave the second
input argument empty, as in
sortrows (tblA, {[]}, direction) or pass a
colon argument for vars as in
sortrows (tblA, {':'}, direction) or pass a
tblB = topkrows (…, k, Name, Value)
returns the top k rows from table tblA sorted with any of the
previous syntaxes and further specified by additional parameters for
sorting rows of a table with the following Name-Value paired arguments.
'MissingPlacement' specifies the placement of missing
values with one of the following options: 'auto' places the
missing elements at the bottom for ascending order and at the top for
descending order; 'first' places missing elements at the top;
'last' places missing elements at the bottom.
'ComparisonMethod' specifies the element comparison method
with one of the following options: 'auto' sorts rows using the
real part for real numbers and the magnitude for complex numbers;
'real' sorts rows using the real part for both real and complex
numbers; 'abs' sorts rows using the magnitude for both real and
complex numbers. For complex numbers with equal magnitude, the phase
angle in the interval is further used to break ties.
[tblB, index] = topkrows (…) also returns an
index vector such that tblB = tblA(index,:).
'After', location)'Before', location)'NewVariableNames', newNames)Add new variables to a table.
tblB = addvars (tblA, var1, …, varN)
adds new variables to the right of the last variable in table tblA.
Each of the arrays specified by the input arguments var1,
…, varN becomes a new variable and its name is derived from
the input argument’s variable name or a default is created if the input
argument is not a variable itself. The input arrays can be of any data
type including a table as long as they have the same number of rows as
tblA.
tblB = addvars (…,
adds the new variables after, i.e. to the right, the table variable
specified in location, which can be a character vector, a scalar
integer value or even a logical vector of the same size as
'After', location)width (tblA), as long as it indexes a single variable in
tblA.
tblB = addvars (…,
adds the new variables before, i.e. to the left, the table variable
specified in location, which can be a character vector, a scalar
integer value or even a logical vector of the same size as
'Before', location)width (tblA), as long as it indexes a single variable in
tblA.
tblB = addvars (…, renames the new variables added from the previous
syntaxes according to the names specified by newNames, which can be
a character vector, a cell array of character vectors or a string array.
The number of names in newNames must be the same as the number of
added variables.
'NewVariableNames',
newNames)
Rename variables in a table.
tblB = renamevars (tblA, vars, newNames)
renames the selected variables in the table tblA specified by
vars using the names in newNames.
vars can be any of the following types.
true the variables to be renamed.
vartype object used to create a subscript that selects
variables of a specified type.
newNames can either be a character vector (when renaming a single variable) or a cell array of character vectors or a string array. The number of names specified by newNames must match the number of variables specified by vars.
'After', location)'Before', location)Move variables in a table.
tblB = movevars (tblA, vars) moves the variables
specified by vars to the end of the input table tblA.
vars can be any of the following types.
true the variables to be renamed.
vartype object used to create a subscript that selects
variables of a specified type.
tblB = movevars (…,
moves the selected variables after, i.e. to the right, the table variable
specified in location, which can be a character vector, a scalar
integer value or even a logical vector of the same size as
'After', location)width (tblA), as long as it indexes a single variable in
tblA which is not selected by vars.
tblB = movevars (…,
moves the selected variables before, i.e. to the left, the table variable
specified in location, which can be a character vector, a scalar
integer value or even a logical vector of the same size as
'Before', location)width (tblA), as long as it indexes a single variable in
tblA which is not selected by vars.
Remove variables from a table.
tblB = removevars (tblA, vars) removes the
variables specified by vars from the input table tblA.
vars can be any of the following types.
true the variables to be renamed.
vartype object used to create a subscript that selects
variables of a specified type.
'NewVariableNames', NewNames)Split multicolumn variables in a table.
tblB = splitvars (tblA) splits mutlicolumn variables
in tblA so that they are single-column variables in tblB,
while all single-column variables in tblA are copied to tblB
unaltered. Each newly created single-column variable in tblB is
uniquely named by joining the name of its parent multicolumn variable in
tblA and the corresponding column number. If a variable in
tblA contains a table, then each variable of this nested table is
returned as a newly created variable in tblB. By default, these
variables retain their original name in the nested table, unless there
are duplicate names, in which case the name of the nested table is also
used. If the nested table in tblA contains a multicolumn variable,
then the newly created variable in tblB is also multicolumnar.
tblB = splitvars (tblA, vars) splits only the
variables in tblA specified by vars. If left empty, it
defaults to all variables that can be split. Single-column variables
specified in vars are coppied unaltered.
vars can be any of the following types.
true the variables to be renamed.
vartype object used to create a subscript that selects
variables of a specified type.
tblB = splitvars (…, assigns new names to the variables that are split out of
tblA and copied to tblB. NewNames can be specified as
a cell array of character vectors and/or string arrays.
'NewVariableNames',
NewNames)
Merge table variables into a single multicolumn variable.
tblB = mergevars (tblA, vars) combines the table
variables in tblA specified by vars to create a new
multicolumn variable in tblB. All other variables in tblA
are copied to tblB unaltered. By default, the name of the merged
variable in tblB takes the form , where is the
position of the first variable in tblA among those to be merged,
which is also the location of the merged variable in tblB.
Note that merging variables with a 'string' data type variable
will result to a multicolumn variable of 'string' data type, by
initially converting all other to-be-merged variables into
'string' data type.
vars can be any of the following types.
true the variables to be renamed.
vartype object used to create a subscript that selects
variables of a specified type.
tblB = mergevars (…, Name, Value) further
specifies additional parameters for merging table variables with the
following Name-Value paired arguments.
"NewVariableName" specifies the name of the merged variable
in tblB, which must be unique. "NewVariableName" must be
either a cellstr or string scalar or a character vector.
"MergeAsTable" specifies whether the selected variables
should be merged into a multicolumn variable (default) or into a table
nested into a variable, which is usefull for variables that cannot be
concatenated due to incompatible variable types. "MergeAsTable"
must be either a boolean scalar or a numeric scalar value of 1
(true) or 0 (false).
Convert table variables to specified data type.
tblB = mergevars (tblA, vars) converts the
variables in tblA specified by vars to the specified data
type.
vars can be any of the following types.
true the variables to be renamed.
vartype object used to create a subscript that selects
variables of a specified type.
dataType specifies the data type to convert those variables to. It can either be a character vector defining the name of the data type to convert to or a function handle, which will perform the conversion. a char holding the name of the data type, or a function handle which will perform the conversion. When specifying a name for data type conversion, it can either be a one-argument constructor for the specified data type, which must accept the selected variables’ current data types as input, or an available method, which can be applied on selected variables’ current data types. When specifying a function handle for applying a conversion on selected variables, this function handle must accept a single input argument and return in its output the same rows as the input argument.
Either way, each resulting variable must have the same number of rows as
the respective variable selected for conversion. However, depending on
the chosen type of conversion, the columns of the converted variable(s)
might differ. It is up to the user to ensure that the appropriate type
of conversion is performed. convertvars only checks the custom
function handles for returning the correct number of rows, which must
equal the number of rows of the input table, tblA.
Reorient table by swapping rows into variables.
tblB = rows2vars (tblA) reorients the input table
tblA so that its rows become variables in the output table
tblB and the variables are swapped into rows and their names
are stored into a new variable at the beginning of the output table. If
the contents of tblA can be concatenated, then the corresponding
variables of tblB arrays, otherwise they are cell arrays. If the
input table tblA contains RowNames, then those names become
the variable names of the output table tblB, otherwise the variable
names of tblB are generated automatically. rows2vars cannot
handle multicolumn variables or nested tables.
variables in tblA specified by vars to create a new multicolumn variable in tblB. All other variables in tblA are copied to tblB unaltered. By default, the name of the merged variable in tblB takes the form , where is the position of the first variable in tblA among those to be merged, which is also the location of the merged variable in tblB.
tblB = rows2vars (…, Name, Value) further
specifies additional parameters for merging table variables with the
following Name-Value paired arguments.
"DataVariables" specifies the variables from input table
tblA which will be reoriented. "DataVariables" can be any
of the following types: a character vector specifying a single variable;
a cell array of character vectors or a string array specifying a single
or multiple variables; a numeric array of integer values specifying a
single or multiple variables; a logical vector of the same length as the
width of the input table specifying a single or multiple variables.
"VariableNamesSource" specifies a single variable that
contains the variable names for the output table. The values of the
selected variable must have a data type which can be converted to strings
and the number of unique names in the selected variable must match the
number of rows of the input table. "VariableNamesSource" accepts
the same data types supported by "DataVariables" as long as they
index a single variable, which, however, must not be specified by the
"DataVariables" ame-Value paired argument.
"VariableNamingRule" must be a character vector specifying
the rule for naming variables in the output table tblB. When set
to 'modify' (default), the variable names are modified so that
they are valid variable identifiers. When set to 'preserve', the
original names are preserved.
Stack multiple table variables into a single table variable.
tblB = stack (tblA, vars) stacks the values from
the variables vars in input tblA into a single variable in
output table tblB. By default, the stacked variable in tblB
is named by joining the names of the variables in tblA as defined
by vars. Additionally, a new categorical variable is included in
tblB that indicates which variable in tblA the stacked data
in each row of tblB comes from. By default, this categorical
variable is named by appending "_Indicator" to the name of the
stacked variable. Variables in tblA that are not defined in
vars for stacking are replicated in tblB. If tblA
contains RowNames, these are not stacked.
vars can be any of the following types.
true the variables to be renamed.
vartype object used to create a subscript that selects
variables of a specified type.
tblB = stack (…, Name, Value) further
specifies additional parameters for merging table variables with the
following Name-Value paired arguments.
"ConstantVariables" specifies the variables other than
vars to include in the output table. By default, all remaining
variables not specified by vars are included in the output table.
Specifying "ConstantVariables" allows you to select specific
variables to replicate in tblB. Row names in tblA are always
replicated in tblB. You can specify "ConstantVariables" in
the same manner as with vars.
"NewDataVariableName" specifies the name for the new data
variable in the output table tblB. It can be a character vector,
a string scalar, or a cellstring scalar.
"IndexVariableName" specifies the name for the new
indicator variable in the output table tblB. It can be a character
vector, a string scalar, or a cellstring scalar.
[tblB, idxA] = stack (…) also returns an index
vector, idxA, indicating the correspondence between the rows in
tblB and the rows in tblA.
Unstack a single table variable into multiple table variables.
tblB = stack (tblA, vars, ivar) unstacks the values from
the variables vars in input tblA into a single variable in
output table tblB. By default, the stacked variable in tblB
is named by joining the names of the variables in tblA as defined
by vars. Additionally, a new categorical variable is included in
tblB that indicates which variable in tblA the stacked data
in each row of tblB comes from. By default, this categorical
variable is named by appending "_Indicator" to the name of the
stacked variable. Variables in tblA that are not defined in
vars for stacking are replicated in tblB. If tblA
contains RowNames, these are not stacked.
vars can be any of the following types.
true the variables to be renamed.
vartype object used to create a subscript that selects
variables of a specified type.
tblB = stack (…, Name, Value) further
specifies additional parameters for merging table variables with the
following Name-Value paired arguments.
"ConstantVariables" specifies the variables other than
vars to include in the output table. By default, all remaining
variables not specified by vars are included in the output table.
Specifying "ConstantVariables" allows you to select specific
variables to replicate in tblB. Row names in tblA are always
replicated in tblB. You can specify "ConstantVariables" in
the same manner as with vars.
"NewDataVariableName" specifies the name for the new data
variable in the output table tblB. It can be a character vector,
a string scalar, or a cellstring scalar.
"IndexVariableName" specifies the name for the new
indicator variable in the output table tblB. It can be a character
vector, a string scalar, or a cellstring scalar.
[tblB, idxA] = stack (…) also returns an index
vector, idxA, indicating the correspondence between the rows in
tblB and the rows in tblA.
Add custom properties to a table.
T = addprop (T, propertyNames, propertyTypes)
adds properties that contain custom metadata to the table T. The
input argument propertyNames specifies the names of the custom
properties to be added and propertyTypes the type of each
corresponding custom property, that is whether the metadata values
contained in the property apply to table T as a whole, or to the
variables of T. Both propertyNames and propertyTypes
can be character vectors, cell arrays of character vectors, or stings.
When defined as cell arrays of character vectors or stings, they must
have the same number of elements.
Valid propertyTypes are either 'table' or
'variable'. When defined as 'table', the custom property
can contain a scalar value of arbitrary type, which applies as metadata
to the table as a whole. When defined as 'variable', the custom
property contains a vector, whose elements correspond to the number of
variables in the table.
After adding custom properties using addprop, metadata values can
be assigned to the properties using dot syntax.
Remove custom properties from a table.
T = rmprop (T, propertyNames) removes properties
that contain custom metadata from the table T. The input argument
propertyNames specifies the names of the custom properties to be
removed and it can either be a character vector, a cell array of
character vectors, or a sting array.
Combine two tables by rows using key variables.
Inner join between two tables by rows using key variables.
Outer join between two tables by rows using key variables.
Union of two tables by rows.
Intersection of two tables by rows.
Find set members between two tables by rows.
Difference between two tables by rows.
Exclusive OR of two tables by rows.
Determine if any table element is missing.
TF = anymissing (tblA) returns true if at
least one element in table var{tblA is missing, otherwise tt returns
false. TF is a logical scalar value.
Missing values are defined according to the data type of each variable in tblA:
NaN - double, single, duration and calendarDuration
NaT - datetime
<missing> - string
<undefined> - categorical
'' - cell arrays of character vectors
[] - cell arrays
Find missing values in table.
Finds missing values in obj’s variables.
If indicator is not supplied, uses the standard missing values for each variable’s data type. If indicator is supplied, the same indicator list is applied across all variables.
All variables in this must be vectors. (This is due to the requirement
that size(out) == size(obj).)
Returns a logical array the same size as obj.
Remove missing table elements by rows.
'constant', val)'knn')'knn', k)Fill missing table elements.
Remove missing table elements by rows.
table.pivot is not documented.
table.groupcounts is not documented.
table.groupfilter is not documented.
table.groupsummary is not documented.
table.grouptransform is not documented.
table.findgroups is not documented.
table.splitapply is not documented.
table.rowfun is not documented.
table.varfun is not documented.
Horizontal concatenation for tables.
tbl = horzcat (tbl1, tbl2, …) merges
tables by horizontally concatenating them, provided that all input tables
have collectively unique variable names and the same number of rows.
Input tables that have row names must share the same unique set of row
names but not necessarily in the same order. When row names are present
in multiple input tables, their position is matched to the row names of
the first input table. Input tables without row names are concatenated
by position without re-indexing. Output table’s Description and
UserData properties are assigned using the first non-empty value.
Test input table for being a column vector.
TF = iscolumn (tbl) returns true if the input
table tbl has a single variable. The number of columns within that
variable does not matter.
Test input table for being empty.
For tables, isempty is true if the number of rows is 0 or the
number of variables is 0.
Test input table for being a matrix.
For tables, ismatrix is always true, by definition.
Test input table for being a row vector.
TF = isrow (tbl) returns true if the input
table tbl has a single row.
Test input table for being a scalar.
TF = isscalar (tbl) returns true if the input
table tbl has a single row and a single variable.
Test input table for being a vector.
TF = isvector (tbl) returns true if the input
table tbl has a single row or a single column.
Length along longest dimension.
Number of table dimensions.
For tables, ndims(tbl) is always 2.
Total number of elements in table.
For compatibility reasons with Octave’s OOP interface and subsasgn
behavior, table’s numel is defined to always return 1. This is an
incompatibility with Matlab.
Replicate elements of a table.
Replicates elements of the input table tblA in a similar fashion
to how repelem applies to a matrix. Only two dimensions are
supported for tables.
Repeat copies of a table.
Repeats cp[ies of the input table tblA in a similar fashion
to how repmat applies to a matrix. Only two dimensions are
supported for tables.
Return the size of a table.
For tables, the size is [number-of-rows x number-of-variables].
This is the same as [height(obj), width(obj)].
Remove singleton dimensions.
For tables, this is always a no-op that returns the input table unmodified, because tables always have exactly 2 dimensions.
Vertical concatenation for tables.
tbl = vertcat (tbl1, tbl2, …) merges
tables by vertically concatenating them, provided that all input tables
have the same variable names but not necessarily in the same order. The
position of the variable names are matched to those of the first input
table.
When input tables have row names, they must be unique across tables. In
such case, concatenated rows from input tables without row names are
automatically assigned default input names using the input table’s name
as a prefix. Output table’s Description and UserData
properties are assigned using the first non-empty value.
## Store patient date 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)
## Use indexing to access variables
meanHeight = mean (T.Height)
## Calculate body mass index (BMI), and add it as a new table variable.
T.BMI = (T.Weight * 0.453592) ./ (T.Height * 0.0254) .^ 2
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
meanHeight = 67
T =
5x7 table
LastName Age Smoker Height Weight BloodPressure BMI
___________ ___ ______ ______ ______ _____________ _______
{'Sanchez'} 38 true 71 176 124 93 24.5467
{'Johnson'} 43 false 69 163 109 77 24.0706
{'Li' } 38 true 64 131 125 83 22.4858
{'Diaz' } 40 false 67 133 117 75 20.8305
{'Brown' } 49 true 64 119 122 80 20.4261
|
## Preallocate a table by specifying its size and the variable data types
sz = [4, 3];
varTypes = {"double", "datetime", "string"};
T = table ("Size", sz, "VariableTypes", varTypes)
## Specify variable names with the "VariableNames" name-value pair argument
varNames = {"Temperature", "Time", "Station"};
T2 = table ("Size", sz, "VariableTypes", varTypes, "VariableNames", varNames)
## Add rows of data to the first two rows of table T2
T2(1,:) = {75, datetime(2024, 2, 5), string("S1")};
T2(2,:) = {75, datetime(2024, 2, 6), string("S2")}
T =
4x3 table
Var1 Var2 Var3
____ ____ _________
0 NaT |
## Create a table from various types of arrays
T = table (string ({"M";"F";"M"}), [45;32;34], ...
{"NY";"CA";"MA"}, logical ([1;0;0]),...
"VariableNames", {"Gender", "Age", "State", "Vote"})
## Create the same table using the state names as row names
T = table (string ({"M";"F";"M"}), [45;32;34], logical ([1;0;0]), ...
"VariableNames", {"Gender", "Age", "Vote"}, ...
"RowNames", {"NY";"CA";"MA"})
T =
3x4 table
Gender Age State Vote
______ ___ ______ _____
"M" 45 {'NY'} true
"F" 32 {'CA'} false
"M" 34 {'MA'} false
T =
3x3 table
Gender Age Vote
______ ___ _____
NY "M" 45 true
CA "F" 32 false
MA "M" 34 false
|
## Create a Table from patient data
load patients
BloodPressure = [Systolic Diastolic];
T = table (Gender, Age, Smoker, BloodPressure, "RowNames", LastName);
## Add descriptions and units to table
T.Properties.Description = "Simulated patient data";
T.Properties.VariableUnits = {"", "Yrs", "", "mm Hg"};
T.Properties.VariableDescriptions(4) = {"Systolic/Diastolic"};
## Print a summary of the table
summary (T)
Description: Simulated patient data
Variables:
Gender: 100x1 cell
Age: 100x1 double
Properties:
Units: Yrs
Values:
Min 25
Median 39
Max 50
Smoker: 100x1 logical
Values:
True 34
False 66
BloodPressure: 100x2 double
Properties:
Units: mm Hg
Description: Systolic/Diastolic
Values:
Column 1 Column 2
________ ________
Min 109 68
Median 122 81.5
Max 138 99
|
## 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.Properties.DimensionNames
## Access the row names using the first dimension name.
T.Row
## Access the data using the second dimension name.
T.Variables
## Modify the names of its dimensions using the Properties
T.Properties.DimensionNames = {"Patient","Data"};
T.Properties
## Change a single dimension name
T.Properties.DimensionNames(1) = 'Patients'
T.Properties
T.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
ans =
1x2 cell array
{'Row'} {'Variables'}
ans =
5x1 cell array
{'Sanchez'}
{'Johnson'}
{'Li' }
{'Diaz' }
{'Brown' }
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
TableProperties with properties:
Description: ''
UserData: []
DimensionNames: {'Patient' 'Data'}
VariableNames: {'Age' 'Smoker' 'Height' 'Weight' 'BloodPressure'}
VariableDescriptions: {}
VariableUnits: {}
VariableContinuity: []
RowNames: {5x5 cell}
CustomProperties: No custom properties are set.
Use 'addprop' and 'rmprop' methods to modify CustomProperties.
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
TableProperties with properties:
Description: ''
UserData: []
DimensionNames: {'Patients' 'Data'}
VariableNames: {'Age' 'Smoker' 'Height' 'Weight' 'BloodPressure'}
VariableDescriptions: {}
VariableUnits: {}
VariableContinuity: []
RowNames: {5x5 cell}
CustomProperties: No custom properties are set.
Use 'addprop' and 'rmprop' methods to modify CustomProperties.
ans =
5x1 cell array
{'Sanchez'}
{'Johnson'}
{'Li' }
{'Diaz' }
{'Brown' }
|
## Various ways to specify row names for a table
LastName = {'Sanchez'; 'Johnson'; 'Lee'; 'Diaz'; 'Brown'};
Age = [38;43;38;40;49];
Height = [71;69;64;67;64];
Weight = [176;163;131;133;119];
## Using the constructor
T = table(Age,Weight,Height,'RowNames',LastName)
## Using a cell array of character vectors, a character array,
## or a string array of the same height as the table. They are;
## always converted to cellstr type internally.
T = table(Age,Weight,Height)
fprintf ("## Using a cell array of character vectors\n");
fprintf ("T.Properties.RowNames = LastName\n");
T.Properties.RowNames = LastName
fprintf ("## Using a string array\n");
fprintf ("T.Properties.RowNames = string (LastName)\n");
T.Properties.RowNames = string (LastName)
fprintf ("## Using a character array\n");
fprintf ("T.Properties.RowNames = char (LastName{:})\n");
T.Properties.RowNames = char (LastName{:})
## Using an existing variable of type cellstr, string or char\n");
## array in which case the existing variable is NOT removed.\n");
T = table(Age,Weight,Height,LastName)
fprintf ("## Using an existing variable\n");
fprintf ("T.Properties.RowNames = T.LastName\n");
T.Properties.RowNames = T.LastName
## Referencing an existing variable by its VariableName, which
## must be of type cellstr, string or char array. In this case,
## the existing variable is removed and only used as RowName, as
## in the constructor example. Reference can also be a numeric scalar
## indexing a Variable of appropriate type.
T = table(Age,Weight,Height,LastName);
fprintf ("## Referencing an existing variable with a character vector\n");
fprintf ("T.Properties.RowNames = 'LastName'\n");
T.Properties.RowNames = 'LastName'
T = table(Age,Weight,Height,LastName);
fprintf ("## Referencing an existing variable with a string scalar\n");
fprintf ("T.Properties.RowNames = string(""LastName"")\n");
T.Properties.RowNames = string("LastName")
T = table(Age,Weight,Height,LastName);
fprintf ("## Referencing an existing variable with a cellstr scalar\n");
fprintf ("T.Properties.RowNames = {'LastName'}\n");
T.Properties.RowNames = {'LastName'}
T = table(Age,Weight,Height,LastName);
fprintf ("## Referencing an existing variable with a numeric scalar\n");
fprintf ("T.Properties.RowNames = 4\n");
T.Properties.RowNames = 4
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 =
5x3 table
Age Weight Height
___ ______ ______
38 176 71
43 163 69
38 131 64
40 133 67
49 119 64
## Using a cell array of character vectors
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
## Using a string array
T.Properties.RowNames = string (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
## Using a character array
T.Properties.RowNames = char (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 =
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' }
## Using an existing variable
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' }
## Referencing an existing variable with a character vector
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
## Referencing an existing variable with a string scalar
T.Properties.RowNames = string("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
## Referencing an existing variable with a cellstr scalar
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
## Referencing an existing variable with a numeric scalar
T.Properties.RowNames = 4
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
|
## Display a table with mixed cell arrays as unicolumnar variables
## and other types as multicolumnar variables
Data_A = {[34, 32]; ['text';'picture']; "text"; struct("c","data"); ...
[true, false]; ['some','text']; {'some','text'}; 25.34};
Data_B = {32, 25; 0.2, 135; 0.123, 456; 42, 5; 154, 12; 32, 10; 4, 4; 9, 94};
Data_C = datetime (2000, [1:8;9:16]', 1);
T = table (Data_A, Data_B, Data_C)
T =
8x3 table
Data_A Data_B Data_C
____________ ____________________ __________________________
{ [34 32]} { [32]} { [25]} 01-Jan-2000 01-Sep-2000
{2x7 char } { [0.2]} {[135]} 01-Feb-2000 01-Oct-2000
{'text' } {[0.123]} {[456]} 01-Mar-2000 01-Nov-2000
{1x1 struct} { [42]} { [5]} 01-Apr-2000 01-Dec-2000
{ [1 0]} { [154]} { [12]} 01-May-2000 01-Jan-2001
{'sometext'} { [32]} { [10]} 01-Jun-2000 01-Feb-2001
{1x2 cell } { [4]} { [4]} 01-Jul-2000 01-Mar-2001
{ [25.34]} { [9]} { [94]} 01-Aug-2000 01-Apr-2001
|
## Create a nested table
T1 = table ([1; 2; 3], [4; 5; 6], [7; 8; 9]);
T2 = table ({"a"; "b"; "c"}, {"d"; "e"; "f"}, {"g"; "h"; "i"});
NT = table ([1; 2; 3], T1, [4; 5; 6], T2, {5; 6; 7}, ...
"VariableNames", {"A", "B", "C", "D", "E"})
NT =
3x5 table
A B C D E
_ ____________________ _ _______________________ _____
Var1 Var2 Var3 Var1 Var2 Var3
____ ____ ____ _____ _____ _____
1 1 4 7 4 {'a'} {'d'} {'g'} {[5]}
2 2 5 8 5 {'b'} {'e'} {'h'} {[6]}
3 3 6 9 6 {'c'} {'f'} {'i'} {[7]}
|