Working with MATLAB Dates and Time Data Types

This help page provides an overview and a few simple demonstrations of how one can work with Time Stamps (also know as Date Stamps) with Kornucopia.

Kornucopia's k_units data type is based on a powerful and general multiplicative units engine. You can store and compute with variables containing (by column) different types of quantities such as force, distance, mass, time, and more. With respect to time, Kornucopia's representation is based on time in terms of duration (for example, think of time values from a stop watch). Typical examples of the use of time in Kornucopia would be:

Processing a file or array of physical test data that records the ongoing time duration from the start (trigger) of the test. This time data is typically recorded in one column of the data. At the start, time would typically be 0*s and at successive sample measurements during the test the time values would increase. Any time values recorded before the trigger (so-called pre-trigger region) would have negative time values.
Processing a file or array representing a transient dynamics simulation like the impact of a mechanical structure into a wall. Similar to the physical test data described above, time in the simulation would be stored in one of the columns and it would typically start at 0*s and increase in value as the simulation proceeded.
Representing the total duration of an event might be represented in Kornucopia with a single scalar value of time such as 0.35*ms, or 15.4*min, or 72*day.

In the above examples, the Units used to represent time can be Units like s, ms, min, hr, day, or even fortnight (and several others too).

HOWEVER, you will NOT find time-related Units for month, year, or century in Kornucopia's Units Library. That is because these measures of time do not have unique values. For example, in January a month is 31 days but in February it is 28 days unless it is a leap year, then it is 29 days!). To handle this kind of stuff requires Calendar Math, which is something that MATLAB offers with its Dates and Time functionality.

In Kornucopia you cannot directly store or represent Time Stamp styles of time in Kornucopia's k_units data type (but in a moment we will explain how Kornucopia will automatically convert these to quantities measuring time durations). Examples of Time Stamps are:

06-Jun-2023 18:36:15.325
08:35 AM
08/08/2023 22:50:38:187

To work directly with Time Stamps styles you can store such quantities in MATLAB via data types of timetable and datetime, and differences of such quantities automatically become the duration data type. We note that other MATLAB time-based data types exist too.

Starting in Kornucopia version 5.2-01, the k_units data type will automatically internally convert variables containing data types of timetable, datetime, and duration fed into the k_units function (or any Kornucopia function) into a time duration quantity including storing the starting datetime (if one exists) in the appropriate .Props.ColUserData column of the resulting output variable. Thus, this Kornucopia capability lets you easily work with data that originally was supplied in Time Stamp styles.

Examples of how Kornucopia works with Time Stamp kinds of data

Consider importing the following csv text file from the Kornucopia Examples Data folder into MATLAB to then plot or otherwise calculate with.

The file is a comma delimited CSV file with a header row, no Units stated, and where the 1st column holds time in the form of a Time Stamp. Below we show a few lines of a script to import the file as a MATLAB Table data type followed by the results of its execution.

k_unitsPreferenceActivate('mm_N_ms'); fileDir = k_examplesDir('data'); fName = 'timeStamped_log.csv'; A_t = readtable(fullfile(fileDir, fName), ... 'delim', ',')

A few important notes:

Using MATLAB's readtable function resulted in a MATLAB table being created, A_t.

The column names for the variable automatically came from the input CSV file.
Using the simple call demonstrated resulted in the TimeStamp column holding a cell-string of Time Stamp values. These values cannot be used as a time vector related to any plotting or calculations. We need to convert this column to something more useful, which we will do in a moment.

Let's try having the function k_units simply process the entire A_t variable to convert it to k_units data type. Unfortunately, trying the simple command below yields an error as shown.

A = k_units(A_t);

What Kornucopia is complaining about is that the data in the 1st column of A_t is a cell-string and NOT a MATLAB data type of timetable, datetime, nor duration (nor just some numeric column like the other columns). Thus, it throws an error.

To solve the issue, we first extract the TimeStamp column contents from the table and convert it to a MATLAB datetime data type as shown below.

TS = datetime(A_t.TimeStamp, ... 'InputFormat', 'MM/dd/yyy HH:mm:ss:SSS')

Now we can easily use k_units to convert the TS variable to a quantity of duration and horizontally concatenate that result with the other columns of the A_t variable which are fed into the k_units function. We do two other house-keeping tasks: rename the 1st column to 'Time' and set appropriate units for the other columns of the data. (Note that in this dangerous example, the original data file had NO Units stated anywhere. The user just had to know what they were somehow.)

A = [k_units(TS), k_units(A_t(:, 2:end))] A.Props.ColNames{1} = 'Time'; A(:, 2:end) = A(:, 2:end).overwriteUnits('1, mm/s, mm/s, mm/s')

This next example loads a MAT file that holds 4 variables of data type timetable that came from a MATLAB function that reads motion data from a mobile phone.

Tip: Search the MATLAB help for "Cameras and Mobile Sensing" (no quotes) to see various MATLAB capabilities and functions to read data from a mobile phone.

The few lines of code below loads the MAT file from the Kornucopia Examples Data folder and displays one of the imported variables, Acceleration (a timetable data type).

k_examplesOpen('sensorlog_viaMatlabMobile.mat', ... 'loadMat', 'on'); Acceleration

Because variable Acceleration is a timetable data type, the 1st column holds actual Timestamp data that can be directly worked with. In particular, we can easily convert this entire variable into a k_units data type as shown below.

Accel = k_units(Acceleration) Accel.Props.ColUserData{1}

Notes:

The function k_units converted the Timestamp column to a duration measure of time so that it is easy to plot and compute with. In the Props.ColUserData Property of that column, the function stored the starting datetime timestamp.
The variable Acceleration did NOT have any Units stored in its Properties.VariableUnits Property. This dangerous approach of not including units labels with data is sadly common in many workflows. Had these Units been included with the variable (which is possible), then Kornucopia would have utilized them in its processing and the result would have had the proper units. Since this was not the case in this example, we add the proper units in the last bit of code below.

% Adding the proper units to the acceleration columns. Accel(:, 2:end) = Accel(:, 2:end).overwriteUnits('m/s^2')