Rules for Table and Timetable Mathematics - MATLAB & Simulink (original) (raw)

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 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 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 eitherA or B).

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 theEventLabelsVariable, EventLengthsVariable, andEventEndsVariable properties as the input event table.

When an operation has only one operand:

• The output event table has the same values for theEventLabelsVariable, 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 one-row table.
• If the function reduces the event table along the second dimension, then the output is an event table. However, the EventLabelsVariable,EventLengthsVariable, and EventEndsVariable 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, named mean. Its EventLabelsVariable,EventLengthsVariable, and EventEndsVariable properties are unset.

See Also

table | timetable | eventtable

Related Topics

• Access Data in Tables
• Direct Calculations on Tables and Timetables
• Clean Messy and Missing Data in Tables
• Data Cleaning and Calculations in Tables
• Grouped Calculations in Tables and Timetables