Categories &

Functions List

Class Definition: timetable

datatypes: timetable

Array of tabular data whose rows are labelled by time.

A timetable collects heterogeneous data into columnar variables exactly as a table does, but labels each of its rows with a time instead of a name. The row times are a datetime or a duration vector, one element per row, and they are what the type exists for: rows can be selected, aligned and resampled by when they happened.

Unlike the row names of a table, the row times need not be unique, sorted, or present; duplicates, a descending order and missing times are all accepted and merely make the timetable irregular.

A timetable is regular when its rows are evenly spaced. The spacing is reported by the TimeStep property and its reciprocal SampleRate, and a timetable that is not evenly spaced reports a NaN time step. A timetable told its step at construction, by 'TimeStep' or 'SampleRate', remembers it even where a subset is too short to imply one, so a single row taken out of it is still hourly; one that read its step off the row times it was given has nothing to fall back on and reports NaN there.

A timetable is not a table and neither is a subclass of the other; both derive from the same abstract class, so istabular is true for either while istable and istimetable each single one of them out.

Assigning an empty matrix to a subscripted timetable deletes rows or variables exactly as it does for a table, and the row times go with the rows they label. The row times themselves cannot be deleted.

Besides the timetable constructor, you can also use table2timetable and array2timetable to create timetables from the respective data types.

eventtable derives from this class and inherits every method documented here; where one of them behaves differently for an event table, its own documentation says so.

See also: table, eventtable, istimetable, istabular, isregular, datetime, duration

Source Code: timetable

The timetable class contains the following properties:

Row times, specified as a datetime or duration vector with one element for each row of the timetable. They are stored as a column vector whatever shape they are given in. Unlike the row names of a table they need not be unique, sorted or present: duplicate times, a descending order and missing times are all accepted, and each of them merely makes the timetable irregular. You can access them with tt.Properties.RowTimes and assign them the same way, which recomputes TimeStep.

Time of the first row, of the same type as RowTimes. It follows the first row: deleting the first row leaves StartTime naming the row that is now first. A timetable left with no rows keeps the value it had. Assigning it shifts every row time by the same amount and preserves TimeStep.

Sampling rate, specified as a positive numeric scalar, being the reciprocal of TimeStep measured in seconds. It is NaN whenever the time step is a calendarDuration, a calendar step having no fixed length in seconds, and whenever the timetable is irregular. Assigning it regenerates the row times from StartTime, as assigning TimeStep does.

Spacing between consecutive row times, specified as a duration or calendarDuration scalar, or a NaN duration when the timetable is irregular. Two rows or more always imply a step of their own and it is read off them afresh, so a subset with a gap in it steps by nothing and a reversed one steps backwards. Fewer than two rows imply nothing, and there it matters how the step was arrived at: one given by 'TimeStep' or 'SampleRate' is remembered, while one read off the row times is not and becomes NaN, its class resetting to duration with it. A freshly built one-row timetable has no step either way. A negative step is as regular as a positive one. Assigning it regenerates the row times from StartTime, even when the timetable was irregular.

Event table attached to this timetable, specified as an eventtable, or empty when no events are attached. A plain timetable may be assigned and is converted, though no variable of it is guessed to hold the event labels; assigning [] detaches whatever was there. The event table’s row times must be of the same type as this timetable’s, so a duration-keyed timetable takes a duration-keyed event table and a datetime-keyed one takes a datetime-keyed event table. Nothing requires the events to lie within the span of the row times, and events entirely outside it are accepted.

An operation that preserves the rows carries the event table through unchanged: it is never subsetted, filtered, re-timed or reordered along with them.

An eventtable has no Events property of its own, an event table not being something that can itself carry events.

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.

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.

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. Assigning an empty cell or string array returns the property to its default, and describing a single variable of a table that has no descriptions gives the remaining variables an empty 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. Assigning an empty cell or string array returns the property to its default, and giving a unit to a single variable of a table that has none gives the remaining variables an empty unit.

Continuity of each variable, specified as a cell array of character vectors or a string array carrying one element per variable, each of them 'unset', 'continuous', 'step' or 'event'. It is empty by default, and assigning {} or [] clears it. If specified as a string array, it is converted and stored internally as a cell array of character vectors. You can access it with tbl.Properties.VariableContinuity and you can index individual variables to read or assign their continuity.

A table carries the property but does not act on it, which is also how MATLAB behaves. A timetable uses it to choose the default fill method of each variable when resampling.

MATLAB stores this property as a matlab.tabular.Continuity enumeration. Octave has no enumeration classes, so it is stored and returned here as a cell array of character vectors, as VariableNames and VariableUnits are.

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 an individual custom property 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 whole set may also be taken from another table by assigning that table’s CustomProperties to this one, which replaces every custom property with those of the other table, their types included. A variable-scoped property arriving that way must hold one element for each variable of the receiving table, or be a 0-by-0 empty. Nothing else can be assigned there.

The timetable class offers the following public methods:

timetable Create a new timetable.
vertcat Concatenate timetables vertically.
horzcat Concatenate timetables horizontally.
cat Concatenate timetables along a dimension.
height Number of rows in timetable.
width Number of variables in timetable.
size Size of a timetable.
numel Number of elements in timetable.
ndims Number of dimensions in timetable.
length Length is not defined for a timetable.
isempty True for an empty timetable.
repelem Repeat each row and variable of a timetable in place.
repmat Repeat a timetable as a block.
isregular True when the row times of a timetable are evenly spaced.
istimetable True if input is a ‘timetable’, false otherwise.
isequal Test timetables for equality.
isequaln Test timetables for equality, treating missing values as equal.
ismissing Find missing values in the variables of a timetable.
anymissing True when any variable of a timetable has a missing value.
rmmissing Remove the incomplete rows of a timetable.
standardizeMissing Make given values missing in a timetable.
fillmissing Fill the missing values of a timetable.
summary Summarise a timetable.
addvars Add variables to a timetable.
removevars Remove variables from a timetable.
movevars Move variables within a timetable.
renamevars Rename variables in a timetable.
convertvars Convert variables of a timetable to a given type.
mergevars Combine several variables of a timetable into one.
splitvars Split multi-column variables of a timetable into one each.
head Display or return the first K rows of a timetable.
tail Display or return the last K rows of a timetable.
sortrows Sort the rows of a timetable.
unique Unique rows of a timetable.
topkrows The top K rows of a timetable, in sorted order.
issorted True when the row times of a timetable are in ascending order.
issortedrows True when the rows of a timetable are already in a given order.
containsrange True when a timetable spans the whole of a range of times.
overlapsrange True when a timetable and a range of times have any instant in common.
withinrange True when the whole range of a timetable lies inside a range of times.
varfun Apply a function to each variable of a timetable.
rowfun Apply a function to each row of a timetable.
grouptransform Transform the variables of a timetable group by group.
groupcounts Count the rows of a timetable in each group.
groupsummary Summarise the variables of a timetable group by group.
groupfilter Keep the rows of a timetable whose group passes a test.
stack Stack several variables of a timetable into one.
rows2vars Turn the rows of a timetable into variables.
join Join a timetable with another tabular object.
innerjoin Join a timetable with another tabular object, keeping matched rows.
outerjoin Join a timetable with another tabular object, keeping unmatched rows.
inner2outer Turn the nesting of a timetable inside out.
findgroups Number the groups the rows of a timetable fall into.
splitapply Apply a function to each group of rows of a timetable.
unstack Spread one variable of a timetable across several.
pivot Summarise a timetable across two grouping dimensions.
retime Resample a timetable onto new row times.
lag Shift the data of a timetable along its own row times.
synchronize Put several timetables on one set of row times and set them side by side.
extractevents Build an event table out of the rows of a timetable.
syncevents Copy the attached event table's data onto the rows it covers.
addprop Add custom properties to a timetable.
rmprop Remove custom properties from a timetable.
timetable2table Convert a timetable to a table.
timetable2csv Write a timetable to a comma-separated-value (CSV) file.
timetable2ods Write a timetable to an OpenDocument spreadsheet file.
writetimetable Write a timetable to a file in the MATLAB-compatible form.
empty Create an empty timetable.