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.
An event table is a kind of timetable. So, you can also perform calculations directly on event tables. They follow the same rules that timetables follow. However, they have additional properties that specify event labels and event durations. These properties impose additional constraints when you perform operations on event tables. (since R2023b)
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 all their variables 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.
These functions and operators also support direct calculations on event tables. (since R2023b)
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 —
bounds
,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, timetables, or event tables.
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 onerow 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 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. The operation does not 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 






 Errors  
 Undefined 
 
Undefined 

 


 Undefined 

 Undefined  
 Undefined 
 
Undefined 

 


 Undefined 

 Undefined  
 Undefined 
 
Undefined 
 Undefined  


 Errors 

 Errors  
 Undefined  Undefined  
Undefined 
 Errors  





 Errors  
 Undefined 
 
Undefined 


In general, logical operators and exponential, logarithmic, and trigonometric functions do not propagate units. However, some functions do propagate units when it is known that the output has the same units as the input. The functions that propagate units are:
abs
bounds
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)
Rules for Operations and Functions on Event Tables
Since R2023b
Because an event table is a kind of timetable, operations on event tables follow the rules for operations on timetables. But because event tables have additional properties, operations on event tables have additional constraints.
When both operands are event tables:
The operands must follow the same rules that apply to operations on timetables.
The
EventLabelsVariable
property of both event tables must be set to the same variable name, or it must be unset in both event tables.The
EventLengthsVariable
property of both event tables must be set to the same variable name, or it must be unset in both event tables.The
EventEndsVariable
property of both event tables must be set to the same variable name, or it must be unset in both event tables.
When one operand is an event table, and the other is a timetable or a table:
The operands must follow the same rules that apply to operations on timetables, or to operations where one operand is a timetable and the other is a table.
The output is an event table.
The output event table has the same values for the
EventLabelsVariable
,EventLengthsVariable
, andEventEndsVariable
properties as the input event table.
When an operation has only one operand:
The output event table has the same values for the
EventLabelsVariable
,EventLengthsVariable
, andEventEndsVariable
properties as the input event table.
When a function reduces an event table along a dimension:
If the function reduces the event table along the first dimension, then the output is a table. For example, if you call the
mean
function on an event table to calculate the mean value of each variable, then the output is a onerow table.If the function reduces the event table along the second dimension, then the output is an event table. However, the
EventLabelsVariable
,EventLengthsVariable
, andEventEndsVariable
properties of the output event table are unset because its variables have different names.For example, if you call the
mean
function on an event table to calculate the mean value of each row, then the output is an event table with one variable, namedmean
. ItsEventLabelsVariable
,EventLengthsVariable
, andEventEndsVariable
properties are unset.
See Also
table
 timetable
 eventtable