readvars
Read variables from file
Syntax
Description
[Var1,Var2,...,VarN] = readvars(
creates variables by reading column-oriented data from a file. If the file contains
filename
)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(___,
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.Name,Value
)
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
Example:
| ||||||||
File in a folder | If the file is not in the current folder or in a folder on the
MATLAB path, then specify the full or relative path name in
Example:
Example:
| ||||||||
Internet URL | If the file is specified as an internet uniform resource locator (URL),
then Example:
| ||||||||
Remote Location | If the file is stored at a remote location, then
Based on the remote location,
For more information, see Work with Remote Data. Example:
|
If
filename
includes the file extension, then the importing function determines the file format from the extension. Otherwise, you must specify the'FileType'
name-value pair arguments to indicate the type of file.On Windows® systems with Microsoft® Excel® software, the importing function reads any Excel spreadsheet file format recognized by your version of Excel.
If your system does not have Excel for Windows or if you are using MATLAB Online™, the importing function operates with the
UseExcel
property set tofalse
, and reads only.xls, .xlsx, .xlsm, .xltx, and .xltm
files.For delimited text files, the importing function converts empty fields in the file to either
NaN
(for a numeric variable) or an empty character vector (for a text variable). All lines in the text file must have the same number of delimiters. The importing function ignores insignificant white space in the file.
Data Types: char
| string
opts
— File import options
SpreadsheetImportOptions
| DelimitedtextImportOptions
| FixedWidthImportOptions
| XMLImportOptions
File import options, specified as an SpreadsheetImportOptions
,
DelimitedTextImportOptions
,
FixedWidthImportOptions
, or XMLImportOptions
object created by the detectImportOptions
function. The
opts
object contains properties that control the data import
process. For more information on the properties of each object, see the appropriate
object page.
Type of Files | Output |
---|---|
Spreadsheet files | SpreadsheetImportOptions object (only available for the
Sheet , DataRange , and
VariableNames properties) |
Text files | DelimitedTextImportOptions object |
Fixed-width text files | FixedWidthImportOptions object |
XML files | XMLImportOptions object |
For more information on how to control your import, see Control How MATLAB Imports Your Data.
Name-Value Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: 'NumHeaderLines',5
indicates that the first five lines that
precede the tabular data are header lines.
WebOptions
— HTTP
or HTTPS
request options
weboptions
object
HTTP
or HTTPS
request options, specified as
a weboptions
object. The
weboptions
object determines how to import data when the
specified filename
is an internet URL containing the protocol type
"http://"
or "https://"
.
FileType
— Type of file
'text'
| 'spreadsheet'
Type of file, specified as the comma-separated pair consisting of
'FileType'
and 'text'
or
'spreadsheet'
.
Specify the 'FileType'
name-value pair argument when the
filename
does not include the file extension or if the extension
is other than one of the following:
.txt
,.dat
, or.csv
for delimited text files.xls
,.xlsb
,.xlsm
,.xlsx
,.xltm
,.xltx
, or.ods
for spreadsheet files
Example: 'FileType','text'
Data Types: char
| string
NumHeaderLines
— Number of header lines
positive integer
Number of header lines in the file, specified as the comma-separated pair consisting of 'NumHeaderLines'
and a positive integer. If unspecified, the importing function automatically detects the number of header lines in the file.
Example: 'NumHeaderLines',7
Data Types: single
| double
ExpectedNumVariables
— Expected number of variables
positive integer
Expected number of variables, specified as the comma-separated pair consisting of
'ExpectedNumVariables'
and a positive integer. If unspecified,
the importing function automatically detects the number of variables.
Data Types: single
| double
Range
— Portion of data to read
character vector | string scalar | numeric vector
Portion of the data to read from text or spreadsheet files, specified as the comma
separated pair consisting of 'Range'
and a character vector, string
scalar, or numeric vector in one of these forms.
Ways to specify Range | Description |
---|---|
Starting Cell
| Specify the starting cell for the data as a character vector or string scalar or a two element numeric vector.
Using the starting cell, the importing function automatically detects the extent of the data by beginning the import at the start cell and ending at the last empty row or footer range. Example:
|
Rectangular Range
| Specify the exact range to read using the rectangular range in one of these forms.
The importing function only reads the data contained in the specified range. Any empty fields within the specified range are imported as missing cells. |
Row Range or Column Range
| Specify the range by identifying the beginning and ending rows using Excel row numbers. Using the specified row range, the importing function automatically detects the column extent by reading from the first nonempty column to the end of the data, and creates one variable per column. Example:
Alternatively, specify the range by identifying the beginning and ending columns using Excel column letters or numbers. Using the specified column range, the import function automatically detects the row extent by reading from the first nonempty row to the end of the data or the footer range. The number of columns in
the specified range must match the number specified in the
Example:
|
Starting Row Number
| Specify the first row containing the data using the positive scalar row index. Using the specified row index, the importing function automatically detects the extent of the data by reading from the specified first row to the end of the data or the footer range. Example: |
Excel’s Named Range
| In Excel, you can create names to identify ranges in the
spreadsheet. For instance, you can select a rectangular portion of
the spreadsheet and call it Example:
|
Unspecified or Empty
| If unspecified, the importing function automatically detects the used range. Example:
Note: Used Range refers to the rectangular portion of the spreadsheet that actually contains data. The importing function automatically detects the used range by trimming any leading and trailing rows and columns that do not contain data. Text that is only white space is considered data and is captured within the used range. |
Data Types: char
| string
| double
TextType
— Type for imported text data
"string"
| "char"
Type for imported text data, specified as one of these values:
"string"
— Import text data as string arrays."char"
— Import text data as character vectors.
Example: "TextType","char"
DatetimeType
— Type for imported date and time data
"datetime"
(default) | "text"
| "exceldatenum"
(spreadsheet files only)
Type for imported date and time data, specified as one of these values:
Value | Description |
---|---|
"datetime" | MATLAB
For more information, see
|
"text" | If
|
"exceldatenum"
| Excel serial date numbers The value
|
TreatAsMissing
— Text to interpret as missing data
character vector | string scalar | cell array of character vectors | string array
Text to interpret as missing data, specified as a character vector, string scalar, cell array of character vectors, or string array.
Example: 'TreatAsMissing',{'NA','TBD'}
instructs the importing function to treat any occurrence of NA
or TBD
as a missing fields.
Data Types: char
| string
| cell
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 For more information, see |
'text' | If
|
Data Types: char
| string
DateLocale
— Locale for reading dates
character vector | string scalar
Locale for reading dates, specified as the comma-separated pair consisting of
'DateLocale'
and a character vector or a string scalar of the
form
, where:xx
_YY
YY
is an uppercase ISO 3166-1 alpha-2 code indicating a country.xx
is a lowercase ISO 639-1 two-letter code indicating a language.
This table lists some common values for the locale.
Locale | Language | Country |
---|---|---|
'de_DE' | German | Germany |
'en_GB' | English | United Kingdom |
'en_US' | English | United States |
'es_ES' | Spanish | Spain |
'fr_FR' | French | France |
'it_IT' | Italian | Italy |
'ja_JP' | Japanese | Japan |
'ko_KR' | Korean | Korea |
'nl_NL' | Dutch | Netherlands |
'zh_CN' | Chinese (simplified) | China |
When using the %D
format specifier to read text as
datetime
values, use DateLocale
to specify the
locale in which the importing function should interpret month and day-of-week names and
abbreviations.
If you specify the DateLocale
argument in addition to
opts
the import options, then the importing function uses the
specified value for the DateLocale
argument, overriding the locale
defined in the import options.
Example: 'DateLocale','ja_JP'
DecimalSeparator
— Characters indicating decimal separator
character vector | string scalar
Characters indicating the decimal separator in numeric variables, specified as a character
vector or string scalar. The importing function uses the characters specified in the
DecimalSeparator
name-value pair to distinguish the integer part
of a number from the decimal part.
When converting to integer data types, numbers with a decimal part are rounded to the nearest integer.
Example: If name-value pair is specified as 'DecimalSeparator',','
, then the
importing function imports the text "3,14159"
as the number
3.14159
.
Data Types: char
| string
ThousandsSeparator
— Characters that indicate thousands grouping
character vector | string scalar
Characters that indicate the thousands grouping in numeric variables, specified as a
character vector or string scalar. The thousands grouping characters act as visual
separators, grouping the number at every three place values. The importing function uses
the characters specified in the ThousandsSeparator
name-value pair to
interpret the numbers being imported.
Example: If name-value pair is specified as
'ThousandsSeparator',','
, then the importing function imports the
text "1,234,000"
as 1234000
.
Data Types: char
| string
TrimNonNumeric
— Remove nonnumeric characters
false
(default) | true
Remove nonnumeric characters from a numeric variable, specified as a logical true
or false
.
Example: If name-value pair is specified as 'TrimNonNumeric',true
, then the
importing function reads '$500/-'
as
500
.
Data Types: logical
ConsecutiveDelimitersRule
— Procedure to manage consecutive delimiters
"split"
| "join"
| "error"
Procedure to manage consecutive delimiters in a delimited text file, specified as one of the values in this table.
Value | Behavior |
---|---|
"split" | Split the consecutive delimiters into multiple fields. |
"join" | Join the delimiters into one delimiter. |
"error" | Return an error and cancel the import operation. |
LeadingDelimitersRule
— Procedure to manage leading delimiters
"keep"
| "ignore"
| "error"
Procedure to manage leading delimiters in a delimited text file, specified as one of the values in this table.
Value | Behavior |
---|---|
"keep" | Keep the delimiter. |
"ignore" | Ignore the delimiter. |
"error" | Return an error and cancel the import operation. |
TrailingDelimitersRule
— Procedure to manage trailing delimiters
'keep'
| 'ignore'
| 'error'
Procedure to manage trailing delimiters in a delimited text file, specified as one of the values in this table.
Leading Delimiters Rule | Behavior |
---|---|
'keep' | Keep the delimiter. |
'ignore' | Ignore the delimiter. |
'error' | Return an error and abort the import operation. |
Sheet
— Sheet to read from
''
empty character array (default) | character vector | string scalar | positive scalar integer
Sheet to read from, specified as an empty character array, a character vector or string scalar
containing the sheet name, or a positive scalar integer denoting the sheet
index. Based on the value specified for the Sheet
property, the import function behaves as described in the table.
Specification | Behavior |
---|---|
'' (default) | Import data from the first sheet. |
Name | Import data from the matching sheet name, regardless of order of sheets in the spreadsheet file. |
Integer | Import data from sheet in the position denoted by the integer, regardless of the sheet names in the spreadsheet file. |
Data Types: char
| string
| single
| double
UseExcel
— Flag to start instance of Microsoft Excel for Windows
false
(default) | true
Flag to start an instance of Microsoft
Excel for Windows when reading spreadsheet data, specified as the comma-separated pair
consisting of 'UseExcel'
and either true
, or
false
.
You can set the 'UseExcel'
parameter to one of these values:
true
— The importing function starts an instance of Microsoft Excel when reading the file.false
— The importing function does not start an instance of Microsoft Excel when reading the file. When operating in this mode, the importing function functionality differs in the support of file formats and interactive features, such as formulas and macros.
UseExcel |
|
|
---|---|---|
Supported file formats |
|
|
Support for interactive features, such as formulas and macros | Yes | No |
When reading from spreadsheet files on Windows platforms, if you want to start an instance of Microsoft
Excel, then set the 'UseExcel'
parameter to
true
.
UseExcel
is not supported in noninteractive, automated
environments.
MergedCellColumnRule
— Rule for cells merged across columns
"placeleft"
(default) | "placeright"
| "duplicate"
| "omitrow"
| "error"
Since R2024b
Rule for cells merged across columns, specified as one of the values in this table.
Import Rule | Behavior |
---|---|
"placeleft" | Place the data in the leftmost cell and fill the remaining cells
with the contents of the You can specify the |
"placeright" | Place the data in the rightmost cell and fill the remaining cells
with the contents of the You can specify the |
"duplicate" | Duplicate the data in all cells. |
"omitrow" | Omit rows where merged cells occur. |
"error" | Display an error message and cancel the import operation. |
MergedCellRowRule
— Rule for cells merged across rows
"placetop"
(default) | "placebottom"
| "duplicate"
| "omitvar"
| "error"
Since R2024b
Rule for cells merged across rows, specified as one of the values in this table.
Import Rule | Behavior |
---|---|
"placetop" | Place the data in the top cell and fill the remaining cells with
the contents of the You
can specify the |
"placebottom" | Place the data in the bottom cell and fill the remaining cells
with the contents of the You can specify the |
"duplicate" | Duplicate the data in all cells. |
"omitvar" | Omit variables where merged cells occur. |
"error" | Display an error message and cancel the import operation. |
Version History
Introduced in R2019aR2024b: 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.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)