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.

FixedWidthImportOptions

Import options object for fixed-width text files

Description

A FixedWidthImportOptions object enables you to specify how MATLAB® imports fixed-width 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 FixedWidthImportOptions object to query the current (detected) values of import properties or to assign new values based on your import needs.

Creation

To create a FixedWidthImportOptions object for a clean fixed-width text file, use the detectImportOptions function:

opts = detectImportOptions('MyFixedWidthFile.txt')
Alternatively, for a messy fixed-width text file that is not automatically detected by the detectImportOptions function, create a custom FixedWidthImportOptions object:
opts = matlab.io.text.FixedWidthImportOptions 
To import data using this custom FixedWidthImportOptions object, you must first set up these properties: VariableNames, VariableWidths, VariableTypes, and DataLine.

Properties

expand all

Variable Properties

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

Field widths of variables, specified as a vector of positive integer values. Each positive integer in the vector corresponds to the number of characters in a field that makes up the variable. The VariableWidths property contains an entry corresponding to each variable specified in the VariableNames property.

Example: opts.VariableWidths returns a vector of variable widths where each element corresponds to the width of a variable in the data.

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.

Data Types: cell | single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | categorical | datetime

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.

Data Types: uint16 | uint32 | uint64 | logical | char | 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 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

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;

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

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;

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

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;

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

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;

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

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;

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

Delimited Text Properties

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

Example: ' _'

Example: '?!.,'

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

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

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

Procedure to handle partial fields in the data, specified as one of the values in this table.

Partial Field RuleBehavior
'keep'

Keep the partial field data and convert the text to the appropriate data type.

In some cases, when the importing function is unable to interpret the partial data, a conversion error might occur.

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

'omitrow'Omit rows that contain partial data.
'omitvar'Omit variables that contain partial data.
'wrap'Begin reading the next line of characters.
'error'Display an error message and abort the import operation.

Example: opts.PartialFieldRule = 'keep';

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

Empty Line RuleBehavior
'skip'Skip the empty lines.
'read'Import the empty lines. The importing function parses the empty line using the values specified in VariableWidths, VariableOptions, MissingRule, and other relevant properties, such as Whitespace.
'error'Display an error message and abort the import operation.

Example: opts.EmptyLineRule = 'skip';

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

Missing RuleBehavior
'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';

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

Import Error RuleBehavior
'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';

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

Extra Columns RuleBehavior
'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 typechar.

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

Example:

Object Functions

getvaroptsGet variable import options
setvaroptsSet variable import options
setvartypeSet variable data types

Examples

expand all

Examine a fixed-width formatted text file, create an import options object, and use the object to import the table from the text file.

Load and Preview Fixed-Width Text File

Load the file fixed_width_patients_subset_perfect.txt and preview its contents in a text editor. The screen shot shows that the file contains fixed-width formatted data.

filename = fullfile(matlabroot,'examples','matlab','fixed_width_patients_subset_perfect.txt');

Examine and Extract Properties of Fixed-Width File

The fixed-width text file has tabular data organized by starting location, variable names, and variable widths. Capture these properties and the desired data type for the variables.

DataStartLine = 2;  
VariableNames  = {'LastName','Gender','Age','Location','Height',...
                                                      'Weight','Smoker'};
VariableWidths = [ 10,     7,     4,    26,     7, ...
                                                         7,     7 ] ;                                                  
DataType       = {'char','categorical','double','char','double',...
                                                     'double','logical'};

Create and Configure FixedWidthImportOptions Object

Create a FixedWidthImportOptions object and configure its properties to match the properties of the data in fixed_width_patients_subset_perfect.txt.

opts = matlab.io.text.FixedWidthImportOptions;
opts.DataLine = DataStartLine;    
opts.VariableNames = VariableNames; 
opts.VariableWidths = VariableWidths;               
opts = setvartype(opts,VariableNames,DataType);

Import Table

Use readtable with the FixedWidthImportOptions object to import the table.

T = readtable(filename,opts)
T=10x7 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 
    'Brown'       Female    49     'County General Hospital'      64        119       false 
    'Miller'      Female    33     'VA Hospital'                  64        142       true  
    'Wilson'      Male      40     'VA Hospital'                  68        180       false 
    'Taylor'      Female    31     'County General Hospital'      66        132       false 
    'Thomas'      Female    42     'St. Mary's Medical Center'    66        137       false 
    'Jackson'     Male      25     'VA Hospital'                  71        174       false 
    'Clark'       Female    48     'VA Hospital'                  65        133       false 

Create an import options object to import messy data from a fixed-width formatted text file. Configure the object to handle the messy data and use it to import the table.

Load and Preview Fixed-Width Text File

Load the file fixed_width_patients_subset_messy.txt and preview its contents in a text editor. A screen shot is shown below. The screen shot shows that the file contains:

  • Empty lines – Lines 7, 12, and 13

  • An extra column – Column 8

  • Missing data – Lines 1, 4, 9 and 11

  • Partial fields – Last 3 rows

filename = fullfile(matlabroot,'examples','matlab','fixed_width_patients_subset_messy.txt');

Examine and Capture Properties of Fixed-Width File

The fixed-width text file has tabular data organized by the staring location, variable names, and variable widths. Capture these properties and the data type you want to use for the variables.

DataStartLine = 2;  
VariableNames  = {'LastName','Gender','Age','Location','Height',...
                                                      'Weight','Smoker'};
VariableWidths = [ 10,     7,     4,    26,     7, ...
                                                         7,     7 ] ;                                                  
DataType       = {'char','categorical','double','char','double',...
                                                     'double','logical'};

Create FixedWidthImportOptions Object and Set Up Variable Properties

Create a FixedWidthImportOptions object and configure its properties to match the properties of the data.

opts = matlab.io.text.FixedWidthImportOptions;
opts.DataLine = DataStartLine;    
opts.VariableNames = VariableNames; 
opts.VariableWidths = VariableWidths;               
opts = setvartype(opts,VariableNames,DataType);

Set Up EmptyLinesRule, Missing Rule, and ExtraColumnsRule

Read the empty lines in the data by setting the EmptyLineRule to 'read'. Next, fill the missing instances with predefined values by setting the MisingRule to 'fill'. Finally, to ignore the extra column during the import, set the ExtraColumnsRule to 'ignore'. For more inormation on the properties and their values, see documentation for FixedWidthImportOptions.

opts.EmptyLineRule = 'read';
opts.MissingRule = 'fill'; 
opts.ExtraColumnsRule ='ignore';

Set Up PartialFieldRule

Partial fields occur when the importing function reaches the end-of-line character before the full variable width is traversed. For example, in this preview, the last three rows from the file fixed_width_patients_subset_messy.txt. Here, in the last row of the last column, the end-of-line character appears after two places from the start of the field, before the full variable-width of three is reached.

This occurrence of a partial field somtimes can indicate an error. Therefore, use the ParitalFieldRule to decide how to handle this data. To keep the partial field data and convert it to the appropriate data type, set the ParitalFieldRule to 'keep'. For more infromation on the ParitalFieldRule, see documentation for FixedWidthImportOptions.

opts.PartialFieldRule = 'keep';

Import Table

Import the table by using readtable function and the FixedWidthImportOptions object and preview the data.

T = readtable(filename,opts)
T=15x7 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'    NaN       NaN       false 
    'Jones'       Female          40    'VA Hospital'                   67       133       false 
    'Brown'       Female          49    'County General Hospital'       64       119       false 
    ''            <undefined>    NaN    ''                             NaN       NaN       false 
    'Wilson'      Male            40    'VA Hospital'                   68       180       false 
    'Moore'       Male            28    'St. Mary's Medical Center'    NaN       183       false 
    'Taylor'      Female          31    'County General Hospital'       66       132       false 
    'Anderson'    Female          45    'County General Hospital'       68       NaN       false 
    ''            <undefined>    NaN    ''                             NaN       NaN       false 
    ''            <undefined>    NaN    ''                             NaN       NaN       false 
    'White'       Male            39    'VA Hospital'                   72         2       false 
    'Harris'      Female          36    'St. Mary's Medical Center'     65        12       false 
    'Martin'      Male            48    'VA Hospital'                   71       181       true  

Introduced in R2017a

Was this topic helpful?