readtimetable

Create timetable from file

collapse all in page

Syntax

TT = readtimetable(filename)

TT = readtimetable(filename,opts)

TT = readtimetable(___,Name,Value)

Description

TT = readtimetable(filename) 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
.json for JavaScript Object Notation (JSON) 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 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.

example

TT = readtimetable(filename,opts) additionally uses the import options opts.

example

TT = readtimetable(___,Name,Value) 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 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

example

Examples

collapse all

Create Timetable from Text File

Open Live Script

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

Create Timetable from File Using Import Options

Open Live Script

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

Create Timetable from File and Specify Row Times

Open Live Script

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 Timetable from Spreadsheet File and Format Input Data

Open Live Script

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

`filename` — Name of file to read
string scalar | character vector

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

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

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

Location

Form

Current folder or folder on the MATLAB^® path

Specify the name of the file in filename.

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 pathname in filename.

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, then filename 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™	`s3`
Windows Azure^® Blob Storage	`wasb`, `wasbs`
HDFS™	`hdfs`

For more information, see Work with Remote Data.

Example:"s3://bucketname/path_to_file/my_file.csv"

Example:"wasbs://path_to_file/my_file.csv"

Example:"hdfs:///path_to_file/my_file.csv"

Text Files

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

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

Spreadsheet Files

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

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

JSON Files

(since R2026a)

Files with the .json extension are read as JavaScript Object Notation (JSON) files.
By default, readtimetable creates one table variable for each object key detected as a table variable. Variable names correspond to JSON object key names.

XML Files

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

Microsoft Word Documents

(since R2021b)

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

HTML Files

(since R2021b)

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

Compressed and Archived Files

(since R2025a)

Compressed file formats are read as files.
Archived file formats are treated as folders. For example, the function 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.

`opts` — File import options
`DelimitedTextImportOptions` object | `FixedWidthImportOptions` object | `SpreadsheetImportOptions` object | …

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

File Type	Import Options Object
Text files	`DelimitedTextImportOptions` object
Fixed-width text files	`FixedWidthImportOptions` object
Spreadsheet files	`SpreadsheetImportOptions` object
JSON files	`JSONImportOptions` object
XML files	`XMLImportOptions` object
Microsoft Word documents	`WordDocumentImportOptions` object
HTML files	`HTMLImportOptions` object

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

Name-Value Arguments

expand all

Specify optional pairs of arguments 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.

Example: readtimetable(filename,NumHeaderLines=5) indicates that the first five lines that precede the tabular data are header lines.

Data and Header Location

expand all

`NumHeaderLines` — Number of header lines to skip (Text and spreadsheet files)
nonnegative integer

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

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

Data Types: single | double

`Range` — Range to read (Text and spreadsheet files)
string scalar | character vector | numeric vector

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

Ways to Specify Range Description

Ways to Specify `Range`	Description
`"Cell"` or `[row col]` Starting element	Specify the starting element for the data as one of these values: String scalar or character vector containing a column letter and row number using spreadsheet A1 notation. For example, `A5` is the identifier for the element 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 element, `readtimetable` automatically detects the extent of the data by beginning the import at the starting element and ending at the last empty row. Example: `"A5"` Example: `[5 1]`
`"Corner1:Corner2"` or `[r1 c1 r2 c2]` Rectangular range	Specify the rectangular range for the data as one of these values: String scalar or character vector of the form `"Corner1:Corner2"`, where `Corner1` and `Corner2` are two opposing corners that define the region. For example, `"D2:H4"` represents the 3-by-5 rectangular region between the two corners `D2` and `H4` in the file. The `Range` name-value argument, which uses spreadsheet A1 notation, is not case sensitive. Four-element numeric vector of the form `[r1 c1 r2 c2]` indicating the start row, start column, end row, and end column. For example, `[2 3 15 13]` represents the 14-by-11 rectangular region between the 2nd and 15th rows and the 3rd and 13th columns in the file. `readtimetable` reads only the data contained in the specified range. Any empty fields within the specified range are imported as missing values. The number of columns must match the number specified in the `ExpectedNumVariables` name-value argument. Example: `"D2:H4"` Example: `[2 3 15 13]`
`"Row1:Row2"` Row range	Specify the beginning and ending rows using row numbers in a string scalar or character vector of the form `"Row1:Row2"`. Using the specified row range, `readtimetable` 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: `"1:7"` reads all columns in rows 1 through 7 (inclusive).
`"Column1:Column2"` Column range	Specify the beginning and ending columns using A1 notation column letters in a string scalar or character vector of the form `"Column1:Column2"`. Using the specified column range, `readtimetable` automatically detects the row extent by reading from the first nonempty row to the end of the data. The number of columns must match the number specified in the `ExpectedNumVariables` name-value argument. Example: `"A:F"` reads all rows in columns A through F (inclusive).
`"NamedRange"` Named range (spreadsheet only)	You can create names to identify ranges in a spreadsheet. For instance, you can select a rectangular portion of the spreadsheet and call it `"myTable"`. If a spreadsheet has a named range, then `readtimetable` can read that range using its name.
`""` Unspecified or empty	If you do not specify this name-value argument, `readtimetable` automatically detects the used range. Note: Used range refers to the rectangular portion of the file that actually contains data. `readtimetable` 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.

"Cell" or [row col]

Starting element

Specify the starting element for the data as one of these values:

String scalar or character vector containing a column letter and row number using spreadsheet A1 notation. For example, A5 is the identifier for the element 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 element, readtimetable automatically detects the extent of the data by beginning the import at the starting element and ending at the last empty row.

Example: "A5"

Example: [5 1]

"Corner1:Corner2" or [r1 c1 r2 c2]

Rectangular range

Specify the rectangular range for the data as one of these values:

String scalar or character vector of the form "Corner1:Corner2", where Corner1 and Corner2 are two opposing corners that define the region. For example, "D2:H4" represents the 3-by-5 rectangular region between the two corners D2 and H4 in the file. The Range name-value argument, which uses spreadsheet A1 notation, is not case sensitive.
Four-element numeric vector of the form [r1 c1 r2 c2] indicating the start row, start column, end row, and end column. For example, [2 3 15 13] represents the 14-by-11 rectangular region between the 2nd and 15th rows and the 3rd and 13th columns in the file.

readtimetable reads only the data contained in the specified range. Any empty fields within the specified range are imported as missing values.

The number of columns must match the number specified in the ExpectedNumVariables name-value argument.

Example: "D2:H4"

Example: [2 3 15 13]

"Row1:Row2"

Row range

Specify the beginning and ending rows using row numbers in a string scalar or character vector of the form "Row1:Row2".

Using the specified row range, readtimetable 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: "1:7" reads all columns in rows 1 through 7 (inclusive).

"Column1:Column2"

Column range

Specify the beginning and ending columns using A1 notation column letters in a string scalar or character vector of the form "Column1:Column2".

Using the specified column range, readtimetable automatically detects the row extent by reading from the first nonempty row to the end of the data.

The number of columns must match the number specified in the ExpectedNumVariables name-value argument.

Example: "A:F" reads all rows in columns A through F (inclusive).

"NamedRange"

Named range (spreadsheet only)

You can create names to identify ranges in a spreadsheet. For instance, you can select a rectangular portion of the spreadsheet and call it "myTable". If a spreadsheet has a named range, then readtimetable can read that range using its name.

""

Unspecified or empty

If you do not specify this name-value argument, readtimetable automatically detects the used range.

Note: Used range refers to the rectangular portion of the file that actually contains data. readtimetable 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.

`DataRange` — Location of data (Spreadsheet files)
string scalar | character vector | positive integer | array of positive integers

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

Ways to Specify DataRange Description

Ways to Specify `DataRange`	Description
`"Cell"` Starting cell	Specify the starting cell for the data as a string scalar or character vector containing a column letter and row number, using A1 notation. For example, `A5` is the identifier for the cell at the intersection of column `A` and row `5`. Using the starting cell, `readtimetable` automatically detects the extent of the data by beginning the import at the starting cell and ending at the last empty row or footer range. Example: `"A5"`
`n` Starting row	Specify the starting row containing the data using the positive row index. Using the specified row index, `readtimetable` 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`
`"Corner1:Corner2"` Rectangular range	Specify the range using the form `"Corner1:Corner2"`, where `Corner1` and `Corner2` are two opposing corners that define the region. `readtimetable` reads only the data contained in the specified range. Any empty fields within the specified range are imported as missing values. Example: `"A5:K50"`
`"Row1:Row2"` Row range	Specify the beginning and ending rows using row numbers in a string scalar or character vector of the form `"Row1:Row2"`. Using the specified row range, `readtimetable` 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"`
`"Column1:Column2"` Column range	Specify the beginning and ending columns using A1 notation column letters in a string scalar or character vector of the form `"Column1:Column2"`. Using the specified column range, `readtimetable` automatically detects the row extent by reading from the first nonempty row to the end of the data. Example: `"A:K"`
`[n1 n2; n3 n4; ...]` Multiple row ranges	Specify multiple row ranges using an `N`-by-`2` array containing `N` different row ranges. A valid array of multiple row ranges must: Specify line ranges in an increasing order. Contain only non-overlapping row ranges. Use of `Inf` is supported only for the last row range in the numeric array. Example: `[1 3; 5 6; 8 Inf]`
`""` Empty	Do not read any data. Example: `""`

"Cell"

Starting cell

Specify the starting cell for the data as a string scalar or character vector containing a column letter and row number, using A1 notation. For example, A5 is the identifier for the cell at the intersection of column A and row 5.

Using the starting cell, readtimetable automatically detects the extent of the data by beginning the import at the starting cell and ending at the last empty row or footer range.

Example: "A5"

n

Starting row

Specify the starting row containing the data using the positive row index.

Using the specified row index, readtimetable 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

"Corner1:Corner2"

Rectangular range

Specify the range using the form "Corner1:Corner2", where Corner1 and Corner2 are two opposing corners that define the region.

readtimetable reads only the data contained in the specified range. Any empty fields within the specified range are imported as missing values.

Example: "A5:K50"

"Row1:Row2"

Row range

Specify the beginning and ending rows using row numbers in a string scalar or character vector of the form "Row1:Row2".

Using the specified row range, readtimetable 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"

"Column1:Column2"

Column range

Specify the beginning and ending columns using A1 notation column letters in a string scalar or character vector of the form "Column1:Column2".

Using the specified column range, readtimetable automatically detects the row extent by reading from the first nonempty row to the end of the data.

Example: "A:K"

[n1 n2; n3 n4; ...]

Multiple row ranges

Specify multiple row ranges using an N-by-2 array containing N different row ranges.

A valid array of multiple row ranges must:

Specify line ranges in an increasing order.
Contain only non-overlapping row ranges.

Use of Inf is supported only for the last row range in the numeric array.

Example: [1 3; 5 6; 8 Inf]

""

Empty

Do not read any data.

Example: ""

`Sheet` — Worksheet to read (Spreadsheet files)
`1` (default) | positive integer | string scalar | character vector

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

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

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

Example: 2

Example: "MySheetName"

`TableIndex` — Index of table to read (Microsoft Word and HTML files)
`1` (default) | positive integer

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

If you specify TableIndex, the readtimetable function automatically sets TableSelector to the equivalent XPath expression.

`TableSelector` — Table to read (JSON, XML, Microsoft Word, and HTML files)
string scalar | character vector

Table to read, specified as a string scalar or character vector. If you do not specify this name-value argument, readtimetable detects the table location.

JSON Files

Specify the table to read as a string scalar or character vector containing a JSON Pointer. You must specify TableSelector as a valid RFC 6901 JSON Pointer. For more information, see the IETF definition of JSON Pointer.

An empty string ("") refers to the whole JSON file.

Example: TableSelector="/engineID"

XML Files

Specify the table to read as a string scalar or character vector containing an XPath expression. You must specify TableSelector as a valid XPath version 1.0 expression.

Selection Operation	Syntax
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 (`//`).
Select the value of an attribute belonging to an element node.	Prefix the attribute with an at sign (`@`).
Select a specific node in a set of nodes.	Provide the index of the node you want to select in square brackets (`[]`).
Specify precedence of operations.	Add parentheses around the expression you want to evaluate first.

Example: TableSelector="//table[1]"

`TableNodeName` — JSON key name or XML node name for table data to read (JSON and XML files)
string scalar | character vector

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

`MergedCellColumnRule` — Rule for cells merged across columns (Spreadsheet, Microsoft Word, and HTML files)
`"placeleft"` (default) | `"placeright"` | `"duplicate"` | `"omitrow"` | `"error"`

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 based on the value of `MissingRule`. If `MissingRule` is `"fill"` (default), then fill cells using `FillValue`. You can set the `FillValue` property in the `VariableImportOptions` object of the variable being imported. For more information on setting the `FillValue` property, see `setvaropts`.
`"placeright"`	Place the data in the rightmost cell and fill the remaining cells with the contents of the `FillValue` property based on the value of `MissingRule`. If `MissingRule` is `"fill"` (default), then fill cells using `FillValue`. You can set the `FillValue` property in the `VariableImportOptions` object of the variable being imported. For more information on setting the `FillValue` 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.

`MergedCellRowRule` — Rule for cells merged across rows (Spreadsheet, Microsoft Word, and HTML files)
`"placetop"` (default) | `"placebottom"` | `"duplicate"` | `"omitvar"` | `"error"`

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 based on the value of `MissingRule`. If `MissingRule` is `"fill"` (default), then fill cells using `FillValue`. You can set the `FillValue` property in the `VariableImportOptions` 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 based on the value of `MissingRule`. If `MissingRule` is `"fill"` (default), then fill cells using `FillValue`. You can set the `FillValue` property in the `VariableImportOptions` object of the variable being imported. For more information on setting the `FillValue` 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.

Variables

expand all

`ReadVariableNames` — Read variable names (Text, spreadsheet, JSON, XML, Microsoft Word, and HTML files)
`true` or `1` | `false` or `0`

Read variable names, specified as a numeric or logical 1 (true) or 0 (false). If you do not specify this name-value argument, readtimetable automatically detects the presence of variable names.

Value	Description
`true`	Read variable names. If you also specify an import options object `opts`, `readtimetable` uses the `VariableNamesRange` or `VariableNamesLine` property of `opts` to identify the location of variable names.
`false`	Do not read variable names. Create default variable names of the form `"Var1",...,"VarN"`, where `N` is the number of variables. If you also specify an import options object `opts`, `readtimetable` uses the `VariableNames` property of `opts` to create variable names.
Unspecified	Automatically detect whether the region contains variable names.

Value

Description

true

Read variable names.

If you also specify an import options object opts, readtimetable uses the VariableNamesRange or VariableNamesLine property of opts to identify the location of variable names.

false

Do not read variable names. Create default variable names of the form "Var1",...,"VarN", where N is the number of variables.

If you also specify an import options object opts, readtimetable uses the VariableNames property of opts to create variable names.

Unspecified

Automatically detect whether the region contains variable names.

For text, spreadsheet, Microsoft Word, and HTML files, variable names are detected after header rows. For JSON files, variable names are detected from object key names (since R2026a). For XML files, variable names are detected from element node and attribute names.

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

`VariableNamingRule` — Rule for variable names (Text, spreadsheet, JSON, XML, Microsoft Word, and HTML files)
`"modify"` | `"preserve"`

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

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

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

`ExpectedNumVariables` — Expected number of variables (Text and spreadsheet files)
nonnegative integer

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

`VariableNamesLine` — Location of variable names (Text files)
nonnegative integer

Location of variable names, specified as a nonnegative integer.

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

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

`VariableNamesRange` — Location of variable names (Spreadsheet files)
string scalar | character vector | positive integer

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

Ways to Specify VariableNamesRange Description

Ways to Specify `VariableNamesRange`	Description
`"Cell"` Starting cell	Specify the starting cell for the variable names as a string scalar or character vector containing a column letter and row number, using A1 notation. Example: `"A5"` identifies the cell at the intersection of column `A` and row `5`.
`"Corner1:Corner2"` Rectangular range	Specify the range using the form `"Corner1:Corner2"`, where `Corner1` and `Corner2` are two opposing corners that define the region for variable names. The range must span only one row. Example: `"A5:K5"`
`n` Number index	Specify the row containing the variable names using a positive row index. Example: `5`
`"Row1:Row2"` Row range	Specify the range using the form `"Row1:Row2"`, where `Row1` and `Row2` are the same row index. Variable names must be in a single row. Example: `"5:5"`
`""` Unspecified or empty	Indicate that there are no variable names. Example: `""`

"Cell"

Starting cell

Specify the starting cell for the variable names as a string scalar or character vector containing a column letter and row number, using A1 notation.

Example: "A5" identifies the cell at the intersection of column A and row 5.

"Corner1:Corner2"

Rectangular range

Specify the range using the form "Corner1:Corner2", where Corner1 and Corner2 are two opposing corners that define the region for variable names.

The range must span only one row.

Example: "A5:K5"

n

Number index

Specify the row containing the variable names using a positive row index.

Example: 5

"Row1:Row2"

Row range

Specify the range using the form "Row1:Row2", where Row1 and Row2 are the same row index.

Variable names must be in a single row.

Example: "5:5"

""

Unspecified or empty

Indicate that there are no variable names.

Example: ""

Data Types: string | char | single | double

`VariableNamesRow` — Location of variable names (Microsoft Word and HTML files)
nonnegative integer

Location of variable names, specified as a nonnegative integer.

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

If you do not specify VariableNamesRow, and ReadVariableNames is true (default), then readtimetable imports variable names. If both are unspecified, readtimetable detects if a row contains variable names to import.

`VariableNodeNames` — JSON key names or XML node names to read as table variables (JSON and XML files)
string array | character vector | cell array of character vectors

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

Example: VariableNodeNames=["XMLNodeName1","XMLNodeName2"]

`VariableSelectors` — Variables to read (JSON and XML files)
string array | character vector | cell array of character vectors

Variables to read, specified as a string array, character vector, or cell array of character vectors. If you do not specify this name-value argument, readtimetable detects the location of variables.

JSON Files

(since R2026a)

Specify the variables to read as a string array, character vector, or cell array of character vectors containing JSON Pointers. You must specify VariableSelectors as valid RFC 6901 JSON Pointers. For more information, see the IETF definition of JSON Pointer.

An asterisk (*) in a VariableSelectors value indicates an entire array at that corresponding level is selected.

To read keys as variables, include the string "Keys" with VariableSelectors. For example, VariableSelectors=["Keys" "/ID" "/Name/FirstName"].

An empty string ("") refers to the whole JSON file.

Example: VariableSelectors="/enginetemp"

Example: VariableSelectors=["/enginetemp1","/enginetemp2"]

XML Files

Specify the variables to read as a string array, character vector, or cell array of character vectors containing XPath expressions. You must specify VariableSelectors as valid XPath version 1.0 expressions. For example, suppose you want to import the XML file myFile.xml, which has this structure:

<data>
    <table category="ones">
        <var>1</var>
        <var>2</var>
    </table>
    <table category="tens">
        <var>10</var>
        <var>20</var>
    </table>
</data>

Selection Operation	Syntax	Example
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 (`//`).	Select every node named `var`. T = readtimetable("myFile.xml",VariableSelectors="//var")
Select the value of an attribute belonging to an element node.	Prefix the attribute with an at sign (`@`).	Select the value of the `category` attribute of the `table` node. T = readtimetable("myFile.xml",VariableSelectors="//table/@category")
Select a specific node in a set of nodes.	Provide the index of the node you want to select in square brackets (`[]`).	Select the first `var` node of each `table` node. T = readtimetable("myFile.xml",VariableSelectors="//table/var[1]")
Specify precedence of operations.	Add parentheses around the expression you want to evaluate first.	Select the first `var` node of each `table` node. T = readtimetable("myFile.xml",VariableSelectors="//table/var[1]")
Specify precedence of operations.		Select the first `var` node of the first `table` node. T = readtimetable("myFile.xml",VariableSelectors="(//table/var)[1]")

`CollectOutput` — Concatenate data (Text, JSON, and XML files)
`false` or `0` (default) | `true` or `1`

Concatenate data, specified as a numeric or logical 1 (true) or 0 (false). If CollectOutput is true, then readtimetable concatenates consecutive output cells of the same fundamental MATLAB class into a single array.

Time Data

expand all

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

`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

Rows

expand all

`RowSelector` — XPath expression for rows to read (XML files)
string scalar | character vector

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

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

Example: "/RootNode/ChildNode"

`RowNodeName` — XML nodes specifying rows (XML files)
string scalar | character vector

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

Data Types

expand all

`TextType` — Type for imported text data (Text, spreadsheet, JSON, XML, Microsoft Word, and HTML files)
`"char"` | `"string"`

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

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

`DatetimeType` — Type for imported date and time data (Text, spreadsheet, JSON, XML, Microsoft Word, and HTML files)
`"datetime"` (default) | `"text"` | `"exceldatenum"` (spreadsheet files only)

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

Value Resulting Data Type

Value	Resulting Data Type
`"datetime"`	MATLAB `datetime` data type
`"text"`	The data type depends on the value of `TextType`. If `TextType` is `"char"`, then dates are a cell array of character vectors. If `TextType` is `"string"`, then dates are a string array.
`"exceldatenum"`	Excel serial date numbers This value is valid only for spreadsheet 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.

"datetime"

MATLAB datetime data type

"text"

The data type depends on the value of TextType.

If TextType is "char", then dates are a cell array of character vectors.
If TextType is "string", then dates are a string array.

"exceldatenum"

Excel serial date numbers

This value is valid only for spreadsheet 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.

`DurationType` — Type for imported duration data (Text, JSON, XML, Microsoft Word, and HTML files)
`"duration"` (default) | `"text"`

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

Value Resulting Data Type

Value	Resulting Data Type
`"duration"`	MATLAB `duration` data type
`"text"`	The data type depends on the value of `TextType`. If `TextType` is `"char"`, then duration data is a cell array of character vectors. If `TextType` is `"string"`, then duration data is a string array.

"duration"

MATLAB duration data type

"text"

The data type depends on the value of TextType.

If TextType is "char", then duration data is a cell array of character vectors.
If TextType is "string", then duration data is a string array.

`HexType` — Type for imported hexadecimal data (Text, XML, Microsoft Word, and HTML files)
`"auto"` (default) | `"text"` | `"int8"` | `"int16"` | ...

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

Value	Resulting Data Type
`"auto"`	Detected data type; `readtimetable` determines the smallest integer type that can represent all variable values.
`"text"`	Unaltered input text
`"int8"`	8-bit integer, signed
`"int16"`	16-bit integer, signed
`"int32"`	32-bit integer, signed
`"int64"`	64-bit integer, signed
`"uint8"`	8-bit integer, unsigned
`"uint16"`	16-bit integer, unsigned
`"uint32"`	32-bit integer, unsigned
`"uint64"`	64-bit integer, unsigned

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

`BinaryType` — Type for imported binary data (Text, XML, Microsoft Word, and HTML files)
`"auto"` (default) | `"text"` | `"int8"` | `"int16"` | ...

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

Value	Resulting Data Type
`"auto"`	Detected data type; `readtimetable` determines the smallest integer type that can represent all variable values.
`"text"`	Unaltered input text
`"int8"`	8-bit integer, signed
`"int16"`	16-bit integer, signed
`"int32"`	32-bit integer, signed
`"int64"`	64-bit integer, signed
`"uint8"`	8-bit integer, unsigned
`"uint16"`	16-bit integer, unsigned
`"uint32"`	32-bit integer, unsigned
`"uint64"`	64-bit integer, unsigned

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

`DateLocale` — Locale for reading dates (Text, JSON, XML, Microsoft Word, and HTML files)
string scalar | character vector

Locale for reading dates, specified as a string scalar or character vector of the form xx_YY, where:

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

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

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

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

`TrimNonNumeric` — Remove nonnumeric characters (Text, XML, Microsoft Word, and HTML files)
`false` or `0` (default) | `true` or `1`

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

`DecimalSeparator` — Decimal separator character (Text, XML, Microsoft Word, and HTML files)
`"."` (default) | string scalar | character vector

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

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

`ThousandsSeparator` — Thousands grouping character (Text, XML, Microsoft Word, and HTML files)
`""` (default) | string scalar | character vector

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

`ExponentCharacter` — Exponent characters (Text, XML, Microsoft Word, and HTML files)
`"eEdD"` (default) | string scalar | character vector

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

Example: "eE"

Data Cleaning

expand all

`TreatAsMissing` — Placeholder text to treat as missing value (Text, spreadsheet, XML, Microsoft Word, and HTML files)
string array | character vector | cell array of character vectors

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

Example: "N/A"

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

`ImportErrorRule` — Rule for import errors (Text, spreadsheet, JSON, XML, Microsoft Word, and HTML files)
`"fill"` (default) | `"error"` | `"omitrow"` | `"omitvar"`

Rule for import errors, specified as one of the values in this table. An import error occurs when readtimetable cannot convert a text element to the expected data type.

Import Error Rule	Behavior
`"fill"`	Replace the data where the error occurred with the contents of the `FillValue` property. You can set the `FillValue` property in the `VariableImportOptions` object of the variable being imported. For more information on setting the `FillValue` property, see `setvaropts`.
`"error"`	Display an error message and cancel the import operation.
`"omitrow"`	Omit rows where errors occur.
`"omitvar"`	Omit variables where errors occur.

`MissingRule` — Rule for missing data (Text, spreadsheet, JSON, XML, Microsoft Word, and HTML files)
`"fill"` (default) | `"error"` | `"omitrow"` | `"omitvar"`

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

Missing Rule	Behavior
`"fill"`	Replace missing data with the contents of the `FillValue` property. You can set the `FillValue` property in the `VariableImportOptions` object of the variable being imported. For more information on setting the `FillValue` property, see `setvaropts`.
`"error"`	Display an error message and cancel the import operation.
`"omitrow"`	Omit rows that contain missing data.
`"omitvar"`	Omit variables that contain missing data.

For text files, Microsoft Word, and HTML files, data is considered missing if an expected field in a row does not exist. Because missing fields cause subsequent elements of a row to shift fields, the missing fields are interpreted at the end of the row.

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

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

`ExtraColumnsRule` — Rule for extra columns (Text, Microsoft Word, and HTML files)
`"addvars"` (default) | `"ignore"` | `"wrap"` | `"error"`

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

Extra Columns Rule	Behavior
`"addvars"`	To import extra columns, create new variables. If there are `N` extra columns, then import new variables as `"ExtraVar1","ExtraVar2",...,"ExtraVarN"`. `readtimetable` imports the extra columns as text of data type `char`.
`"ignore"`	Ignore the extra columns of data.
`"wrap"`	Wrap the extra columns of data to new records. This action does not change the number of variables.
`"error"`	Display an error message and cancel the import operation.

`EmptyLineRule` — Rule for empty lines (Text files)
`"skip"` (default) | `"read"` | `"error"`

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

Empty Line Rule	Behavior
`"skip"`	Skip the empty lines.
`"read"`	Import the empty lines. `readtimetable` parses an empty line using the values specified in `VariableWidths`, `VariableOptions`, `MissingRule`, and other relevant arguments, such as `Whitespace`.
`"error"`	Display an error message and cancel the import operation.

`EmptyRowRule` — Rule for empty rows (Microsoft Word and HTML files)
`"skip"` (default) | `"read"` | `"error"`

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

Empty Line Rule	Behavior
`"skip"`	Skip the empty rows.
`"read"`	Import the empty rows. `readtimetable` parses an empty row using the values specified in `VariableWidths`, `VariableOptions`, `MissingRule`, and other relevant arguments, such as `Whitespace`.
`"error"`	Display an error message and cancel the import operation.

`EmptyColumnRule` — Rule for empty columns (Microsoft Word and HTML files)
`"skip"` (default) | `"read"` | `"error"`

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

Empty Column Rule	Behavior
`"skip"`	Skip the empty columns.
`"read"`	Import the empty columns. `readtimetable` parses an empty column using the values specified in `VariableWidths`, `VariableOptions`, `MissingRule`, and other relevant arguments, such as `Whitespace`.
`"error"`	Display an error message and cancel the import operation.

`PartialFieldRule` — Rule for partial fields (Text files)
`"keep"` (default) | `"fill"` | `"omitrow"` | `"omitvar"` | `"wrap"` | `"error"`

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

Partial Field Rule	Behavior
`"keep"`	Keep the partial field data and convert the text to the appropriate data type. If `readtimetable` is unable to interpret the partial data, a conversion error can occur.
`"fill"`	Replace missing data with the contents of the `FillValue` property. You can set the `FillValue` property in the `VariableImportOptions` object of the variable being imported. For more information on setting the `FillValue` property, see `setvaropts`.
`"omitrow"`	Omit rows that contain partial data.
`"omitvar"`	Omit variables that contain partial data.
`"wrap"`	Begin reading the next line of characters.
`"error"`	Display an error message and cancel the import operation.

File Information

expand all

`FileType` — Type of file (Text, spreadsheet, JSON, XML, Microsoft Word, and HTML files)
`"spreadsheet"` | `"text"` | `"delimitedtext"` | `"fixedwidth"` | `"json"` | `"xml"` | `"worddocument"` | `"html"`

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

Value	File Type
`"spreadsheet"`	Spreadsheet files
`"text"`	Text files
`"delimitedtext"`	Delimited text files
`"fixedwidth"`	Fixed-width text files
`"json"`	JSON files
`"xml"`	XML files
`"worddocument"`	Microsoft Word documents
`"html"`	HTML files

Specify this name-value argument when filename does not include the file extension or when its extension is not in this list:

.txt, .dat, or .csv for text files
.xls, .xlsb, .xlsm, .xlsx, .xltm, .xltx, or .ods for spreadsheet files
.json for JSON files
.xml for XML files
.docx for Microsoft Word documents
.html, .xhtml, or .htm for HTML files

`Encoding` — Character encoding scheme (Text files)
`"system"` | `"UTF-8"` | `"ISO-8859-1"` | `"windows-1251"` | `"windows-1252"` | ...

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

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

`UseExcel` — Start instance of Microsoft Excel for Windows (Spreadsheet files)
`false` or `0` (default) | `true` or `1`

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

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

Support	If `UseExcel` is `true`	If `UseExcel` is `false`
Supported file formats	`.xls`, `.xlsb`, `.xlsm`, `.xlsx`, `.xltm`, `.xltx`, `.ods`	`.xls`, `.xlsm`, `.xlsx`, `.xltm`, `.xltx`
Support for interactive features, such as formulas and macros	Yes	No

UseExcel is not supported in noninteractive, automated environments.

`WebOptions` — `HTTP` or `HTTPS` request options (Text, spreadsheet, JSON, XML, Microsoft Word, and HTML files)
`weboptions` object

Since R2022a

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

Text Parsing

expand all

`Delimiter` — Field delimiter character (Text files)
string array | character vector | cell array of character vectors

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

This table lists some commonly used field delimiter characters.

Specifier	Field Delimiter
`","` `"comma"`	Comma
`" "` `"space"`	Space
`"\t"` `"tab"`	Tab
`";"` `"semi"`	Semicolon
`"\|"` `"bar"`	Vertical bar
Unspecified	If you do not specify this name-value argument, `readtimetable` automatically detects the delimiter.

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

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

`LineEnding` — End-of-line characters (Text files)
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. Common end-of-line characters include the newline character ("\n") and the carriage return ("\r"). If you specify "\r\n", then readtimetable treats the combination of the two (\r\n) as end-of-line characters. If you specify {"\r\n", "\r", "\n"}, then \r, \n, and \r\n are all treated as end-of-line characters.

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

`Whitespace` — Characters to treat as white space (Text files)
`"\b\t"` (default) | string scalar | character vector

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

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

Special Character	Representation
Percent	`%%`
Backslash	`\\`
Alarm	`\a`
Backspace	`\b`
Form feed	`\f`
New line	`\n`
Carriage return	`\r`
Horizontal tab	`\t`
Vertical tab	`\v`
Character whose Unicode^® numeric value can be represented by the hexadecimal number, `N`	`\xN`
Character whose Unicode numeric value can be represented by the octal number, `N`	`\N`

Example: " _"

Example: "?!.,"

`CommentStyle` — Comment indicators for text to ignore (Text files)
string array | character vector | cell array of character vectors

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

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

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

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

`LeadingDelimitersRule` — Rule for leading delimiters (Text files)
`"keep"` | `"ignore"` | `"error"`

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

Rule	Behavior
`"keep"`	Keep the delimiter.
`"ignore"`	Ignore the delimiter.
`"error"`	Display an error message and cancel the import operation.

`TrailingDelimitersRule` — Rule for trailing delimiters (Text files)
`"keep"` | `"ignore"` | `"error"`

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

Rule	Behavior
`"keep"`	Keep the delimiter.
`"ignore"`	Ignore the delimiter.
`"error"`	Display an error message and cancel the import operation.

`ConsecutiveDelimitersRule` — Rule for consecutive delimiters (Text files)
`"split"` | `"join"` | `"error"`

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

Rule	Behavior
`"split"`	Split the consecutive delimiters into multiple fields.
`"join"`	Join the delimiters into one delimiter.
`"error"`	Display an error message and cancel the import operation.

`MultipleDelimsAsOne` — Treat multiple delimiters as one (Text files)
`false` or `0` (default) | `true` or `1`

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

`VariableWidths` — Field widths of variables (Text files)
vector of positive integers

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

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

JSON and XML Parsing

expand all

`ParsingMode` — How strictly to follow JSON standards while parsing (JSON files)
`"lenient"` (default) | `"strict"`

Since R2026a

How strictly to follow JSON standards while parsing, specified as one of these values:

"lenient" – The values of AllowComments, AllowInfAndNaN, and AllowTrailingCommas are set to true.
"strict" – The values of AllowComments, AllowInfAndNaN, and AllowTrailingCommas are set to false.

`AllowComments` — Allow comments (JSON files)
`true` or `1` (default) | `false` or `0`

Since R2026a

Allow comments in the input file, specified as one of these values:

Numeric or logical 1 (true) – Comments do not cause an error during import. Comments in the file are not considered data and are not read into MATLAB. Comments can start with "//" for single-line comments or start with "/*" and end with "*/" for multi-line comments.
Numeric or logical 0 (false) – Comments cause an error during import.

`AllowInfAndNaN` — Read `Inf` and `NaN` values (JSON files)
`true` or `1` (default) | `false` or `0`

Since R2026a

Read Inf and NaN values in the input file, specified as one of these values:

Numeric or logical 1 (true) – Inf and NaN values (including Infinity, -Inf, and -Infinity) are read into MATLAB.
Numeric or logical 0 (false) – Inf and NaN values cause an error during import.

`AllowTrailingCommas` — Read trailing commas (JSON files)
`true` or `1` (default) | `false` or `0`

Since R2026a

Read trailing commas in the input file, specified as one of these values:

Numeric or logical 1 (true) – Trailing commas after a JSON array or JSON object do not cause an error during import.
Numeric or logical 0 (false) – Trailing commas cause an error during import.

`RepeatedNodeRule` — Rule for repeated JSON or XML nodes (JSON and XML files)
`"addcol"` (default) | `"ignore"` | `"error"`

Rule for repeated JSON (since R2026a) or XML nodes in a given row of a table, specified as one of the values in this table. For JSON files, this rule applies when the VariableSelectors name-value argument contains a JSON Pointer that points to an array. The array entries are considered repeated nodes.

Rule	Behavior
`"addcol"`	Add columns for each repeated node in a variable to create a matrix in the associated variable. `"addcol"` does not create a separate variable in the table for the repeated node. For example: Input XML data <table> <row> <Var1>1</Var1> <Var2>2</Var2> <Var3>3</Var3> <Var1>11</Var1> <Var1>111</Var1> </row> <row> <Var1>4</Var1> <Var2>5</Var2> <Var3>6</Var3> </row> <row> <Var1>7</Var1> <Var2>8</Var2> <Var3>9</Var3> </row> </table> Output table Var1 Var2 Var3 _______________ ____ ____ 1 11 111 2 3 4 NaN NaN 5 6 7 NaN NaN 8 9
`"ignore"`	Skip the repeated nodes.
`"error"`	Display an error message and cancel the import operation.

Rule

Behavior

"addcol"

Add columns for each repeated node in a variable to create a matrix in the associated variable. "addcol" does not create a separate variable in the table for the repeated node.

For example:

Input XML data

    <table>
        <row>
            <Var1>1</Var1>
            <Var2>2</Var2>
            <Var3>3</Var3>
            <Var1>11</Var1>
            <Var1>111</Var1>
        </row>
        <row>
            <Var1>4</Var1>
            <Var2>5</Var2>
            <Var3>6</Var3>
        </row>
        <row>
            <Var1>7</Var1>
            <Var2>8</Var2>
            <Var3>9</Var3>
        </row>
    </table>

Output table

         Var1          Var2    Var3
    _______________    ____    ____

    1     11    111     2       3  
    4    NaN    NaN     5       6  
    7    NaN    NaN     8       9

"ignore"

Skip the repeated nodes.

"error" Display an error message and cancel the import operation.

`ImportAttributes` — Import attributes (XML files)
`true` or `1` (default) | `false` or `0`

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

`AttributeSuffix` — Attribute suffix (XML files)
`"Attribute"` (default) | string scalar | character vector

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

Example: "_att"

`RegisteredNamespaces` — Set of registered XML namespace prefixes (XML files)
`N`-by-2 string array

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

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

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

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

Variable Metadata

expand all

`VariableUnitsLine` — Location of variable units (Text files)
`0` (default) | nonnegative integer

Location of variable units, specified as a nonnegative integer.

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

`VariableUnitsRange` — Location of variable units (Spreadsheet files)
string scalar | character vector | positive integer

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

Ways to Specify VariableUnitsRange Description

Ways to Specify `VariableUnitsRange`	Description
`"Cell"` Starting cell	Specify the starting cell for the variable units as a string scalar or character vector containing a column letter and row number, using A1 notation. From the starting cell, `readtimetable` identifies a unit for each variable in the data. Example: `"A5"` identifies the cell at the intersection of column `A` and row `5`.
`"Corner1:Corner2"` Rectangular range	Specify the range using the form `"Corner1:Corner2"`, where `Corner1` and `Corner2` are two opposing corners that define the region for variable units. The range must span only one row. Example: `"A5:K5"`
`n` Number index	Specify the row containing the variable units using a positive row index. Example: `5`
`"Row1:Row2"` Row range	Specify the range using the form `"Row1:Row2"` where `Row1` and `Row2` are the same row index. Variable units must be in a single row. Example: `"5:5"`
`""` Unspecified or empty	Indicate that there are no variable units. Example: `""`

"Cell"

Starting cell

Specify the starting cell for the variable units as a string scalar or character vector containing a column letter and row number, using A1 notation.

From the starting cell, readtimetable identifies a unit for each variable in the data.

Example: "A5" identifies the cell at the intersection of column A and row 5.

"Corner1:Corner2"

Rectangular range

Specify the range using the form "Corner1:Corner2", where Corner1 and Corner2 are two opposing corners that define the region for variable units.

The range must span only one row.

Example: "A5:K5"

n

Number index

Specify the row containing the variable units using a positive row index.

Example: 5

"Row1:Row2"

Row range

Specify the range using the form "Row1:Row2" where Row1 and Row2 are the same row index.

Variable units must be in a single row.

Example: "5:5"

""

Unspecified or empty

Indicate that there are no variable units.

Example: ""

Data Types: string | char | single | double

`VariableUnitsRow` — Location of variable units (Microsoft Word and HTML files)
`0` (default) | nonnegative integer

Location of variable units, specified as a nonnegative integer.

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

`VariableUnitsSelector` — Variable units (JSON and XML files)
string scalar | character vector

Variable units, specified as a string scalar or character vector. If you do not specify this name-value argument, readtimetable does not import variable units.

JSON Files

(since R2026a)

Specify the variable units as a string scalar or character vector containing a JSON Pointer. You must specify VariableUnitsSelector as a valid RFC 6901 JSON Pointer. For more information, see the IETF definition of JSON Pointer.

Example: VariableUnitsSelector="/statuses/metadata/units"

XML Files

Specify the variable units as a string scalar or character vector containing an XPath expression. You must specify VariableUnitsSelector as a valid XPath version 1.0 expression.

Example: VariableUnitsSelector="/RootNode/ChildNode"

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

`VariableDescriptionsLine` — Location of variable descriptions (Text files)
`0` (default) | nonnegative integer

Location of variable descriptions, specified as a nonnegative integer.

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

`VariableDescriptionsRange` — Location of variable descriptions (Spreadsheet files)
string scalar | character vector | positive integer

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

Ways to Specify VariableDescriptionsRange Description

Ways to Specify `VariableDescriptionsRange`	Description
`"Cell"` Starting cell	Specify the starting cell for the variable descriptions as a string scalar or character vector containing a column letter and row number, using A1 notation. From the starting cell, `readtimetable` identifies a description for each variable in the data. Example: `"A5"` identifies the cell at the intersection of column `A` and row `5`.
`"Corner1:Corner2"` Rectangular range	Specify the range using the form `"Corner1:Corner2"`, where `Corner1` and `Corner2` are two opposing corners that define the region for variable descriptions. The range must span only one row. Example: `"A5:K5"`
`"Row1:Row2"` Row range	Specify the range using the form `"Row1:Row2"` where `Row1` and `Row2` are the same row index. Variable descriptions must be in a single row. Example: `"5:5"`
`n` Number index	Specify the row containing the descriptions using a positive row index. Example: `5`
`""` Unspecified or empty	Indicate that there are no variable descriptions. Example: `""`

"Cell"

Starting cell

Specify the starting cell for the variable descriptions as a string scalar or character vector containing a column letter and row number, using A1 notation.

From the starting cell, readtimetable identifies a description for each variable in the data.

Example: "A5" identifies the cell at the intersection of column A and row 5.

"Corner1:Corner2"

Rectangular range

Specify the range using the form "Corner1:Corner2", where Corner1 and Corner2 are two opposing corners that define the region for variable descriptions.

The range must span only one row.

Example: "A5:K5"

"Row1:Row2"

Row range

Specify the range using the form "Row1:Row2" where Row1 and Row2 are the same row index.

Variable descriptions must be in a single row.

Example: "5:5"

n

Number index

Specify the row containing the descriptions using a positive row index.

Example: 5

""

Unspecified or empty

Indicate that there are no variable descriptions.

Example: ""

Data Types: string | char | single | double

`VariableDescriptionsRow` — Location of variable descriptions (Microsoft Word and HTML files)
`0` (default) | nonnegative integer

Location of variable descriptions, specified as a nonnegative integer.

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

`VariableDescriptionsSelector` — Variable descriptions (JSON and XML files)
string scalar | character vector

Variable descriptions, specified as a string scalar or character vector. If you do not specify this name-value argument, readtimetable does not import variable descriptions.

JSON Files

(since R2026a)

Specify the variable descriptions as a string scalar or character vector containing a JSON Pointer. You must specify VariableDescriptionsSelector as a valid RFC 6901 JSON Pointer. For more information, see the IETF definition of JSON Pointer.

Example: VariableDescriptionsSelector="/statuses/metadata"

XML Files

Specify the variable descriptions as a string scalar or character vector containing an XPath expression. You must specify VariableDescriptionsSelector as a valid XPath version 1.0 expression.

Example: VariableDescriptionsSelector="/RootNode/RowNode/@Name"

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

Output Arguments

collapse all

`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:

<data>
    <table category="ones">
        <var>1</var>
        <var>2</var>
    </table>
    <table category="tens">
        <var>10</var>
        <var>20</var>
    </table>
</data>

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 = readtimetable('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 = readtimetable('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 = readtimetable('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 = readtimetable('myFile.xml', 'VariableSelectors', '//table/var[1]')	data = 2×1 table var ___ 1 10
Specify precedence of operations.		data = readtimetable('myFile.xml', 'VariableSelectors', '(//table/var)[1]')	data = table var ___ 1

Version History

Introduced in R2019a

expand all

R2026a: Read JSON files

Read JSON data as a timetable. Specify optional name-value arguments to control the import behavior. For example, set AllowComments to false if you want comments in the input JSON file to cause an error during import.

R2025a: Read data from compressed and archived files

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

R2024b: 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.

readtimetable

Syntax

Description

Examples

Create Timetable from Text File

Create Timetable from File Using Import Options

Create Timetable from File and Specify Row Times

Create Timetable from Spreadsheet File and Format Input Data

Input Arguments

filename — Name of file to read string scalar | character vector

Text Files

Spreadsheet Files

JSON Files

XML Files

Microsoft Word Documents

HTML Files

Compressed and Archived Files

opts — File import options DelimitedTextImportOptions object | FixedWidthImportOptions object | SpreadsheetImportOptions object | …

Name-Value Arguments

Data and Header Location

NumHeaderLines — Number of header lines to skip (Text and spreadsheet files) nonnegative integer

Range — Range to read (Text and spreadsheet files) string scalar | character vector | numeric vector

DataRange — Location of data (Spreadsheet files) string scalar | character vector | positive integer | array of positive integers

Sheet — Worksheet to read (Spreadsheet files) 1 (default) | positive integer | string scalar | character vector

TableIndex — Index of table to read (Microsoft Word and HTML files) 1 (default) | positive integer

TableSelector — Table to read (JSON, XML, Microsoft Word, and HTML files) string scalar | character vector

JSON Files

XML Files

TableNodeName — JSON key name or XML node name for table data to read (JSON and XML files) string scalar | character vector

MergedCellColumnRule — Rule for cells merged across columns (Spreadsheet, Microsoft Word, and HTML files) "placeleft" (default) | "placeright" | "duplicate" | "omitrow" | "error"

MergedCellRowRule — Rule for cells merged across rows (Spreadsheet, Microsoft Word, and HTML files) "placetop" (default) | "placebottom" | "duplicate" | "omitvar" | "error"

Variables

ReadVariableNames — Read variable names (Text, spreadsheet, JSON, XML, Microsoft Word, and HTML files) true or 1 | false or 0

VariableNamingRule — Rule for variable names (Text, spreadsheet, JSON, XML, Microsoft Word, and HTML files) "modify" | "preserve"

ExpectedNumVariables — Expected number of variables (Text and spreadsheet files) nonnegative integer

VariableNamesLine — Location of variable names (Text files) nonnegative integer

VariableNamesRange — Location of variable names (Spreadsheet files) string scalar | character vector | positive integer

VariableNamesRow — Location of variable names (Microsoft Word and HTML files) nonnegative integer

VariableNodeNames — JSON key names or XML node names to read as table variables (JSON and XML files) string array | character vector | cell array of character vectors

VariableSelectors — Variables to read (JSON and XML files) string array | character vector | cell array of character vectors

JSON Files

XML Files

CollectOutput — Concatenate data (Text, JSON, and XML files) false or 0 (default) | true or 1

Time Data

RowTimes — Row times variable variable name | time vector

SampleRate — Sample rate for row times numeric scalar

TimeStep — Time step between row times duration scalar | calendarDuration scalar

StartTime — Start time of row times datetime scalar | duration scalar

Rows

RowSelector — XPath expression for rows to read (XML files) string scalar | character vector

RowNodeName — XML nodes specifying rows (XML files) string scalar | character vector

Data Types

TextType — Type for imported text data (Text, spreadsheet, JSON, XML, Microsoft Word, and HTML files) "char" | "string"

DatetimeType — Type for imported date and time data (Text, spreadsheet, JSON, XML, Microsoft Word, and HTML files) "datetime" (default) | "text" | "exceldatenum" (spreadsheet files only)

DurationType — Type for imported duration data (Text, JSON, XML, Microsoft Word, and HTML files) "duration" (default) | "text"

HexType — Type for imported hexadecimal data (Text, XML, Microsoft Word, and HTML files) "auto" (default) | "text" | "int8" | "int16" | ...

BinaryType — Type for imported binary data (Text, XML, Microsoft Word, and HTML files) "auto" (default) | "text" | "int8" | "int16" | ...

DateLocale — Locale for reading dates (Text, JSON, XML, Microsoft Word, and HTML files) string scalar | character vector

TrimNonNumeric — Remove nonnumeric characters (Text, XML, Microsoft Word, and HTML files) false or 0 (default) | true or 1

DecimalSeparator — Decimal separator character (Text, XML, Microsoft Word, and HTML files) "." (default) | string scalar | character vector

ThousandsSeparator — Thousands grouping character (Text, XML, Microsoft Word, and HTML files) "" (default) | string scalar | character vector

ExponentCharacter — Exponent characters (Text, XML, Microsoft Word, and HTML files) "eEdD" (default) | string scalar | character vector

Data Cleaning

TreatAsMissing — Placeholder text to treat as missing value (Text, spreadsheet, XML, Microsoft Word, and HTML files) string array | character vector | cell array of character vectors

ImportErrorRule — Rule for import errors (Text, spreadsheet, JSON, XML, Microsoft Word, and HTML files) "fill" (default) | "error" | "omitrow" | "omitvar"

MissingRule — Rule for missing data (Text, spreadsheet, JSON, XML, Microsoft Word, and HTML files) "fill" (default) | "error" | "omitrow" | "omitvar"

ExtraColumnsRule — Rule for extra columns (Text, Microsoft Word, and HTML files) "addvars" (default) | "ignore" | "wrap" | "error"

EmptyLineRule — Rule for empty lines (Text files) "skip" (default) | "read" | "error"

EmptyRowRule — Rule for empty rows (Microsoft Word and HTML files) "skip" (default) | "read" | "error"

EmptyColumnRule — Rule for empty columns (Microsoft Word and HTML files) "skip" (default) | "read" | "error"

PartialFieldRule — Rule for partial fields (Text files) "keep" (default) | "fill" | "omitrow" | "omitvar" | "wrap" | "error"

File Information

FileType — Type of file (Text, spreadsheet, JSON, XML, Microsoft Word, and HTML files) "spreadsheet" | "text" | "delimitedtext" | "fixedwidth" | "json" | "xml" | "worddocument" | "html"

Encoding — Character encoding scheme (Text files) "system" | "UTF-8" | "ISO-8859-1" | "windows-1251" | "windows-1252" | ...

UseExcel — Start instance of Microsoft Excel for Windows (Spreadsheet files) false or 0 (default) | true or 1

WebOptions — HTTP or HTTPS request options (Text, spreadsheet, JSON, XML, Microsoft Word, and HTML files) weboptions object

Text Parsing

Delimiter — Field delimiter character (Text files) string array | character vector | cell array of character vectors

LineEnding — End-of-line characters (Text files) string array | character vector | cell array of character vectors

Whitespace — Characters to treat as white space (Text files) "\b\t" (default) | string scalar | character vector

`filename` — Name of file to read
string scalar | character vector

`opts` — File import options
`DelimitedTextImportOptions` object | `FixedWidthImportOptions` object | `SpreadsheetImportOptions` object | …

`NumHeaderLines` — Number of header lines to skip (Text and spreadsheet files)
nonnegative integer

`Range` — Range to read (Text and spreadsheet files)
string scalar | character vector | numeric vector

`DataRange` — Location of data (Spreadsheet files)
string scalar | character vector | positive integer | array of positive integers

`Sheet` — Worksheet to read (Spreadsheet files)
`1` (default) | positive integer | string scalar | character vector

`TableIndex` — Index of table to read (Microsoft Word and HTML files)
`1` (default) | positive integer

`TableSelector` — Table to read (JSON, XML, Microsoft Word, and HTML files)
string scalar | character vector

`TableNodeName` — JSON key name or XML node name for table data to read (JSON and XML files)
string scalar | character vector

`MergedCellColumnRule` — Rule for cells merged across columns (Spreadsheet, Microsoft Word, and HTML files)
`"placeleft"` (default) | `"placeright"` | `"duplicate"` | `"omitrow"` | `"error"`

`MergedCellRowRule` — Rule for cells merged across rows (Spreadsheet, Microsoft Word, and HTML files)
`"placetop"` (default) | `"placebottom"` | `"duplicate"` | `"omitvar"` | `"error"`

`ReadVariableNames` — Read variable names (Text, spreadsheet, JSON, XML, Microsoft Word, and HTML files)
`true` or `1` | `false` or `0`

`VariableNamingRule` — Rule for variable names (Text, spreadsheet, JSON, XML, Microsoft Word, and HTML files)
`"modify"` | `"preserve"`

`ExpectedNumVariables` — Expected number of variables (Text and spreadsheet files)
nonnegative integer

`VariableNamesLine` — Location of variable names (Text files)
nonnegative integer

`VariableNamesRange` — Location of variable names (Spreadsheet files)
string scalar | character vector | positive integer

`VariableNamesRow` — Location of variable names (Microsoft Word and HTML files)
nonnegative integer

`VariableNodeNames` — JSON key names or XML node names to read as table variables (JSON and XML files)
string array | character vector | cell array of character vectors

`VariableSelectors` — Variables to read (JSON and XML files)
string array | character vector | cell array of character vectors

`CollectOutput` — Concatenate data (Text, JSON, and XML files)
`false` or `0` (default) | `true` or `1`

`RowTimes` — Row times variable
variable name | time vector

`SampleRate` — Sample rate for row times
numeric scalar

`TimeStep` — Time step between row times
duration scalar | calendarDuration scalar

`StartTime` — Start time of row times
datetime scalar | duration scalar

`RowSelector` — XPath expression for rows to read (XML files)
string scalar | character vector

`RowNodeName` — XML nodes specifying rows (XML files)
string scalar | character vector

`TextType` — Type for imported text data (Text, spreadsheet, JSON, XML, Microsoft Word, and HTML files)
`"char"` | `"string"`

`DatetimeType` — Type for imported date and time data (Text, spreadsheet, JSON, XML, Microsoft Word, and HTML files)
`"datetime"` (default) | `"text"` | `"exceldatenum"` (spreadsheet files only)

`DurationType` — Type for imported duration data (Text, JSON, XML, Microsoft Word, and HTML files)
`"duration"` (default) | `"text"`

`HexType` — Type for imported hexadecimal data (Text, XML, Microsoft Word, and HTML files)
`"auto"` (default) | `"text"` | `"int8"` | `"int16"` | ...

`BinaryType` — Type for imported binary data (Text, XML, Microsoft Word, and HTML files)
`"auto"` (default) | `"text"` | `"int8"` | `"int16"` | ...

`DateLocale` — Locale for reading dates (Text, JSON, XML, Microsoft Word, and HTML files)
string scalar | character vector

`TrimNonNumeric` — Remove nonnumeric characters (Text, XML, Microsoft Word, and HTML files)
`false` or `0` (default) | `true` or `1`

`DecimalSeparator` — Decimal separator character (Text, XML, Microsoft Word, and HTML files)
`"."` (default) | string scalar | character vector

`ThousandsSeparator` — Thousands grouping character (Text, XML, Microsoft Word, and HTML files)
`""` (default) | string scalar | character vector

`ExponentCharacter` — Exponent characters (Text, XML, Microsoft Word, and HTML files)
`"eEdD"` (default) | string scalar | character vector

`TreatAsMissing` — Placeholder text to treat as missing value (Text, spreadsheet, XML, Microsoft Word, and HTML files)
string array | character vector | cell array of character vectors

`ImportErrorRule` — Rule for import errors (Text, spreadsheet, JSON, XML, Microsoft Word, and HTML files)
`"fill"` (default) | `"error"` | `"omitrow"` | `"omitvar"`

`MissingRule` — Rule for missing data (Text, spreadsheet, JSON, XML, Microsoft Word, and HTML files)
`"fill"` (default) | `"error"` | `"omitrow"` | `"omitvar"`

`ExtraColumnsRule` — Rule for extra columns (Text, Microsoft Word, and HTML files)
`"addvars"` (default) | `"ignore"` | `"wrap"` | `"error"`

`EmptyLineRule` — Rule for empty lines (Text files)
`"skip"` (default) | `"read"` | `"error"`

`EmptyRowRule` — Rule for empty rows (Microsoft Word and HTML files)
`"skip"` (default) | `"read"` | `"error"`

`EmptyColumnRule` — Rule for empty columns (Microsoft Word and HTML files)
`"skip"` (default) | `"read"` | `"error"`

`PartialFieldRule` — Rule for partial fields (Text files)
`"keep"` (default) | `"fill"` | `"omitrow"` | `"omitvar"` | `"wrap"` | `"error"`

`FileType` — Type of file (Text, spreadsheet, JSON, XML, Microsoft Word, and HTML files)
`"spreadsheet"` | `"text"` | `"delimitedtext"` | `"fixedwidth"` | `"json"` | `"xml"` | `"worddocument"` | `"html"`

`Encoding` — Character encoding scheme (Text files)
`"system"` | `"UTF-8"` | `"ISO-8859-1"` | `"windows-1251"` | `"windows-1252"` | ...

`UseExcel` — Start instance of Microsoft Excel for Windows (Spreadsheet files)
`false` or `0` (default) | `true` or `1`

`WebOptions` — `HTTP` or `HTTPS` request options (Text, spreadsheet, JSON, XML, Microsoft Word, and HTML files)
`weboptions` object

`Delimiter` — Field delimiter character (Text files)
string array | character vector | cell array of character vectors

`LineEnding` — End-of-line characters (Text files)
string array | character vector | cell array of character vectors

`Whitespace` — Characters to treat as white space (Text files)
`"\b\t"` (default) | string scalar | character vector

`CommentStyle` — Comment indicators for text to ignore (Text files)
string array | character vector | cell array of character vectors

`LeadingDelimitersRule` — Rule for leading delimiters (Text files)
`"keep"` | `"ignore"` | `"error"`

`TrailingDelimitersRule` — Rule for trailing delimiters (Text files)
`"keep"` | `"ignore"` | `"error"`

`ConsecutiveDelimitersRule` — Rule for consecutive delimiters (Text files)
`"split"` | `"join"` | `"error"`

`MultipleDelimsAsOne` — Treat multiple delimiters as one (Text files)
`false` or `0` (default) | `true` or `1`

`VariableWidths` — Field widths of variables (Text files)
vector of positive integers

`ParsingMode` — How strictly to follow JSON standards while parsing (JSON files)
`"lenient"` (default) | `"strict"`

`AllowComments` — Allow comments (JSON files)
`true` or `1` (default) | `false` or `0`

`AllowInfAndNaN` — Read `Inf` and `NaN` values (JSON files)
`true` or `1` (default) | `false` or `0`

`AllowTrailingCommas` — Read trailing commas (JSON files)
`true` or `1` (default) | `false` or `0`

`RepeatedNodeRule` — Rule for repeated JSON or XML nodes (JSON and XML files)
`"addcol"` (default) | `"ignore"` | `"error"`

`ImportAttributes` — Import attributes (XML files)
`true` or `1` (default) | `false` or `0`

`AttributeSuffix` — Attribute suffix (XML files)
`"Attribute"` (default) | string scalar | character vector

`RegisteredNamespaces` — Set of registered XML namespace prefixes (XML files)
`N`-by-2 string array

`VariableUnitsLine` — Location of variable units (Text files)
`0` (default) | nonnegative integer

`VariableUnitsRange` — Location of variable units (Spreadsheet files)
string scalar | character vector | positive integer

`VariableUnitsRow` — Location of variable units (Microsoft Word and HTML files)
`0` (default) | nonnegative integer

`VariableUnitsSelector` — Variable units (JSON and XML files)
string scalar | character vector

`VariableDescriptionsLine` — Location of variable descriptions (Text files)
`0` (default) | nonnegative integer

`VariableDescriptionsRange` — Location of variable descriptions (Spreadsheet files)
string scalar | character vector | positive integer

`VariableDescriptionsRow` — Location of variable descriptions (Microsoft Word and HTML files)
`0` (default) | nonnegative integer

`VariableDescriptionsSelector` — Variable descriptions (JSON and XML files)
string scalar | character vector

`TT` — Output timetable
timetable