writetimetable

Write timetable to file

Syntax

writetimetable(TT)

writetimetable(TT,filename)

writetimetable(___,Name,Value)

Description

writetimetable(TT) writes the timetable TT to a comma-delimited text file. The file name is the workspace variable name of the timetable, appended with the extension .txt. If writetimetable cannot construct the file name from the input timetable name, then it writes to the file timetable.txt.

Each column of each variable in TT becomes a column in the output file. The variable names of TT become column headings in the first line of the file. The writetimetable function overwrites any existing file.

writetimetable(TT,filename) writes to a file with the name and extension specified by filename.

writetimetable determines the file format based on the specified extension. The extension must be one of the following:

• .txt, .dat, or .csv for delimited text files

• .xls, .xlsm, or .xlsx for Excel^® spreadsheet files

• .xlsb for Excel spreadsheet files supported on systems with Excel for Windows^®

• .xml for Extensible Markup Language (XML) files.

writetimetable(___,Name,Value) uses additional options specified by one or more Name,Value pair arguments and can include any of the input arguments in previous syntaxes.

For example, you can specify whether to write the variable names as column headings in the output file.

Examples

Write Timetable to Text File

Create a timetable, write it to a comma-separated text file, and then write the timetable to another text file with a different delimiter character.

Define a timetable in the workspace with row times duration vector RowTimes.

RowTimes = seconds(1:5)';
TT = timetable(RowTimes,[98;97.5;97.9;98.1;97.9],[120;111;119;117;116],...
               'VariableNames',{'Reading1','Reading2'})

TT=5×2 timetable
    RowTimes    Reading1    Reading2
    ________    ________    ________

    1 sec           98        120   
    2 sec         97.5        111   
    3 sec         97.9        119   
    4 sec         98.1        117   
    5 sec         97.9        116   

Write the timetable to a comma delimited text file and display the file contents. The writetimetable function outputs a text file named TT.txt.

writetimetable(TT)
type 'TT.txt'

RowTimes,Reading1,Reading2
1 sec,98,120
2 sec,97.5,111
3 sec,97.9,119
4 sec,98.1,117
5 sec,97.9,116

To write the same timetable to a text file with a different delimiter character, use the 'Delimiter' name-value pair.

writetimetable(TT,'TT_bar.txt','Delimiter','bar')
type 'TT_bar.txt'

RowTimes|Reading1|Reading2
1 sec|98|120
2 sec|97.5|111
3 sec|97.9|119
4 sec|98.1|117
5 sec|97.9|116

Write Timetable to Spreadsheet File

Create a timetable, write it to a spreadsheet file, and then display the contents of the file.

Define a timetable in the workspace with row times as a datetime vector.

Y = [2014:2018]'; M = ones(5,1); D = ones(5,1);
RowTimes = datetime(Y,M,D); % Create Row Times
TT = timetable(RowTimes,[98;97.5;97.9;98.1;97.9],[120;111;119;117;116],...
               'VariableNames',{'Reading1','Reading2'})

TT=5×2 timetable
     RowTimes      Reading1    Reading2
    ___________    ________    ________

    01-Jan-2014        98        120   
    01-Jan-2015      97.5        111   
    01-Jan-2016      97.9        119   
    01-Jan-2017      98.1        117   
    01-Jan-2018      97.9        116   

Write the table to spreadsheet file 'TT.xlsx'. By default, the writetimetable function writes the first worksheet in the file. Use the 'Sheet' name-value pair to specify the worksheet to write to.

writetimetable(TT,'TT.xlsx','Sheet',2)

Read and display the file contents.

readtimetable('TT.xlsx','Sheet',2) 

ans=5×2 timetable
          RowTimes          Reading1    Reading2
    ____________________    ________    ________

    01-Jan-2014 00:00:00        98        120   
    01-Jan-2015 00:00:00      97.5        111   
    01-Jan-2016 00:00:00      97.9        119   
    01-Jan-2017 00:00:00      98.1        117   
    01-Jan-2018 00:00:00      97.9        116   

Input Arguments

TT — Input timetable

timetable

Input timetable.

filename — File name

character vector | string scalar

File name, specified as a character vector or string scalar.

Depending on the location you are writing to, filename can take on one of these forms.

Location	Form
Current folder	To write to the current folder, specify the name of the file in filename. Example: 'myTextFile.csv'
Other folders	To write to a folder different from the current folder, specify the full or relative path name in filename. Example: 'C:\myFolder\myTextFile.csv' Example: 'myFolder\myExcelFile.xlsx'
Remote Location	To write to a remote location, filename must contain the full path of the file specified as a uniform resource locator (URL) of the form: scheme_name://path_to_file/my_file.ext Based on the remote location, scheme_name can be one of the values in this table. Remote Location scheme_name Amazon S3™ s3 Windows Azure® Blob Storage wasb, wasbs HDFS™ hdfs For more information, see Work with Remote Data. Example: 's3://bucketname/path_to_file/my_file.xlsx'

• If filename includes the file extension, then the writing function determines the file format from the extension. Otherwise, the writing function creates a comma separated text file and appends the extension .txt. Alternatively, you can specify filename without the file’s extension, and then include the 'FileType' name-value pair arguments to indicate the type of file.

• If filename does not exist, then the writing function creates the file.

• If filename is the name of an existing text file, then the writing function overwrites the file.

• If filename is the name of an existing spreadsheet file, then the writing function writes the data to the specified location, but does not overwrite any values outside the range of the input data.

Data Types: char | string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'WriteVariableNames',false indicates that the variable names should not be included as the first row of the output file.

Text and Spreadsheet Files

FileType — Type of file

'text' | 'spreadsheet'

Type of file, specified as the comma-separated pair consisting of 'FileType' and a character vector or string containing 'text' or 'spreadsheet'.

The 'FileType' name-value pair must be used with the filename input argument. You do not need to specify the 'FileType' name-value pair argument if the filename input argument includes a standard file extension. The following standard file extensions are recognized by the writing function:

• .txt, .dat, or .csv for delimited text files

• .xls, .xlsm, or .xlsx for Excel spreadsheet files

• .xlsb for Excel spreadsheet files supported on systems with Excel for Windows

Example: 'FileType','spreadsheet'

Data Types: char | string

WriteVariableNames — Indicator for writing variable names as column headings

true (default) | false

Indicator for writing variable names as column headings, specified as the comma-separated pair consisting of 'WriteVariableNames' and either true or false.

Indicator	Behavior
true	The writing function includes variable names as the column headings of the output. This is the default behavior.
false	The writing function does not include variable names in the output.

DateLocale — Locale for writing dates

character vector | string scalar

Locale for writing dates, specified as the comma-separated pair consisting of 'DateLocale' and a character vector or a string scalar. When writing datetime values to the file, use DateLocale to specify the locale in which writetimetable should write month and day-of-week names and abbreviations. The character vector or string takes the form xx_YY, where xx is a lowercase ISO 639-1 two-letter code indicating a language, and YY is an uppercase ISO 3166-1 alpha-2 code indicating a country. For a list of common values for the locale, see the Locale name-value pair argument for the datetime function.

The writing function ignores the 'DateLocale' parameter value whenever dates can be written as Excel-formatted dates.

Example: 'DateLocale','ja_JP'

Data Types: char | string

WriteMode — Writing mode

character vector | string scalar

Writing mode, specified as the comma-separated pair consisting of 'WriteMode' and a character vector or a string scalar. Select a write mode based on the file type.

File Type	Write Mode
Text Files	'overwrite' (default) — Overwrite the file. 'append' — Append data to the file. If the file you specified does not exist, then the writing function creates and writes data to a new file.
Spreadsheet Files	'inplace' (default) — Update only the range occupied by the input data. The writing function does not alter any data outside of the range occupied by the input data. If you do not specify a sheet, then the writing function writes to the first sheet. 'overwritesheet' — Clear the specified sheet and write the input data to the cleared sheet. If you do not specify a sheet, then the writing function clears the first sheet and writes the input data to it. 'append' — The writing function appends the input data to the bottom of the occupied range of the specified sheet. If you do not specify a sheet, then the writing function appends the input data to the bottom of the occupied range of the first sheet. 'replacefile' — Remove all other sheets from the file, then clear and write the input data to the to the specified sheet. If you do not specify a sheet, then the writing function removes all other sheets from the file, and then clears and writes the input data to the first sheet. If the file you specified does not exist, then the writing function creates a new file and writes the input data to the first sheet.

• When WriteVariableNames is set to true, the writing function does not support the write mode 'append'.

• For spreadsheet files:

  • When the write mode is 'append', the writing function does not support the Range parameter.

  • If the file you specified does not exist, then the writing function performs the same actions as 'replacefile'.

Example: 'WriteMode','append'

Data Types: char | string

Text Files Only

Delimiter — Field delimiter character

character vector | string scalar

Field delimiter character, specified as the comma-separated pair consisting of 'Delimiter' and a character vector or string scalar containing one of these specifiers:

Specifier	Field Delimiter
',' 'comma'	Comma. This is the default behavior.
' ' 'space'	Space
'\t' 'tab'	Tab
';' 'semi'	Semicolon
'|' 'bar'	Vertical bar

You can use the 'Delimiter' name-value pair only for delimited text files.

Example: 'Delimiter','space'

Data Types: char | string

QuoteStrings — Indicator for writing quoted text

"minimal" (default) | "all" | "none"

Indicator for writing quoted text, specified as "minimal", "all", or "none".

• If QuoteStrings is "minimal", then the function encloses any variables containing the delimiter, line ending, or double-quote character in double-quote characters.

• If QuoteStrings is "all", then the function encloses all text, categorical, datetime, and duration variables in double-quote characters.

• If QuoteStrings is "none", then the function does not enclose variables in double-quote characters.

You can use the QuoteStrings name-value argument only with delimited text files.

Encoding — Character encoding scheme

'UTF-8' (default) | 'ISO-8859-1' | 'windows-1251' | 'windows-1252' | ...

Character encoding scheme associated with the file, specified as the comma-separated pair consisting of 'Encoding' and 'system' or a standard character encoding scheme name. When you do not specify any encoding, the writing function uses UTF-8 to write the file.

Example: 'Encoding','UTF-8' uses UTF-8 as the encoding.

Data Types: char | string

Spreadsheet Files Only

Sheet — Worksheet to write to

character vector | string scalar | positive integer

Worksheet to write to, specified as the comma-separated pair consisting of 'Sheet' and a character vector or a string scalar containing the worksheet name or a positive integer indicating the worksheet index. The worksheet name cannot contain a colon (:). To determine the names of sheets in a spreadsheet file, use sheets = sheetnames(filename). For more information, see sheetnames.

Specify the worksheet to write to by name or index:

• name — If the specified sheet name does not exist in the file, then the writing function adds a new sheet at the end of the worksheet collection.

• index — If the specified sheet index is an index larger than the number of worksheets, then the writing function appends empty sheets until the number of worksheets in the workbook equals the sheet index. The writing function also generates a warning indicating that it has added a new worksheet.

You can use the 'Sheet' name-value pair only with spreadsheet files.

Example: 'Sheet',2

Example: 'Sheet', 'MySheetName'

Data Types: char | string | single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Range — Rectangular portion of worksheet to write to

character vector | string scalar

Rectangular portion of worksheet to write to, specified as the comma-separated pair consisting of 'Range' and a character vector or string scalar in one of the following forms.

Form of the Value of Range	Description
'Corner1'	Corner1 specifies the first cell of the region to write. The writing function writes the data starting at this cell. Example: 'Range','D2'
'Corner1:Corner2'	Corner1 and Corner2 are two opposing corners that define the region to write. For example, 'D2:H4' represents the 3-by-5 rectangular region between the two corners D2 and H4 on the worksheet. The 'Range' name-value pair argument is not case sensitive, and uses Excel A1 reference style (see Excel help). Example: 'Range','D2:H4' If the range you specify is smaller than the size of the input data, then the writing function writes only a subset of the input data that fits into the range. If the range you specify is larger than the size of the input data, then the writing function leaves the remainder of the region as it is.

The 'Range' name-value pair can only be used with Excel files.

Example: 'Range', 'A1:F10'

Data Types: char | string

UseExcel — Flag to start instance of Microsoft^® Excel for Windows

false (default) | true

Flag to start an instance of Microsoft Excel for Windows when writing spreadsheet data, specified as the comma-separated pair consisting of 'UseExcel' and either true, or false.

You can set the 'UseExcel' parameter to one of these values:

• true — The writing function starts an instance of Microsoft Excel when writing the file.

• false — The writing function does not start an instance of Microsoft Excel when writing the file. When operating in this mode, functionality for writing differs in the support of file formats and interactive features, such as formulas and macros.

UseExcel	true	false
Supported file formats	.xls, .xlsx, .xlsm, .xltx, .xltm, .xlsb, .ods	.xls, .xlsx, .xlsm, .xltx, .xltm
Support for interactive features, such as formulas and macros	Yes	No

When writing to spreadsheet files on Windows platforms, if you want to start an instance of Microsoft Excel, then set the 'UseExcel' parameter to true.

UseExcel is not supported in noninteractive, automated environments.

AutoFitWidth — Automatically adjust column width

true (default) | false

Automatically adjust column width, specified as true or false. If you specify a value of 0 or false, then writetimetable will not automatically adjust the column widths to fit the data in the cells.

Example: 'AutoFitWidth',0

PreserveFormat — Preserve cell formatting

true (default) | false

Preserve cell formatting of existing spreadsheet, specified as true or false. If you specify false, writetimetable will not preserve the cell formatting of the spreadsheet. Formatting includes elements such as fonts, cell borders, and color-shaded cells.

When writing datetime data to a spreadsheet file, you must set both 'PreserveFormat' and the 'UseExcel' Name-Value pair to true to preserve the existing cell formatting. If 'UseExcel' is set to false and 'PreserveFormat' is set to true when writing datetime data to the file, writetimetable will not preserve the existing cell formatting of the file.

Example: 'PreserveFormat',false

XML Files Only

AttributeSuffix — Attribute suffix

'Attribute' (default) | character vector | string scalar

Attribute suffix, specified as the comma-separated pair consisting of 'AttributeSuffix' and either a character vector or string scalar indicating which variable names in the input table to write as attributes in the output XML file.

For example, for a variable name AttName_att in the input table, you can specify 'AttributeSuffix','_att' to indicate that 'AttName' should be written out as an attribute in the output XML file.

• If you do not specify 'AttributeSuffix', writetimetable defaults to writing variables with the suffix 'Attribute' as attributes in the output XML file.

• If the attribute specified as the value of 'AttributeSuffix' matches the suffix appended to the variable name in the input table, the suffix will be dropped from the variable name in the output XML file. For example, if you specify 'AttributeSuffix','_att', a variable in the input table named MyField_att will correspond to the attribute named MyField in the XML file.

Example: 'AttributeSuffix','_att'

RowNodeName — XML row node name

'row' | string array

XML row node name, specified as the comma-separated pair consisting of 'RowNodeName' and either a character vector or string scalar the writing function writes as the node name in the output XML file that corresponds to the rows in the input table. If you do not specify RowNodeName, then the writing function writes 'row' as the name of the row nodes in the output table.

Example: 'TableNodeName','RootName'

TableNodeName — XML root node name

'table' (default) | character vector | string array

XML root node name, specified as the comma-separated pair consisting of 'TableNodeName' and either a character vector or string scalar the writing function writes as the root node name in the output XML file. If you do not specify TableNodeName, then the writing function writes 'table' as the name of the root node in the output table.

Example: 'TableNodeName','RootName'

Algorithms

• There are some instances where the writetimetable function creates a file that does not represent the input data exactly. You will notice this when you use the readtimetable function to read that file. The resulting data might not have the exact same format or contents as the original data. If you need to save your timetable and retrieve it at a later time to exactly match the original timetable, with the same data and organization, then save it as a MAT-file. writetimetable writes an inexact table in the following instances:

  • writetimetable writes out numeric data using long g format, and categorical or character data as unquoted text.

  • writetimetable writes out variables that have more than two dimensions as two dimensional variables, with the trailing dimensions collapsed.

  • For cell-valued variables, writetimetable writes out the variables differently based on the data type of the content in the cells.

    • If the content of the cell is of the data type numeric, text, logical, categorical, datetime, or duration, then the writetimetable function writes out the contents of each cell as a single row, in multiple, delimiter-separated fields.

    • Otherwise, the writetimetable function writes out a single empty field.

• Excel converts Inf values to 65535. MATLAB^® converts NaN, NaT, <undefined> categorical values, and <missing> string values to empty cells.

Version History

Introduced in R2019a