export

(Not Recommended) Write dataset array to file

The dataset data type is not recommended. To work with heterogeneous data, use the MATLAB® table data type instead. See MATLAB table documentation for more information.

Syntax

export(DS,'file',filename)
export(DS)
export(DS,'file',filename,'Delimiter',delim)
export(DS,'XLSfile',filename)
export(DS,'XPTFile',filename)
export(DS,...,'WriteVarNames',false)
export(DS,...,'WriteObsNames',false)

Description

export(DS,'file',filename) writes the dataset array DS to a tab-delimited text file, including variable names and observation names, if present. If the observation names exist, the name in the first column of the first line of the file is the first dimension name for the dataset (by default, 'Observations'). export overwrites any existing file named filename.

export(DS) writes to a text file whose default name is the name of the dataset array DS appended by '.txt'. If export cannot construct the file name from the dataset array input, it writes to the file 'dataset.txt'. export overwrites any existing file.

export(DS,'file',filename,'Delimiter',delim) writes the dataset array DS to a text file using the delimiter delim. delim must be one of the following:

  • ' ' or 'space'

  • '\t' or 'tab'

  • ',' or 'comma'

  • ';' or 'semi'

  • '|' or 'bar'

export(DS,'XLSfile',filename) writes the dataset array DS to a Microsoft® Excel® spreadsheet file, including variable names and observation names (if present). You can specify the 'Sheet' and 'Range' parameter name/value pairs, with parameter values as accepted by the xlsread function. Since export uses the xlswrite function internally, this syntax is only compatible with Microsoft Excel for Windows®, and does not work on a Mac. For more information, see xlswrite.

export(DS,'XPTFile',filename) writes the dataset array DS to a SAS XPORT format file. When writing to an XPORT format file, variables must be scalar valued. export saves observation names to a variable called obsnames, unless the WriteObsNames parameter described below is false. The XPORT format restricts the length of variable names to eight characters; longer variable names are truncated.

export(DS,...,'WriteVarNames',false) does not write the variable names to the text file. export(DS,...,'WriteVarNames',true) is the default, writing the names as column headings in the first line of the file.

export(DS,...,'WriteObsNames',false) does not write the observation names to the text file. export(DS,...,'WriteObsNames',true) is the default, writing the names as the first column of the file.

In some cases, export creates a text file that does not represent A exactly, as described below. If you use dataset to read the file back into MATLAB, the new dataset array may not have exactly the same contents as the original dataset array. Save A as a MAT file if you need to import it again as a dataset array.

export writes out numeric variables using long g format, and categorical or character variables as unquoted text.

For non-character variables with more than one column, export writes out multiple delimiter-separated fields on each line, and constructs suitable column headings for the first line of the file.

export writes out variables that have more than two dimensions as a single empty field in each line of the file.

For cell-valued variables, export writes out the contents of each cell only when the cell contains a single row, and writes out a single empty field otherwise.

In some cases, export creates a file that cannot be read back into MATLAB using dataset. Writing a dataset array that contains a cell-valued variable whose cell contents are not scalars results in a mismatch in the file between the number of fields on each line and the number of column headings on the first line. Writing a dataset array that contains a cell-valued variable whose cell contents are not all the same length results in a different number of fields on each line in the file. Therefore, if you might need to import a dataset array again, save it as a .mat file.

Examples

Move data between external text files and dataset arrays in the MATLAB workspace:

A = dataset('file','sat2.dat','delimiter',',')
A = 
    Test                  Gender          Score
    'Verbal'              'Male'          470  
    'Verbal'              'Female'        530  
    'Quantitative'        'Male'          520  
    'Quantitative'        'Female'        480  

export(A(A.Score > 500,:),'file','HighScores.txt')

B = dataset('file','HighScores.txt','delimiter','\t')
B = 
    Test                  Gender          Score
    'Verbal'              'Female'        530  
    'Quantitative'        'Male'          520

See Also