readtimetable - Create timetable from file - MATLAB (original) (raw)

Create timetable from file

Syntax

Description

[TT](#mw%5Fabeab181-1594-4bfa-8688-c4f4c17d93f4) = readtimetable([filename](#mw%5F71b5cf43-fa25-4b28-ad8b-d70c777d79ce)) creates a timetable by reading column-oriented data from a file.

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
.zip, .gz, or .tar for compressed and archived files

For text and spreadsheet files, readtimetable creates one variable inTT for each column in the file and reads variable names from the first row of the file. For XML files, readtimetable creates one variable inT 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 typedatetime or duration in the tabular data to be the row times of the timetable. The remaining columns become variables of the timetable.

example

[TT](#mw%5Fabeab181-1594-4bfa-8688-c4f4c17d93f4) = readtimetable([filename](#mw%5F71b5cf43-fa25-4b28-ad8b-d70c777d79ce),[opts](#mw%5Fa1225061-618e-466e-8ba2-eecd7509bcf2%5Fsep%5Fbtx%5F238-1-opts)) additionally uses the import options opts.

example

[TT](#mw%5Fabeab181-1594-4bfa-8688-c4f4c17d93f4) = readtimetable(___,[Name,Value](#namevaluepairarguments)) 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.

To set specific import options for your data, you can either use theopts object or you can specify name-value pairs. When you specify name-value pairs in addition to opts, thenreadtimetable 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

example

Examples

collapse all

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.

TT: 1468×5 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

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 = 1×6 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: 1468×5 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

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: 1468×5 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 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.

TT: 80×9 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

collapse all

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 infilename.Example: 'myFile.txt'
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 infilename.Example: 'C:\myFolder\myFile.xlsx'Example: 'dataDir\myFile.txt'
Internet URL	If the file is specified as an internet uniform resource locator (URL), then filename must contain the protocol type'http://' or'https://'.Example: 'http://hostname/path\_to\_file/my\_data.csv'
Remote Location	If the file is stored at a remote location, thenfilename must contain the full path of the file specified with the form:scheme_name://path_to_file/_my_file.ext_Based on the remote location,scheme_name can be one of the values in this table. Remote Location_scheme_name_Amazon S3™s3Windows Azure® Blob Storagewasb, wasbsHDFS™hdfsFor more information, see Work with Remote Data.Example: 's3://bucketname/path_to_file/my_file.csv'

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 theUseExcel property set to false, 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.
Compressed file formats are read as files. Archived file formats are treated as folders. For example, the function interprets mydatafiles.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. (since R2025a)

Data Types: char | string

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 infilename.Example: 'myFile.txt'
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 infilename.Example: 'C:\myFolder\myFile.xlsx'Example: 'dataDir\myFile.txt'
Internet URL	If the file is specified as an internet uniform resource locator (URL), then filename must contain the protocol type'http://' or'https://'.Example: 'http://hostname/path\_to\_file/my\_data.csv'
Remote Location	If the file is stored at a remote location, thenfilename must contain the full path of the file specified with the form:scheme_name://path_to_file/_my_file.ext_Based on the remote location,scheme_name can be one of the values in this table. Remote Location_scheme_name_Amazon S3s3Windows Azure Blob Storagewasb, wasbsHDFShdfsFor more information, see Work with Remote Data.Example: 's3://bucketname/path_to_file/my_file.csv'

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 to false, 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

File import options, specified as an SpreadsheetImportOptions,DelimitedTextImportOptions,FixedWidthImportOptions, or XMLImportOptions object created by the detectImportOptions function. Theopts object contains properties that control the data import process. For more information on the properties of each object, see the appropriate object page.

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.

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.

All Supported File Types

expand all

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

Text and Spreadsheet Files

expand all

Type of file, specified as the comma-separated pair consisting of'FileType' and 'text' or'spreadsheet'.

Specify the 'FileType' name-value pair argument when thefilename 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

Data Types: single | double

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

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'Cell' or[row col]	Specify the starting cell for the data as a character vector or string scalar or a two element numeric vector. Character vector or string scalar containing a column letter and row number using ExcelA1 notation. For example,A5 is the identifier for the cell at the intersection of column A and row 5. Two element numeric vector of the form [row col] indicating the starting row and column.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: 'A5' or [5 1]
Rectangular Range'Corner1:Corner2' or[r1 c1 r2 c2]	Specify the exact range to read using the rectangular range in one of these forms. 'Corner1:Corner2' — Specify the range using Corner1 andCorner2 which are the two opposing corners that define the region to read in ExcelA1 notation. For example,'C2:N15'.[r1 c1 r2 c2] — Specify the range using a four element numeric vector containing start-row, start-column, end-row, and end-column. For example, [2 3 15 13].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'Row1:Row2' or'Column1:Column2'	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: '5:500'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 theExpectedNumVariables property.Example: 'A:K'
Starting Row Numbern	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:5
Excel’s Named Range'NamedRange'	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 'myTable'. If such named ranges exist in a spreadsheet, then the importing function can read that range using its name.Example: 'Range','myTable'
Unspecified or Empty''	If unspecified, the importing function automatically detects the used range.Example: 'Range',''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

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"

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

Value	Description
"datetime"	MATLABdatetime data type For more information, seedatetime.
"text"	If "DatetimeType" is specified as"text", then the type for imported date and time data depends on the value specified in the "TextType" parameter: If "TextType" is set to "char", then the importing function returns dates as a cell array of character vectors. If "TextType" is set to "string", then the importing function returns dates as an array of strings.
"exceldatenum"	Excel serial date numbersThe value"exceldatenum" is applicable only for spreadsheet files, and is not valid for text files. A serial date number is a single number equal to the number of days from a given reference date. Excel serial date numbers use a different reference date than MATLAB serial date numbers. For more information on Excel dates, see Differences between the 1900 and the 1904 date system in Excel.

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

Read the first row as variable names, specified as the comma-separated pair consisting of 'ReadVariableNames' and eithertrue or false. If unspecified, the importing function automatically detects the presence of variable names.

Indicator	Description
true	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 T.
false	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'Var1',...,'VarN', where N is the number of variables.
Unspecified	When left unspecified, the importing function automatically detectstrue 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 to true, then the importing function reads the variable names from the specified file by using the VariableNamesRange or theVariableNamesLine property of the import options object.
If ReadVariableNames is set to false, then the importing function reads the variable names from theVariableNames property of the import options object.

Data Types: logical

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 containsdatetime or duration 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 a duration 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

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

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

Start time of the row times, specified as the comma-separated pair consisting ofStartTime 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

Flag to preserve variable names, specified as either "modify" or"preserve".

"modify" — Convert invalid variable names (as determined by the isvarname function) to valid MATLAB identifiers.
"preserve" — Preserve variable names that are not valid MATLAB identifiers such as variable names that include spaces and non-ASCII characters.

Starting in R2019b, variable names and row names can include any characters, including spaces and non-ASCII characters. Also, they can start with any characters, not just letters. Variable and row names do not have to be valid MATLAB identifiers (as determined by the isvarname function). To preserve these variable names and row names, set the value of VariableNamingRule to "preserve". Variable names are not refreshed when the value of VariableNamingRule is changed from "modify" to "preserve".

Data Types: char | string

Text Files Only

expand all

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

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 duration data type For more information, see duration.
'text'	If 'DurationType' is specified as 'text', then the type for imported duration data depends on the value specified in the 'TextType' parameter: If 'TextType' is set to'char', then the importing function returns duration data as a cell array of character vectors. If 'TextType' is set to'string', then the importing function returns duration data as an array of strings.

Data Types: char | string

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

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

This table lists some common values for the locale.

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 asdatetime values, use DateLocale to specify the locale in which the importing function should interpret month and day-of-week names and abbreviations.

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

Example: 'DateLocale','ja_JP'

Data Types: char | string

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/-' as500.

Data Types: logical

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.

Spreadsheet Files Only

expand all

Data Types: char | string | single | double

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, orfalse.

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

true — The importing function starts an instance ofMicrosoft 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	true	false
Supported file formats	.xls, .xlsx, .xlsm, .xltx, .xltm, .xlsb, .ods	.xls, .xlsx, .xlsm, .xltx, .xltm
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 totrue.

UseExcel is not supported in noninteractive, automated environments.

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 FillValue property.You can specify the FillValue property in the VariableImportOptions object of the variable being imported. For more information on setting theFillValue property, see setvaropts.
"placeright"	Place the data in the rightmost cell and fill the remaining cells with the contents of the FillValue property.You can specify the FillValue property in the VariableImportOptions object of the variable being imported. For more information on setting theFillValue property, see setvaropts.
"duplicate"	Duplicate the data in all cells.
"omitrow"	Omit rows where merged cells occur.
"error"	Display an error message and cancel the import operation.

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 FillValue property.You can specify the FillValue property in theVariableImportOptions object of the variable being imported. For more information on setting the FillValue property, see setvaropts.
"placebottom"	Place the data in the bottom cell and fill the remaining cells with the contents of the FillValue property.You can specify the FillValue property in the VariableImportOptions object of the variable being imported. For more information on setting theFillValue property, see setvaropts.
"duplicate"	Duplicate the data in all cells.
"omitvar"	Omit variables where merged cells occur.
"error"	Display an error message and cancel the import operation.

XML Files Only

expand all

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'

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

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'

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'

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

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

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

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

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

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'

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

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

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'

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'

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'RepeatedNodeRule' as'addcol' does not create a separate variable in the table for the repeated node.
'ignore'	Skip importing the repeated nodes.
'error'	Display an error message and abort the import operation.

Example: 'RepeatedNodeRule','ignore'

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

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

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

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

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

Output Arguments

collapse all

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 filemyFile.xml, which has the following structure: 12

1020

This table provides the XPath syntaxes that are supported for XPath selector name-value arguments, such as `VariableSelectors` or `TableSelector`. | Selection Operation | Syntax | Example | Result | | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | | Select every node whose name matches the node you want to select, regardless of its location in the document. | Prefix the name with two forward slashes (//). | data = readtable('myFile.xml', 'VariableSelectors', '//var') | data = 4×1 table var \_\_\_ 1 2 10 20 | | Read the value of an attribute belonging to an element node. | Prefix the attribute with an at sign (@). | data = readtable('myFile.xml', 'VariableSelectors', '//table/@category') | data = 2×1 table categoryAttribute \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ "ones" "tens" | | Select a specific node in a set of nodes. | Provide the index of the node you want to select in square brackets (\[\]). | data = readtable('myFile.xml', 'TableSelector', '//table\[1\]') | data = 2×1 table var \_\_\_ 1 2 | | Specify precedence of operations. | Add parentheses around the expression you want to evaluate first. | data = readtable('myFile.xml', 'VariableSelectors', '//table/var\[1\]') | data = 2×1 table var \_\_\_ 1 10 | | data = readtable('myFile.xml', 'VariableSelectors', '(//table/var)\[1\]') | data = table var \_\_\_ 1 | | |

Version History

Introduced in R2019a

expand all

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

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