timetable.writetimetable
timetable: writetimetable (tt, filename)
timetable: writetimetable (tt, filename, Name, Value)
Write a timetable to a file in the MATLAB-compatible form.
writetimetable (tt, filename) writes the timetable
tt to filename with no hidden metadata of any kind: one
header row of names and then one row per row of the timetable, which is
what readtimetable and MATLAB both expect. The file type follows
the extension, .txt, .csv and .dat being text
and .ods, .fods, .xlsx and .xlsm
spreadsheets, and 'FileType' overrides it.
The row times lead the file under the row dimension name, as MATLAB
writes them. They are not optional: a timetable without them is not
one, so there is no switch to leave them out, and 'WriteRowNames'
is refused because a timetable has no row names.
.ods is the OpenDocument spreadsheet format, an open standard
that LibreOffice and other applications read and write on every
platform. MATLAB is the exception and cannot be given one.
Its writetimetable refuses the extension, and its readers open an
OpenDocument file only by handing it to Excel, so a MATLAB user without
Excel cannot read one at all. A file written for a MATLAB user should
therefore be .csv or .xlsx. Everywhere else the format
is a good choice, and timetable2ods writes it losslessly and is
the only format of the package that carries an event table.
A zone-aware datetime is written in the RFC 9557 form,
2024-03-09T22:00:00-05:00[America/New_York], rather than as the
display string MATLAB writes. This is deviation D7; see the
note below for why it is better. An unzoned datetime and a
duration are written as MATLAB writes them, both of those
round-tripping through MATLAB exactly.
The following Name-Value options are supported:
| Name | Value |
|---|---|
'FileType' | 'text' or 'spreadsheet',
overriding what the extension says. |
'WriteVariableNames' | A logical scalar specifying
whether the header row of names is written (default true). |
'Delimiter' | The field delimiter of a text file, named
('comma', 'space', 'tab', 'semi',
'bar') or given as the character itself (default ','). |
'QuoteStrings' | 'minimal', 'all' or
'none', saying which text fields are quoted (default
'minimal'). |
'Sheet' | The sheet of a spreadsheet to write. |
'Range' | The top-left cell a fresh spreadsheet write is anchored at, in A1 notation. |
'WriteMode' | 'overwrite' or 'append'
for a text file; 'overwritesheet', 'inplace',
'append' or 'replacefile' for a spreadsheet. |
Source Code: timetable
An attached event table is not written and nothing warns, as
nothing warns in MATLAB. Use timetable2ods, the only format of
the package that carries events.
Deviation D7, and why the RFC 9557 form is the better answer.
MATLAB writes a zoned datetime as its display string, so the zone
is written only when the Format happens to ask for it, and
readtimetable then reads the file back unzoned and at the wrong
instant without complaining. Measured against R2026a, no text
form of a zoned row time survives MATLAB’s own reader: given a format
carrying the offset, MATLAB writes
2024-03-09T22:00:00-05:00 itself and then fails to read that
very file, so there is no encoding that keeps MATLAB working. The
choice is between a loud failure there and a silent one, and this
package takes the loud one. RFC 9557 is a published standard, not an
invention of ours, and it carries both the offset and the zone name: the
offset alone cannot name a zone, and the name alone cannot say which
side of a repeated hour an instant falls on, so a timestamp inside a
daylight-saving fold round-trips here and would not otherwise.
See also: readtimetable, timetable2ods, timetable2csv, table.writetable
Source Code: timetable
writetimetable writes the MATLAB-compatible form: no hidden metadata, one header row of names, the row times leading under the row dimension's name, and one row per row. readtimetable reads it back.
TT = timetable ([12.5; 13.1; 11.8], ...
'RowTimes', datetime (2024, 1, (1:3)'), ...
'VariableNames', {'Reading'});
filename = fullfile (tempdir (), 'plain.csv');
writetimetable (TT, filename);
type (filename);
Time,Reading 01-Jan-2024,12.5 02-Jan-2024,13.1 03-Jan-2024,11.8
readtimetable (filename)
ans =
3x1 timetable
Time Reading
___________ _______
01-Jan-2024 12.5
02-Jan-2024 13.1
03-Jan-2024 11.8
delete (filename);
A zone-aware datetime is written in the RFC 9557 form, which carries the offset and the zone name. MATLAB writes the display string instead and cannot read the zone back at all, so this file says more than a MATLAB one does about the same instants.
t = datetime (2024, 3, 9, 22, 0, 0, 'TimeZone', 'America/New_York') ...
+ hours (0:2)';
TT = timetable ([1; 2; 3], 'RowTimes', t, 'VariableNames', {'Reading'});
filename = fullfile (tempdir (), 'zoned.csv');
writetimetable (TT, filename);
type (filename);
Time,Reading 2024-03-09T22:00:00-05:00[America/New_York],1 2024-03-09T23:00:00-05:00[America/New_York],2 2024-03-10T00:00:00-05:00[America/New_York],3
readtimetable (filename).Properties.RowTimes.TimeZone
ans = America/New_York
delete (filename);
Carrying the offset as well as the zone name is what makes a repeated hour survive. These two rows are the same wall clock on the night the clocks go back, one hour apart in real time, and they come back as the two distinct instants they are.
a = datetime (2024, 11, 3, 5, 30, 0, 'TimeZone', 'UTC');
a.TimeZone = 'America/New_York';
b = datetime (2024, 11, 3, 6, 30, 0, 'TimeZone', 'UTC');
b.TimeZone = 'America/New_York';
TT = timetable ([1; 2], 'RowTimes', [a; b], 'VariableNames', {'Reading'});
filename = fullfile (tempdir (), 'fold.csv');
writetimetable (TT, filename);
type (filename);
Time,Reading 2024-11-03T01:30:00-04:00[America/New_York],1 2024-11-03T01:30:00-05:00[America/New_York],2
back = readtimetable (filename); tzoffset (back.Properties.RowTimes)
ans =
2x1 duration array
-04:00
-05:00
delete (filename);