detectImportOptions - Create import options based on file content - MATLAB (original) (raw)

Main Content

Create import options based on file content

Syntax

Description

[opts](#bvcithw-opts) = detectImportOptions([filename](#bvcithw-filename),[Name,Value](#namevaluepairarguments)) locates a table in a file with the help of additional parameters specified by one or more Name,Value pair arguments.

example

Examples

collapse all

Read Spreadsheet File Using Import Options

Configure how readtable interprets your file using an import options object. For example, use an import options object to read only specified variables from a spreadsheet file.

First, create an import options object from a file by using detectImportOptions to detect aspects of your spreadsheet file, including variable names and types. In this case, detectImportOptions creates a SpreadsheetImportOptions object.

opts = detectImportOptions("patients.xls")

opts = SpreadsheetImportOptions with properties:

Sheet Properties: Sheet: ''

Replacement Properties: MissingRule: 'fill' ImportErrorRule: 'fill' MergedCellColumnRule: 'placeleft' MergedCellRowRule: 'placetop'

Variable Import Properties: Set types by name using setvartype VariableNames: {'LastName', 'Gender', 'Age' ... and 7 more} VariableTypes: {'char', 'char', 'double' ... and 7 more} SelectedVariableNames: {'LastName', 'Gender', 'Age' ... and 7 more} VariableOptions: [1-by-10 matlab.io.VariableImportOptions] Access VariableOptions sub-properties using setvaropts/getvaropts VariableNamingRule: 'modify'

Range Properties: DataRange: 'A2' (Start Cell) VariableNamesRange: 'A1' RowNamesRange: '' VariableUnitsRange: '' VariableDescriptionsRange: '' To display a preview of the table, use preview

Specify which variables to import by modifying the import options object. Then, import the specified variables using readtable with the import options object. Display the first 5 rows of the table.

opts.SelectedVariableNames = ["Systolic","Diastolic"]; T = readtable("patients.xls",opts); T(1:5,:)

ans=5×2 table Systolic Diastolic ________ _________

  124          93    
  109          77    
  125          83    
  117          75    
  122          80    

Read Subset of Text File Using Import Options

Configure how readtable interprets your file using an import options object. For example, use an import options object to read only a subset of a text file.

First, create an import options object by using detectImportOptions to detect aspects of your text file, including variable names and types, delimiters, and white-space characters. In this case, detectImportOptions creates a DelimitedTextImportOptions object.

opts = detectImportOptions("airlinesmall.csv")

opts = DelimitedTextImportOptions with properties:

Format Properties: Delimiter: {','} Whitespace: '\b\t ' LineEnding: {'\n' '\r' '\r\n'} CommentStyle: {} ConsecutiveDelimitersRule: 'split' LeadingDelimitersRule: 'keep' TrailingDelimitersRule: 'ignore' EmptyLineRule: 'skip' Encoding: 'ISO-8859-1'

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

Variable Import Properties: Set types by name using setvartype VariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more} VariableTypes: {'double', 'double', 'double' ... and 26 more} SelectedVariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more} VariableOptions: [1-by-29 matlab.io.VariableImportOptions] Access VariableOptions sub-properties using setvaropts/getvaropts VariableNamingRule: 'modify'

Location Properties: DataLines: [2 Inf] VariableNamesLine: 1 RowNamesColumn: 0 VariableUnitsLine: 0 VariableDescriptionsLine: 0 To display a preview of the table, use preview

Specify the subset of variables to import by modifying the import options object. Then, import the subset of data using readtable with the import options object.

opts.SelectedVariableNames = ["TaxiIn","TaxiOut"]; T = readtable("airlinesmall.csv",opts);

Detect and Use Import Options for Microsoft Word Document File

Detect import options for a Microsoft Word document file, specify the table to import, and then read the data.

The file MaintenanceReport.docx contains two tables. The last row of the second table contains a cell with merged columns that do not match the table variables.

Detect the import options using the detectImportOptions function. Specify to read from the second table by setting TableIndex to 2.

filename = "MaintenanceReport.docx"; opts = detectImportOptions(filename,'TableIndex',2)

opts = WordDocumentImportOptions with properties:

Replacement Properties: MissingRule: "fill" ImportErrorRule: "fill" EmptyRowRule: "skip" MergedCellColumnRule: "placeleft" MergedCellRowRule: "placetop" ExtraColumnsRule: "addvars"

Variable Import Properties: Set types by name using setvartype VariableNames: ["Description" "Category" "Urgency" "Resolution" "Cost"] VariableTypes: ["string" "string" "string" "string" "string"] SelectedVariableNames: ["Description" "Category" "Urgency" "Resolution" "Cost"] VariableOptions: [1-by-5 matlab.io.VariableImportOptions] Access VariableOptions sub-properties using setvaropts/getvaropts VariableNamingRule: "preserve"

Location Properties: TableSelector: "(//w:tbl)[2]" DataRows: [2 Inf] VariableNamesRow: 1 VariableUnitsRow: 0 VariableDescriptionsRow: 0 RowNamesColumn: 0

To skip reading rows that have cells with merged columns, set the MergedCellColumnRule property to 'omitrow'.

opts.MergedCellColumnRule = 'omitrow';

Read the table from the Microsoft Word document file using the readtable function with the options object.

filename = "MaintenanceReport.docx"; T = readtable(filename,opts)

T=3×5 table Description Category Urgency Resolution Cost
_____________________________________________________________________ ____________________ ________ __________________ ________

"Items are occasionally getting stuck in the scanner spools."            "Mechanical Failure"    "Medium"    "Readjust Machine"    "$45"   
"Loud rattling and banging sounds are coming from assembler pistons."    "Mechanical Failure"    "Medium"    "Readjust Machine"    "$35"   
"There are cuts to the power when starting the plant."                   "Electronic Failure"    "High"      "Full Replacement"    "$16200"

Detect and Use Import Options for HTML File

Detect import options for an HTML file, specify the table to import, and then read the data.

Detect the import options of the first table from the URL https://www.mathworks.com/help/matlab/text-files.html containing the text "readtable". Detect the import options using the detectImportOptions function and specify the table to read using the XPath query "//TABLE[contains(.,'readtable')]". Specify to not read variable names by setting ReadVariableNames to false.

url = "https://www.mathworks.com/help/matlab/text-files.html"; opts = detectImportOptions(url,'TableSelector',"//TABLE[contains(.,'readtable')]",'ReadVariableNames',false)

opts = HTMLImportOptions with properties:

Replacement Properties: MissingRule: "fill" ImportErrorRule: "fill" EmptyRowRule: "skip" MergedCellColumnRule: "placeleft" MergedCellRowRule: "placetop" ExtraColumnsRule: "addvars"

Variable Import Properties: Set types by name using setvartype VariableNames: ["Var1" "Var2"] VariableTypes: ["string" "string"] SelectedVariableNames: ["Var1" "Var2"] VariableOptions: Show all 2 VariableOptions Access VariableOptions sub-properties using setvaropts/getvaropts VariableNamingRule: "preserve"

Location Properties: TableSelector: "//TABLE[contains(.,'readtable')]" DataRows: [1 Inf] VariableNamesRow: 0 VariableUnitsRow: 0 VariableDescriptionsRow: 0 RowNamesColumn: 0

Read the table using the readtable function.

T=4×2 table Var1 Var2
________________ ____________________________

"readtable"         "Create table from file"    
"writetable"        "Write table to file"       
"readtimetable"     "Create timetable from file"
"writetimetable"    "Write timetable to file"   

Designate Data Type for Imported Text Data

Import text data as a string data type by specifying import options.

Create an options object for the file.

opts = detectImportOptions('outages.csv');

Specify which variables to import using readtable, and then show a summary. The data type of the selected variables is char.

opts.SelectedVariableNames = {'Region','Cause'}; T = readtable('outages.csv',opts); summary(T)

T: 1468x2 table

Variables:

Region: cell array of character vectors
Cause: cell array of character vectors

Statistics for applicable variables:

          NumMissing

Region        0     
Cause         0     

Import text data as a string data type, and then create import options by specifying the TextType name-value pair.

opts = detectImportOptions('outages.csv','TextType','string');

Specify which variables to import using readtable, and then show a summary. The data type of the selected variables is now string.

opts.SelectedVariableNames = {'Region','Cause'}; T = readtable('outages.csv',opts); summary(T)

T: 1468x2 table

Variables:

Region: string
Cause: string

Statistics for applicable variables:

          NumMissing

Region        0     
Cause         0     

Read XML File as Table

Import the contents of an XML file into a table.

The students.xml file has seven sibling nodes named Student, which each contain the same child nodes and attributes.

First, create an XMLImportOptions object by using detectImportOptions to detect aspects of your XML file. Read just the street names into a table by specifying the VariableSelectors name-value argument as the XPath expression of the Street element node. Register a custom namespace prefix to the existing namespace URL by setting the RegisteredNamespaces name-value argument.

opts = detectImportOptions("students.xml",RegisteredNamespaces=["myPrefix","https://www.mathworks.com"], ... VariableSelectors="//myPrefix:Street");

Then, import the specified variable using readtable with the import options object.

T = readtable("students.xml",opts)

T=7×1 table Street
___________________

"591 Spring Lane"  
"4641 Pearl Street"
"30 Highland Road" 
"3388 Moore Avenue"
"3388 Moore Avenue"
"22 Angie Drive"   
"65 Decatur Lane"  

Input Arguments

collapse all

filename — Name of file to read

character vector | string scalar

Name of the file to read, specified as a character vector or string scalar.

Depending on the location of your file, filename can take on one of these forms.

If filename includes the file extension, thendetectImportOptions determines the file format from the extension. Otherwise, you must specify the 'FileType' name-value pair to indicate the type of file.

The detectImportOptions function supports these file extensions: .txt, .dat,.csv, .xls,.xlsb, .xlsm,.xlsx, .xltm,.xltx, .ods,.xml, .docx,.html, .xhtml, and.htm.

Note

File extensions .xlsb and .ods are only supported on platforms with Excel® for Windows®.

Data Types: char | string

Name-Value Arguments

Specify optional pairs of arguments asName1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'FileType','spreadsheet'

All Supported File Types

collapse all

FileType — Type of file

'spreadsheet' | 'text' | 'delimitedtext' | 'fixedwidth' | 'xml' | 'worddocument' | 'html'

Type of file, specified as the comma-separated pair consisting of'FileType' and one of these values.

Use the 'FileType' name-value pair argument whenfilename does not include the file extension, or when the extension is not one of these:

• .txt, .dat, or.csv for text files
• .xls, .xlsb,.xlsm, .xlsx,.xltm, .xltx, or.ods for spreadsheet files
• .xml, for XML files
• .docx for Microsoft Word document files
• .html, .xhtml, or.htm for HTML files

File extensions .xlsb and .ods are only supported on platforms with Excel for Windows.

Example: 'FileType','text'

Data Types: char | string

TextType — Type for imported text data

"string" | "char"

Type for imported text data, specified as one of these values:

• "string" — Import text data as string arrays.
• "char" — Import text data as character vectors.

Example: "TextType","char"

DatetimeType — Type for imported date and time data

"datetime" (default) | "text" | "exceldatenum" (spreadsheet files only)

Type for imported date and time data, specified as one of these values:

ReadVariableNames — Read first row as variable names

true | false

Indicator for reading the first row as variable names, specified as the comma-separated pair consisting of 'ReadVariableNames' and either true or false. If unspecified, readtable automatically detects the presence of variable names.

Data Types: logical

VariableNamingRule — Flag to preserve variable names

"modify" (default) | "preserve"

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

ReadRowNames — Indicator for reading the first column as row names

false (default) | true

Indicator for reading first column as row names, specified as the comma-separated pair consisting of 'ReadRowNames' and either false ortrue.

Data Types: logical

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

Example: opts.MissingRule = 'omitrow';

Data Types: char | string

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

Example: opts.ImportErrorRule = 'omitvar';

Data Types: char | string

WebOptions — HTTP or HTTPS request options

weboptions object

HTTP or HTTPS request options, specified as a weboptions object. Theweboptions object determines how to import data when the specified filename is an internet URL containing the protocol type "http://" or"https://".

Text and Spreadsheet Files

collapse all

ExpectedNumVariables — Expected number of variables

positive integer

Expected number of variables, specified as the comma-separated pair consisting of'ExpectedNumVariables' and a positive integer. If unspecified, the importing function automatically detects the number of variables.

Data Types: single | double

Number of header lines in the file, specified as the comma-separated pair consisting of 'NumHeaderLines' and a positive integer. If unspecified, the importing function automatically detects the number of header lines in the file.

Example: 'NumHeaderLines',7

Data Types: single | double

Range — Portion of data to read

character vector | string scalar | numeric vector

Portion of the data to read from text or spreadsheet files, specified as the comma separated pair consisting of 'Range' and a character vector, string scalar, or numeric vector in one of these forms.

Data Types: char | string | double

Parameters for Spreadsheet Files Only

collapse all

Sheet to read from, specified as an empty character array, a character vector or string scalar containing the sheet name, or a positive scalar integer denoting the sheet index. Based on the value specified for the Sheet property, the import function behaves as described in the table.

Data Types: char | string | single | double

DataRange — Location of data

character vector | string scalar | positive scalar integer | array of positive scalar integers | cell array of character vector | string array

Location of data to be imported, specified as a character vector, string scalar, cell array of character vectors, string array, positive scalar integer or an N-by-2 array of positive scalar integers. Specify DataRange using one of these forms.

Data Types: char | string | cell | single | double

RowNamesRange — Location of row names

character vector | string scalar | positive scalar integer | '' empty character array

Location of row names, specified as a character vector, string scalar, positive scalar integer, or an empty character array. Specify RowNamesRange as one of the values in this table.

Data Types: char | single | double

VariableNamesRange — Location of variable names

character vector | string scalar | positive scalar integer | '' empty character array

Location of variable names, specified as a character vector, string scalar, positive scalar integer, or an empty character array. Specify VariableNamesRange as one of the values in this table.

Data Types: char | single | double

VariableUnitsRange — Location of variable units

character vector | string scalar | positive scalar integer | '' empty character array

Location of variable units, specified as a character vector, string scalar, positive scalar integer, or an empty character array. Specify VariableUnitsRange as one of the values in this table.

Data Types: char | string | single | double

VariableDescriptionsRange — Location of variable descriptions

character vector | string scalar | '' empty character array

Location of variable descriptions, specified as a character vector, string scalar, positive scalar integer, or an empty character array. Specify VariableDescriptionRange as one of the values in this table.

Data Types: char | string | single | double

MergedCellColumnRule — Rule for cells merged across columns

"placeleft" (default) | "placeright" | "duplicate" | "omitrow" | "error"

Since R2024b

Rule for cells merged across columns, specified as one of the values in this table.

MergedCellRowRule — Rule for cells merged across rows

"placetop" (default) | "placebottom" | "duplicate" | "omitvar" | "error"

Since R2024b

Rule for cells merged across rows, specified as one of the values in this table.

Parameters for Text Files Only

collapse all

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

Example: "Delimiter","|"

Example: "Delimiter",[";","*"]

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

TrailingDelimitersRule — Procedure to manage trailing delimiters

'keep' | 'ignore' | 'error'

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

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

Field widths of variables in a fixed-width text file, 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 theVariableNames property.

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 string array, character vector, or cell array of character vectors.

Example: "LineEnding","\n"

Example: "LineEnding","\r\n"

Example: "LineEnding",["\b",":"]

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

Style of comments, specified as a string array, character vector, or cell array of character vectors. For single- and multi-line comments, the starting identifier must be the first non-white-space character. For single-line comments, specify a single identifier to treat lines starting with the identifier as comments. For multi-line comments, lines from the starting (first) identifier to the ending (second) identifier are treated as comments. No more than two character vectors of identifiers can be specified.

For example, to ignore the line following a percent symbol as the first non-white-space character, specify CommentStyle as"%".

Example: "CommentStyle",["/*"]

Example: "CommentStyle",["/*","*/"]

DurationType — Output data type of duration data

'duration' (default) | 'text'

Output data type of duration data from text files, specified as the comma-separated pair consisting of 'DurationType' and either 'duration' or 'text'.

Data Types: char | string

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

Data Types: char | string

TreatAsMissing — Text to interpret as missing data

character vector | string scalar | cell array of character vectors | string array

Text to interpret as missing data, specified as a character vector, string scalar, cell array of character vectors, or string array.

When the importing function finds missing instances, it uses the specification in the MissingRule property to determine the appropriate action.

Example: 'TreatAsMissing',{'NA','TBD'} instructs the importing function to treat any occurrence of NA orTBD as a missing fields.

Data Types: char | string | cell

DateLocale — Locale for reading dates

character vector | string scalar

Locale for reading dates, specified as the comma-separated pair consisting of'DateLocale' and a character vector or a string scalar of the form _`xx`__ _`YY`_, where:

• YY is an uppercase ISO 3166-1 alpha-2 code indicating a country.
• xx is a lowercase ISO 639-1 two-letter code indicating a language.

This table lists some common values for the locale.

When using the %D format specifier to read text asdatetime values, use DateLocale to specify the locale in which the importing function should interpret month and day-of-week names and abbreviations.

If you specify the DateLocale argument in addition toopts the import options, then the importing function uses the specified value for the DateLocale argument, overriding the locale defined in the import options.

Example: 'DateLocale','ja_JP'

ThousandsSeparator — Characters that indicate the thousands grouping

character vector | string scalar

Characters that indicate the thousands grouping in numeric variables, specified as a character vector or string scalar. The thousands grouping characters act as visual separators, grouping the number at every three place values. The importing function uses the characters in theThousandsSeparator property to interpret the numbers being imported.

Data Types: char | string

DecimalSeparator — Characters indicating decimal separator

character vector | string scalar

Characters indicating the decimal separator in numeric variables, specified as a character vector or string scalar. The importing function uses the DecimalSeparator property to distinguish the integer part of a number from the decimal part.

When converting to integer data types, numbers with a decimal part are rounded to the nearest integer.

Data Types: char | string

TrimNonNumeric — Remove nonnumeric characters

false (default) | true

Remove nonnumeric characters from a numeric variable, specified as a logical true or false.

Data Types: logical

HexType — Output data type of hexadecimal data

'auto' (default) | 'text' | 'int8' | 'int16' | ...

Output data type of hexadecimal data, specified as the comma-separated pair consisting of 'HexType' and one of the values listed in the table.

The input file represents hexadecimal values as text, using either 0x or0X as a prefix and the characters0-9,a-f, and A-F as digits. (Uppercase and lowercase letters represent the same digits—for example,'0xf' and '0xF' both represent15.)

The importing function converts the hexadecimal values to the data type specified by the value of 'HexType'.

Example: 'HexType','uint16' converts text representing hexadecimal values (such as '0xFF') to unsigned 16-bit integers (such as 255) in the output table.

Data Types: char | string

BinaryType — Output data type of binary data

'auto' (default) | 'text' | 'int8' | 'int16' | ...

Output data type of binary data, specified as the comma-separated pair consisting of'BinaryType' and one of the values listed in the table.

The input file represents binary values as text, using either 0b or0B as a prefix and the characters 0 and1 as digits.

The importing function converts the binary values to the data type specified by the value of 'BinaryType'.

Example: 'BinaryType','uint16' converts text representing binary values (such as '0b11111111') to unsigned 16-bit integers (such as255) in the output table.

Data Types: char | string

XML Files Only

collapse all

ImportAttributes — Import attributes

logical 1 or true (default) | logical 0 or false

Import attributes, specified as the comma-separated pair consisting of'ImportAttributes' and either 1 (true) or 0 (false). If you specify false, then the reading function will not import the XML attributes in the input file as variables in the output table.

Example: 'ImportAttributes',false

AttributeSuffix — Attribute suffix

'Attribute' (default) | character vector | string scalar

Attribute suffix, specified as the comma-separated pair consisting of'AttributeSuffix' and either a character vector or string scalar. This argument specifies the suffix the reading function appends to all table variables that correspond to attributes in the input XML file. If you do not specify'AttributeSuffix', then the reading function defaults to appending the suffix 'Attribute' to all variable names corresponding to attributes in the input XML file.

Example: 'AttributeSuffix','_att'

RowNodeName — Table row XML node name

character vector | string array

Table row XML node name, specified as the comma-separated pair consisting of'RowNodeName' and either a character vector or string scalar. This argument specifies the XML node name that delineates rows of the output table.

Example: 'RowNodeName','XMLNodeName'

RowSelector — Table row XPath expression

character vector | string scalar

Table row XPath expression, specified as a character vector or string scalar that the reading function uses to select individual rows of the output table. You must specifyRowSelector as a valid XPath version 1.0 expression.

Example: 'RowSelector','/RootNode/ChildNode'

VariableNodeNames — Table variable XML node names

cell array of character vectors | string array

Table variable XML node names, specified as the comma-separated pair consisting of'VariableNodeNames' and either a cell array of character vectors or string array. This argument specifies the XML node name that the reading function uses to identify the XML nodes to read as variables in the output table.

Example: 'VariableNodeNames',{'XMLNodeName1','XMLNodeName2'}

Example: 'VariableNodeNames',"XMLNodeName"

Example: 'VariableNodeNames',["XMLNodeName1","XMLNodeName2"]

VariableSelectors — Table variable XPath expressions

cell array of character vectors | string array

Table variable XPath expressions, specified as a cell array of character vectors or string array that the reading function uses to select table variables. You must specifyVariableSelectors as valid XPath version 1.0 expressions.

Example: 'VariableSelectors',{'/RootNode/ChildNode'}

Example: 'VariableSelectors',"/RootNode/ChildNode"

Example: 'VariableSelectors',["/RootNode/ChildNode1","/RootNode/ChildNode2"]

TableNodeName — Table XML node name

character vector | string scalar

Table XML node name, specified as the comma-separated pair consisting of'TableNodeName' and either a character vector or string scalar. This argument specifies the node in the input structure that the reading function should read to a table.

Example: 'TableNodeName','NodeName'

VariableUnitsSelector — Variable units XPath expression

character vector | string scalar

Variable units XPath, specified as a character vector or string scalar that the reading function uses to select the table variable units. You must specifyVariableUnitsSelector as a valid XPath version 1.0 expression.

Example: 'VariableUnitsSelector','/RootNode/ChildNode'

VariableDescriptionsSelector — Variable descriptions XPath expression

character vector | string scalar

Variable descriptions XPath expression, specified as a character vector or string scalar that the reading function reads uses to select the table variable descriptions. You must specify VariableDescriptionsSelector as a valid XPath version 1.0 expression.

Example: 'VariableDescriptionsSelector','/RootNode/ChildNode'

RowNamesSelector — Table row names XPath expression

character vector | string scalar

Table row names XPath expression, specified as a character vector or string scalar that the reading function uses to select the names of the table rows. You must specifyRowNamesSelector as a valid XPath version 1.0 expression.

Example: 'RowNamesSelector','/RootNode/ChildNode'

RepeatedNodeRule — Procedure to handle repeated XML nodes

'addcol' (default) | 'ignore' | 'error'

Procedure to handle repeated XML nodes in a given row of a table, specified as'addcol', 'ignore', or'error'.

Example: 'RepeatedNodeRule','ignore'

RegisteredNamespaces — Set of registered XML namespace prefixes

string array

Set of registered XML namespace prefixes, specified as the comma-separated pair consisting of RegisteredNamespaces and an array of prefixes. The reading function uses these prefixes when evaluating XPath expressions on an XML file. Specify the namespace prefixes and their associated URLs as an Nx2 string array.RegisteredNamespaces can be used when you also evaluate an XPath expression specified by a selector name-value argument, such asStructSelector for readstruct, orVariableSelectors for readtable andreadtimetable.

By default, the reading function automatically detects namespace prefixes to register for use in XPath evaluation, but you can also register new namespace prefixes using theRegisteredNamespaces name-value argument. You might register a new namespace prefix when an XML node has a namespace URL, but no declared namespace prefix in the XML file.

For example, evaluate an XPath expression on an XML file calledexample.xml that does not contain a namespace prefix. Specify'RegisteredNamespaces' as ["myprefix", "https://www.mathworks.com"] to assign the prefixmyprefix to the URLhttps://www.mathworks.com.

T = readtable("example.xml", "VariableSelector", "/myprefix:Data",... "RegisteredNamespaces", ["myprefix", "https://www.mathworks.com"])

Example: 'RegisteredNamespaces',["myprefix", "https://www.mathworks.com"]

Microsoft Word Document and HTML Files Only

collapse all

TableIndex — Index of table to read

1 (default) | positive integer

Index of table to read from Microsoft Word document or HTML file containing multiple tables, specified as a positive integer.

When you specify TableIndex, the software automatically sets TableSelector to the equivalent XPath expression.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

MergedCellColumnRule — Rule for cells merged across columns

"placeleft" (default) | "placeright" | "duplicate" | "omitrow" | "error"

Rule for cells merged across columns, specified as one of the values in this table.

MergedCellRowRule — Rule for cells merged across rows

"placetop" (default) | "placebottom" | "duplicate" | "omitvar" | "error"

Rule for cells merged across rows, specified as one of the values in this table.

VariableNamesRow — Row containing variable names

nonnegative integer

Row containing variable names, specified as a nonnegative integer.

• If you do not specify VariableNamesRow, then the software reads variable names according to the ReadVariableNames argument.
• If VariableNamesRow is 0, then the software does not import the variable names.
• Otherwise, the software imports the variable names from the specified row.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

VariableUnitsRow — Row containing variable units

0 (default) | nonnegative integer

Row containing variable units, specified as a nonnegative integer.

If VariableUnitsRow is 0, then the software does not import the variable units. Otherwise, the software imports the variable units from the specified row.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

VariableDescriptionsRow — Row containing variable descriptions

0 (default) | nonnegative integer

Row containing variable descriptions, specified as a nonnegative integer.

If VariableDescriptionsRow is 0, then the software does not import the variable descriptions. Otherwise, the software imports the variable descriptions from the specified row.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

EmptyRowRule — Rule to apply to empty rows in the table

"skip" (default) | "read" | "error"

Rule to apply to empty rows in the table, specified as one of the following:

• "skip" – Skip empty rows.
• "read" – Read empty rows.
• "error" – Ignore empty rows during table detection and error when reading.

EmptyColumnRule — Rule to apply to empty columns in the table

"skip" (default) | "read" | "error"

Rule to apply to empty columns in the table, specified as one of the following:

• "skip" – Skip empty columns.
• "read" – Read empty columns.
• "error" – Ignore empty columns during table detection and error when reading.

Microsoft Word Document, HTML, and XML Files Only

collapse all

TableSelector — Table data XPath expression

character vector | string scalar

Table data XPath expression, specified as a character vector or string scalar that the reading function uses to select the output table data. You must specifyTableSelector as a valid XPath version 1.0 expression.

Example: 'TableSelector','/RootNode/ChildNode'

Output Arguments

collapse all

opts — Import options for file

SpreadsheetImportOptions | DelimitedtextImportOptions | FixedWidthImportOptions | XMLImportOptions

Import options for the specified file, returned as aSpreadsheetImportOptions,DelimitedTextImportOptions,FixedWidthImportOptions, orXMLImportOptions object. The type of options object depends on the type of file specified. For text files (.txt, .dat, or.csv), the detectImportOptions function returns a DelimitedTextImportOptions orFixedWidthImportOptions object. For spreadsheet files (.xls,.xlsb, .xlsm,.xlsx, .xltm,.xltx, or .ods), thedetectImportOptions function returns a SpreadsheetImportOptions object. For XML files (.xml),detectImportOptions returns an XMLImportOptions object.

Tips

• Updating Property Values After Creating the Import Options Object: Use of dot notation is not recommended to update the properties of the import options object created bydetectImportOptions. When you set properties using dot notation, MATLAB does not re-detect all the import options for the file. Therefore, to update and re-detect all the properties, you must specify the new values by using name-value arguments. For example, update the value for theConsecutiveDelimitersRule property and re-detect the import options as follows.
  opts = detectImportOptions(__,'ConsecutiveDelimitersRule','join')
• Use XPath selectors to specify which elements of the XML input document to import. For example, suppose you want to import the XML filemyFile.xml, which has the following structure: 12 1020 This table provides the XPath syntaxes that are supported for XPath selector name-value arguments, such as `VariableSelectors` or `TableSelector`. | Selection Operation | Syntax | Example | Result | | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | | Select every node whose name matches the node you want to select, regardless of its location in the document. | Prefix the name with two forward slashes (//). | data = readtable('myFile.xml', 'VariableSelectors', '//var') | data = 4×1 table var \_\_\_ 1 2 10 20 | | Read the value of an attribute belonging to an element node. | Prefix the attribute with an at sign (@). | data = readtable('myFile.xml', 'VariableSelectors', '//table/@category') | data = 2×1 table categoryAttribute \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ "ones" "tens" | | Select a specific node in a set of nodes. | Provide the index of the node you want to select in square brackets (\[\]). | data = readtable('myFile.xml', 'TableSelector', '//table\[1\]') | data = 2×1 table var \_\_\_ 1 2 | | Specify precedence of operations. | Add parentheses around the expression you want to evaluate first. | data = readtable('myFile.xml', 'VariableSelectors', '//table/var\[1\]') | data = 2×1 table var \_\_\_ 1 10 | | data = readtable('myFile.xml', 'VariableSelectors', '(//table/var)\[1\]') | data = table var \_\_\_ 1 | | |

Version History

Introduced in R2016b

expand all

R2024b: Specify how to import merged cells in spreadsheets

When importing data from spreadsheets, you can specify howdetectImportOptions imports cells that are merged across rows and columns by using the MergedCellRowRule andMergedCellColumnRule name-value arguments.