Timetables

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The reference material consulted while preparing these pages is listed in the section bibliography.

Written against MATLAB R2026b. GNU Octave 11.3.0 has no timetable type in its core, so every example on this page is not run here: the code was checked line by line against the R2026b documentation and no captured output is shown. Results are described in prose where they follow from the documented behavior.

A timetable is a table that associates a time with each row. Everything that works for tables works for timetables (indexing with (), {} and ., head, sortrows, groupsummary, joins and plots), and in addition timetables provide functions to align, combine, resample and aggregate time-stamped data. They were introduced in R2016b. Use a timetable whenever rows are readings at times, as in the heatflow thermocouple log; use a plain table when rows are unrelated records.

Terminology

  • Row times are the values that label the rows. They are datetime, duration or (since R2026b) numeric double or single values. The row times are not a table variable: they have their own dimension, named Time by default, which is reached with dot notation, TT.Time.

  • A timetable is regular when its row times are evenly spaced (by a fixed duration or by a calendar unit such as a month) and sorted, and irregular otherwise. isregular(TT) tests it. Since R2026b, isregular also treats row times at the end of every month or quarter as regular.

  • TT.Properties.StartTime, TimeStep and SampleRate describe a regular timetable. They are empty or NaN where they do not apply.

  • Resampling puts the data on a new set of times, by interpolation or by copying values. Aggregating combines the values that fall in each time bin, for example a one-minute mean.

  • Time bins are the intervals between consecutive new row times. Each new row time is the left edge of its bin, and the next one is the right edge.

  • A subscript object (timerange, withtol, labels) selects rows by time rather than by position.

Creating timetables

Syntax Meaning

TT = timetable(Time,var1,...,varN)

Row times first, which must then be a datetime or duration vector; the data variables follow. The names come from the workspace variable names.

TT = timetable(var1,...,varN,RowTimes=rowTimes)

Row times given by name; rowTimes can be datetime, duration or numeric (R2026b). The row-time dimension is named Time, whatever the workspace variable is called.

TT = timetable(var1,...,varN,SampleRate=Fs)

Regular row times at Fs samples per second (Hz), starting at zero seconds.

TT = timetable(var1,...,varN,TimeStep=dt)

Regular row times spaced by dt, which is a duration, calendarDuration or numeric scalar, starting at zero seconds.

TT = timetable(Size=sz,VariableTypes=types,RowTimes=rowTimes)

Preallocates a timetable (also with SampleRate= or TimeStep=).

TT = table2timetable(T)

Converts a table; the first datetime or duration variable becomes the row times (or give RowTimes=).

TT = array2timetable(A,RowTimes=rowTimes)

Converts a numeric array.

TT = readtimetable(filename)

Reads a file; the first column of type datetime or duration becomes the row times. See below.

Other conversions are timetable2table(TT) (the row times become a variable) and timeseries2timetable for timeseries objects.

% Not run here: a regular timetable for the first sensor of the plate
Time = datetime(2026,1,15,10,0,0) + minutes(0:4)';
Temperature = [21.5; 21.6; 21.8; NaN; 22.0];
S1   = timetable(Time, Temperature);

% The same data from a time step
S1b = timetable(Temperature, TimeStep=minutes(1));  % duration row times 0 to 4 min

Not run here. S1 has the row times 10:00 to 10:04 on 15 January 2026 and one variable. The call that omits Time creates duration row times starting at 0 minutes, so no calendar date is recorded.

Source: MATLAB documentation: timetable

Reading a timetable from a file

The heatflow scenario logs thermocouple readings to a CSV file with a timestamp, a sensor ID and a temperature, with gaps (illustrative data; the real file is in the scenario’s data folder):

Time,SensorID,Temperature
2026-01-15 10:00:00,S1,21.5
2026-01-15 10:00:30,S2,22.1
2026-01-15 10:01:00,S1,21.6
2026-01-15 10:01:30,S2,
2026-01-15 10:02:00,S1,21.8
2026-01-15 10:02:30,S2,22.4

readtimetable reads such a file. It takes the same options as readtable (including import options from detectImportOptions, setvartype and VariableNamingRule; see Reading and Writing Tabular Data) and makes the first datetime or duration column the row times. Gaps in numeric columns become NaN.

opts = detectImportOptions("data/sensors.csv");
opts = setvartype(opts, "SensorID", "categorical");
sensorLog = readtimetable("data/sensors.csv", opts);

s1 = sensorLog(sensorLog.SensorID == "S1", "Temperature");     % rows of sensor S1 only
s2 = sensorLog(sensorLog.SensorID == "S2", "Temperature");

Not run here. sensorLog is a 6-by-2 timetable with the variables SensorID (categorical) and Temperature. s1 and s2 are one-variable timetables with the rows of one sensor each. A file with a timestamp column that MATLAB does not recognise as a date needs setvaropts(opts,"Time",InputFormat=...) first (see Dates and Times).

Source: MATLAB documentation: readtimetable

Numeric row times (R2026b)

Since R2026b a timetable can have numeric row times (double or single), which label rows with unit-agnostic quantities such as distance, depth or a day number rather than a clock time. The heatflow plate offers a natural example: temperatures along a line of sensors, labelled by distance from the edge.

With numeric row times the subscript TT(3,:) still means the third row. To select by row-time value, wrap the values in labels, which was introduced in R2026b for this purpose.

Distance    = [0.0; 0.1; 0.2; 0.3];       % metres from the left edge
Temperature = [21.5; 22.0; 22.6; 23.1];
profile = timetable(Temperature, RowTimes=Distance);

byRow   = profile(3, :);              % the third row, at distance 0.2
byLabel = profile(labels(0.3), :);    % the row whose row time is 0.3

Not run here. byRow is the row with the row time 0.2 and byLabel the row at 0.3. timerange, withtol and retime accept numeric values for such a timetable, and lag accepts a labels object for the shift. The numeric row times must all be double or all single, and timerange bounds must be numeric of the same class. Releases before R2026b reject numeric row times; keep the distance in a table variable (a plain table) for older code.

Source: MATLAB documentation: labels

Selecting rows by time

A timetable is indexed like a table with position, logical masks and variable names. Because rows have times, three subscript objects select by time.

Subscript Selects

timerange(t1,t2)

Rows whose time is in the half-open interval from t1 (included) to t2 (not included). t1 and t2 are datetime or duration scalars, text that denotes a date and time, or numeric scalars; they must match the row-time type. timerange(t1,t2,intervalType) changes the interval: open, closed, openleft or openright. timerange(startPeriod,endPeriod,unit) and timerange(period,unit) select whole calendar units such as a month or a day.

withtol(times,tol)

Rows whose time matches one of times within the tolerance tol (a nonnegative duration or numeric value). Useful for readings that are nominally every 30 seconds but jitter.

labels(values)

Rows whose numeric row time equals one of values (R2026b).

Datetime scalars can also index rows directly: TT(datetime(2026,1,15,10,2,0),:) selects the row at exactly that time.

firstTwo = S1(timerange(datetime(2026,1,15,10,0,0), datetime(2026,1,15,10,2,0)), :);   % 10:00 and 10:01
whole    = S1(timerange("2026-01-15", "days"), :);                                      % the whole day
near     = sensorLog(withtol(datetime(2026,1,15,10,1,0), seconds(5)), :);                    % rows within 5 s of 10:01:00

Not run here. firstTwo has two rows because the end time is excluded.

Source: MATLAB documentation: timerange

retime: resample and aggregate

TT2 = retime(TT1, newTimes, method) is the central function: it returns a timetable with new row times and new data. Its forms are:

TT2 = retime(TT1,newTimeStep,method)
TT2 = retime(TT1,"regular",method,TimeStep=dt)
TT2 = retime(TT1,"regular",method,SampleRate=Fs)
TT2 = retime(TT1,newTimes,method)

and the same without method (the default). The inputs are:

  • newTimeStep, a name from the list yearly, quarterly, monthly, weekly, daily, hourly, minutely or secondly; dt, a duration, calendarDuration or numeric scalar of any size; Fs, a sample rate in Hz; or newTimes, a sorted, unique datetime, duration or numeric vector, which can be irregular.

  • method, which is a character vector, a string scalar or a function handle.

Method family Methods and behavior

Fill

fillwithmissing (gaps become NaN or another missing indicator) and fillwithconstant (uses the Constant name-value argument, default 0). Values are copied where the new and old times coincide.

Nearest neighbour

previous, next and nearest copy the value from the neighbouring input row. Input row times must be sorted.

Interpolation

linear, spline, pchip and makima. Input row times must be sorted and unique. EndValues controls extrapolation before the first and after the last input time (extrap by default, or a scalar).

Aggregation

sum, prod, mean, median, mode, min, max, count, firstvalue, lastvalue, or a function handle such as @std (the function must return a scalar or a row vector and accept empty input). Each new row time is the left edge of a bin and the next one the right edge; IncludedEdge is left (default) or right. All named aggregations skip NaN, NaT and other missing values; a function handle sees them.

default

The default when no method is given: fill with missing values, or the per-variable methods given by the VariableContinuity property.

As the documentation puts it, the first row time of TT2 is on the time step before the earliest row time of TT1, and the row times of TT2 cover the range of TT1 but may not include any of its actual row times.

Per-variable methods are set with TT.Properties.VariableContinuity = ["continuous" "step" "event" ...] (one entry per variable; unset is the default). A continuous variable (a temperature) is interpolated, a step variable (a mode setting) holds its previous value, and an event variable (a count of events) is filled with missing values. The default method then uses these. Retiming with an explicit method overrides them.

The sensor log resampled to one-minute means

% Not run here: one-minute means for sensor S1 of the log read above
oneMinute = retime(s1, "minutely", "mean");

% Interpolate to a regular 15 second grid instead
fine = retime(s1, "regular", "linear", TimeStep=seconds(15));

% Aggregate without skipping the gaps: a function handle sees NaN
strict = retime(s1, "minutely", @mean);

Not run here. With the six-row sample above, s1 has readings at 10:00:00, 10:01:00 and 10:02:00 for sensor S1 (the S2 rows were removed by the mask), so oneMinute has one row per minute bin with the mean of the readings in the bin. If a bin held the NaN gap, mean would skip it and the bin would hold the mean of the other readings; the function-handle form strict returns NaN for such a bin. fine has rows every 15 seconds, filled by linear interpolation between the neighbouring readings. Treat NaN gaps before interpolating (see Missing Data).

Source: MATLAB documentation: retime

retime also resolves duplicate or irregular times: retiming a timetable that has repeated row times to a regular step aggregates the duplicates, and retime(TT,"regular","firstvalue",TimeStep=...) keeps one value per step.

synchronize: combine timetables on a common time vector

TT = synchronize(TT1,TT2) combines the variables of several timetables in one, on the union of their row times. It is like a horizontal concatenation that allows different row times, and it inserts missing values where a timetable has no data. Variables with the same name in the inputs are renamed. More control:

TT = synchronize(TT1,TT2,newTimeBasis,method)
TT = synchronize(TT1,TT2,newTimeStep,method)
TT = synchronize(TT1,TT2,"regular",method,TimeStep=dt)
TT = synchronize(TT1,TT2,newTimes,method)
TT = synchronize(TT1,...,TTN,___)

  • newTimeBasis is one of union (default), intersection, commonrange, first or last: how the output row times are built from the input row times. first and last take the row times of the first or the last input timetable.

  • The other arguments and the methods are the ones of retime. If method is omitted, VariableContinuity or missing-value fill applies.

% Not run here: put the two sensors side by side on a common one-minute grid
both = synchronize(s1, s2, "minutely", "mean");

Not run here. both has one row per minute and two temperature variables; because both inputs have a variable called Temperature, MATLAB renames them (commonly by adding a suffix), so rename the variables first with renamevars when you need predictable names.

Source: MATLAB documentation: synchronize

lag and other time-based operations

  • lag(TT) shifts the data forward in time by one row (a lag) and puts a missing value in the first row; lag(TT,n) shifts by n rows (negative n shifts backward: a lead); lag(TT,dt) shifts by a time interval that is a multiple of the time step, and may be a labels object for numeric row times. The row times of the timetable are unchanged, and it must be regular.

  • sortrows(TT) sorts by row times. unique(TT.Time) finds repeated times. isregular(TT) and TT.Properties.TimeStep test and describe regularity. Row times need not be sorted or unique when the timetable is created, but many functions require it.

  • diff(TT.Time) returns the time differences as a duration vector; seconds(...), minutes(...) and hours(...) convert (see Dates and Times).

  • eventtable and eventfilter (since R2023a) attach tables of events to a timetable and select rows around the events.

prev  = lag(oneMinute);             % previous minute's mean in each row
delta = oneMinute.Temperature - prev.Temperature;   % change from the previous minute

Not run here. The first row of delta is NaN, because lag fills the first row with a missing value.

Source: MATLAB documentation: lag

Calculations and plots

Since R2023a, mathematical operations such as +, .* and mean can be applied directly to a timetable when all variables support the operation (see Tables); since R2026b, *, / and \ accept a scalar operand. Grouped calculations by calendar unit use groupsummary with a time bin, as in groupsummary(TT,"Time","hour","mean"); like the named retime aggregations, the named groupsummary methods omit NaN values. Plotting functions accept a timetable followed by variable names; with no x variable, they plot against the row times, as in plot(S1,"Temperature"), and stackedplot(both) draws one axis per variable on a shared time axis.

Source: MATLAB documentation: Plots That Support Tables

Common errors and pitfalls

The exact message and identifier for these cases vary by release and were not run here; the causes are documented behavior.

  • Row times of the wrong type in a subscript. timerange, withtol and labels must match the row-time type: a datetime range on duration row times, or numeric bounds on datetime row times, is an error.

  • Numeric subscripts are positions, not times. On a timetable with numeric row times, TT(3,:) is the third row. Use labels for the value.

  • timerange excludes the end. The interval is half-open: to include the last row use the closed interval type or a later end time.

  • Unsorted or duplicate row times. Interpolating methods need sorted, unique row times; aggregation methods need sorted newTimes. Sort with sortrows(TT) and aggregate duplicates first with retime or groupsummary.

  • retime with NaN data. Named aggregations skip missing values, so a mean over a bin of all NaN gives NaN and a count of 0. Interpolation does not repair a gap; use fillmissing or rmmissing first.

  • First row time of retime. With a named time step the first output time depends on the step and the earliest input time (the documentation says it is on the time step before the earliest row time), which can surprise when only a few rows exist. Give newTimes to control it.

  • lag of an irregular timetable. lag requires regular row times; retime to a regular grid first.

  • Time zones and daylight-saving. datetime row times with a time zone are compared in absolute time. Make all timetables you combine use the same time zone or none (see Dates and Times).

  • Row-time variable name. The dimension is Time by default, even if the input was t. Rename with TT.Properties.DimensionNames{1} = "Timestamp" or DimensionNames= at creation.

Where older books differ

  • Books from before R2016b describe time series with the timeseries object (in base MATLAB) and datenum columns in matrices or tables, and datestr/datenum for formatting. The datetime type and the timetable that uses it (R2016b) replace them. timeseries2timetable and table2timetable convert old data.

  • retime, synchronize and the timerange and withtol subscripts arrived with timetable and are newer than most books. lag and isregular extensions, events (R2023a), and numeric row times with labels (R2026b) are newer still.

  • Old code writes name-value pairs as 'TimeStep',dt; current code can use TimeStep=dt (R2021a, per the retime documentation). Both still work.

See Also

References