readtable
Create table from file
Syntax
Description
T = readtable(filename)readtable detects elements of your data, such as
delimiter and data types, to determine how to import your data.
T = readtable(filename,Name=Value)TextType
name-value argument.
T = readtable(filename,opts)opts. Use an import options object to configure how
readtable interprets your file. Compared to name-value arguments, an import
options object provides more control, better performance, and reusability of the file import
configuration.
T = readtable(filename,opts,Name=Value)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
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
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 a JSON file into a table.
The students.json file has three sibling nodes, which each contain the same child nodes and attributes.
type students.json[
{
"ID": "S11305",
"Name": {
"FirstName": "Priya",
"LastName": "Thompson"
},
"Age": 18.0,
"Year": "Freshman",
"Address": {
"Street": "591 Spring Lane",
"City": "Natick",
"State": "MA"
},
"Major": "Computer Science",
"Minor": "English Literature"
},
{
"ID": "S23451",
"Name": {
"FirstName": "Conor",
"LastName": "Cole"
},
"Age": 18.0,
"Year": "Freshman",
"Address": {
"Street": "4641 Pearl Street",
"City": "San Francisco",
"State": "CA"
},
"Major": "Microbiology",
"Minor": "Public Health"
},
{
"ID": "S119323",
"Name": {
"FirstName": "Morgan",
"LastName": "Yang"
},
"Age": 21.0,
"Year": "Senior",
"Address": {
"Street": "30 Highland Road",
"City": "Detroit",
"State": "MI"
},
"Major": "Political Science"
}
]
First, create a JSONImportOptions object by using detectImportOptions to detect aspects of your JSON file. Read just the street names into a table by specifying the VariableSelectors name-value argument as the JSON Pointer of the Street object key.
opts = detectImportOptions("students.json",VariableSelectors="/Address/Street");
Then, import the specified variable using readtable with the import options object.
T = readtable("students.json",opts)T=3×1 table
Street
___________________
"591 Spring Lane"
"4641 Pearl Street"
"30 Highland Road"
Import the contents of an XML file into a table.
The students.xml file has three sibling nodes named Student, which each contain the same child nodes and attributes.
type students.xml<?xml version="1.0" encoding="utf-8"?>
<Students>
<Student ID="S11305">
<Name FirstName="Priya" LastName="Thompson" />
<Age>18</Age>
<Year>Freshman</Year>
<Address>
<Street xmlns="https://www.mathworks.com">591 Spring Lane</Street>
<City>Natick</City>
<State>MA</State>
</Address>
<Major>Computer Science</Major>
<Minor>English Literature</Minor>
</Student>
<Student ID="S23451">
<Name FirstName="Conor" LastName="Cole" />
<Age>18</Age>
<Year>Freshman</Year>
<Address>
<Street xmlns="https://www.mathworks.com">4641 Pearl Street</Street>
<City>San Francisco</City>
<State>CA</State>
</Address>
<Major>Microbiology</Major>
<Minor>Public Health</Minor>
</Student>
<Student ID="S119323">
<Name FirstName="Morgan" LastName="Yang" />
<Age>21</Age>
<Year>Senior</Year>
<Address>
<Street xmlns="https://www.mathworks.com">30 Highland Road</Street>
<City>Detriot</City>
<State>MI</State>
</Address>
<Major>Political Science</Major>
</Student>
</Students>
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=3×1 table
Street
___________________
"591 Spring Lane"
"4641 Pearl Street"
"30 Highland Road"
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
"readtable" "Create table from file"
"writetable" "Write table to file"
"readtimetable" "Create timetable from file"
"writetimetable" "Write timetable to file"
