timetable

Methods

⌂ timetable

Method Reference: timetable.timetable2ods

timetable: timetable2ods (tt, file)
timetable: timetable2ods (tt, file, Name, Value)

Write a timetable to an OpenDocument spreadsheet file.

timetable2ods (tt, file) writes the timetable tt to file, which may be a character vector, a cellstr, or a string scalar. When file ends in .ods a compressed (ZIP-packaged) OpenDocument spreadsheet is written; when it ends in .fods a flat (single-XML) one is written instead. The resulting file can be read back with ods2timetable.

The data sheet is headed by the row dimension name and the variable names and then carries one natively typed cell per value, and a hidden __datatypes_meta__ sheet carries the variable types, descriptions and units, exactly as table2ods writes them.

The row times lead the sheet as a column of their own, written as native date or time cells as a datetime or duration variable is, so a spreadsheet application shows them as times rather than as text. The column is tagged RowTimes in the hidden sheet, followed by the row times’ own type, their TimeZone where they have one, and their Format, so that all three come back exactly.

The row times are not optional: a timetable without them is not one, so there is no switch to leave them out.

The following Name-Value options are supported:

NameValue
'Sheet'The name of the sheet to write (default 'Sheet1'). When file already exists the named sheet is added or replaced while every other sheet is preserved, so a workbook can be built up one object at a time.
'WriteVariableNames'A logical scalar specifying whether the variable names are written (default true). When false the file carries none at all, the hidden metadata sheet included, so ods2timetable numbers the variables on read and can no longer group the columns. The row dimension name is a name too and goes with them.
'WriteMode''overwritesheet' or 'inplace' replace the sheet (the default when the sheet exists), 'append' appends the timetable’s rows to it, and 'replacefile' discards any existing file.

Source Code: timetable

An attached event table is written too, on a sheet of its own named <sheet>_Events, with a ## Events crossref: line in the hidden metadata sheet tying the two together and carrying the event table’s three variable designations. ods2timetable reads that sheet back and attaches it, and skips it when choosing which sheet to read. This is the only file format of the package that carries events: timetable2csv and writetimetable drop them.

Note the following round-trip limitation when reading the file back with ods2timetable: calendarDuration and categorical variables are returned as cell arrays of character vectors and their values are not reconstructed.

See also: ods2timetable, timetable2csv, struct2ods, table.table2ods

Source Code: timetable

timetable2ods writes a timetable to an OpenDocument spreadsheet, one natively typed cell per value. The row times become real date cells, so a spreadsheet application shows them as times rather than as text, and ods2timetable restores their type, zone and format exactly.

 t = datetime (2024, 3, 9, 22, 0, 0, 'TimeZone', 'America/New_York') ...
     + hours (0:2)';
 Reading = [12.5; 13.1; 11.8];
 TT = timetable (Reading, 'RowTimes', t)
TT =
  3x1 timetable

            Time            Reading    
    ____________________    _______    

    09-Mar-2024 22:00:00       12.5    
    09-Mar-2024 23:00:00       13.1    
    10-Mar-2024 00:00:00       11.8
 filename = fullfile (tempdir (), 'readings.ods');
 timetable2ods (TT, filename);
 ods2timetable (filename)
ans =
  3x1 timetable

            Time            Reading    
    ____________________    _______    

    09-Mar-2024 22:00:00       12.5    
    09-Mar-2024 23:00:00       13.1    
    10-Mar-2024 00:00:00       11.8
 delete (filename);

This is the only file format of the package that carries an event table. It goes on a sheet of its own, and a cross-reference in the hidden metadata sheet ties the two together, so the events come back attached.

 t = datetime (2024, 1, 1) + hours (0:5)';
 TT = timetable ([1; 2; 3; 4; 5; 6], 'RowTimes', t, ...
                 'VariableNames', {'Flow'});
 TT.Properties.Events = eventtable (t([2 4]), ...
                                    'EventLabels', {'opened'; 'closed'}, ...
                                    'EventLengths', hours ([2; 1]));
 filename = fullfile (tempdir (), 'flow.ods');
 timetable2ods (TT, filename);
 back = ods2timetable (filename);
 back.Properties.Events
ans =
  2x2 eventtable

            Time            EventLabels    EventLengths    
    ____________________    ___________    ____________    

    01-Jan-2024 01:00:00    {'opened' }            2 hr    
    01-Jan-2024 03:00:00    {'closed' }            1 hr
 delete (filename);

Writing to a named 'Sheet' of an existing workbook adds or replaces just that sheet and leaves the others alone, so a table and a timetable can share one file and each comes back as what it was.

 filename = fullfile (tempdir (), 'workbook.ods');
 table2ods (table ([38; 43], 'VariableNames', {'Age'}), filename, ...
            'Sheet', 'Patients');
 TT = timetable ([1; 2], 'RowTimes', datetime (2024, 1, [1; 2]), ...
                 'VariableNames', {'Visit'});
 timetable2ods (TT, filename, 'Sheet', 'Visits');
 s = ods2struct (filename);
 class (s.Patients)
ans = table
 class (s.Visits)
ans = timetable
 delete (filename);