readtable - Create table from file - MATLAB (original) (raw)

Main Content

Syntax

Description

[T](#btx%5F238-1%5Fsep%5Fshared-T) = readtable([filename](#mw%5Fb0826a11-ea6e-45f6-92ce-54960958581f)) creates a table by reading column-oriented data from a text file, spreadsheet (includingMicrosoft® Excel®) file, XML file, HTML file, or a Microsoft Word document. readtable detects elements of your data, such as delimiter and data types, to determine how to import your data.

example

[T](#btx%5F238-1%5Fsep%5Fshared-T) = readtable([filename](#mw%5Fb0826a11-ea6e-45f6-92ce-54960958581f),[Name,Value](#namevaluepairarguments)) specifies options using one or more name-value arguments. For example, you can read the first row of the file as variable names or as data by using the ReadVariableNames name-value argument.

example

[T](#btx%5F238-1%5Fsep%5Fshared-T) = readtable([filename](#mw%5Fb0826a11-ea6e-45f6-92ce-54960958581f),[opts](#mw%5Fda8f54b7-5bd3-4640-9eb5-715f76a3a7f0)) creates a table using the options specified by the import options objectopts. Use an import options object to configure howreadtable interprets your file. Compared to name-value arguments, an import options object provides more control, better performance, and reusability of the file import configuration.

example

[T](#btx%5F238-1%5Fsep%5Fshared-T) = readtable([filename](#mw%5Fb0826a11-ea6e-45f6-92ce-54960958581f),[opts](#mw%5Fda8f54b7-5bd3-4640-9eb5-715f76a3a7f0),[Name,Value](#namevaluepairarguments)) creates a table using both an import options object and name-value arguments. If you specify name-value arguments in addition to an import options object, then readtable supports only the ReadVariableNames, ReadRowNames,DateLocale, and Encoding name-value arguments for text files, and the ReadVariableNames, ReadRowNames,Sheet, and UseExcel name-value arguments for spreadsheet files.

example

Examples

collapse all

Read Text File as Table

Import the contents of a text file into a table. The resulting table contains one variable for each column in the file and uses the entries in the first line of the file as variable names.

T = readtable("myCsvTable.dat")

T=5×6 table LastName Gender Age Height Weight Smoker ____________ ______ ___ ______ ______ ______

{'Smith'   }    {'M'}     38       71       176        1   
{'Johnson' }    {'M'}     43       69       163        0   
{'Williams'}    {'F'}     38       64       131        0   
{'Jones'   }    {'F'}     40       67       133        0   
{'Brown'   }    {'F'}     49       64       119        0   

Read Text File with Missing Data

Create a table from a text file that contains data gaps. By default, readtable fills the gaps with the appropriate missing values.

T = readtable("headersAndMissing.txt")

T=5×6 table LastName Gender Age Height Weight Smoker ___________ __________ ___ ______ ______ ______

{'Wu'     }    {'M'     }     38      71       176        1   
{'Johnson'}    {'M'     }     43      69       163        0   
{'Sanchez'}    {'F'     }     38      64       131        0   
{'Brown'  }    {'F'     }    NaN      67       133        0   
{'Picard' }    {0x0 char}    NaN      64       119        0   

To omit the rows with the data gaps, specify the MissingRule name-value argument.

T = readtable("headersAndMissing.txt",MissingRule="omitrow")

T=3×6 table LastName Gender Age Height Weight Smoker ___________ ______ ___ ______ ______ ______

{'Wu'     }    {'M'}     38       71       176        1   
{'Johnson'}    {'M'}     43       69       163        0   
{'Sanchez'}    {'F'}     38       64       131        0   

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

Read Spreadsheet File as Table with Row Names

Create a table from a spreadsheet that contains variable names in the first row and row names in the first column. Display the first five rows and first four variables of the table.

T = readtable("patients.xls",ReadRowNames=true); T(1:5,1:4)

ans=5×4 table Gender Age Location Height __________ ___ _____________________________ ______

Smith       {'Male'  }    38     {'County General Hospital'  }      71  
Johnson     {'Male'  }    43     {'VA Hospital'              }      69  
Williams    {'Female'}    38     {'St. Mary's Medical Center'}      64  
Jones       {'Female'}    40     {'VA Hospital'              }      67  
Brown       {'Female'}    49     {'County General Hospital'  }      64  

Read Spreadsheet File Using Specific Range

Create a table using data from a specified region of a spreadsheet. Use the data from the 5-by-3 rectangular region between the corners C2 and E6. Do not use the first row of this region as variable names. The resulting table uses the default variable names instead.

T = readtable("patients.xls",Range="C2:E6",ReadVariableNames=false)

T=5×3 table Var1 Var2 Var3 ____ _____________________________ ____

 38     {'County General Hospital'  }     71 
 43     {'VA Hospital'              }     69 
 38     {'St. Mary's Medical Center'}     64 
 40     {'VA Hospital'              }     67 
 49     {'County General Hospital'  }     64 

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

Read Microsoft Word Document as Table

Import a table from a Microsoft Word document into a table in MATLAB. In this case, the document contains two tables, and the second table contains merged cells. Read the second table by setting the TableIndex name-value argument. Skip rows that have cells with merged columns by setting the MergedCellColumnRule name-value argument.

filename = "MaintenanceReport.docx"; T = readtable(filename,TableIndex=2,MergedCellColumnRule="omitrow")

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"

Alternatively, you can select a table with an XPath selector by using the TableSelector name-value argument. To select the Microsoft Word document table that contains the text "Description", use the XPath selector "//w:tbl[contains(.,'Description')]".

T = readtable(filename, ... TableSelector="//w:tbl[contains(.,'Description')]", ... MergedCellColumnRule="omitrow")

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"

Read HTML Webpage as Table

Import the first table from the URL https://www.mathworks.com/help/matlab/text-files.html that contains the text "readtable" using the XPath selector "//TABLE[contains(.,'readtable')]". The table does not have a header row, so set the ReadVariableNames name-value argument to false.

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

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"   

Input Arguments

collapse all

filename — Name of file to read

string scalar | character vector

Name of the file to read, specified as a string scalar or character vector.readtable supports reading data from text, spreadsheet, XML, and HTML files as well as Microsoft Word documents.

If filename does not include an extension, use theFileType name-value argument to indicate the file format. By default,readtable creates variables that have data types that are appropriate for the data values detected in each column of the input file.

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

Text Files

• Files with .txt, .dat, or.csv extensions are read as delimited text files.
• By default, readtable creates one table variable for each column in the file and reads variable names from the first row of the file. Empty fields are converted to either NaN for a numeric variable or an empty character vector for a text variable. White space is ignored when reading the file.
• All lines in the text file must have the same number of delimiters.

For more options, see the name value arguments for Text Files.

For commonly used text file workflows, see Import Data from Text File to Table.

Spreadsheet Files

• Files with .xls, .xlsb,.xlsm, .xlsx, .xltm,.xltx, or .ods extensions are read as spreadsheet files.
• By default, readtable creates one table variable for each column in the file and reads variable names from the first row of the file.
• On Windows® systems with Microsoft Excel software, readtable reads any Excel spreadsheet file format recognized by your version of Excel. If your system does not have Microsoft Excel for Windows or if you are using MATLAB Online™, then readtable operates with theUseExcel property set to false and reads only files with .xls, .xlsm, .xlsx,.xltm, and .xltx extensions.
• Large files in XLSX format sometimes load slowly. For better import and export performance, Microsoft recommends that you use the XLSB format.

For more options, see the name value arguments for Spreadsheet Files.

For commonly used spreadsheet file workflows, see Read Spreadsheet Data into Table.

XML Files

• Files with the .xml extension are read as Extensible Markup Language (XML) files.
• By default, readtable creates one table variable for each element or attribute node detected as a table variable. Variable names correspond to element and attribute names.

For more options, see the name value arguments for XML Files.

Microsoft Word Document Files

• Files with the .docx extension are read as Microsoft Word document files.
• By default, readtable imports data from the first table in the document, creates one table variable for each column in the file, and reads variable names from the first row of the table.

For more options, see the name value arguments for Microsoft Word Document Files.

HTML Files

• Files with the .html, .xhtml, or.htm extensions are read as Hypertext Markup Language (HTML) files.
• By default, readtable imports data from the first<TABLE> element, creates one table variable for each column in the file, and reads variable names from the first row of the table.

For more options, see the name value arguments for HTML Files.

opts — File import options

DelimitedTextImportOptions object | FixedWidthImportOptions object | SpreadsheetImportOptions object | …

File import options, specified as one of the import options objects in the table, created by either the detectImportOptions function or the associated import options function. The import options object contains properties that configure the data import process. readtable uses only the relevant properties of each import options object.

For more information on how to control your import, see Control How MATLAB Imports Your Data.

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.

Example: readtable(filename,ReadVariableNames=false) indicates that the first row of the file does not correspond to variable names.

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

Example: readtable(filename,"ReadVariableNames",false) indicates that the first row of the file does not correspond to variable names.

Text Files

collapse all

FileType — Type of file

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

Type of file, specified as 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

Example: "FileType","text"

ReadRowNames — Option to read first column as row names

false or 0 (default) | true or 1

Option to read the first column as row names, specified as a numeric or logical 1 (true) or 0 (false).

• Set ReadRowNames to true when the first column of the region to read contains the row names for the table.
• Set ReadRowNames to false when the first column of the region to read contains data, not the row names for the table.

If both the ReadVariableNames and ReadRowNames name-value arguments are true, then readtable saves the name in the first column of the first row of the region to read as the first dimension name in the property T.Properties.DimensionNames.

If you specify the ReadRowNames argument in addition to an import options object, then the readtable behavior changes based on the specification:

• If ReadRowNames is true, then read the row names from the specified file by using the RowNamesColumn (DelimitedTextImportOptions,FixedWidthImportOptions), RowNamesRange (SpreadsheetImportOptions), or RowNamesSelector (XMLImportOptions) property of the respective import options object.
• If ReadRowNames is false, then do not import row names.

If you use the import options syntax without specifying ReadRowNames,readtable uses the value associated with the import options object and its ReadRowNames name-value argument.

Example: "ReadRowNames",true

Delimiter — Field delimiter character

character vector | cell array of character vectors | string

Field delimiter character, specified as Delimiter and a character vector, a cell array of character vectors, or a string. Specify Delimiter using any valid character such as a comma "," or a period".".

This table lists some commonly used field delimiter characters.

To treat consecutive delimiters as a single delimiter, specifyDelimiter as a cell array of character vectors. In addition, you must also specify the MultipleDelimsAsOne option.

Example: "Delimiter","," or"Delimiter","comma"

LeadingDelimitersRule — Procedure to manage leading delimiters

"keep" | "ignore" | "error"

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

Example: "LeadingDelimitersRule","keep"

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.

Example: "TrailingDelimitersRule","keep"

ConsecutiveDelimitersRule — Procedure to handle consecutive delimiters

"split" | "join" | "error"

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

Example: "ConsecutiveDelimitersRule","split"

MultipleDelimsAsOne — Multiple delimiter handling

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

Multiple delimiter handling, specified as MultipleDelimsAsOne and either true or false. If true, thenreadtable treats consecutive delimiters as a single delimiter. Repeated delimiters separated by white-space are also treated as a single delimiter. You must also specify the Delimiter option.

Example: "MultipleDelimsAsOne",1

NumHeaderLines — Number of header lines

0 | positive integer

Number of header lines to skip at the beginning of the file, specified asNumHeaderLines and either 0 or a positive integer. If unspecified, readtable automatically detects the number of lines to skip.

Example: "NumHeaderLines",2

Data Types: single | double

TreatAsMissing — Placeholder text to treat as empty value

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

Placeholder text to treat as an empty value, specified as"TreatAsMissing" and a character vector, cell array of character vectors, string scalar, or string array. Table elements corresponding to these characters are set to the missing value associated with the data type. For more information, see fillmissing.

Example: "TreatAsMissing","N/A" or"TreatAsMissing","N/A" sets N/A within numeric columns to NaN.

Example: "TreatAsMissing",{'.','NA','N/A'} or"TreatAsMissing",[".","NA","N/A"] sets .,NA and N/A within numeric columns toNaN.

MissingRule — Procedure to manage missing data

"fill" (default) | "error" | "omitrow" | "omitvar"

Procedure to manage missing data, specified as one of the values in this table. Data is considered missing if an expected field in a row does not exist. Because missing fields cause subsequent elements of a row to shift fields, the missing fields are interpreted at the end of the row.

Example: "MissingRule","omitrow"

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 DatetimeType and one of these values: "datetime", "text", or"exceldatenum". The value "exceldatenum" is applicable only for spreadsheet files, and is not valid for text files.

Example: "DatetimeType","datetime"

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 theisvarname 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".

Example: "VariableNamingRule","preserve"

ImportErrorRule — Procedure to handle import errors

"fill" (default) | "error" | "omitrow" | "omitvar"

Procedure to handle import errors, specified as one of the values in this table. An import error occurs when readtable is unable to convert a text element to the expected data type.

Example: "ImportErrorRule","omitvar"

WebOptions — HTTP or HTTPS request options

weboptions object

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

ReadVariableNames — Read first row as variable names

true | false | 1 | 0

Indicator for reading the first row as variable names, specified asReadVariableNames and either true,false, 1, or 0. If unspecified,readtable automatically detects the presence of variable names.

Note: If both the"ReadVariableNames" and "ReadRowNames" logical indicators are true, then readtable saves the name in the first column of the first row of the region to read as the first dimension name in the property, T.Properties.DimensionNames.

If you specify the ReadVariableNames argument in addition toopts the import options, then the readtable behavior changes based on the specification:

• If ReadVariableNames is true, then read the variable names from the specified file by using the VariableNamesRange or the VariableNamesLine property of the import options object.
• If ReadVariableNames is false, then read the variable names from the VariableNames property of the import options object.

Example: "ReadVariableNames",true

ExpectedNumVariables — Expected number of variables

positive integer

Expected number of variables, specified as ExpectedNumVariables and a positive integer. If unspecified, readtable automatically detects the number of variables.

Example: "ExpectedNumVariables",5

Data Types: single | double

VariableWidths — Field widths of variables

vector of positive integer values

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.

Example: "VariableWidths",[10,7,4,26,7]

Whitespace — Characters to treat as white space

string scalar | character vector

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

This table shows how to represent special characters that you cannot enter using ordinary text.

Example: "Whitespace"," _"

Example: "Whitespace","?!.,"

EmptyLineRule — Procedure to handle empty lines

"skip" | "read" | "error"

Procedure to handle empty lines in the data, specified as one of the values in this table. readtable interprets white space as empty. A line is considered empty if it contains no fields. A line is defined by two end-of-line characters.

Example: "EmptyLineRule","skip"

VariableNamesLine — Variable names location

0 (default) | positive scalar integer

Variable names location, specified as a positive scalar integer. TheVariableNamesLine 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: "VariableNamesLine",6

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

PartialFieldRule — Procedure to handle partial fields

"keep" | "fill" | "omitrow" | "omitvar" | "wrap" | "error"

Procedure to handle partial fields in the data, specified as one of the values in this table. A field is considered partially filled if it terminates before the end of the expected width. This applies only to fields with fixed widths.

Example: "PartialFieldRule","keep"

VariableUnitsLine — Variable units location

0 (default) | positive scalar integer

Variable units location, specified as a positive scalar integer. TheVariableUnitsLine 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: "VariableUnitsLine",8

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

VariableDescriptionsLine — Variable description location

0 (default) | positive scalar integer

Variable description location, specified as a positive scalar integer. TheVariableDescriptionsLine 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: "VariableDescriptionsLine",7

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

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. Columns are considered extra if a row has more columns than expected.

Example: "ExtraColumnsRule","addvars"

Format — Column format

character vector | string scalar | "auto"

Column format of the file, specified as Format and a character vector or a string scalar having one or more conversion specifiers, or "auto". The conversion specifiers are the same as the specifiers accepted by thetextscan function.

Specifying the format can significantly improve speed for some large files. If you do not specify a value for Format, then readtable uses%q to interpret nonnumeric columns. The %q specifier reads the text and omits double quotation marks (") if appropriate.

• If you do not specify the "Format" name-value pair, then thereadtable function behaves as though you have used the results of thedetectImportOptions function to import the data. For more information on the consequences of this behavior, see Compatibility Considerations.
• If you specify "Format","auto", then the variables created aredouble arrays, cell array of character vectors, ordatetime arrays, depending on the data. If the entire column is numeric, variables are imported as double. If any element in a column is not numeric, the variables are imported as cell arrays of character vectors, or asdatetime arrays if the values represent dates and times.

Example: "Format","auto"

EmptyValue — Returned value for empty numeric fields

NaN (default) | numeric scalar

Returned value for empty numeric fields in delimited text files, specified asEmptyValue and a numeric scalar.

Example: "EmptyValue",0

CollectOutput — Logical indicator determining data concatenation

false (default) | true

Logical indicator determining data concatenation, specified asCollectOutput and either true orfalse. If true, then readtable concatenates consecutive output cells of the same fundamental MATLAB class into a single array.

Example: "CollectOutput",true

CommentStyle — Symbols designating text to ignore

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

Symbols designating text to ignore, specified as CommentStyle and a character vector, cell array of character vectors, string scalar, or string array.

For example, specify a character such as "%" to ignore text following the symbol on the same line. Specify a cell array of two character vectors, such as{'/*','*/'}, to ignore any text between those sequences.

MATLAB checks for comments only at the start of each field, not within a field.

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

ExponentCharacter — Exponent characters

"eEdD" (default) | character vector | string scalar

Exponent characters, specified as ExponentCharacter and a character vector or string scalar. The default exponent characters are e,E, d, and D.

Example: "ExponentCharacter","eE"

LineEnding — End-of-line characters

character vector | string scalar

End-of-line characters, specified as LineEnding and a character vector or string scalar. The character vector must be "\r\n" or it must specify a single character. Common end-of-line characters are a newline character ("\n") or a carriage return ("\r"). If you specify"\r\n", then readtable treats any of\r, \n, and the combination of the two (\r\n) as end-of-line characters.

The default end-of-line sequence is \n, \r, or\r\n, depending on the contents of your file.

If there are missing values and an end-of-line sequence at the end of the last line in a file, then readtable returns empty values for those fields. This ensures that individual cells in output cell array, C, are the same size.

Example: "LineEnding",":"

DateLocale — Locale for reading dates

character vector | string scalar

Locale for reading dates, specified as 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 readtable should interpret month and day-of-week names and abbreviations.

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

Example: "DateLocale","ja_JP"

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 readtable uses the characters specified in the DecimalSeparator name-value argument 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.

Example: If name-value pair is specified as "DecimalSeparator",",", then readtable imports the text "3,14159" as the number3.14159.

ThousandsSeparator — Characters that indicate 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 readtable uses the characters specified in the ThousandsSeparator name-value argument to interpret the numbers being imported.

Example: If name-value pair is specified as "ThousandsSeparator",",", then readtable imports the text "1,234,000" as1234000.

TrimNonNumeric — Remove nonnumeric characters

false (default) | true

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

Example: If name-value pair is specified as "TrimNonNumeric",true, then readtable reads "$500/-" as500.

Data Types: logical

Encoding — Character encoding scheme

"UTF-8" | "ISO-8859-1" | "windows-1251" | "windows-1252" | ...

Character encoding scheme associated with the file, specified asEncoding and "system" or a standard character encoding scheme name. When you do not specify any encoding, the readtable function uses automatic character set detection to determine the encoding when reading the file.

If you specify the "Encoding" argument in addition to the import options, then the readtable function uses the specified value for"Encoding", overriding the encoding defined in the import options.

Example: "Encoding","UTF-8" uses UTF-8 as the encoding.

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

DurationType — Output data type of duration data

"duration" (default) | "text"

Output data type of duration data from text files, specified asDurationType and either "duration" or"text".

Example: "DurationType","text"

HexType — Output data type of hexadecimal data

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

Output data type of hexadecimal data, specified as HexType and one of the values listed in the table.

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

readtable 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 as255) in the output table.

BinaryType — Output data type of binary data

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

Output data type of binary data, specified as 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.

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

Spreadsheet Files

collapse all

FileType — Type of file

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

Type of file, specified as 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

Example: "FileType","text"

ReadRowNames — Option to read first column as row names

false or 0 (default) | true or 1

Option to read the first column as row names, specified as a numeric or logical1 (true) or 0 (false).

• Set ReadRowNames to true when the first column of the region to read contains the row names for the table.
• Set ReadRowNames to false when the first column of the region to read contains data, not the row names for the table.

If both the ReadVariableNames and ReadRowNames name-value arguments are true, then readtable saves the name in the first column of the first row of the region to read as the first dimension name in the property, T.Properties.DimensionNames.

If you specify the ReadRowNames argument in addition to an import options object, then the readtable behavior changes based on the specification:

• If ReadRowNames is true, then read the row names from the specified file by using the RowNamesColumn (DelimitedTextImportOptions,FixedWidthImportOptions), RowNamesRange (SpreadsheetImportOptions), or RowNamesSelector (XMLImportOptions) property of the respective import options object.
• If ReadRowNames is false, then do not import row names.

If you use the import options syntax without specifying ReadRowNames,readtable uses the value associated with the import options object and its ReadRowNames name-value argument.

Example: "ReadRowNames",true

TreatAsMissing — Placeholder text to treat as empty value

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

Placeholder text to treat as an empty value, specified asTreatAsMissing and a character vector, cell array of character vectors, string scalar, or string array. Table elements corresponding to these characters are set to the missing value associated with the data type. For more information, see fillmissing.

Example: "TreatAsMissing","N/A" or"TreatAsMissing","N/A" sets N/A within numeric columns to NaN.

Example: "TreatAsMissing",{'.','NA','N/A'} or"TreatAsMissing",[".","NA","N/A"] sets .,NA and N/A within numeric columns toNaN.

MissingRule — Procedure to manage missing data

"fill" (default) | "error" | "omitrow" | "omitvar"

Procedure to manage missing data, specified as one of the values in this table. Data is considered missing if the expected field in the row has no data and the field type is blank or empty.

Example: "MissingRule","omitrow"

Range — Portion of worksheet to read

character vector | string scalar

Portion of the worksheet to read, indicated as a rectangular area specified as a character vector or string scalar in one of the following forms.

Example: "Range", "A1:F10"

Example: "Range", "A1:F10"—

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 anN-by-2 array of positive scalar integers. SpecifyDataRange using one of these forms.

Example: "DataRange", "B2:H15"

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.

Example: "RowNamesRange", "A1:H1"

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.

Example: "VariableNamesRange","A1:A15"

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.

Example: "VariableUnitsRange","A1:A5"

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. SpecifyVariableDescriptionRange as one of the values in this table.

Example: "VariableDescriptionsRange","B1:B15"

Data Types: char | string | single | double

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 DatetimeType and one of these values: "datetime", "text", or"exceldatenum". The value "exceldatenum" is applicable only for spreadsheet files, and is not valid for text files.

Example: "DatetimeType","datetime"

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 theisvarname 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".

Example: "VariableNamingRule","preserve"

ImportErrorRule — Procedure to handle import errors

"fill" (default) | "error" | "omitrow" | "omitvar"

Procedure to handle import errors, specified as one of the values in this table. An import error occurs when readtable is unable to convert data to the expected data type or the cell has the Microsoft error data type.

Example: "ImportErrorRule","omitvar"

WebOptions — HTTP or HTTPS request options

weboptions object

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

ReadVariableNames — Read first row as variable names

true | false | 1 | 0

Indicator for reading the first row as variable names, specified asReadVariableNames and either true,false, 1, or 0. If unspecified,readtable automatically detects the presence of variable names.

Note: If both the"ReadVariableNames" and "ReadRowNames" logical indicators are true, then readtable saves the name in the first column of the first row of the region to read as the first dimension name in the property, T.Properties.DimensionNames.

If you specify the ReadVariableNames argument in addition toopts the import options, then the readtable behavior changes based on the specification:

• If ReadVariableNames is true, then read the variable names from the specified file by using the VariableNamesRange or the VariableNamesLine property of the import options object.
• If ReadVariableNames is false, then read the variable names from the VariableNames property of the import options object.

Example: "ReadVariableNames",true

ExpectedNumVariables — Expected number of variables

positive integer

Expected number of variables, specified as ExpectedNumVariables and a positive integer. If unspecified, readtable automatically detects the number of variables.

Example: "ExpectedNumVariables",5

Data Types: single | double

Sheet — Worksheet to read

1 (default) | positive integer | character vector | string scalar

Worksheet to read, specified as Sheet and a positive integer indicating the worksheet index or a character vector or string scalar containing the worksheet name. The worksheet name cannot contain a colon (:). To determine the names of sheets in a spreadsheet file, use sheets = sheetnames(filename). For more information, see sheetnames.

If you specify the Sheet argument in addition toopts the import options, then the readtable function uses the specified value for Sheet argument, overriding the sheet name defined in the import options.

Example: "Sheet", 2

Example: 'Sheet', 'MySheetName'

Example: "Sheet", "MySheetName"

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

UseExcel — Flag to start instance of Microsoft Excel for Windows

false (default) | true

Flag to start an instance of Microsoft Excel for Windows when reading spreadsheet data, specified as UseExcel and either true, or false.

You can set the "UseExcel" parameter to one of these values:

• true — readtable starts an instance ofMicrosoft Excel when reading the file.
• false — readtable does not start an instance ofMicrosoft Excel when reading the file. When operating in this mode,readtable functionality differs in the support of file formats and interactive features, such as formulas and macros.

When reading from spreadsheet files on Windows platforms, if you want to start an instance of Microsoft Excel, then set the "UseExcel" parameter totrue.

UseExcel is not supported in noninteractive, automated environments.

Example: "UseExcel",true

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.

XML Files

collapse all

FileType — Type of file

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

Type of file, specified as 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

Example: "FileType","text"

ReadRowNames — Option to read the first column as row names

false or 0 (default) | true or 1

Option to read the first column as row names, specified as a numeric or logical1 (true) or 0 (false).

• Set ReadRowNames to true when the first column of the region to read contains the row names for the table.
• Set ReadRowNames to false when the first column of the region to read contains data, not the row names for the table.

If both the ReadVariableNames and ReadRowNames name-value arguments are true, then readtable saves the name in the first column of the first row of the region to read as the first dimension name in the property, T.Properties.DimensionNames.

If you specify the ReadRowNames argument in addition to an import options object, then the readtable behavior changes based on the specification:

• If ReadRowNames is true, then read the row names from the specified file by using the RowNamesColumn (DelimitedTextImportOptions,FixedWidthImportOptions), RowNamesRange (SpreadsheetImportOptions), or RowNamesSelector (XMLImportOptions) property of the respective import options object.
• If ReadRowNames is false, then do not import row names.

If you use the import options syntax without specifying ReadRowNames,readtable uses the value associated with the import options object and its ReadRowNames name-value argument.

Example: "ReadRowNames",true

TreatAsMissing — Placeholder text to treat as empty value

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

Placeholder text to treat as an empty value, specified asTreatAsMissing and a character vector, cell array of character vectors, string scalar, or string array. Table elements corresponding to these characters are set to the missing value associated with the data type. For more information, see fillmissing.

Example: 'TreatAsMissing','N/A' or"TreatAsMissing","N/A" sets N/A within numeric columns to NaN.

Example: 'TreatAsMissing',{'.','NA','N/A'} or"TreatAsMissing",[".","NA","N/A"] sets .,NA and N/A within numeric columns toNaN.

MissingRule — Procedure to manage missing data

"fill" (default) | "error" | "omitrow" | "omitvar"

Procedure to manage missing data, specified as one of the values in this table. Data is considered missing if an expected node does not exist.

Example: "MissingRule","omitrow"

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 DatetimeType and one of these values: "datetime", "text", or"exceldatenum". The value "exceldatenum" is applicable only for spreadsheet files, and is not valid for text files.

Example: "DatetimeType","datetime"

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 theisvarname 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".

Example: "VariableNamingRule","preserve"

ImportErrorRule — Procedure to handle import errors

"fill" (default) | "error" | "omitrow" | "omitvar"

Procedure to handle import errors, specified as one of the values in this table. An import error occurs when readtable is unable to convert text to the expected data type.

Example: "ImportErrorRule","omitvar"

WebOptions — HTTP or HTTPS request options

weboptions object

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

AttributeSuffix — Attribute suffix

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

Attribute suffix, specified as 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"

ImportAttributes — Import attributes

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

Import attributes, specified as ImportAttributes and either1 (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

RowNodeName — Table row XML node name

character vector | string scalar

Table row XML node name, specified as 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 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.

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:

TableNodeName — Table XML node name

character vector | string scalar

Table XML node name, specified as 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 asRegisteredNamespaces 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 prefix myprefix to the URL https://www.mathworks.com.

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

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

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. Use XPath selectors to specify which elements of the XML input document to import.

Example: "myFile.xml", "TableSelector", "//table[1]"

Microsoft Word Document Files

collapse all

FileType — Type of file

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

Type of file, specified as 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

Example: "FileType","text"

ReadRowNames — Option to read first column as row names

false or 0 (default) | true or 1

Option to read the first column as row names,specified as a numeric or logical1 (true) or 0 (false).

• Set ReadRowNames to true when the first column of the region to read contains the row names for the table.
• Set ReadRowNames to false when the first column of the region to read contains data, not the row names for the table.

If both the ReadVariableNames and ReadRowNames name-value arguments are true, then readtable saves the name in the first column of the first row of the region to read as the first dimension name in the property, T.Properties.DimensionNames.

If you specify the ReadRowNames argument in addition to an import options object, then the readtable behavior changes based on the specification:

• If ReadRowNames is true, then read the row names from the specified file by using the RowNamesColumn (DelimitedTextImportOptions,FixedWidthImportOptions), RowNamesRange (SpreadsheetImportOptions), or RowNamesSelector (XMLImportOptions) property of the respective import options object.
• If ReadRowNames is false, then do not import row names.

If you use the import options syntax without specifying ReadRowNames,readtable uses the value associated with the import options object and its ReadRowNames name-value argument.

Example: "ReadRowNames",true

TreatAsMissing — Placeholder text to treat as empty value

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

Placeholder text to treat as an empty value, specified asTreatAsMissing and a character vector, cell array of character vectors, string scalar, or string array. Table elements corresponding to these characters are set to the missing value associated with the data type. For more information, see fillmissing.

Example: 'TreatAsMissing','N/A' or"TreatAsMissing","N/A" sets N/A within numeric columns to NaN.

Example: 'TreatAsMissing',{'.','NA','N/A'} or"TreatAsMissing",[".","NA","N/A"] sets .,NA and N/A within numeric columns toNaN.

MissingRule — Procedure to manage missing data

"fill" (default) | "error" | "omitrow" | "omitvar"

Procedure to manage missing data, specified as one of the values in this table. Data is considered missing if an expected field in a row does not exist.

Example: "MissingRule","omitrow"

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.

Example: "EmptyRowRule","read"

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.

Example: "EmptyColumnRule","error"

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 DatetimeType and one of these values: "datetime", "text", or"exceldatenum". The value "exceldatenum" is applicable only for spreadsheet files, and is not valid for text files.

Example: "DatetimeType","datetime"

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 theisvarname 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".

Example: "VariableNamingRule","preserve"

ImportErrorRule — Procedure to handle import errors

"fill" (default) | "error" | "omitrow" | "omitvar"

Procedure to handle import errors, specified as one of the values in this table. An import error occurs when readtable is unable to convert text to the expected data type.

Example: "ImportErrorRule","omitvar"

WebOptions — HTTP or HTTPS request options

weboptions object

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

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 setsTableSelector to the equivalent XPath expression.

Example: "TableIndex",2

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.

Example: "VariableNamesRow",2

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.

Example: "VariableUnitsRow",3

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.

Example: "VariableDescriptionsRow",4

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

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. Use XPath selectors to specify which elements of the XML input document to import.

Example: "TableSelector","/RootNode/ChildNode"

Example: "myFile.xml", "TableSelector", "//table[1]"

HTML Files

collapse all

FileType — Type of file

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

Type of file, specified as 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

Example: "FileType","text"

ReadRowNames — Option to read first column as row names

false or 0 (default) | true or 1

Option to read the first column as row names, specified as a numeric or logical1 (true) or 0 (false).

• Set ReadRowNames to true when the first column of the region to read contains the row names for the table.
• Set ReadRowNames to false when the first column of the region to read contains data, not the row names for the table.

If both the ReadVariableNames and ReadRowNames name-value arguments are true, then readtable saves the name in the first column of the first row of the region to read as the first dimension name in the property T.Properties.DimensionNames.

If you specify the ReadRowNames argument in addition to an import options object, then the readtable behavior changes based on the specification:

• If ReadRowNames is true, then read the row names from the specified file by using the RowNamesColumn (DelimitedTextImportOptions,FixedWidthImportOptions), RowNamesRange (SpreadsheetImportOptions), or RowNamesSelector (XMLImportOptions) property of the respective import options object.
• If ReadRowNames is false, then do not import row names.

If you use the import options syntax without specifying ReadRowNames,readtable uses the value associated with the import options object and its ReadRowNames name-value argument.

Example: "ReadRowNames",true

TreatAsMissing — Placeholder text to treat as empty value

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

Placeholder text to treat as an empty value, specified asTreatAsMissing and a character vector, cell array of character vectors, string scalar, or string array. Table elements corresponding to these characters are set to the missing value associated with the data type. For more information, see fillmissing.

Example: "TreatAsMissing","N/A" or"TreatAsMissing","N/A" sets N/A within numeric columns to NaN.

Example: 'TreatAsMissing',{'.','NA','N/A'} or"TreatAsMissing",[".","NA","N/A"] sets .,NA and N/A within numeric columns toNaN.

MissingRule — Procedure to manage missing data

"fill" (default) | "error" | "omitrow" | "omitvar"

Procedure to manage missing data, specified as one of the values in this table. Data is considered missing if an expected field in a row does not exist.

Example: "MissingRule","omitrow"

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.

Example: "EmptyRowRule","read"

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.

Example: "EmptyColumnRule","error"

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 DatetimeType and one of these values: "datetime", "text", or"exceldatenum". The value "exceldatenum" is applicable only for spreadsheet files, and is not valid for text files.

Example: "DatetimeType","datetime"

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 theisvarname 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".

Example: "VariableNamingRule","preserve"

ImportErrorRule — Procedure to handle import errors

"fill" (default) | "error" | "omitrow" | "omitvar"

Procedure to handle import errors, specified as one of the values in this table. An import error occurs when readtable is unable to convert text to the expected data type.

Example: "ImportErrorRule","omitvar"

WebOptions — HTTP or HTTPS request options

weboptions object

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

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 setsTableSelector to the equivalent XPath expression.

Example: "TableIndex",2

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.

Example: "VariableNamesRow",2

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.

Example: "VariableUnitsRow",3

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.

Example: "VariableDescriptionsRow",4

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

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. Use XPath selectors to specify which elements of the XML input document to import.

Example: "TableSelector","/RootNode/ChildNode"

Example: "myFile.xml", "TableSelector", "//table[1]"

Output Arguments

collapse all

Output table, returned as a table. The table can store metadata such as descriptions, variable units, variable names, and row names. For more information, see the Properties section of table.

Extended Capabilities

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

Usage notes and limitations:

• Text and spreadsheet file workflows are supported in thread-based environments.

Version History

Introduced in R2013b

expand all

R2024b: Specify how to import merged cells in spreadsheets

When importing data from spreadsheets, you can specify how readtable imports cells that are merged across rows and columns by using theMergedCellRowRule and MergedCellColumnRule name-value arguments.

R2023a: Create tables from text and spreadsheet files in thread-based environments

This function supports thread-based environments for text and spreadsheet file workflows.

R2020a: Results of detectImportOptions function used by default to import tabular data

By default, the readtable function uses the results of thedetectImportOptions function to import tabular data. In essence, these two function calls behave identically.

T = readtable(filename) T = readtable(filename,detectImportOptions(filename))

In R2020a, there are several differences between the default behavior ofreadtable and its default behavior in previous releases.

To call readtable with the default behavior it had up to R2019b, use the 'Format','auto' name-value pair argument.

T = readtable(filename,'Format','auto')