This is machine translation

Translated by

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.

DelimitedTextImportOptions

Import options object for delimited text

expand all in page

Description

A DelimitedTextImportOptions object enables you to specify how MATLAB^® imports tabular data from text files. The object contains properties that control the data import process, including the handling of errors and missing data. Use a DelimitedTextImportOptions object to query the current (detected) values of import properties or to assign new values based on your import needs.

Create Object

Create a DelimitedTextImportOptions object using the detectImportOptions function.

Properties

expand all

Variable Properties

`VariableNames` — Variable names
cell array of character vectors

Variable names, specified as a cell array of character vectors. The VariableNames property contains the names to use when importing variables.

If the data contains N variables, but no variable names are detected, then the VariableNames property contains {'Var1','Var2',...,'VarN'}.

Example: opts.VariableNames returns the current (detected) variable names.

Example: opts.VariableNames(3) = {'Height'} changes the name of the third variable to Height.

Data Types: char | cell

`VariableTypes` — Variable data types
cell array of character vectors

Variable data types, specified as a cell array of character vectors. The VariableTypes property designates the data types to use when importing variables. When assigning new values, specify VariableTypes as a cell array of valid data type names.

To update the VariableTypes property, use the setvartype function.

Example: opts.VariableTypes returns the current (detected) variable data types.

Example: opts = setvartype(opts,'Height',{'double'}) changes the data type of the variable Height to double.

`SelectedVariableNames` — Subset of variables to import
character vector | cell array of character vectors | array of numeric indices

Subset of variables to import, specified as a character vector, a cell array of character vectors, or an array of numeric indices.

SelectedVariableNames must be a subset of names contained in the VariableNames property. By default, SelectedVariableNames contains all the variable names from the VariableNames property, which means that all variables are imported.

Use the SelectedVariableNames property to import only the variables of interest. Specify a subset of variables using the SelectedVariableNames property and use readtable to import only that subset.

Example: opts.SelectedVariableNames = {'Height','LastName'} selects only two variables, Height and LastName, for the import operation.

Example: opts.SelectedVariableNames = [1 5] selects only two variables, the first variable and the fifth variable, for the import operation.

Example: T = readtable(filename,opts) returns a table containing only the variables specified in the SelectedVariableNames property of the opts object.

`VariableOptions` — Type specific variable import options
array of variable import options objects

Type specific variable import options, returned as an array of variable import options objects. The array contains an object corresponding to each variable specified in the VariableNames property. Each object in the array contains properties that support the importing of data with a specific data type.

Variable options support these data types: numeric, text, logical, datetime, or categorical.

To query the current (or detected) options for a variable, use the getvaropts function.

To set and customize options for a variable, use the setvaropts function.

Example: opts.VariableOptions returns a collection of VariableImportOptions objects, one corresponding to each variable in the data.

Example: getvaropts(opts,'Height') returns the VariableImportOptions object for the Height variable.

Example: opts = setvaropts(opts,'Height','FillValue',0) sets the FillValue property for the variable Height to 0.

Location Properties

`DataLine` — Data start location
positive scalar integer

Data start location, specified as a positive scalar integer. The DataLine property specifies the line number where data begins in the text file.

The value for the DataLine property must be greater than 0.

Example: opts.DataLine = 5;

`RowNamesColumn` — Row names location
`0` (default) | positive scalar integer

Row names location, specified as a positive scalar integer. The RowNamesColumn property specifies the location of the column containing the row names.

If RowNamesColumn is specified as 0, then do not import the row names. Otherwise, import the row names from the specified column.

Example: opts.RowNamesColumn = 2;

`VariableNamesLine` — Variable names location
`0` (default) | positive scalar integer

Variable names location, specified as a positive scalar integer. The VariableNamesLine property specifies the line number where variable names are located.

If VariableNamesLine is specified as 0, then do not import the variable names. Otherwise, import the variable names from the specified line.

Example: opts.VariableNamesLine = 6;

`VariableDescriptionsLine` — Variable description location
`0` (default) | positive scalar integer

Variable description location, specified as a positive scalar integer. The VariableDescriptionsLine property specifies the line number where variable descriptions are located.

If VariableDescriptionsLine is specified as 0, then do not import the variable descriptions. Otherwise, import the variable descriptions from the specified line.

Example: opts.VariableDescriptionsLine = 7;

`VariableUnitsLine` — Variable units location
`0` (default) | positive scalar integer

Variable units location, specified as a positive scalar integer. The VariableUnitsLine property specifies the line number where variable units are located.

If VariableUnitsLine is specified as 0, then do not import the variable units. Otherwise, import the variable units from the specified line.

Example: opts.VariableUnitsLine = 8;

Delimited Text Properties

`Delimiter` — Field delimiter characters
character vector | cell array of character vectors

Field delimiter characters, specified as a character vector or a cell array of character vectors.

Example: '|'

Example: {';','*'}

Data Types: char | cell

`Whitespace` — Characters to treat as white space
character vector

Characters to treat as white space, specified as a character vector of one or more characters.

Example: ' _'

Example: '?!.,'

`LineEnding` — End-of-line characters
`{'\n','\r','\r\n'}` (default) | character vector | cell array of character vectors

End-of-line characters, specified as a character vector of one or more characters or a cell array of character vectors.

Example: '\n'

Example: '\r\n'

Example: {'\b',':'}

Data Types: char | cell

`CommentStyle` — Style of comments
character vector | cell array of character vectors

Style of comments, specified as a character vector or cell array of character vectors.

For example, specify CommentStyle as '%' to ignore the text following a percent sign on the same line.

Example: {'/*'}

Data Types: char | cell

`ConsecutiveDelimitersRule` — Procedure to handle consecutive delimiters
`'split'` | `'join'` | `'error'`

Procedure to handle consecutive delimiters, specified as one of the values in this table.

Consecutive Delimiters Rule	Behavior
`'split'`	Split the consecutive delimiters into multiple fields.
`'join'`	Join the delimiters into one delimiter.
`'error'`	Error and abort the import operation.

Example: 'join'

`LeadingDelimitersRule` — Procedure to manage leading delimiters
`'keep'` | `'ignore'` | `'error'`

Procedure to manage leading delimiters, specified as one of the values in this table.

Rule	Behavior
`'keep'`	Keep the delimiter.
`'ignore'`	Ignore the delimiter.
`'error'`	Error and abort the import operation.

Example: 'ignore'

`Encoding` — File encoding
`'system'` (default) | `'UTF-8'` | `'ISO-8859-1'` | `'windows-1251'` | `'windows-1252'` | ...

File encoding, specified as 'system' or a standard character encoding scheme name like one of the values in this table.

`'Big5'`	`'ISO-8859-1'`	`'windows-847'`
`'Big5-HKSCS'`	`'ISO-8859-2'`	`'windows-949'`
`'CP949'`	`'ISO-8859-3'`	`'windows-1250'`
`'EUC-KR'`	`'ISO-8859-4'`	`'windows-1251'`
`'EUC-JP'`	`'ISO-8859-5'`	`'windows-1252'`
`'EUC-TW'`	`'ISO-8859-6'`	`'windows-1253'`
`'GB18030'`	`'ISO-8859-7'`	`'windows-1254'`
`'GB2312'`	`'ISO-8859-8'`	`'windows-1255'`
`'GBK'`	`'ISO-8859-9'`	`'windows-1256'`
`'IBM866'`	`'ISO-8859-11'`	`'windows-1257'`
`'KOI8-R'`	`'ISO-8859-13'`	`'windows-1258'`
`'KOI8-U'`	`'ISO-8859-15'`	`'US-ASCII'`
	`'Macintosh'`	`'UTF-8'`
	`'Shift_JIS'`

Example: 'system' uses the system default encoding.

Replacement Rules

`MissingRule` — Procedure to manage missing data
`'fill'` | `'error'` | `'omitrow'` | `'omitvar'`

Procedure to manage missing data, specified as one of the values in this table.

Missing Rule	Behavior
`'fill'`	Replace missing data with the contents of the `FillValue` property. The `FillValue` property is specified in the `VariableImportOptions` object of the variable being imported. For more information on accessing the `FillValue` property, see `getvaropts`.
`'error'`	Stop importing and display an error message showing the missing record and field.
`'omitrow'`	Omit rows that contain missing data.
`'omitvar'`	Omit variables that contain missing data.

Example: opts.MissingRule = 'omitrow';

`ImportErrorRule` — Procedure to handle import errors
`'fill'` | `'error'` | `'omitrow'` | `'omitvar'`

Procedure to handle import errors, specified as one of the values in this table.

Import Error Rule	Behavior
`'fill'`	Replace the data where the error occurred with the contents of the `FillValue` property. The `FillValue` property is specified in the `VariableImportOptions` object of the variable being imported. For more information on accessing the `FillValue` property, see `getvaropts`.
`'error'`	Stop importing and display an error message showing the error-causing record and field.
`'omitrow'`	Omit rows where errors occur.
`'omitvar'`	Omit variables where errors occur.

Example: opts.ImportErrorRule = 'omitvar';

`ExtraColumnsRule` — Procedure to handle extra columns
`'addvars'` | `'ignore'` | `'wrap'` | `'error'`

Procedure to handle extra columns in the data, specified as one of the values in this table.

Extra Columns Rule	Behavior
`'addvars'`	To import extra columns, create new variables. If there are `N` extra columns, then import new variables as `'ExtraVar1', 'ExtraVar2',..., 'ExtraVarN'`. NOTE: The extra columns are imported as text with data type`char`.
`'ignore'`	Ignore the extra columns of data.
`'wrap'`	Wrap the extra columns of data to new records. This action does not change the number of variables.
`'error'`	Error and abort the import operation.

Example:

Object Functions

`getvaropts`	Get variable import options
`setvaropts`	Set variable import options
`setvartype`	Set variable data types

Examples

expand all

Create and Use Import Options for Text Files

Open Script

Create import options, tailor the data types for multiple variables, and then read the data.

Create an import options object from a text file.

opts = detectImportOptions('airlinesmall.csv')

opts = 

  DelimitedTextImportOptions with properties:

   Format Properties:
                    Delimiter: {','}
                   Whitespace: '\b\t '
                   LineEnding: {'\n'  '\r'  '\r\n'}
                 CommentStyle: {}
    ConsecutiveDelimitersRule: 'split'
        LeadingDelimitersRule: 'keep'
                EmptyLineRule: 'skip'
                     Encoding: 'US-ASCII'

   Replacement Properties:
                  MissingRule: 'fill'
              ImportErrorRule: 'fill'
             ExtraColumnsRule: 'addvars'

   Variable Import Properties:   Set types by name with setvartype
                VariableNames: {1×29 cell}
                VariableTypes: {1×29 cell}
        SelectedVariableNames: {1×29 cell}

   Location Properties:
                     DataLine: 2
            VariableNamesLine: 1
               RowNamesColumn: 0
            VariableUnitsLine: 0
     VariableDescriptionsLine: 0

          VariableOptions: [1×29 VariableOptions]
    Access VariableOptions sub-properties using setvaropts/getvaropts

Examine the Type property of variables TaxiIn and TaxiOut.

getvaropts(opts,{'TaxiIn','TaxiOut'})

ans = 

  1×2 TextVariableImportOptions array with properties:

    WhitespaceRule
    Type
    FillValue
    Name
    QuoteRule
    TreatAsMissing

Change the type of the variables TaxiIn and TaxiOut to double.

 opts = setvartype(opts,{'TaxiIn','TaxiOut'},'double');

Specify the subset of variables to import and examine.

opts.SelectedVariableNames = {'TaxiIn','TaxiOut'};

Use the readtable function along with the options object to import the selected variables. Display a summary of the table.

T = readtable('airlinesmall.csv',opts);
summary(T)

Variables:

    TaxiIn: 123523×1 double
        Values:

            min        0      
            median     5      
            max        1451   
            NaNs       37383  

    TaxiOut: 123523×1 double
        Values:

            min        0       
            median     13      
            max        755     
            NaNs       37364

Documentation

This is machine translation

DelimitedTextImportOptions

Description

Create Object

Properties

Variable Properties

VariableNames — Variable namescell array of character vectors

VariableTypes — Variable data typescell array of character vectors

SelectedVariableNames — Subset of variables to importcharacter vector | cell array of character vectors | array of numeric indices

VariableOptions — Type specific variable import optionsarray of variable import options objects

Location Properties

DataLine — Data start locationpositive scalar integer

RowNamesColumn — Row names location0 (default) | positive scalar integer

VariableNamesLine — Variable names location0 (default) | positive scalar integer

VariableDescriptionsLine — Variable description location0 (default) | positive scalar integer

VariableUnitsLine — Variable units location0 (default) | positive scalar integer

Delimited Text Properties

Delimiter — Field delimiter characterscharacter vector | cell array of character vectors

Whitespace — Characters to treat as white spacecharacter vector

LineEnding — End-of-line characters{'\n','\r','\r\n'} (default) | character vector | cell array of character vectors

CommentStyle — Style of commentscharacter vector | cell array of character vectors

ConsecutiveDelimitersRule — Procedure to handle consecutive delimiters'split' | 'join' | 'error'

LeadingDelimitersRule — Procedure to manage leading delimiters'keep' | 'ignore' | 'error'

Encoding — File encoding'system' (default) | 'UTF-8' | 'ISO-8859-1' | 'windows-1251' | 'windows-1252' | ...

Replacement Rules

MissingRule — Procedure to manage missing data'fill' | 'error' | 'omitrow' | 'omitvar'

ImportErrorRule — Procedure to handle import errors'fill' | 'error' | 'omitrow' | 'omitvar'

ExtraColumnsRule — Procedure to handle extra columns'addvars' | 'ignore' | 'wrap' | 'error'

Object Functions

Examples

Create and Use Import Options for Text Files

See Also

Introduced in R2016b

Select Your Country

Americas

Europe

Asia Pacific

MATLAB Documentation

Other Documentation

Support

Tackling Big Data with MATLAB

`VariableNames` — Variable names
cell array of character vectors

`VariableTypes` — Variable data types
cell array of character vectors

`SelectedVariableNames` — Subset of variables to import
character vector | cell array of character vectors | array of numeric indices

`VariableOptions` — Type specific variable import options
array of variable import options objects

`DataLine` — Data start location
positive scalar integer

`RowNamesColumn` — Row names location
`0` (default) | positive scalar integer

`VariableNamesLine` — Variable names location
`0` (default) | positive scalar integer

`VariableDescriptionsLine` — Variable description location
`0` (default) | positive scalar integer

`VariableUnitsLine` — Variable units location
`0` (default) | positive scalar integer

`Delimiter` — Field delimiter characters
character vector | cell array of character vectors

`Whitespace` — Characters to treat as white space
character vector

`LineEnding` — End-of-line characters
`{'\n','\r','\r\n'}` (default) | character vector | cell array of character vectors

`CommentStyle` — Style of comments
character vector | cell array of character vectors

`ConsecutiveDelimitersRule` — Procedure to handle consecutive delimiters
`'split'` | `'join'` | `'error'`

`LeadingDelimitersRule` — Procedure to manage leading delimiters
`'keep'` | `'ignore'` | `'error'`

`Encoding` — File encoding
`'system'` (default) | `'UTF-8'` | `'ISO-8859-1'` | `'windows-1251'` | `'windows-1252'` | ...

`MissingRule` — Procedure to manage missing data
`'fill'` | `'error'` | `'omitrow'` | `'omitvar'`

`ImportErrorRule` — Procedure to handle import errors
`'fill'` | `'error'` | `'omitrow'` | `'omitvar'`

`ExtraColumnsRule` — Procedure to handle extra columns
`'addvars'` | `'ignore'` | `'wrap'` | `'error'`