Rules for Table and Timetable Mathematics

You can perform calculations directly on tables and timetables without indexing to extract their data. Most of the common functions and operators for mathematics and statistics support tables and timetables. Operations on tables and timetables have rules about data types and sizes as well as variable names, row names, row times, and variable units. Operations on tables and timetables whose variables have units also have rules for propagating those units into the output table or timetable.

Functions and Operators That Support Tables and Timetables

These MATLAB^® functions and operators support direct calculations on tables and timetables. You can use these functions and operators on your tables and timetables if their variables all have data types that support calculations. Operations that have two operands must also follow the rules listed in the next section. You do not have to index into your tables and timetables to extract arrays of data.

Arithmetic functions and operators — +, -, .*, ./, .\, .^, abs, ceil, cumprod, cumsum, diff, fix, floor, mod, prod, rem, round, sum
Relational operators — ==, >=, >, <=, <, ~=
Logical operators — &, ~, |, xor
Trigonometric functions — acos, acosd, acosh, acot, acotd, acoth, acsc, acscd, acsch, asec, asecd, asech, asin, asind, asinh, atan, atan2, atan2d, atand, atanh, cos, cosd, cosh, cospi, cot, cotd, coth, csc, cscd, csch, sec, secd, sech, sin, sind, sinh, sinpi, tan, tand, tanh
Exponential and logarithmic functions — exp, expm1, log, log10, log1p, log2, nextpow2, nthroot, pow2, reallog, realpow, realsqrt, sqrt
Statistics functions — cummax, cummin, max, mean, median, min, mode, var

For example, these statements use arithmetic, relational, and logical operators as well as mathematics and statistics functions with operands that are tables and timetables.

T = T .* 0.5;
T = T1 + T2;
T2 = T > 10;
T2 = ~(T < 0);
T2 = abs(T);
T2 = mean(T);

Rules for Operations on Tables and Timetables

When performing operations on two operands, such as addition, directly on tables and timetables, follow these rules about data types, sizes, variables, and rows.

When only one operand is a table or timetable:

The other operand must be a numeric or logical array.
The other operand must have a compatible size. It can be a scalar, vector, or matrix. Multidimensional arrays are not supported.

When both operands are tables or timetables:

Both operands must have the same size, or one of them must be a one-row table.
Both operands must have variables with the same names. However, the variables in each operand can be in a different order.
If both operands are tables and both have row names, then their row names must be the same. However, the row names in each operand can be in a different order.
If both operands are timetables, then their row times must be the same. However, the row times in each operand can be in a different order.
If one operand is a timetable and the other operand is a table, then the table cannot have row names. The output is a timetable.

Rules for Tables and Timetables with Units

Table and timetable variables have several properties, such as names, descriptions, and units. If you define units for any variables, then the units can affect operations where both operands are tables or timetables.

In general, these rules apply to operations on tables and timetables with variables that have units:

If the VariableUnits property of a table or timetable is {}, the default value, then the units are undefined.
If you specify empty strings, "", as units, then those units are undefined.
If you perform an operation on two operands, both operands have units, and the units are incompatible, then the operation returns an error.
If you perform an operation on two operands and only one operand has units, then in general the result has the same units, but the operation also issues a warning.
If an operation or function would result in modified or compound units, such as a multiplication that results in units of kg*m, then the result of the operation or function has no units.

Operations and functions do not support unit conversions. For example, if a variable in one table has units of meters (m), and the corresponding variable in the other table has units of centimeters (cm), then the operation treats those units as incompatible units. There is no attempt to convert centimeters to meters.

This table shows rules for arithmetic operations when table or timetable variables have units that are the same (both A), different (A and B), or undefined (one unit is undefined, and the other is either A or B).

Arithmetic Operation	Units in First Operand	Units in Second Operand	Units in Output
`plus` `minus`	`A`	`A`	`A`
	`A`	`B`	Errors
	`A`	Undefined	`A` (warns)
`times`	`A`	`A`	Undefined
	`A`	`B`	Undefined
	`A`	Undefined	`A` (warns)
`rdivide` `ldivide`	`A`	`B`	Undefined
	`A`	Undefined	`A` (warns)
	Undefined	`B`	Undefined
`power`	`A`	`B`	Errors
	`A`	Undefined	Undefined
	Undefined	`B`	Errors
`rem` `mod`	`A`	`A`	`A`
	`A`	`B`	Errors
	`A`	Undefined	`A` (warns)
	Undefined	`B`	`B` (warns)

In general, logical operators and exponential, logarithmic, and trigonometric functions do not propagate units. However, there are some functions that do propagate units when it is known that the output has the same units as the input. The functions that propagate units are:

abs
ceil
cummax
cummin
cumsum
fix
floor
max
mean
median
min
mode (units propagated to first and third outputs only)
round
std
sum
var (units propagated to second output only)