delimitedTextImportOptions - Import options object for delimited text - MATLAB (original) (raw)

Import options object for delimited text

Description

A DelimitedTextImportOptions object 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 a DelimitedTextImportOptions object using either thedetectImportOptions function or thedelimitedTextImportOptions function (described here):

Use detectImportOptions to detect and populate the import properties based on the contents of the delimited text file specified infilename.
opts = detectImportOptions(filename);
Use delimitedTextImportOptions to define the import properties based on your import requirements.

Syntax

Description

opts = delimitedTextImportOptions creates aDelimitedTextImportOptions object with one variable.

example

opts = delimitedTextImportOptions('NumVariables',[numVars](#bvetpdy-1%5Fsep%5Fmw%5Ff5acc160-778c-42ed-a7f2-be23ca93c208)) creates the object with the number of variables specified innumVars.

example

opts = delimitedTextImportOptions(___,`Name,Value`) specifies additional properties forDelimitedTextImportOptions object using one or more name-value pair arguments.

example

Input Arguments

expand all

Number of variables, specified as a positive scalar integer.

Properties

expand all

Variable Properties

Data Types: char | string | cell

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

"modify" — Convert invalid variable names (as determined by the isvarname function) 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 the isvarname function). To preserve these variable names and row names, set the value of VariableNamingRule to "preserve". Variable names are not refreshed when the value of VariableNamingRule is changed from "modify" to "preserve".

Data Types: char | string

Location Properties

Delimited Text Properties

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.

Data Types: char | string

Replacement Rules

Data Types: char | string

Object Functions

Examples

collapse all

Define an import options object to read multiple variables from patients.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 the delimitedTextImportOptions function and your variable information to initialize the import options object opts.

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

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

preview('patients.dat',opts)

ans=8×7 table LastName Gender Age Location Height Weight Smoker ____________ ______ ___ _____________________________ ______ ______ ______

{'Smith'   }    Male      38     {'County General Hospital'  }      71       176      true  
{'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      true  
{'Wilson'  }    Male      40     {'VA Hospital'              }      68       180      false

Import the data using readtable.

T = readtable('patients.dat',opts); whos T

Name Size Bytes Class Attributes

T 100x7 33987 table

Version History

Introduced in R2016b

expand all

Use the delimitedTextImportOptions function to create aDelimitedTextImportOptions object. Previously, you could create this object only by using the detectImportOptions function.