writetimetable
Write timetable to file
Description
writetimetable(
writes the timetable
TT
)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(
writes to a file with the name and extension specified by
TT
,filename
)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(___,
uses additional options specified by one or more Name,Value
)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 Example: | ||||||||
Other folders | To write to a folder different from the current folder, specify the full or relative path name in Example: Example: | ||||||||
Remote Location | To write to a remote location,
Based on the remote location,
For more information, see Work with Remote Data. Example:
|
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 specifyfilename
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.
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 |
---|---|
| The writing function includes variable names as the column headings of the output. This is the default behavior. |
| 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
,
where xx
_YY
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 |
If the file you specified does not exist, then the writing function creates and writes data to a new file. |
Spreadsheet Files |
|
When
WriteVariableNames
is set totrue
, 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 theRange
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
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. This is the default behavior. |
| Space |
| Tab |
| Semicolon |
| 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
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 |
---|---|
' |
Example: |
' |
Example:
|
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 |
|
|
---|---|---|
Supported file formats |
|
|
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
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 namedMyField_att
will correspond to the attribute namedMyField
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 thereadtimetable
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 usinglong 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 to65535
. MATLAB® convertsNaN
,NaT
,<undefined>
categorical values, and<missing>
string values to empty cells.
Version History
Introduced in R2019a
See Also
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)