Documentation

writetable

Write table to file

Syntax

  • writetable(T)
    example
  • writetable(T,filename)
  • writetable(___,Name,Value)
    example

Description

example

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

Each column of each variable in T becomes a column in the output file. The variable names of T become column headings in the first line of the file.

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

writetable 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, .xlsb, .xlsm, or .xlsx for Excel® spreadsheet files

example

writetable(___,Name,Value) writes the table to a file with 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

collapse all

Write Table to Text File

Create a table.

T = table(['M';'F';'M'],[45 45;41 32;40 34],...
    {'NY';'CA';'MA'},[true;false;false])
T = 

    Var1      Var2      Var3    Var4 
    ____    ________    ____    _____

    M       45    45    'NY'    true 
    F       41    32    'CA'    false
    M       40    34    'MA'    false

Write the table to a comma delimited text file and display the file contents.

writetable(T)

writetable outputs a text file named T.txt.

type 'T.txt'
Var1,Var2_1,Var2_2,Var3,Var4
M,45,45,NY,1
F,41,32,CA,0
M,40,34,MA,0

writetable appends a unique suffix to the variable name, Var2, above the two columns of corresponding data.

Write Table to Space-Delimited Text File

Create a table.

T = table(['M';'F';'M'],[45 45;41 32;40 34],...
    {'NY';'CA';'MA'},[true;false;false])
T = 

    Var1      Var2      Var3    Var4 
    ____    ________    ____    _____

    M       45    45    'NY'    true 
    F       41    32    'CA'    false
    M       40    34    'MA'    false

Write the table to a space-delimited text file named myData.txt and display the file contents.

writetable(T,'myData.txt','Delimiter',' ')
type 'myData.txt'
Var1 Var2_1 Var2_2 Var3 Var4
M 45 45 NY 1
F 41 32 CA 0
M 40 34 MA 0

writetable appends a unique suffix to the variable name, Var2, above the two columns of corresponding data.

Write Table to Text File Including Row Names

Create a table.

LastName = {'Smith';'Johnson';'Williams';'Jones';'Brown'};
Age = [38;43;38;40;49];
Height = [71;69;64;67;64];
Weight = [176;163;131;133;119];
BloodPressure = [124 93; 109 77; 125 83; 117 75; 122 80];

T = table(Age,Height,Weight,BloodPressure,...
    'RowNames',LastName)
T = 

                Age    Height    Weight    BloodPressure
                ___    ______    ______    _____________

    Smith       38     71        176       124     93   
    Johnson     43     69        163       109     77   
    Williams    38     64        131       125     83   
    Jones       40     67        133       117     75   
    Brown       49     64        119       122     80   

Write the table, T, to a comma delimited text file, called myPatientData.dat, and display the file contents.

writetable(T,'myPatientData.dat','WriteRowNames',true)
type 'myPatientData.dat'
Row,Age,Height,Weight,BloodPressure_1,BloodPressure_2
Smith,38,71,176,124,93
Johnson,43,69,163,109,77
Williams,38,64,131,125,83
Jones,40,67,133,117,75
Brown,49,64,119,122,80

The first column, which contains the row names, has the column heading, Row. This is the first dimension name for the table from the property T.Properties.DimensionNames.

Write Foreign-Language Dates to Text File

Convert English dates in a table to German and write the table to file.

Create a table that contains a datetime array with dates in English. Create column vectors of numeric data to go with the dates.

D = datetime({'01-Jan-2014';'01-Feb-2014';'01-Mar-2014'});
D.Format = 'dd MMMM yyyy';
X1 = [20.2;21.6;20.7];
X2 = [100.5;102.7;99.8];
T = table(D,X1,X2)
T = 

           D             X1      X2  
    ________________    ____    _____

    01 January 2014     20.2    100.5
    01 February 2014    21.6    102.7
    01 March 2014       20.7     99.8

Write the table to a text file. Specify German for the locale of the dates using the DateLocale name-value pair argument, and display the dates in the text file.

writetable(T,'myfile.txt','DateLocale','de_DE');
type myfile.txt
D,X1,X2
01 Januar 2014,20.2,100.5
01 Februar 2014,21.6,102.7
01 März 2014,20.7,99.8

Write Quoted Strings to CSV File

Create a table.

T = table(['M';'F';'M'],[45;41;36],...
    {'New York, NY';'San Diego, CA';'Boston, MA'},[true;false;false])
T = 

    Var1    Var2         Var3          Var4 
    ____    ____    _______________    _____

    M       45      'New York, NY'     true 
    F       41      'San Diego, CA'    false
    M       36      'Boston, MA'       false

Write the table to a comma-separated text file named myData.csv and view the file contents. Enclose strings in double quotation marks using the 'QuoteStrings' name-value pair argument, to ensure that the commas in the third column are not treated as delimiters.

writetable(T,'myData.csv','Delimiter',',','QuoteStrings',true)
type 'myData.csv'
Var1,Var2,Var3,Var4
"M",45,"New York, NY",1
"F",41,"San Diego, CA",0
"M",36,"Boston, MA",0

Write Table to Specific Sheet and Range in Spreadsheet

Create a table.

T = table(['M';'F';'M'],[45 45;41 32;40 34],...
    {'NY';'CA';'MA'},[true;false;false])
T = 

    Var1         Var2         Var3    Var4 
    ____    ______________    ____    _____

    M       45          45    'NY'    true 
    F       41          32    'CA'    false
    M       40          34    'MA'    false

Write the table to a spreadsheet named myData.xls. Include the data on the second sheet in the 5-by-5 region with corners at B2 and F6.

writetable(T,'myData.xls','Sheet',2,'Range','B2:F6')

Excel fills the row of the spreadsheet from B6 to F6 with #N/A since the range specified is larger than the size of the input table T.

Input Arguments

collapse all

T — Input datatable

Input data, specified as a table.

filename — File namestring

File name, specified as a string. To write to a specific folder, specify the full path name. Otherwise, writetable writes to a file in the current folder. If filename includes the file extension, then writetable determines the file format from the extension. Otherwise, writetable 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 writetable creates the file.

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

  • If filename is the name of an existing spreadsheet file, then writetable writes a table to the specified location, but does not overwrite any values outside that range.

Example: 'myData.xls'

Example: 'C:\test\myData.txt'

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

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 the string '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 writetable can determine the file type from an extension in the filename input argument. writetable can determine the file type from these extensions:

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

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

Example: writetable(T,'mySpreadsheet','FileType','spreadsheet')

'WriteVariableNames' — Indicator for writing variable names as column headingstrue (default) | false | 1 | 0

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

Indicator

Behavior

true

writetable includes variable names as the column headings of the output. This is the default behavior.

If both the 'WriteVariablesNames' and 'WriteRowNames' logical indicators are true, then writetable uses the first dimension name from the property T.Properties.DimensionNames as the column heading for the first column of the output.

false

writetable does not include variable names in the output.

'WriteRowNames' — Indicator for writing row names in first columnfalse (default) | true | 0 | 1

Indicator for writing row names in first column, specified as the comma-separated pair consisting of 'WriteRowNames' and either false, true, 0, or 1.

Indicator

Behavior

false

writetable does not include the row names from T in the output. This is the default behavior.

true

writetable includes the row names from T as the first column of the output.

If both the 'WriteVariablesNames' and 'WriteRowNames' logical indicators are true, then writetable uses the first dimension name from the property T.Properties.DimensionNames as the column heading for the first column of the output.

'Delimiter' — Field delimiter characterstring

Field delimiter character, specified as the comma-separated pair consisting of 'Delimiter' and one of the following strings:

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'

'QuoteStrings' — Indicator for writing quoted stringsfalse (default) | true | 0 | 1

Indicator for writing quoted strings, specified as the comma-separated pair consisting of 'QuoteStrings' and either false, true, 0, or 1. If 'QuoteStrings' is true, then writetable encloses strings in double quotation marks, and replaces any double-quote characters that appear as part of a string with two double-quote characters. For an example, see Write Quoted Strings to CSV File.

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

'DateLocale' — Locale for writing datesstring

Locale for writing dates, specified as the comma-separated pair consisting of 'DateLocale' and a string. The 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.

When writing datetime values to the file, use DateLocale to specify the locale in which writetable should write month and day-of-week names and abbreviations.

Example: 'DateLocale','ja_JP'

'Sheet' — Worksheet to write tostring containing worksheet name | positive integer indicating worksheet index

Worksheet to write to, specified as the comma-separated pair consisting of 'Sheet' and a string containing the worksheet name or a positive integer indicating the worksheet index. The worksheet name string cannot contain a colon (:). To determine the names of sheets in a spreadsheet file, use [status,sheets] = xlsfinfo(filename).

If the sheet does not exist, then writetable adds a new sheet at the end of the worksheet collection. If the sheet is an index larger than the number of worksheets, then writetable appends empty sheets until the number of worksheets in the workbook equals the sheet index. In either case, writetable 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

'Range' — Rectangular portion of worksheet to write tostring

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

Form of the Value of RangeDescription
'Corner1'

Corner1 specifies the first cell of the region to write. writetable writes table T beginning 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).

If the range you specify is larger than the size of the input table T, Excel software fills the remainder of the region with #N/A. If the range specified is smaller than the size of the input table T, then writetable writes only the subset that fits into the range.

Example: 'Range','D2:H4'

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

Limitations

  • On Linux® systems, writetable writes only to text files and does not write to spreadsheet files.

More About

expand all

Tips

  • In the cases below, writetable creates a file that does not represent T exactly. Then, if you use readtable to read that file and create a new table, the result might not have the same format or contents as the original table. Save T as a MAT-file if you need to import it again as a table with the same data and organization.

    • writetable outputs numeric variables using long g format, and categorical or character variables as unquoted strings in text files.

    • For variables that have more than one column, writetable appends a unique identifier to the variable name to use as the column headings.

    • For output variables that have more than two dimensions, writetable outputs these variables as two dimensional where the trailing dimensions are collapsed. For example, writetable outputs a 4-by-3-by-2 variable as if its size were 4-by-6.

    • For variables with a cell data type, writetable outputs the contents of each cell as a single row, in multiple fields. If the contents are other than numeric, logical, character, or categorical, then writetable outputs a single empty field.

Algorithms

Excel converts Inf values to 65535. MATLAB® converts NaN values to empty cells.

See Also

|

Introduced in R2013b

Was this topic helpful?