readtimetable
Create timetable from file
Syntax
Description
creates a timetable by reading column-oriented data from a file.TT
= readtimetable(filename
)
readtimetable
determines the file format from the file extension:
.txt
,.dat
, or.csv
for delimited text files.xls
,.xlsb
,.xlsm
,.xlsx
,.xltm
,.xltx
, or.ods
for spreadsheet files.xml
for Extensible Markup Language (XML) files.
For text and spreadsheet files, readtimetable
creates one variable in
TT
for each column in the file and reads variable names from the first
row of the file. For XML files, readtimetable
creates one variable in
T
for each element or attribute node detected as a timetable variable.
Variable names correspond to element and attribute names.
readtimetable
sets the first column of type
datetime
or duration
in the tabular data to be the
row times of the timetable. The remaining columns become variables of the timetable.
creates a timetable from a file with additional options specified by one or more name-value
pair arguments. Use any of the input arguments from the previous syntaxes before specifying
the name-value pairs.TT
= readtimetable(___,Name,Value
)
To set specific import options for your data, you can either use the
opts
object or you can specify name-value pairs. When you specify
name-value pairs in addition to opts
, then
readtimetable
supports only these name-value pairs:
Text and spreadsheet parameters —
ReadVariableNames
,RowTimes
,SampleRate
,TimeStep
,StartTime
Text only parameters —
DateLocale
,Encoding
Spreadsheet only parameters —
Sheet
,UseExcel
Examples
Create Timetable from Text File
Create a table from the comma-separated text file.
TT = readtimetable('outages.csv');
Display a summary of the table. When creating a timetable, if you do not specify any parameters for row times, then the readtimetable
function detects and designates the first datetime or duration variable in the data, OutageTime
, as the row times variable. The remaining variables become the variables of the timetable.
summary(TT)
TT: 1468x5 timetable Row Times: OutageTime: datetime Variables: Region: cell array of character vectors Loss: double Customers: double RestorationTime: datetime Cause: cell array of character vectors Statistics for applicable variables and row times: NumMissing Min Median Max Mean Std OutageTime 0 2002-02-01 12:18 2010-03-18 21:05 2014-01-15 02:41 2009-07-03 12:49 27450:31:25 Region 0 Loss 604 0 180.2583 2.3418e+04 563.8885 1.8793e+03 Customers 328 0 7.5765e+04 5.9689e+06 1.6693e+05 3.6873e+05 RestorationTime 29 2002-02-07 16:50 2010-03-31 10:54 2042-09-18 23:31 2009-07-27 15:47 28592:30:37 Cause 0
Create Timetable from File Using Import Options
Detect import options for a text file, specify the variable types, and then create a timetable from the data.
Create an import options object from a file and examine the variable options.
opts = detectImportOptions('outages.csv');
opts.VariableOptions
ans = 1x6 heterogeneous VariableImportOptions (TextVariableImportOptions, DatetimeVariableImportOptions, NumericVariableImportOptions) array with properties: Name Type FillValue TreatAsMissing QuoteRule Prefixes Suffixes EmptyFieldRule
Modify the options object to specify the desired datatypes for the variables in the data. Change the datatypes for the variables Region
and Cause
to categorical.
opts = setvartype(opts,{'Region','Cause'},{'categorical','categorical'});
Use readtimetable
along with the options object to import the timetable. Then display a summary of the timetable.
TT = readtimetable('outages.csv',opts);
summary(TT)
TT: 1468x5 timetable Row Times: OutageTime: datetime Variables: Region: categorical (5 categories) Loss: double Customers: double RestorationTime: datetime Cause: categorical (10 categories) Statistics for applicable variables and row times: NumMissing Min Median Max Mean Std OutageTime 0 2002-02-01 12:18 2010-03-18 21:05 2014-01-15 02:41 2009-07-03 12:49 27450:31:25 Region 0 Loss 604 0 180.2583 2.3418e+04 563.8885 1.8793e+03 Customers 328 0 7.5765e+04 5.9689e+06 1.6693e+05 3.6873e+05 RestorationTime 29 2002-02-07 16:50 2010-03-31 10:54 2042-09-18 23:31 2009-07-27 15:47 28592:30:37 Cause 0
Create Timetable from File and Specify Row Times
Read a table from the comma-separated text file and create a timetable with a row times variable of your choice.
Create an import options object and preview the tabular data.
opts = detectImportOptions('outages.csv'); preview('outages.csv',opts)
ans=8×6 table
Region OutageTime Loss Customers RestorationTime Cause
_____________ ________________ ______ __________ ________________ ___________________
{'SouthWest'} 2002-02-01 12:18 458.98 1.8202e+06 2002-02-07 16:50 {'winter storm' }
{'SouthEast'} 2003-01-23 00:49 530.14 2.1204e+05 NaT {'winter storm' }
{'SouthEast'} 2003-02-07 21:15 289.4 1.4294e+05 2003-02-17 08:14 {'winter storm' }
{'West' } 2004-04-06 05:44 434.81 3.4037e+05 2004-04-06 06:10 {'equipment fault'}
{'MidWest' } 2002-03-16 06:18 186.44 2.1275e+05 2002-03-18 23:23 {'severe storm' }
{'West' } 2003-06-18 02:49 0 0 2003-06-18 10:54 {'attack' }
{'West' } 2004-06-20 14:39 231.29 NaN 2004-06-20 19:16 {'equipment fault'}
{'West' } 2002-06-06 19:28 311.86 NaN 2002-06-07 00:51 {'equipment fault'}
Create a timetable by specifying the RestorationTime
variable to be the row times variable for the timetable. Then, display a summary of the timetable.
TT = readtimetable('outages.csv','RowTimes','RestorationTime'); summary(TT)
TT: 1468x5 timetable Row Times: RestorationTime: datetime Variables: Region: cell array of character vectors OutageTime: datetime Loss: double Customers: double Cause: cell array of character vectors Statistics for applicable variables and row times: NumMissing Min Median Max Mean Std RestorationTime 29 2002-02-07 16:50 2010-03-31 10:54 2042-09-18 23:31 2009-07-27 15:47 28592:30:37 Region 0 OutageTime 0 2002-02-01 12:18 2010-03-18 21:05 2014-01-15 02:41 2009-07-03 12:49 27450:31:25 Loss 604 0 180.2583 2.3418e+04 563.8885 1.8793e+03 Customers 328 0 7.5765e+04 5.9689e+06 1.6693e+05 3.6873e+05 Cause 0
Create Timetable from Spreadsheet File and Format Input Data
Create a timetable from a spreadsheet file and format the input data. For instance, create a timetable from the file quarterlyFinances1999To2019.csv
, specify the start date of the time stamps and the time between each of them, and remove the "$" symbol from the data.
Read the data in the file quarterlyFinances1999To2019.csv
as a timetable. Specify the length of time between consecutive row times to be one calendar quarter, beginning on the date January 1, 1999. Set 'VariableNamingRule'
to preserve
to preserve the whitespace in the variable names, and set 'TrimNonNumeric'
to true
to remove the "$" symbol before the numeric values in the data.
TT = readtimetable("quarterlyFinances1999To2019.csv","TimeStep", calquarters(1),"StartTime", datetime(1999, 1, 1),... "VariableNamingRule", "preserve", "TrimNonNumeric", true);
Display a summary of the data.
summary(TT)
TT: 80x9 timetable Row Times: Time: datetime Variables: Net Sales: double Cost of Sales: double Gross Margin: double Research and Development Expenses: double Administrative Expenses: double Total Operating Expenses: double Net Income: double Total Shares: double Earnings per Share: double Statistics for applicable variables and row times: NumMissing Min Median Max Mean Std Time 0 01-Jan-1999 16-Nov-2008 01-Oct-2018 15-Nov-2008 04:30:00 50925:56:30 NetSales 0 3.5066e+04 1.0407e+05 1.7684e+05 1.0377e+05 3.8034e+04 CostOfSales 0 1.8106e+04 4.8624e+04 7.7742e+04 4.8410e+04 1.7219e+04 GrossMargin 0 1.4563e+04 5.6719e+04 9.9097e+04 5.5361e+04 2.1060e+04 ResearchAndDevelopmentExpenses 0 4.9049e+03 2.4637e+04 4.5234e+04 2.4761e+04 1.1524e+04 AdministrativeExpenses 0 1.0474e+03 2.0153e+03 2.8115e+03 1.9745e+03 497.5852 TotalOperatingExpenses 0 5.9925e+03 2.6518e+04 4.8045e+04 2.6736e+04 1.1987e+04 NetIncome 0 7.6343e+03 2.8586e+04 5.1051e+04 2.8625e+04 9.8181e+03 TotalShares 0 822 1.8205e+03 2710 1.8013e+03 496.7446 EarningsPerShare 0 6.5200 15.5150 24.6200 15.7921 3.2653
Input Arguments
filename
— Name of file to read
character vector | string scalar
Name of the file to read, specified as a character vector or a string scalar.
Depending on the location of your file, filename
can take on one of
these forms.
Location | Form | ||||||||
---|---|---|---|---|---|---|---|---|---|
Current folder or folder on the MATLAB® path | Specify the name of the file in
Example:
| ||||||||
File in a folder | If the file is not in the current folder or in a folder on the
MATLAB path, then specify the full or relative path name in
Example:
Example:
| ||||||||
Internet URL | If the file is specified as an internet uniform resource locator (URL),
then Example:
| ||||||||
Remote Location | If the file is stored at a remote location, then
Based on the remote location,
For more information, see Work with Remote Data. Example:
|
If
filename
includes the file extension, then the importing function determines the file format from the extension. Otherwise, you must specify the'FileType'
name-value pair arguments to indicate the type of file.On Windows® systems with Microsoft® Excel® software, the importing function reads any Excel spreadsheet file format recognized by your version of Excel.
If your system does not have Excel for Windows or if you are using MATLAB Online™, the importing function operates with the
UseExcel
property set tofalse
, and reads only.xls, .xlsx, .xlsm, .xltx, and .xltm
files.For delimited text files, the importing function converts empty fields in the file to either
NaN
(for a numeric variable) or an empty character vector (for a text variable). All lines in the text file must have the same number of delimiters. The importing function ignores insignificant white space in the file.
Data Types: char
| string
opts
— File import options
SpreadsheetImportOptions
| DelimitedtextImportOptions
| FixedWidthImportOptions
| XMLImportOptions
File import options, specified as an SpreadsheetImportOptions
,
DelimitedTextImportOptions
,
FixedWidthImportOptions
, or XMLImportOptions
object created by the detectImportOptions
function. The
opts
object contains properties that control the data import
process. For more information on the properties of each object, see the appropriate
object page.
Type of Files | Output |
---|---|
Spreadsheet files | SpreadsheetImportOptions object (only available for the
Sheet , DataRange , and
VariableNames properties) |
Text files | DelimitedTextImportOptions object |
Fixed-width text files | FixedWidthImportOptions object |
XML files | XMLImportOptions 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 as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: 'NumHeaderLines',5
indicates that the first five lines that
precede the tabular data are header lines.
WebOptions
— HTTP
or HTTPS
request options
weboptions
object
HTTP
or HTTPS
request options, specified as
a weboptions
object. The
weboptions
object determines how to import data when the
specified filename
is an internet URL containing the protocol type
"http://"
or "https://"
.
FileType
— Type of file
'text'
| 'spreadsheet'
Type of file, specified as the comma-separated pair consisting of
'FileType'
and 'text'
or
'spreadsheet'
.
Specify the 'FileType'
name-value pair argument when the
filename
does not include the file extension or if the extension
is other than one of the following:
.txt
,.dat
, or.csv
for delimited text files.xls
,.xlsb
,.xlsm
,.xlsx
,.xltm
,.xltx
, or.ods
for spreadsheet files
Example: 'FileType','text'
Data Types: char
| string
NumHeaderLines
— Number of header lines
positive integer
Number of header lines in the file, specified as the comma-separated pair consisting of 'NumHeaderLines'
and a positive integer. If unspecified, the importing function automatically detects the number of header lines in the file.
Example: 'NumHeaderLines',7
Data Types: single
| double
ExpectedNumVariables
— Expected number of variables
positive integer
Expected number of variables, specified as the comma-separated pair consisting of
'ExpectedNumVariables'
and a positive integer. If unspecified,
the importing function automatically detects the number of variables.
Data Types: single
| double
Range
— Portion of data to read
character vector | string scalar | numeric vector
Portion of the data to read from text or spreadsheet files, specified as the comma
separated pair consisting of 'Range'
and a character vector, string
scalar, or numeric vector in one of these forms.
Ways to specify Range | Description |
---|---|
Starting Cell
| Specify the starting cell for the data as a character vector or string scalar or a two element numeric vector.
Using the starting cell, the importing function automatically detects the extent of the data by beginning the import at the start cell and ending at the last empty row or footer range. Example:
|
Rectangular Range
| Specify the exact range to read using the rectangular range in one of these forms.
The importing function only reads the data contained in the specified range. Any empty fields within the specified range are imported as missing cells. |
Row Range or Column Range
| Specify the range by identifying the beginning and ending rows using Excel row numbers. Using the specified row range, the importing function automatically detects the column extent by reading from the first nonempty column to the end of the data, and creates one variable per column. Example:
Alternatively, specify the range by identifying the beginning and ending columns using Excel column letters or numbers. Using the specified column range, the import function automatically detects the row extent by reading from the first nonempty row to the end of the data or the footer range. The number of columns in
the specified range must match the number specified in the
Example:
|
Starting Row Number
| Specify the first row containing the data using the positive scalar row index. Using the specified row index, the importing function automatically detects the extent of the data by reading from the specified first row to the end of the data or the footer range. Example: |
Excel’s Named Range
| In Excel, you can create names to identify ranges in the
spreadsheet. For instance, you can select a rectangular portion of
the spreadsheet and call it Example:
|
Unspecified or Empty
| If unspecified, the importing function automatically detects the used range. Example:
Note: Used Range refers to the rectangular portion of the spreadsheet that actually contains data. The importing function automatically detects the used range by trimming any leading and trailing rows and columns that do not contain data. Text that is only white space is considered data and is captured within the used range. |
Data Types: char
| string
| 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 one of these values:
Value | Description |
---|---|
"datetime" | MATLAB
For more information, see
|
"text" | If
|
"exceldatenum"
| Excel serial date numbers The value
|
TreatAsMissing
— Text to interpret as missing data
character vector | string scalar | cell array of character vectors | string array
Text to interpret as missing data, specified as a character vector, string scalar, cell array of character vectors, or string array.
Example: 'TreatAsMissing',{'NA','TBD'}
instructs the importing function to treat any occurrence of NA
or TBD
as a missing fields.
Data Types: char
| string
| cell
ReadVariableNames
— Read first row as variable names
true
| false
Read the first row as variable names, specified as the comma-separated pair
consisting of 'ReadVariableNames'
and either
true
or false
. If unspecified, the importing
function automatically detects the presence of variable names.
Indicator | Description |
---|---|
| Use when the first row of the region to read contains the
variable names for the table. The importing function creates a variable,
with the detected variable name, for each column in |
| Use when the first row of the region to read contains data in the
table. The importing function creates default variable names of the form
|
Unspecified | When left unspecified, the importing function automatically detects
true or false and proceeds
accordingly. |
When you specify ReadVariableNames
name-value pair in addition
to opts
, then the importing function proceeds as follows.
If
ReadVariableNames
is set totrue
, then the importing function reads the variable names from the specified file by using theVariableNamesRange
or theVariableNamesLine
property of the import options object.If
ReadVariableNames
is set tofalse
, then the importing function reads the variable names from theVariableNames
property of the import options object.
Data Types: logical
RowTimes
— Row times variable
variable name | time vector
Row times variable, specified as the comma-separated pair consisting of 'RowTimes'
and a variable name or a time vector.
Variable name must be a character vector or string scalar containing the name of any variable in the input table that contains
datetime
orduration
values. The variable specified by the variable name provides row time labels for the rows. The remaining variables of the input table become the variables of the timetable.Time vector must be a
datetime
vector or aduration
vector. The number of elements of time vector must equal the number of rows of the input table. The time values in the time vector do not need to be unique, sorted, or regular. All the variables of the input table become variables of the timetable.
Data Types: char
| string
| datetime
| duration
SampleRate
— Sample rate for row times
numeric scalar
Sample rate for row times, specified as the comma-separated pair consisting of
'SampleRate'
and a numeric scalar. The sample rate is the number
of samples per second (Hz) of the time vector of the output timetable.
When you use 'SampleRate'
to specify the row time vector of the
timetable, the default first row time (start time) is zero second. To set a start time
other than zero, specify the'StartTime'
name-value pair.
Data Types: double
TimeStep
— Time step between row times
duration scalar | calendarDuration scalar
Time step between row times, specified as the comma-separated pair consisting of
'TimeStep'
and a duration scalar or calendarDuration scalar. The
value of the 'TimeStep'
parameter specifies the length of time
between consecutive row times. The importing function uses the time step value to
calculate regularly spaced row times.
When you use 'TimeStep'
to specify the row time vector of the
timetable, the default first row time (start time) is zero second. To set a start time
other than zero, specify the 'StartTime'
name-value pair.
If the 'TimeStep'
is a calendar duration value, then the
'StartTime'
must be a datetime value.
Data Types: duration
| calendarDuration
StartTime
— Start time of row times
datetime scalar | duration scalar
Start time of the row times, specified as the comma-separated pair consisting of
StartTime
and a datetime scalar or duration scalar.
To define the time vector for the timetable, use 'StartTime'
with either the 'SampleRate'
or the 'TimeStep'
name-value pair arguments.
The data type of the start time, dictates the data type of the row time vector.
If the start time is a datetime value, then the row times of the timetable are datetime values.
If the start time is a duration value, then the row times are durations.
Data Types: datetime
| duration
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"
.
Data Types: char
| string
Delimiter
— Field delimiter characters
string array | character vector | cell array of character vectors
Field delimiter characters in a delimited text file, specified as a string array, character vector, or cell array of character vectors.
Example: "Delimiter","|"
Example: "Delimiter",[";","*"]
Whitespace
— Characters to treat as white space
character vector | string scalar
Characters to treat as white space, specified as a character vector or string scalar containing one or more characters.
Example: 'Whitespace',' _'
Example: 'Whitespace','?!.,'
LineEnding
— End-of-line characters
["\n","\r","\r\n"]
(default) | string array | character vector | cell array of character vectors
End-of-line characters, specified as a string array, character vector, or cell array of character vectors.
Example: "LineEnding","\n"
Example: "LineEnding","\r\n"
Example: "LineEnding",["\b",":"]
CommentStyle
— Style of comments
string array | character vector | cell array of character vectors
Style of comments, specified as a string array, character vector, or cell array of character vectors. For single- and multi-line comments, the starting identifier must be the first non-white-space character. For single-line comments, specify a single identifier to treat lines starting with the identifier as comments. For multi-line comments, lines from the starting (first) identifier to the ending (second) identifier are treated as comments. No more than two character vectors of identifiers can be specified.
For example, to ignore the line following a percent symbol as the first
non-white-space character, specify CommentStyle
as
"%"
.
Example: "CommentStyle",["/*"]
Example: "CommentStyle",["/*","*/"]
Encoding
— Character encoding scheme
'UTF-8'
| 'ISO-8859-1'
| 'windows-1251'
| 'windows-1252'
| ...
Character encoding scheme associated with the file, specified as the
comma-separated pair consisting of 'Encoding'
and
'system'
or a standard character encoding scheme name. When you
do not specify any encoding, the readtimetable
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 readtimetable
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.
Data Types: char
| string
DurationType
— Output data type of duration data
'duration'
(default) | 'text'
Output data type of duration data from text files, specified as the comma-separated pair consisting of 'DurationType'
and either 'duration'
or 'text'
.
Value | Type for Imported Duration Data |
---|---|
'duration' | MATLAB For more information, see |
'text' | If
|
Data Types: char
| string
DateLocale
— Locale for reading dates
character vector | string scalar
Locale for reading dates, specified as the comma-separated pair consisting of
'DateLocale'
and a character vector or a string scalar of the
form
, where:xx
_YY
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.
Locale | Language | Country |
---|---|---|
'de_DE' | German | Germany |
'en_GB' | English | United Kingdom |
'en_US' | English | United States |
'es_ES' | Spanish | Spain |
'fr_FR' | French | France |
'it_IT' | Italian | Italy |
'ja_JP' | Japanese | Japan |
'ko_KR' | Korean | Korea |
'nl_NL' | Dutch | Netherlands |
'zh_CN' | Chinese (simplified) | China |
When using the %D
format specifier to read text as
datetime
values, use DateLocale
to specify the
locale in which the importing function should interpret month and day-of-week names and
abbreviations.
If you specify the DateLocale
argument in addition to
opts
the import options, then the importing function uses the
specified value for the DateLocale
argument, overriding the locale
defined in the import options.
Example: 'DateLocale','ja_JP'
DecimalSeparator
— Characters indicating decimal separator
character vector | string scalar
Characters indicating the decimal separator in numeric variables, specified as a character
vector or string scalar. The importing function uses the characters specified in the
DecimalSeparator
name-value pair 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 the
importing function imports the text "3,14159"
as the number
3.14159
.
Data Types: char
| string
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 importing function uses
the characters specified in the ThousandsSeparator
name-value pair to
interpret the numbers being imported.
Example: If name-value pair is specified as
'ThousandsSeparator',','
, then the importing function imports the
text "1,234,000"
as 1234000
.
Data Types: char
| string
TrimNonNumeric
— Remove nonnumeric characters
false
(default) | true
Remove nonnumeric characters from a numeric variable, specified as a logical true
or false
.
Example: If name-value pair is specified as 'TrimNonNumeric',true
, then the
importing function reads '$500/-'
as
500
.
Data Types: logical
ConsecutiveDelimitersRule
— Procedure to manage consecutive delimiters
"split"
| "join"
| "error"
Procedure to manage consecutive delimiters in a delimited text file, specified as one of the values in this table.
Value | Behavior |
---|---|
"split" | Split the consecutive delimiters into multiple fields. |
"join" | Join the delimiters into one delimiter. |
"error" | Return an error and cancel the import operation. |
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.
Value | Behavior |
---|---|
"keep" | Keep the delimiter. |
"ignore" | Ignore the delimiter. |
"error" | Return an error and cancel the import operation. |
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.
Leading Delimiters Rule | Behavior |
---|---|
'keep' | Keep the delimiter. |
'ignore' | Ignore the delimiter. |
'error' | Return an error and abort the import operation. |
Sheet
— Sheet to read from
''
empty character array (default) | character vector | string scalar | positive scalar integer
Sheet to read from, specified as an empty character array, a character vector or string scalar
containing the sheet name, or a positive scalar integer denoting the sheet
index. Based on the value specified for the Sheet
property, the import function behaves as described in the table.
Specification | Behavior |
---|---|
'' (default) | Import data from the first sheet. |
Name | Import data from the matching sheet name, regardless of order of sheets in the spreadsheet file. |
Integer | Import data from sheet in the position denoted by the integer, regardless of the sheet names in the spreadsheet file. |
Data Types: char
| string
| single
| double
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 the comma-separated pair
consisting of 'UseExcel'
and either true
, or
false
.
You can set the 'UseExcel'
parameter to one of these values:
true
— The importing function starts an instance of Microsoft Excel when reading the file.false
— The importing function does not start an instance of Microsoft Excel when reading the file. When operating in this mode, the importing function functionality differs in the support of file formats and interactive features, such as formulas and macros.
UseExcel |
|
|
---|---|---|
Supported file formats |
|
|
Support for interactive features, such as formulas and macros | Yes | No |
When reading from spreadsheet files on Windows platforms, if you want to start an instance of Microsoft
Excel, then set the 'UseExcel'
parameter to
true
.
UseExcel
is not supported in noninteractive, automated
environments.
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.
Import Rule | Behavior |
---|---|
"placeleft" | Place the data in the leftmost cell and fill the remaining cells
with the contents of the You can specify the |
"placeright" | Place the data in the rightmost cell and fill the remaining cells
with the contents of the You can specify the |
"duplicate" | Duplicate the data in all cells. |
"omitrow" | Omit rows where merged cells occur. |
"error" | Display an error message and cancel the import operation. |
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.
Import Rule | Behavior |
---|---|
"placetop" | Place the data in the top cell and fill the remaining cells with
the contents of the You
can specify the |
"placebottom" | Place the data in the bottom cell and fill the remaining cells
with the contents of the You can specify the |
"duplicate" | Duplicate the data in all cells. |
"omitvar" | Omit variables where merged cells occur. |
"error" | Display an error message and cancel the import operation. |
AttributeSuffix
— Attribute suffix
'Attribute'
(default) | character vector | string scalar
Attribute suffix, specified as the comma-separated pair consisting of
'AttributeSuffix'
and either a character vector or string scalar.
This argument specifies the suffix the reading function appends to all table variables
that correspond to attributes in the input XML file. If you do not specify
'AttributeSuffix'
, then the reading function defaults to
appending the suffix 'Attribute'
to all variable names corresponding
to attributes in the input XML file.
Example: 'AttributeSuffix','_att'
ImportAttributes
— Import attributes
logical 1
or true
(default) | logical 0
or false
Import attributes, specified as the comma-separated pair consisting of
'ImportAttributes'
and either 1
(true
) or 0
(false
). If you
specify false
, then the reading function will not import the XML
attributes in the input file as variables in the output table.
Example: 'ImportAttributes',false
RowNodeName
— Table row XML node name
character vector | string array
Table row XML node name, specified as the comma-separated pair consisting of
'RowNodeName'
and either a character vector or string scalar.
This argument specifies the XML node name that delineates rows of the output
table.
Example: 'RowNodeName','XMLNodeName'
RowSelector
— Table row XPath expression
character vector | string scalar
Table row XPath expression, specified as a character vector or string scalar that the
reading function uses to select individual rows of the output table. You must specify
RowSelector
as a valid XPath version 1.0 expression.
Example: 'RowSelector','/RootNode/ChildNode'
VariableNodeNames
— Table variable XML node names
cell array of character vectors | string array
Table variable XML node names, specified as the comma-separated pair consisting of
'VariableNodeNames'
and either a cell array of character vectors
or string array. This argument specifies the XML node name that the reading function
uses to identify the XML nodes to read as variables in the output table.
Example: 'VariableNodeNames',{'XMLNodeName1','XMLNodeName2'}
Example: 'VariableNodeNames',"XMLNodeName"
Example: 'VariableNodeNames',["XMLNodeName1","XMLNodeName2"]
VariableSelectors
— Table variable XPath expressions
cell array of character vectors | string array
Table variable XPath expressions, specified as a cell array of character vectors or
string array that the reading function uses to select table variables. You must specify
VariableSelectors
as valid XPath version 1.0 expressions.
Example: 'VariableSelectors',{'/RootNode/ChildNode'}
Example: 'VariableSelectors',"/RootNode/ChildNode"
Example: 'VariableSelectors',["/RootNode/ChildNode1","/RootNode/ChildNode2"]
TableNodeName
— Table XML node name
character vector | string scalar
Table XML node name, specified as the comma-separated pair consisting of
'TableNodeName'
and either a character vector or string scalar.
This argument specifies the node in the input structure that the reading function should
read to a table.
Example: 'TableNodeName','NodeName'
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 specify
TableSelector
as a valid XPath version 1.0 expression.
Example: 'TableSelector','/RootNode/ChildNode'
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 specify
VariableUnitsSelector
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'
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'
.
Repeated Node Rule | Behavior |
---|---|
'addcol' | Add columns for the repeated nodes under the variable header in
the table. Specifying the value of
|
'ignore' | Skip importing the repeated nodes. |
'error' | Display an error message and abort the import operation. |
Example: 'RepeatedNodeRule','ignore'
RegisteredNamespaces
— Set of registered XML namespace prefixes
string array
Set of registered XML namespace prefixes, specified as the comma-separated pair
consisting of RegisteredNamespaces
and an array of prefixes. The
reading function uses these prefixes when evaluating XPath expressions on an XML file.
Specify the namespace prefixes and their associated URLs as an Nx2 string array.
RegisteredNamespaces
can be used when you also evaluate an XPath
expression specified by a selector name-value argument, such as
StructSelector
for readstruct
, or
VariableSelectors
for readtable
and
readtimetable
.
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 the
RegisteredNamespaces
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 called
example.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"]
Output Arguments
TT
— Output timetable
timetable
Output timetable. The timetable can store metadata such as descriptions, variable
units, variable names, and row times. For more information, see the Properties sections
of timetable
.
Tips
Use XPath selectors to specify which elements of the XML input document to import. For example, suppose you want to import the XML file
myFile.xml
, which has the following structure:This table provides the XPath syntaxes that are supported for XPath selector name-value arguments, such as<data> <table category="ones"> <var>1</var> <var>2</var> </table> <table category="tens"> <var>10</var> <var>20</var> </table> </data>
VariableSelectors
orTableSelector
.Selection Operation Syntax Example Result Select every node whose name matches the node you want to select, regardless of its location in the document. Prefix the name with two forward slashes ( //
).data = readtable('myFile.xml', 'VariableSelectors', '//var')
data = 4×1 table var ___ 1 2 10 20
Read the value of an attribute belonging to an element node. Prefix the attribute with an at sign ( @
).data = readtable('myFile.xml', 'VariableSelectors', '//table/@category')
data = 2×1 table categoryAttribute _________________ "ones" "tens"
Select a specific node in a set of nodes. Provide the index of the node you want to select in square brackets ( []
).data = readtable('myFile.xml', 'TableSelector', '//table[1]')
data = 2×1 table var ___ 1 2
Specify precedence of operations. Add parentheses around the expression you want to evaluate first. data = readtable('myFile.xml', 'VariableSelectors', '//table/var[1]')
data = 2×1 table var ___ 1 10
data = readtable('myFile.xml', 'VariableSelectors', '(//table/var)[1]')
data = table var ___ 1
Version History
Introduced in R2019aR2024b: Specify how to import merged cells in spreadsheets
When importing data from spreadsheets, you can specify how
readtimetable
imports cells that are merged across rows and columns by
using the MergedCellRowRule
and MergedCellColumnRule
name-value arguments.
See Also
Functions
Live Editor Tasks
Apps
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: United States.
You can also select a web site from the following list
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)
Asia Pacific
- Australia (English)
- India (English)
- New Zealand (English)
- 中国
- 日本Japanese (日本語)
- 한국Korean (한국어)