readvars

Read variables from file

Syntax

[Var1,Var2,...,VarN] = readvars(filename)

[Var1,Var2,...,VarN] = readvars(filename,opts)

[Var1,Var2,...,VarN] = readvars(___,Name,Value)

Description

[Var1,Var2,...,VarN] = readvars(filename) creates variables by reading column-oriented data from a file. If the file contains N columns of data, then readvars returns N variables Var1,Var2,...,VarN.

readvars 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

[Var1,Var2,...,VarN] = readvars(filename,opts) additionally uses the import options opts.

[Var1,Var2,...,VarN] = readvars(___,Name,Value) creates variables 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. If you specify name-value pairs in addition to opts, then readvars supports only these name-value pairs:

• Text Files — DateLocale, Encoding

• Spreadsheet Files — Sheet, UseExcel

Examples

Read Variables from Text File

Import columns from tabular data in a text file as separate variables. First, preview the contents of the text file outages.csv and then read columns.

Preview the data in outages.csv. The file has 6 variables.

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'}

Import the first three columns as separate variables in the workspace.

[Region,OutageTime,Loss] = readvars('outages.csv');
whos Region OutageTime Loss

  Name               Size             Bytes  Class       Attributes

  Loss            1468x1              11744  double                
  OutageTime      1468x1              23520  datetime              
  Region          1468x1             198476  cell                  

Read Variables from Spreadsheet File

Import columns from a spreadsheet file as separate variables in the workspace. First, preview the contents of the text file outages.csv and then read columns as separate variables.

Preview the data in patients.xls. The file has 10 variables.

opts = detectImportOptions('patients.xls');
preview('patients.xls',opts)

ans=8×10 table
      LastName        Gender      Age              Location               Height    Weight    Smoker    Systolic    Diastolic    SelfAssessedHealthStatus
    ____________    __________    ___    _____________________________    ______    ______    ______    ________    _________    ________________________

    {'Smith'   }    {'Male'  }    38     {'County General Hospital'  }      71       176      true        124          93             {'Excellent'}      
    {'Johnson' }    {'Male'  }    43     {'VA Hospital'              }      69       163      false       109          77             {'Fair'     }      
    {'Williams'}    {'Female'}    38     {'St. Mary's Medical Center'}      64       131      false       125          83             {'Good'     }      
    {'Jones'   }    {'Female'}    40     {'VA Hospital'              }      67       133      false       117          75             {'Fair'     }      
    {'Brown'   }    {'Female'}    49     {'County General Hospital'  }      64       119      false       122          80             {'Good'     }      
    {'Davis'   }    {'Female'}    46     {'St. Mary's Medical Center'}      68       142      false       121          70             {'Good'     }      
    {'Miller'  }    {'Female'}    33     {'VA Hospital'              }      64       142      true        130          88             {'Good'     }      
    {'Wilson'  }    {'Male'  }    40     {'VA Hospital'              }      68       180      false       115          82             {'Good'     }      

Import the first three columns as separate variables in the workspace.

[LastName,Gender,Age] = readvars('patients.xls');
whos  LastName Gender Age

  Name            Size            Bytes  Class     Attributes

  Age           100x1               800  double              
  Gender        100x1             13012  cell                
  LastName      100x1             13216  cell                

Read Variables from Specified Sheet and Range Using Import Options

Preview the data from a spreadsheet file and import columns of data from a specified sheet and range as separate variables.

The spreadsheet file airlinesmall_subset.xlsx contains data in multiple worksheets for years between 1996 and 2008. Each worksheet has data for a given year. Preview the data from file airlinesmall_subset.xlsx. The preview function shows data from the first worksheet by default.

opts = detectImportOptions('airlinesmall_subset.xlsx');
preview('airlinesmall_subset.xlsx',opts)

ans=8×29 table
    Year    Month    DayofMonth    DayOfWeek    DepTime    CRSDepTime    ArrTime    CRSArrTime    UniqueCarrier    FlightNum     TailNum      ActualElapsedTime    CRSElapsedTime    AirTime    ArrDelay    DepDelay    Origin      Dest      Distance    TaxiIn    TaxiOut    Cancelled    CancellationCode    Diverted    CarrierDelay    WeatherDelay      SDelay      SecurityDelay    LateAircraftDelay
    ____    _____    __________    _________    _______    __________    _______    __________    _____________    _________    __________    _________________    ______________    _______    ________    ________    _______    _______    ________    ______    _______    _________    ________________    ________    ____________    ____________    __________    _____________    _________________

    1996      1          18            4         2117         2120        2305         2259          {'HP'}           415       {'N637AW'}           108                 99            85           6          -3       {'COS'}    {'PHX'}      551         5         18           0           {0x0 char}          0         {0x0 char}      {0x0 char}     {0x0 char}     {0x0 char}         {0x0 char}    
    1996      1          12            5         1252         1245        1511         1500          {'HP'}           610       {'N905AW'}            79                 75            58          11           7       {'LAX'}    {'PHX'}      370         3         18           0           {0x0 char}          0         {0x0 char}      {0x0 char}     {0x0 char}     {0x0 char}         {0x0 char}    
    1996      1          16            2         1441         1445        1708         1721          {'HP'}           211       {'N165AW'}            87                 96            74         -13          -4       {'RNO'}    {'PHX'}      601         4          9           0           {0x0 char}          0         {0x0 char}      {0x0 char}     {0x0 char}     {0x0 char}         {0x0 char}    
    1996      1           1            1         2258         2300        2336         2335          {'HP'}          1245       {'N183AW'}            38                 35            20           1          -2       {'TUS'}    {'PHX'}      110         6         12           0           {0x0 char}          0         {0x0 char}      {0x0 char}     {0x0 char}     {0x0 char}         {0x0 char}    
    1996      1           4            4         1814         1814        1901         1910          {'US'}           683       {'N963VJ'}            47                 56            34          -9           0       {'DTW'}    {'PIT'}      201         6          7           0           {0x0 char}          0         {0x0 char}      {0x0 char}     {0x0 char}     {0x0 char}         {0x0 char}    
    1996      1          31            3         1822         1820        1934         1925          {'US'}           757       {'N912VJ'}            72                 65            52           9           2       {'PHL'}    {'PIT'}      267         6         14           0           {0x0 char}          0         {0x0 char}      {0x0 char}     {0x0 char}     {0x0 char}         {0x0 char}    
    1996      1          18            4          729          730         841          843          {'US'}          1564       {'N941VJ'}            72                 73            58          -2          -1       {'DCA'}    {'PVD'}      357         3         11           0           {0x0 char}          0         {0x0 char}      {0x0 char}     {0x0 char}     {0x0 char}         {0x0 char}    
    1996      1          26            5         1704         1705        1829         1839          {'NW'}          1538       {'N960N' }            85                 94            69         -10          -1       {'DTW'}    {'RIC'}      456         3         13           0           {0x0 char}          0         {0x0 char}      {0x0 char}     {0x0 char}     {0x0 char}         {0x0 char}    

Configure the values in the opts object to import 10 rows for the columns 5 and 6 of the worksheet named '2007'.

opts.Sheet = '2007';
opts.SelectedVariableNames = [5 6]; 
opts.DataRange = '2:11';
[DepTime,CRSDepTime] = readvars('airlinesmall_subset.xlsx',opts);

Display the variables.

[DepTime, CRSDepTime]

ans = 10×2

         711         710
         652         655
        1116        1120
         825         825
        1411        1400
        1935        1935
        2005        2005
        1525        1525
        1133        1105
         922         925

Read Variables from Specified Sheet and Range

Preview the data from a spreadsheet file and import columns as separate variables from a specified sheet and range.

The spreadsheet file airlinesmall_subset.xlsx contains data in multiple worksheets for years between 1996 and 2008. Each worksheet has data for a given year. Preview the data from file airlinesmall_subset.xlsx. The preview function shows data from the first worksheet by default.

opts = detectImportOptions('airlinesmall_subset.xlsx');
preview('airlinesmall_subset.xlsx',opts)

ans=8×29 table
    Year    Month    DayofMonth    DayOfWeek    DepTime    CRSDepTime    ArrTime    CRSArrTime    UniqueCarrier    FlightNum     TailNum      ActualElapsedTime    CRSElapsedTime    AirTime    ArrDelay    DepDelay    Origin      Dest      Distance    TaxiIn    TaxiOut    Cancelled    CancellationCode    Diverted    CarrierDelay    WeatherDelay      SDelay      SecurityDelay    LateAircraftDelay
    ____    _____    __________    _________    _______    __________    _______    __________    _____________    _________    __________    _________________    ______________    _______    ________    ________    _______    _______    ________    ______    _______    _________    ________________    ________    ____________    ____________    __________    _____________    _________________

    1996      1          18            4         2117         2120        2305         2259          {'HP'}           415       {'N637AW'}           108                 99            85           6          -3       {'COS'}    {'PHX'}      551         5         18           0           {0x0 char}          0         {0x0 char}      {0x0 char}     {0x0 char}     {0x0 char}         {0x0 char}    
    1996      1          12            5         1252         1245        1511         1500          {'HP'}           610       {'N905AW'}            79                 75            58          11           7       {'LAX'}    {'PHX'}      370         3         18           0           {0x0 char}          0         {0x0 char}      {0x0 char}     {0x0 char}     {0x0 char}         {0x0 char}    
    1996      1          16            2         1441         1445        1708         1721          {'HP'}           211       {'N165AW'}            87                 96            74         -13          -4       {'RNO'}    {'PHX'}      601         4          9           0           {0x0 char}          0         {0x0 char}      {0x0 char}     {0x0 char}     {0x0 char}         {0x0 char}    
    1996      1           1            1         2258         2300        2336         2335          {'HP'}          1245       {'N183AW'}            38                 35            20           1          -2       {'TUS'}    {'PHX'}      110         6         12           0           {0x0 char}          0         {0x0 char}      {0x0 char}     {0x0 char}     {0x0 char}         {0x0 char}    
    1996      1           4            4         1814         1814        1901         1910          {'US'}           683       {'N963VJ'}            47                 56            34          -9           0       {'DTW'}    {'PIT'}      201         6          7           0           {0x0 char}          0         {0x0 char}      {0x0 char}     {0x0 char}     {0x0 char}         {0x0 char}    
    1996      1          31            3         1822         1820        1934         1925          {'US'}           757       {'N912VJ'}            72                 65            52           9           2       {'PHL'}    {'PIT'}      267         6         14           0           {0x0 char}          0         {0x0 char}      {0x0 char}     {0x0 char}     {0x0 char}         {0x0 char}    
    1996      1          18            4          729          730         841          843          {'US'}          1564       {'N941VJ'}            72                 73            58          -2          -1       {'DCA'}    {'PVD'}      357         3         11           0           {0x0 char}          0         {0x0 char}      {0x0 char}     {0x0 char}     {0x0 char}         {0x0 char}    
    1996      1          26            5         1704         1705        1829         1839          {'NW'}          1538       {'N960N' }            85                 94            69         -10          -1       {'DTW'}    {'RIC'}      456         3         13           0           {0x0 char}          0         {0x0 char}      {0x0 char}     {0x0 char}     {0x0 char}         {0x0 char}    

Import 10 rows of the first three variables from the worksheet named '2007'.

[Year, Month, DayOfMonth] = readvars('airlinesmall_subset.xlsx','Sheet','2007','Range','A2:C11');
whos Year Month DayOfMonth

  Name             Size            Bytes  Class     Attributes

  DayOfMonth      10x1                80  double              
  Month           10x1                80  double              
  Year            10x1                80  double              

disp([Year Month DayOfMonth])

        2007           1           2
        2007           1           3
        2007           1           4
        2007           1           5
        2007           1           7
        2007           1           8
        2007           1           9
        2007           1          11
        2007           1          12
        2007           1          13

Input Arguments

filename — Name of file to read

character vector | string scalar

Name of the file to read, specified as a character vector or a string scalar.

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

Location	Form
Current folder or folder on the MATLAB® path	Specify the name of the file in 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 path name 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'

• If filename includes the file extension, then the importing function determines the file format from the extension. Otherwise, you must specify the 'FileType' name-value pair arguments to indicate the type of file.

• On Windows^® systems with Microsoft^® Excel^® software, the importing function reads any Excel spreadsheet file format recognized by your version of Excel.

• If your system does not have Excel for Windows or if you are using MATLAB Online™, the importing function operates with the UseExcel property set to false, and reads only .xls, .xlsx, .xlsm, .xltx, and .xltm files.

• For delimited text files, the importing function converts empty fields in the file to either NaN (for a numeric variable) or an empty character vector (for a text variable). All lines in the text file must have the same number of delimiters. The importing function ignores insignificant white space in the file.

Data Types: char | string

opts — File import options

SpreadsheetImportOptions | DelimitedtextImportOptions | FixedWidthImportOptions | XMLImportOptions

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

Type of Files	Output
Spreadsheet files	SpreadsheetImportOptions object (only available for the Sheet, DataRange, and VariableNames properties)
Text files	DelimitedTextImportOptions object
Fixed-width text files	FixedWidthImportOptions object
XML files	XMLImportOptions object

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

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'NumHeaderLines',5 indicates that the first five lines that precede the tabular data are header lines.

All Supported File Types

WebOptions — HTTP or HTTPS request options

weboptions object

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

Text and Spreadsheet Files

FileType — Type of file

'text' | 'spreadsheet'

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

Specify the 'FileType' name-value pair argument when the filename does not include the file extension or if the extension is other than one of the following:

• .txt, .dat, or .csv for delimited text files

• .xls, .xlsb, .xlsm, .xlsx, .xltm, .xltx, or .ods for spreadsheet files

Example: 'FileType','text'

Data Types: char | string

NumHeaderLines — Number of header lines

positive integer

Number of header lines in the file, specified as the comma-separated pair consisting of 'NumHeaderLines' and a positive integer. If unspecified, the importing function automatically detects the number of header lines in the file.

Example: 'NumHeaderLines',7

Data Types: single | double

ExpectedNumVariables — Expected number of variables

positive integer

Expected number of variables, specified as the comma-separated pair consisting of 'ExpectedNumVariables' and a positive integer. If unspecified, the importing function automatically detects the number of variables.

Data Types: single | double

Range — Portion of data to read

character vector | string scalar | numeric vector

Portion of the data to read from text or spreadsheet files, specified as the comma separated pair consisting of 'Range' and a character vector, string scalar, or numeric vector in one of these forms.

Ways to specify Range	Description
Starting Cell 'Cell' or [row col]	Specify the starting cell for the data as a character vector or string scalar or a two element numeric vector. Character vector or string scalar containing a column letter and row number using Excel A1 notation. For example, A5 is the identifier for the cell at the intersection of column A and row 5. Two element numeric vector of the form [row col] indicating the starting row and column. Using the starting cell, the importing function automatically detects the extent of the data by beginning the import at the start cell and ending at the last empty row or footer range. Example: 'A5' or [5 1]
Rectangular Range 'Corner1:Corner2' or [r1 c1 r2 c2]	Specify the exact range to read using the rectangular range in one of these forms. 'Corner1:Corner2' — Specify the range using Corner1 and Corner2 which are the two opposing corners that define the region to read in Excel A1 notation. For example, 'C2:N15'. [r1 c1 r2 c2] — Specify the range using a four element numeric vector containing start-row, start-column, end-row, and end-column. For example, [2 3 15 13]. The importing function only reads the data contained in the specified range. Any empty fields within the specified range are imported as missing cells.
Row Range or Column Range 'Row1:Row2' or 'Column1:Column2'	Specify the range by identifying the beginning and ending rows using Excel row numbers. Using the specified row range, the importing function automatically detects the column extent by reading from the first nonempty column to the end of the data, and creates one variable per column. Example: '5:500' Alternatively, specify the range by identifying the beginning and ending columns using Excel column letters or numbers. Using the specified column range, the import function automatically detects the row extent by reading from the first nonempty row to the end of the data or the footer range. The number of columns in the specified range must match the number specified in the ExpectedNumVariables property. Example: 'A:K'
Starting Row Number n	Specify the first row containing the data using the positive scalar row index. Using the specified row index, the importing function automatically detects the extent of the data by reading from the specified first row to the end of the data or the footer range. Example:5
Excel’s Named Range 'NamedRange'	In Excel, you can create names to identify ranges in the spreadsheet. For instance, you can select a rectangular portion of the spreadsheet and call it 'myTable'. If such named ranges exist in a spreadsheet, then the importing function can read that range using its name. Example: 'Range','myTable'
Unspecified or Empty ''	If unspecified, the importing function automatically detects the used range. Example: 'Range','' Note: Used Range refers to the rectangular portion of the spreadsheet that actually contains data. The importing function automatically detects the used range by trimming any leading and trailing rows and columns that do not contain data. Text that is only white space is considered data and is captured within the used range.

Data Types: char | string | double

TextType — Type for imported text data

"string" | "char"

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

• "string" — Import text data as string arrays.

• "char" — Import text data as character vectors.

Example: "TextType","char"

DatetimeType — Type for imported date and time data

"datetime" (default) | "text" | "exceldatenum" (spreadsheet files only)

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

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

TreatAsMissing — Text to interpret as missing data

character vector | string scalar | cell array of character vectors | string array

Text to interpret as missing data, specified as a character vector, string scalar, cell array of character vectors, or string array.

Example: 'TreatAsMissing',{'NA','TBD'} instructs the importing function to treat any occurrence of NA or TBD as a missing fields.

Data Types: char | string | cell

Text Files Only

Delimiter — Field delimiter characters

string array | character vector | cell array of character vectors

Field delimiter characters in a delimited text file, specified as a string array, character vector, or cell array of character vectors.

Example: "Delimiter","|"

Example: "Delimiter",[";","*"]

Whitespace — Characters to treat as white space

character vector | string scalar

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

Example: 'Whitespace',' _'

Example: 'Whitespace','?!.,'

LineEnding — End-of-line characters

["\n","\r","\r\n"] (default) | string array | character vector | cell array of character vectors

End-of-line characters, specified as a string array, character vector, or cell array of character vectors.

Example: "LineEnding","\n"

Example: "LineEnding","\r\n"

Example: "LineEnding",["\b",":"]

CommentStyle — Style of comments

string array | character vector | cell array of character vectors

Style of comments, specified as a string array, character vector, or cell array of character vectors. For single- and multi-line comments, the starting identifier must be the first non-white-space character. For single-line comments, specify a single identifier to treat lines starting with the identifier as comments. For multi-line comments, lines from the starting (first) identifier to the ending (second) identifier are treated as comments. No more than two character vectors of identifiers can be specified.

For example, to ignore the line following a percent symbol as the first non-white-space character, specify CommentStyle as "%".

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

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

Encoding — Character encoding scheme

'UTF-8' | 'ISO-8859-1' | 'windows-1251' | 'windows-1252' | ...

Character encoding scheme associated with the file, specified as the comma-separated pair consisting of 'Encoding' and 'system' or a standard character encoding scheme name. When you do not specify any encoding, the readvars function uses automatic character set detection to determine the encoding when reading the file.

If you specify the 'Encoding' argument in addition to the import options, then the readvars function uses the specified value for 'Encoding', overriding the encoding defined in the import options.

Example: 'Encoding','UTF-8' uses UTF-8 as the encoding.

Example: 'Encoding','system' uses the system default encoding.

Data Types: char | string

DurationType — Output data type of duration data

'duration' (default) | 'text'

Output data type of duration data from text files, specified as the comma-separated pair consisting of 'DurationType' and either 'duration' or 'text'.

Value	Type for Imported Duration Data
'duration'	MATLAB duration data type For more information, see duration.
'text'	If 'DurationType' is specified as 'text', then the type for imported duration data depends on the value specified in the 'TextType' parameter: If 'TextType' is set to 'char', then the importing function returns duration data as a cell array of character vectors. If 'TextType' is set to 'string', then the importing function returns duration data as an array of strings.

Data Types: char | string

DateLocale — Locale for reading dates

character vector | string scalar

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

• YY is an uppercase ISO 3166-1 alpha-2 code indicating a country.

• xx is a lowercase ISO 639-1 two-letter code indicating a language.

This table lists some common values for the locale.

Locale	Language	Country
'de_DE'	German	Germany
'en_GB'	English	United Kingdom
'en_US'	English	United States
'es_ES'	Spanish	Spain
'fr_FR'	French	France
'it_IT'	Italian	Italy
'ja_JP'	Japanese	Japan
'ko_KR'	Korean	Korea
'nl_NL'	Dutch	Netherlands
'zh_CN'	Chinese (simplified)	China

When using the %D format specifier to read text as datetime values, use DateLocale to specify the locale in which the importing function should interpret month and day-of-week names and abbreviations.

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

Example: 'DateLocale','ja_JP'

DecimalSeparator — Characters indicating decimal separator

character vector | string scalar

Characters indicating the decimal separator in numeric variables, specified as a character vector or string scalar. The importing function uses the characters specified in the DecimalSeparator name-value pair to distinguish the integer part of a number from the decimal part.

When converting to integer data types, numbers with a decimal part are rounded to the nearest integer.

Example: If name-value pair is specified as 'DecimalSeparator',',', then the importing function imports the text "3,14159" as the number 3.14159.

Data Types: char | string

ThousandsSeparator — Characters that indicate thousands grouping

character vector | string scalar

Characters that indicate the thousands grouping in numeric variables, specified as a character vector or string scalar. The thousands grouping characters act as visual separators, grouping the number at every three place values. The importing function uses the characters specified in the ThousandsSeparator name-value pair to interpret the numbers being imported.

Example: If name-value pair is specified as 'ThousandsSeparator',',', then the importing function imports the text "1,234,000" as 1234000.

Data Types: char | string

TrimNonNumeric — Remove nonnumeric characters

false (default) | true

Remove nonnumeric characters from a numeric variable, specified as a logical true or false.

Example: If name-value pair is specified as 'TrimNonNumeric',true, then the importing function reads '$500/-' as 500.

Data Types: logical

ConsecutiveDelimitersRule — Procedure to manage consecutive delimiters

"split" | "join" | "error"

Procedure to manage consecutive delimiters in a delimited text file, specified as one of the values in this table.

Value	Behavior
"split"	Split the consecutive delimiters into multiple fields.
"join"	Join the delimiters into one delimiter.
"error"	Return an error and cancel the import operation.

LeadingDelimitersRule — Procedure to manage leading delimiters

"keep" | "ignore" | "error"

Procedure to manage leading delimiters in a delimited text file, specified as one of the values in this table.

Value	Behavior
"keep"	Keep the delimiter.
"ignore"	Ignore the delimiter.
"error"	Return an error and cancel the import operation.

TrailingDelimitersRule — Procedure to manage trailing delimiters

'keep' | 'ignore' | 'error'

Procedure to manage trailing delimiters in a delimited text file, specified as one of the values in this table.

Leading Delimiters Rule	Behavior
'keep'	Keep the delimiter.
'ignore'	Ignore the delimiter.
'error'	Return an error and abort the import operation.

Spreadsheet Files Only

Sheet — Sheet to read from

'' empty character array (default) | character vector | string scalar | positive scalar integer

Sheet to read from, specified as an empty character array, a character vector or string scalar containing the sheet name, or a positive scalar integer denoting the sheet index. Based on the value specified for the Sheet property, the import function behaves as described in the table.

Specification	Behavior
'' (default)	Import data from the first sheet.
Name	Import data from the matching sheet name, regardless of order of sheets in the spreadsheet file.
Integer	Import data from sheet in the position denoted by the integer, regardless of the sheet names in the spreadsheet file.

Data Types: char | string | single | double

UseExcel — Flag to start instance of Microsoft Excel for Windows

false (default) | true

Flag to start an instance of Microsoft Excel for Windows when reading spreadsheet data, specified as the comma-separated pair consisting of 'UseExcel' and either true, or false.

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

• true — The importing function starts an instance of Microsoft Excel when reading the file.

• false — The importing function does not start an instance of Microsoft Excel when reading the file. When operating in this mode, the importing function functionality differs in the support of file formats and interactive features, such as formulas and macros.

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

When reading from spreadsheet files on Windows platforms, if you want to start an instance of Microsoft Excel, then set the 'UseExcel' parameter to true.

UseExcel is not supported in noninteractive, automated environments.

MergedCellColumnRule — Rule for cells merged across columns

"placeleft" (default) | "placeright" | "duplicate" | "omitrow" | "error"

Since R2024b

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

Import Rule	Behavior
"placeleft"	Place the data in the leftmost cell and fill the remaining cells with the contents of the FillValue property. You can specify 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. You can specify 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

"placetop" (default) | "placebottom" | "duplicate" | "omitvar" | "error"

Since R2024b

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

Import Rule	Behavior
"placetop"	Place the data in the top cell and fill the remaining cells with the contents of the FillValue property. You can specify 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. You can specify 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.

Version History

Introduced in R2019a

R2024b: Specify how to import merged cells in spreadsheets

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