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

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.

Examples

collapse all

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   

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' }    {0×0 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   

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: Show all 29 VariableOptions 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);

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  

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 

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: Show all 10 VariableOptions 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    

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"  

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"

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

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

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 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 in the file is ignored.
• All lines in the text file must have the same number of delimiters.

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 commonly used spreadsheet file workflows, see Read Spreadsheet Data into Table.

XML Files

(since R2021a)

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

Microsoft Word Documents

(since R2021b)

• Files with the .docx extension are read as Microsoft Word 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.

HTML Files

(since R2021b)

• Files with .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 table, and reads variable names from the first row of the table.

Compressed and Archived Files

(since R2025a)

• Compressed file formats are read as files.
• Archived file formats are treated as folders. For example, the function interpretsmydatafiles.zip as a folder, so you must specify a file within it, such as mydatafiles.zip/file1.xlsx.
• For files ending with the .gz extension, the function determines the file format by using the extension preceding .gz. For example,mydata.csv.gz is read as a CSV file.

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

expand all

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) specifies to read the first row of the file as data instead of variable names.

Data and Header Location

expand all

Number of header lines to skip at the beginning of the file, specified as a nonnegative integer. If you do not specify this name-value argument, readtable automatically detects the number of lines to skip.

Reading of variable names and data begins with the first nonheader line.

Data Types: single | double

Range to read from the file, specified as a string scalar, character vector, or numeric vector in one of these forms.

Location of the data, specified as a string scalar, character vector, positive integer, or N-by-2 array of positive integers in one of these forms.

Worksheet to read, specified as a positive integer indicating the worksheet index or a string scalar or character vector containing the worksheet name. By default,readtable reads the first sheet.

If you specify a string scalar or character vector, the worksheet name cannot contain a colon (:). To determine the names of sheets in a spreadsheet file, usesheets = sheetnames(filename). For more information, see sheetnames.

If you specify the Sheet argument in addition to [opts](readtable.html#mw%5Fda8f54b7-5bd3-4640-9eb5-715f76a3a7f0), then thereadtable function uses the specified value for Sheet, overriding the sheet name defined in the import options.

Example: 2

Example: "MySheetName"

Index of the table to read from a file containing multiple tables, specified as a positive integer. By default, readtable reads the first table.

If you specify TableIndex, the readtable function automatically sets [TableSelector](readtable.html#mw%5Ffba2c992-4db3-49ab-9727-9356cbb8ade5) to the equivalent XPath expression.

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

XPath expression for the table to read, specified as a string scalar or character vector. You must specify TableSelector as a valid XPath version 1.0 expression.

If you do not specify this name-value argument, readtable detects the table location.

Example: "//table[1]"

XML node name for the table data to read, specified as a string scalar or character vector.

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

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

Variables

expand all

Whether to read variable names, specified as a numeric or logical 1 (true) or 0 (false). If you do not specify this name-value argument, readtable automatically detects the presence of variable names after header rows.

If both ReadVariableNames and ReadRowNames aretrue, 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.

Rule for variable names, specified as one of these values:

• "modify" — Convert invalid variable names (as determined by theisvarname function) to valid MATLAB identifiers. This value is the default for text and spreadsheet files.
• "preserve" — Preserve variable names that are not valid MATLAB identifiers, such as variable names that include spaces and non-ASCII characters. This value is the default for XML, Microsoft Word, and HTML files.

Variable and row names do not have to be valid MATLAB identifiers. They can include any characters, including spaces and non-ASCII characters. Also, they can start with any character, not just letters.

Expected number of variables, specified as a nonnegative integer. If you do not specify this name-value argument, readtable automatically detects the number of variables.

Location of variable names, specified as a nonnegative integer.

If VariableNamesLine is 0, thenreadtable does not import variable names. Otherwise,readtable imports the variable names from the specified line.

If variable names exist, and both VariableNamesLine andReadVariableNames are unspecified, readtable detects which line contains variable names and imports them.

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

Location of variable names, specified as a string scalar, character vector, or positive integer in one of these forms.

Data Types: string | char | single | double

Location of variable names, specified as a nonnegative integer.

If VariableNamesRow is 0, thenreadtable does not import variable names. Otherwise,readtable imports the variable names from the specified row.

If you do not specify VariableNamesRow, andReadVariableNames is true (default), thenreadtable imports variable names. If both are unspecified, readtable detects if a row contains variable names to import.

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

Names of XML nodes to read as table variables, specified as a string array or cell array of character vectors. If nested nodes have the same name,VariableNodeNames selects the nodes at the top level.

Example: ["XMLNodeName1","XMLNodeName2"]

XPath expressions for variables to read, specified as a string array or cell array of character vectors. You must specify VariableSelectors as valid XPath version 1.0 expressions.

Use XPath expressions to specify which elements of the XML input file to import. For example, suppose you want to import the XML filemyFile.xml, which has this structure:

If you do not specify this name-value argument, readtable detects the location of variables.

Whether to concatenate data, specified as a numeric or logical 1 (true) or 0 (false). IfCollectOutput is true, thenreadtable concatenates consecutive output cells of the same fundamental MATLAB class into a single array.

Rows

expand all

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

If both ReadVariableNames and ReadRowNames aretrue, 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.

Location of row names, specified as a nonnegative integer.

If RowNamesColumn is 0, thenreadtable does not import row names. Otherwise,readtable imports row names from the specified column.

If you do not specify RowNamesColumn, andReadRowNames is true, readtable imports the first column as the row names.

Location of row names, specified as a string scalar, character vector, or positive integer in one of these forms.

Data Types: string | char | single | double

XPath expression for row names, specified as a string scalar or character vector. You must specify RowNamesSelector as a valid XPath version 1.0 expression.

If you do not specify this name-value argument, readtable does not import row names.

Example: "/RootNode/ChildNode"

XPath expression for selecting individual rows from a table, specified as a string scalar or character vector. You must specify RowSelector as a valid XPath version 1.0 expression.

If you do not specify this name-value argument, readtable detects the location of rows.

Example: "/RootNode/ChildNode"

XML nodes specifying rows, specified as a string scalar or character vector.

Data Types

expand all

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

• "char" — Import text data as character vectors. This value is the default for text and spreadsheet files.
• "string" — Import text data as string arrays. This value is the default for XML, Microsoft Word, and HTML files.

Type for imported date and time data, specified as one of the values in this table.

Type for imported duration data, specified as one of the values in this table.

Type for imported hexadecimal data, specified as one of the values in this table.

The input file can represent hexadecimal values as text, using either0x 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.

Type for imported binary data, specified as one of the values in this table.

The input file can represent binary values as text, using either 0b or 0B as a prefix and the characters 0 and1 as digits. For example, 0b11111111 represents 255.

Locale for reading dates, specified as a string scalar or character vector of the form_`xx`__ _`YY`_, where:

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

Use DateLocale to specify the locale in whichreadtable interprets month and day-of-week names and abbreviations.

This table lists some common values for the locale.

If you specify the DateLocale argument in addition to an import options object opts, the argument value overrides the locale defined in the import options.

Whether to remove nonnumeric characters from a numeric variable, specified as a numeric or logical 1 (true) or 0 (false). For example, if TrimNonNumeric istrue, then readtable reads "$500/-" as 500.

Decimal separator character in numeric variables, specified as a string scalar or single-character character vector. The separator character distinguishes the integer part of a number from the decimal part. For example, if the separator is ",", thenreadtable imports the text "3,14159" as the number3.14159.

When converting to integer data types, readtable rounds numbers with a decimal part to the nearest integer. DecimalSeparator does not accept numeric digits as values.

Thousands grouping character in numeric variables, specified as a string scalar or character vector. The grouping character acts as a visual separator, grouping a number at every three place values. For example, if the grouping character is ",", then readtable imports the text "1,234,000" as1234000.

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

Example: "eE"

Data Cleaning

expand all

Placeholder text to treat as missing value, specified as a string array, character vector, or cell array of character vectors. readtable imports table elements corresponding to this placeholder text as the missing value associated with the data type of the element.

Example: "N/A"

Example: [".","NA","N/A"]

Rule for 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.

Rule for missing data, specified as one of the values in this table.

For text files, data is 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.

For spreadsheet files, data is missing if the expected field in a row has no data and the field type is blank or empty.

For XML files, data is missing if an expected node does not exist.

For Microsoft Word files, data is missing if an expected field in a row does not exist.

For HTML files, data is missing if an expected field in a row does not exist.

Rule for extra columns in the data, specified as one of the values in this table.readtable considers columns to be extra if a row has more columns than expected.

Returned value for empty numeric fields in delimited text files, specified asNaN or a numeric scalar.

Example: 0

Rule for empty lines in the data, specified as one of the values in this table.readtable considers a line to be empty if it contains only white-space characters.

Rule for empty rows in the data, specified as one of the values in this table.

Rule for empty columns in the data, specified as one of the values in this table.

Rule for partial fields in the data, specified as one of the values in this table.readtable considers a field to be partially filled if it reaches the end of a line in fewer characters than the expected width. This name-value argument applies only to fields with fixed widths.

File Information

expand all

Type of file, specified as one of the values in this table.

Specify this name-value argument when [filename](readtable.html#mw%5Fb0826a11-ea6e-45f6-92ce-54960958581f) does not include the file extension or when its extension is not in this list:

• .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 documents
• .html, .xhtml, or .htm for HTML files

Character encoding scheme associated with the file, specified as"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 an import options object opts, the argument value overrides the encoding defined in the import options.

Whether to start an instance of Microsoft Excel for Windows when reading spreadsheet data, specified as a numeric or logical1 (true) or 0 (false).

Based on this argument, readtable supports different file formats and interactive features, such as formulas and macros.

UseExcel is not supported in noninteractive, automated environments.

Since R2022a

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://".

Text Parsing

expand all

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

This table lists some commonly used field delimiter characters.

To treat multiple characters as a single delimiter, specify Delimiter as a string array or cell array of character vectors. If you want to treat an unknown number of consecutive delimiters as one, specifyConsecutiveDelimitersRule="join".

Delimiter is valid only with delimited text files and is not valid with fixed-width text files.

End-of-line characters, specified as a string array, character vector, or cell array of character vectors. Common end-of-line characters include the newline character ("\n") and the carriage return ("\r"). If you specify"\r\n", then readtable treats the combination of the two (\r\n) as end-of-line characters. If you specify {"\r\n", "\r", "\n"}, then \r, \n, and\r\n are all treated as end-of-line characters.

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

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

Example: "?!.,"

Comment indicators for text to ignore, specified as a string array, character vector, or cell array of character vectors.

For example, specify a character, such as "%", to ignore text following that character on the same line. Specify a string array, such as["/*","*/"], to ignore any text between sequences.

readtable checks for comments only at the start of each line, not within lines.

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

Rule for leading delimiters in a delimited text file, specified as one of the values in this table.

Rule for trailing delimiters in a delimited text file, specified as one of the values in this table.

Rule for consecutive delimiters in a delimited text file, specified as one of the values in this table.

Whether to treat multiple delimiters as one, specified as a numeric or logical1 (true) or 0 (false).

Field widths of variables in a fixed-width text file, specified as a vector of positive integers. Each integer corresponds to the number of characters in a field that make up the variable.

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

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

Specifying the format can significantly improve the import speed for some large files.

If you do not specify Format, then readtable behaves as though you have used the results of the detectImportOptions function to import the data. For more information on the consequences of this behavior, see the R2020a Version History note.

If you set Format to "auto", then the variables created are double arrays, cell arrays of character vectors, ordatetime arrays, depending on the data. If an entire column is numeric, the resulting variable is of type double. If any element in a column is not numeric, the resulting variable is a cell array of character vectors or adatetime array if the values represent dates and times.

XML Parsing

expand all

Whether to import XML attributes as variables in the output table, specified as a numeric or logical 1 (true) or 0 (false). By default, readtable imports XML attributes as variables in the output table.

Suffix used to distinguish attributes from elements in the output table, specified as a string scalar or character vector. This argument specifies the suffixreadtable appends to all table variables that correspond to attributes in the input XML file. If you do not specify AttributeSuffix, thenreadtable appends the suffix "Attribute" to all variable names corresponding to attributes in the input XML file.

Example: "_att"

Rule for repeated XML nodes in a given row of a table, specified as one of the values in this table.

Set of registered XML namespace prefixes, specified as an N-by-2 string array of prefixes and their associated URLs. readtable uses these prefixes when evaluating XPath expressions on an XML file.

You can use RegisteredNamespaces when you also evaluate an XPath expression specified by a selector name-value argument, such asVariableSelectors.

By default, readtable automatically detects namespace prefixes to use in XPath evaluation. To select an XML node with an undeclared namespace prefix, register a custom namespace URL for the namespace prefix using theRegisteredNamespaces name-value argument. For example, assign the prefixmyprefix to the URL https://www.mathworks.com in an XML file that does not contain a namespace prefix.

T = readtable(filename,VariableSelectors="/myprefix:Data", ... RegisteredNamespaces=["myprefix","https://www.mathworks.com"])

Variable Metadata

expand all

Location of variable units, specified as a nonnegative integer.

If VariableUnitsLine is 0, thenreadtable does not import variable units. Otherwise,readtable imports the variable units from the specified line.

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

Location of variable units, specified as a string scalar, character vector, or positive integer in one of these forms.

Data Types: string | char | single | double

Location of variable units, specified as a nonnegative integer.

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

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

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

If you do not specify this name-value argument, readtable does not import variable units.

Example: "/RootNode/ChildNode"

Example: "//table[1]/units/"

Location of variable descriptions, specified as a nonnegative integer.

If VariableDescriptionsLine is 0, thenreadtable does not import variable descriptions. Otherwise,readtable imports the variable descriptions from the specified line.

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

Location of variable descriptions, specified as a string scalar, character vector, or positive integer in one of these forms.

Data Types: string | char | single | double

Location of variable descriptions, specified as a nonnegative integer.

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

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

XPath expression for variable descriptions, specified as a string scalar or character vector. You must specify VariableDescriptionsSelector as a valid XPath version 1.0 expression.

If you do not specify this name-value argument, readtable does not import variable descriptions.

Example: "/RootNode/RowNode/@Name"

Example: "//table[1]/descriptions/*"

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

expand all

Usage notes and limitations:

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

Version History

Introduced in R2013b

expand all

You can read data from compressed and archived files as a table.

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.

Read XML data as a table with optional name-value arguments to control the import behavior. For example, set ImportAttributes to false to ignore attribute nodes.

Additionally, you can read all supported file types from an internet URL. Specify the filename as a string that includes the protocol type http:// orhttps://.

The PreserveVariableNames argument is not recommended. UseVariableNamingRule instead. Specify one of the following values:

• 'preserve' preserves spaces and non-ASCII characters in variable names. Tables support variable names with these characters starting in R2019b.
• 'modify' converts text with spaces and non-ASCII characters to valid MATLAB identifiers.

There are no plans to remove support for PreserveVariableNames.

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

This change results in several behavior differences.

To restore the previous behavior, set Format to"auto".

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

Text that is prefixed with the characters '0x' is now treated as hexadecimal data and text with the prefix '0b' is treated as binary data.

Additionally, when reading text data, readtable now uses automatic character set detection.

The default setting for UseExcel on Windows systems with Excel installed isfalse. To preserve the previous behavior, set UseExcel totrue.

T = readtable(filename,UseExcel=true)