Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

writetable

Write table to file

collapse all in page

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

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

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

Open Script

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.

Open Script

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.

Open Script

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.

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
Open Script

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. Use 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
Open Script

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

Input data, specified as a table.

File name, specified as a character vector. 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.

collapse all

Type of file, specified as the comma-separated pair consisting of 'FileType' and a character vector 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 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, .xlsm, or .xlsx for Excel spreadsheet files

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

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

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 'WriteVariableNames' 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.

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 'WriteVariableNames' 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.

Field delimiter character, specified as the comma-separated pair consisting of 'Delimiter' and one of the following 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'

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

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

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

writetable ignores the 'DateLocale' parameter value whenever dates can be written as Excel-formatted dates. See Algorithms for more information.

Example: 'DateLocale','ja_JP'

Worksheet to write to, specified as the comma-separated pair consisting of 'Sheet' and a character vector 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 [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

Rectangular portion of worksheet to write to, specified as the comma-separated pair consisting of 'Range' and a character vector 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).

Example: 'Range','D2:H4'

  • If the range you specify is smaller than the size of the input table T, then writetable writes only a subset of the input table that fits into the range.

  • If the range you specify is larger than the size of the input table T, then writetable leaves the remainder of the region as it is.

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

More About

collapse all

Tips

  • In the cases below, writetable creates a file that does not represent T exactly. You will notice this when 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. If you need to import T again as a table with the same data and organization, save it as a MAT-file.

    • When writing to text files, writetable outputs numeric variables using long g format, and categorical or character variables as unquoted characters.

    • 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, NaT, <undefined> categorical values, and <missing> string values to empty cells.

For Excel files, writetable writes table variables containing datetime arrays as Excel dates. If the table contains datetime arrays with years prior to either 1900 or 1904, then writetable writes the variables as text. For more information on Excel dates, see https://support.microsoft.com/en-us/kb/214330.

See Also

|

Introduced in R2013b

Was this topic helpful?
MATLAB Documentation
Other Documentation
Support
Tackling Big Data with MATLAB

Tackling Big Data with MATLAB

Watch now