MATLAB - Timetables

MATLAB - Modern Data Handling with Timetables

A timetable is a modern and highly efficient data container in MATLAB, introduced in version R2016b. It is specifically designed for handling time-stamped data. Think of it as a specialized table where each row is explicitly associated with a point in time. Data is stored in column-oriented variables that can have different data types and sizes, as long as they all have the same number of rows. Timetables are essential for modern data analysis, providing a rich set of functions to align, combine, and perform calculations on time-stamped data with ease and accuracy.

The key advantage of timetables over older methods (like using separate vectors for time and data) is that the time and data are intrinsically linked. This prevents data-time mismatches and simplifies complex operations like resampling and synchronization. Real-world applications for timetables are abundant:

• Financial Analysis: Storing and analyzing stock market data, which is inherently time-dependent. You can easily resample tick-by-tick data into daily intervals or align data from different stocks.
• Medical Research: Tracking patient vital signs or experimental results over time. Timetables make it easy to analyze data from multiple subjects, even if the measurements were not taken at the exact same moments.
• Environmental Science: Monitoring and assessing environmental data, such as temperature, humidity, and pollutant levels from sensor networks.
• Engineering and IoT: Analyzing sensor data from vehicles, industrial machinery, or smart devices. GPS coordinates, temperature readings, and pressure values can be cleanly organized and processed.

Let’s dive into how to create and work with timetables in modern MATLAB.

Creating a Timetable

MATLAB offers several flexible ways to create a timetable. The most direct and recommended approach is using the timetable() function.

Using the timetable() Function

The timetable() constructor is the primary method for creating timetables from scratch.

Syntax

% Basic syntax
TT = timetable(RowTimes, Var1, ..., VarN);

% Recommended syntax with named variables
TT = timetable(RowTimes, Var1, ..., 'VariableNames', {'Name1', ...});

The function creates a timetable where RowTimes is a datetime or duration vector that provides the timestamps for each row. The data variables Var1, ..., VarN can be of different types (e.g., double, string, cell), but they must all have the same number of rows as the length of RowTimes. It is a best practice to name your variables explicitly during creation for clarity.

Example

Let’s create a timetable to store weather data.

% 1. Define the timestamps using a datetime array
SampleTimes = datetime('2023-10-26 09:00:00') + hours(0:2)';

% 2. Define the data variables
Temperature = [15.2; 16.1; 15.8]; % in Celsius
Humidity = [55.3; 52.1; 54.5];    % in Percent
Conditions = ["Sunny"; "Sunny"; "Partly Cloudy"];

% 3. Create the timetable with named variables
WeatherTT = timetable(SampleTimes, Temperature, Humidity, Conditions, ...
    'VariableNames', {'TempC', 'Humidity', 'Conditions'})

Executing this code in MATLAB produces the following output:

WeatherTT =

  3×3 timetable

    SampleTimes            TempC    Humidity      Conditions
    ____________________    _____    ________    _________________

    26-Oct-2023 09:00:00    15.2       55.3      "Sunny"
    26-Oct-2023 10:00:00    16.1       52.1      "Sunny"
    26-Oct-2023 11:00:00    15.8       54.5      "Partly Cloudy"

Converting from Other Data Types

You can also create timetables by converting other MATLAB data types.

• array2timetable(): Useful for quickly converting a purely numeric matrix where each column represents a different variable.
• table2timetable(): The standard way to convert an existing table to a timetable. The source table must contain a datetime or duration variable to be used as the row times.

Example: table2timetable()

Let’s first create a regular table and then convert it.

% Create a source table
EventTime = datetime({'2023-01-01 09:00:00'; '2023-01-01 10:30:00'});
EventType = ["Start"; "Stop"];
EventValue = [100; 150];
T = table(EventTime, EventType, EventValue);

% Convert the table to a timetable
% MATLAB automatically detects the 'EventTime' column as the row times.
TT = table2timetable(T)

The output will be a timetable with EventTime as the row time vector and EventType and EventValue as data variables.

Legacy Note: timeseries Objects

In older MATLAB versions, timeseries objects were commonly used. While you can convert them to timetables using timeseries2timetable() for backward compatibility, this workflow is now considered legacy. For all new projects, you should create and use timetables directly.

Working with Timetables

The real power of timetables comes from the specialized functions for indexing, processing, and synchronizing time-stamped data.

• Indexing: Access data by time using timerange or by variable name using dot notation (e.g., WeatherTT.TempC).
• Synchronizing: Use synchronize to combine two timetables, aligning their data based on time. This is incredibly powerful for merging data from different sources.
• Resampling: Use retime to change the sampling frequency of a timetable, for example, converting minute-by-minute data to hourly averages. You can specify aggregation methods like 'mean', 'sum', or 'max'.

Example: Resampling with retime

% Create a high-frequency timetable
Times = datetime('now') + minutes(0:59)';
Data = rand(60, 1) * 10;
FineTT = timetable(Times, Data);

% Resample to 15-minute intervals, taking the mean value
CoarseTT = retime(FineTT, 'regular', 'mean', 'TimeStep', minutes(15))

Best Practices

• Be Explicit: Always name your variables clearly using the 'VariableNames' property.
• Mind Time Zones: datetime objects can be time zone-aware. Be consistent with time zones to avoid errors, especially when merging data from different geographic locations.
• Leverage Built-in Functions: Before writing a custom loop, check if a built-in function like retime, synchronize, or fillmissing can do the job. They are optimized for performance.
• Vectorize Operations: Perform calculations on entire timetable variables at once (e.g., WeatherTT.TempF = WeatherTT.TempC * 9/5 + 32;) instead of iterating row by row.