Main Content

delimitedTextImportOptions

Import options object for delimited text

expand all in page

Description

ADelimitedTextImportOptionsobject enables you to specify how MATLAB®imports tabular data from delimited text files. The object contains properties that control the data import process, including the handling of errors and missing data.

Creation

You can create aDelimitedTextImportOptionsobject using either thedetectImportOptionsfunction or thedelimitedTextImportOptionsfunction (described here):

  • UsedetectImportOptionsto detect and populate the import properties based on the contents of the delimited text file specified infilename.

    opts = detectImportOptions(filename);

  • UsedelimitedTextImportOptionsto define the import properties based on your import requirements.

Syntax

opts = delimitedTextImportOptions
opts = delimitedTextImportOptions('NumVariables',numVars)
opts = delimitedTextImportOptions(___,Name,Value)

Description

example

opts = delimitedTextImportOptionscreates aDelimitedTextImportOptionsobject with one variable.

example

opts = delimitedTextImportOptions('NumVariables',numVars)creates the object with the number of variables specified innumVars.

example

opts = delimitedTextImportOptions(___,Name,Value)specifies additionalpropertiesforDelimitedTextImportOptionsobject using one or more name-value pair arguments.

Input Arguments

expand all

Number of variables, specified as a positive scalar integer.

Properties

expand all

Variable Properties

Variable names, specified as a cell array of character vectors or string array. TheVariableNamesproperty contains the names to use when importing variables.

If the data containsNvariables, but no variable names are specified, then theVariableNamesproperty contains{'Var1','Var2',...,'VarN'}.

To support invalid MATLAB identifiers as variable names, such as variable names containing spaces and non-ASCII characters, set the value ofVariableNamingRuleto'preserve'.

Example:选择。VariableNamesreturns the current (detected) variable names.

Example:选择。VariableNames(3) = {'Height'}changes the name of the third variable toHeight.

Data Types:char|string|cell

Flag to preserve variable names, specified as either"modify"or"preserve".

  • "modify"——转换无效的变量名(as determined by theisvarnamefunction) to valid MATLAB identifiers.

  • "preserve"— Preserve variable names that are not valid MATLAB identifiers such as variable names that include spaces and non-ASCII characters.

Starting in R2019b, variable names and row names can include any characters, including spaces and non-ASCII characters. Also, they can start with any characters, not just letters. Variable and row names do not have to be valid MATLAB identifiers (as determined by theisvarnamefunction). To preserve these variable names and row names, set the value ofVariableNamingRuleto"preserve". Variable names are not refreshed when the value ofVariableNamingRuleis changed from"modify"to"preserve".

Data Types:char|string

Data type of variable, specified as a cell array of character vectors, or string array containing a set of valid data type names. TheVariableTypesproperty designates the data types to use when importing variables.

To update theVariableTypesproperty, use thesetvartypefunction.

Example:选择。VariableTypesreturns the current variable data types.

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

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

SelectedVariableNamesmust be a subset of names contained in theVariableNamesproperty. By default,SelectedVariableNames包含所有的变量names from theVariableNamesproperty, which means that all variables are imported.

Use theSelectedVariableNamesproperty to import only the variables of interest. Specify a subset of variables using theSelectedVariableNamesproperty and usereadtableto import only that subset.

To support invalid MATLAB identifiers as variable names, such as variable names containing spaces and non-ASCII characters, set the value ofVariableNamingRuleto'preserve'.

Example:选择。SelectedVariableNames = {'Height','LastName'}selects only two variables,HeightandLastName, for the import operation.

Example:选择。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 theSelectedVariableNamesproperty of theoptsobject.

Data Types:uint16|uint32|uint64|char|string|cell

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 theVariableNamesproperty. 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分类.

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

To set and customize options for a variable, use thesetvaroptsfunction.

Example:选择。VariableOptionsreturns a collection ofVariableImportOptionsobjects, one corresponding to each variable in the data.

Example:getvaropts(opts,'Height')returns theVariableImportOptionsobject for theHeightvariable.

Example:opts = setvaropts(opts,'Height','FillValue',0)sets theFillValueproperty for the variableHeightto0.

Location Properties

Data location, specified as a positive scalar integer or aN-by-2array of positive scalar integers. SpecifyDataLinesusing one of these forms.

Specify as

Description

n

Specify thefirst linethat contains the data. Specifying the value usingnsets the value ofDataLinesproperty to[n inf]. The importing function reads all rows betweennand the end-of-file.

nmust be a positive integer greater than zero.

[n1 n2]

Specify theline rangethat contains the data.n1is the first line that contains the data and then2is the last line that contains the data.

Values in the array[n1 n2]must be nonzero positive integers andn2must be greater thann1.

[n1 n2; n3 n4;...]

Specifymultiple line rangesto read with anN-by-2array containingNdifferent line ranges.

A valid array of multiple line ranges must:

  • Specify line ranges in an increasing order, that is the first line range specified in the array appears in the file before the other line ranges.

  • Contain only nonoverlapping line ranges.

When specifying multiple line ranges, useInfonly when specifying the end of the last line range in the array. For example,[1 3; 5 6; 8 Inf].

Example:选择。DataLines = 5sets theDataLinesproperty to the value[5 inf]. Read all rows of data starting from row5to the end-of-file.

Example:选择。DataLines = [2 6]sets the property to read lines2through6.

Example:选择。DataLines = [1 3; 5 6; 8 inf]sets the property to read rows1,2,3,5,6, and all rows between8, and the end-of-file.

Data Types:single|double|uint8|uint16|uint32|uint64

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

IfRowNamesColumnis specified as 0, then do not import the row names. Otherwise, import the row names from the specified column.

Example:选择。RowNamesColumn = 2;

Data Types:single|double|uint8|uint16|uint32|uint64

Variable names location, specified as a positive scalar integer. TheVariableNamesLine属性指定变量的行号names are located.

IfVariableNamesLineis specified as 0, then do not import the variable names. Otherwise, import the variable names from the specified line.

Example:选择。VariableNamesLine = 6;

Data Types:single|double|uint8|uint16|uint32|uint64

Variable description location, specified as a positive scalar integer. TheVariableDescriptionsLine属性指定变量的行号descriptions are located.

IfVariableDescriptionsLineis specified as 0, then do not import the variable descriptions. Otherwise, import the variable descriptions from the specified line.

Example:选择。VariableDescriptionsLine = 7;

Data Types:single|double|uint8|uint16|uint32|uint64

Variable units location, specified as a positive scalar integer. TheVariableUnitsLine属性指定变量的行号units are located.

IfVariableUnitsLineis specified as 0, then do not import the variable units. Otherwise, import the variable units from the specified line.

Example:选择。VariableUnitsLine = 8;

Data Types:single|double|uint8|uint16|uint32|uint64

Delimited Text Properties

Field delimiter characters in a delimited text file, specified as a character vector, string scalar, cell array of character vectors, or string array.

Example:'Delimiter','|'

Example:'Delimiter',{';','*'}

Data Types:char|string|cell

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

Example:'Whitespace',' _'

Example:'Whitespace','?!.,'

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

Example:'LineEnding','\n'

Example:'LineEnding','\r\n'

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

Data Types:char|string|cell

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

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

Example:'CommentStyle',{'/*'}

Data Types:char|string|cell

Procedure to handle consecutive delimiters in a delimited text file, 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' Return an error and abort the import operation.

Data Types:char|string

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

Leading Delimiters Rule Behavior
'keep' Keep the delimiter.
'ignore' Ignore the delimiter.
'error' Return an error and abort the import operation.

Procedure to manage trailing delimiters in a delimited text file, specified as one of the values in this table.

Leading Delimiters Rule Behavior
'keep' Keep the delimiter.
'ignore' Ignore the delimiter.
'error' Return an error and abort the import operation.

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 function uses automatic character set detection to determine the encoding when reading the file.

Example:'Encoding','system'uses the system default encoding.

Data Types:char|string

Replacement Rules

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 theFillValueproperty.

TheFillValueproperty is specified in theVariableImportOptionsobject of the variable being imported. For more information on accessing theFillValueproperty, seegetvaropts.
'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:选择。MissingRule = 'omitrow';

Data Types:char|string

Procedure to handle empty lines in the data, specified as'skip','read', or'error'. The importing function interprets white space as empty.

Empty Line Rule Behavior
'skip' Skip the empty lines.
'read' Import the empty lines. The importing function parses the empty line using the values specified inVariableWidths,VariableOptions,MissingRule, and other relevant properties, such asWhitespace.
'error' Display an error message and abort the import operation.

Example:选择。EmptyLineRule = 'skip';

Data Types:char|string

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 theFillValueproperty.

TheFillValueproperty is specified in theVariableImportOptionsobject of the variable being imported. For more information on accessing theFillValueproperty, seegetvaropts.
'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:选择。ImportErrorRule = 'omitvar';

Data Types:char|string

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 areNextra columns, then import new variables as'ExtraVar1', 'ExtraVar2',..., 'ExtraVarN'. Extra columns of data are imported as if theirVariableTypesarechar.
'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' Display an error message and abort the import operation.

Data Types:char|string

Object Functions

getvaropts Get variable import options
setvaropts Set variable import options
setvartype Set variable data types
preview Preview eight rows from file using import options

Examples

collapse all

Open Live Script

Define an import options object to read multiple variables frompatients.dat.

Based on the contents of your file, define these variable properties: names, types, delimiter character, data starting location, and the extra column rule.

varNames = {'LastName','Gender','Age','Location','Height','Weight','Smoker'} ; varTypes = {'char','categorical','int32','char','double','double','logical'} ; delimiter =','; dataStartLine = 2; extraColRule ='ignore';

Use thedelimitedTextImportOptionsfunction and your variable information to initialize the import options objectopts.

opts = delimitedTextImportOptions('VariableNames',varNames,...'VariableTypes',varTypes,...'Delimiter',delimiter,...'DataLines', dataStartLine,...'ExtraColumnsRule',extraColRule);

Use thepreviewfunction with the import options object to preview the data.

preview('patients.dat',opts)
ans=8×7 tableLastName Gender Age Location Height Weight Smoker ____________ ______ ___ _____________________________ ______ ______ ______ {'Smith' } Male 38 {'County General Hospital' } 71 176 false {'Johnson' } Male 43 {'VA Hospital' } 69 163 false {'Williams'} Female 38 {'St. Mary's Medical Center'} 64 131 false {'Jones' } Female 40 {'VA Hospital' } 67 133 false {'Brown' } Female 49 {'County General Hospital' } 64 119 false {'Davis' } Female 46 {'St. Mary's Medical Center'} 68 142 false {'Miller' } Female 33 {'VA Hospital' } 64 142 false {'Wilson' } Male 40 {'VA Hospital' } 68 180 false

Import the data usingreadtable.

T = readtable('patients.dat',opts); whosT
Name Size Bytes Class Attributes T 100x7 30563 table

Tips

  • Introduced in:

    • R2016b —DelimitedTextImportOptionsobject

    • R2018b —delimitedTextImportOptionsfunction

See Also

|