timetable

Methods

⌂ timetable

Method Reference: timetable.timetable2csv

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

Write a timetable to a comma-separated-value (CSV) file.

timetable2csv (tt, file) writes the timetable tt to file, which may be a character vector, a cellstr, or a string scalar. The resulting file can be read back with csv2timetable.

The file begins with a comment line reporting how many consecutive rows hold the variable types, names, descriptions, and units, in that order. Those header rows are followed by one row of data per timetable row. The variables are serialized exactly as table2csv serializes them.

The row times lead the file as a column of their own, written in ISO 8601 form so that they are exact whatever their display format. The column is tagged RowTimes in the variable-type row, followed by the row times’ own type, their TimeZone where they have one, and their Format; the row dimension name travels in the variable-name row beside it. A zone-aware datetime and a duration of any resolution therefore both come back exactly as they went out, which writetimetable does not manage for either.

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
'WriteVariableNames'A logical scalar specifying whether the variable names are written (default true). When false the file carries none, so csv2timetable numbers the variables on read and can no longer group the columns: a multicolumn variable comes back as separate variables and a nested table as flat columns. The row dimension name is a name too and goes with them, so the row times come back under the default Time.

Source Code: timetable

A CSV file holds one table and has nowhere to put a second, so an attached event table is not written and nothing warns. Write the timetable to an OpenDocument spreadsheet with timetable2ods to keep its events. TimeStep, SampleRate and VariableContinuity are not written either; the first two are worked out again from the row times on read.

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

See also: csv2timetable, timetable2ods, writetimetable, table.table2csv

Source Code: timetable

timetable2csv writes a timetable to a text file that keeps everything: the row times lead the file in ISO 8601 form, and their type, time zone and display format ride in the header block rather than in the values. csv2timetable gives back what went in.

 t = datetime (2024, 3, 9, 22, 0, 0, 'TimeZone', 'America/New_York') ...
     + hours (0:3)';
 Reading = [12.5; 13.1; 11.8; 12.0];
 Site = categorical ({'N'; 'S'; 'N'; 'S'});
 TT = timetable (Reading, Site, 'RowTimes', t)
TT =
  4x2 timetable

            Time            Reading    Site    
    ____________________    _______    ____    

    09-Mar-2024 22:00:00       12.5       N    
    09-Mar-2024 23:00:00       13.1       S    
    10-Mar-2024 00:00:00       11.8       N    
    10-Mar-2024 01:00:00         12       S
 filename = fullfile (tempdir (), 'readings.csv');
 timetable2csv (TT, filename);
 back = csv2timetable (filename)
warning: csv2table: 'categorical' strings are not converted.
warning: called from
    csv2table>cell2var at line 502 column 5
    csv2table>@<anonymous> at line 325 column 50
    __cell2tbl__ at line 50 column 7
    csv2table at line 324 column 7
    csv2timetable at line 82 column 3
    __eval_demo__ at line 84 column 9
    __demo_notebook__ at line 43 column 3
    __build_demos__ at line 79 column 7
    method_texi2html at line 84 column 5
    classdef_texi2html at line 463 column 9
    package_texi2html at line 344 column 11

back =
  4x2 timetable

            Time            Reading    Site     
    ____________________    _______    _____    

    09-Mar-2024 22:00:00       12.5    {'N'}    
    09-Mar-2024 23:00:00       13.1    {'S'}    
    10-Mar-2024 00:00:00       11.8    {'N'}    
    10-Mar-2024 01:00:00         12    {'S'}
 delete (filename);

The file is readable in any text editor. Its first line says how many header rows follow, the second types every column, and the third names them. The row-time column is tagged RowTimes ahead of its own type, and the row dimension's name sits beside it.

 TT = timetable ([1; 2], 'RowTimes', datetime (2024, 1, [1; 2]), ...
                 'VariableNames', {'Count'});
 TT.Properties.DimensionNames{1} = 'Day';
 filename = fullfile (tempdir (), 'counts.csv');
 timetable2csv (TT, filename);
 type (filename);
"# varTypes 1 rows; varNames 1 rows; varDescriptions 0 rows; varUnits 0 rows.",
"RowTimes|datetime|dd-MMM-uuuu","double"
"Day","Count"
"2024-01-01T00:00:00",1
"2024-01-02T00:00:00",2
 delete (filename);

A CSV file holds one table and has nowhere to put a second, so an attached event table is not written and nothing warns. Write the timetable to an OpenDocument spreadsheet to keep its events.

 t = datetime (2024, 1, 1) + hours (0:3)';
 TT = timetable ([1; 2; 3; 4], 'RowTimes', t, 'VariableNames', {'Flow'});
 TT.Properties.Events = eventtable (t(2), 'EventLabels', {'valve opened'});
 filename = fullfile (tempdir (), 'flow.csv');
 timetable2csv (TT, filename);
 csv2timetable (filename).Properties.Events
ans = [](0x0)
 delete (filename);