readmatrix - Read matrix from file - MATLAB (original) (raw)
Syntax
Description
A = readmatrix([filename](#mw%5Fd1e678b1-89eb-46cd-973e-6a2b1ace08f3)) creates an array by reading column-oriented data from a file. The readmatrix function performs automatic detection of import parameters for your file.
readmatrix determines the file format from the file extension:
.txt,.dat, or.csvfor delimited text files.xls,.xlsb,.xlsm,.xlsx,.xltm,.xltx, or.odsfor spreadsheet files.zip,.gz, or.tarfor compressed and archived files.
For files containing mixed numeric and text data, readmatrix imports the data as a numeric array by default.
A = readmatrix([filename](#mw%5Fd1e678b1-89eb-46cd-973e-6a2b1ace08f3),[opts](#mw%5F242c5758-0d40-4b04-addc-3a5de11f672a%5Fsep%5Fbtx%5F238-1-opts)) additionally uses the import options opts.
A = readmatrix(___,[Name,Value](#namevaluepairarguments)) creates an array from a file with additional options specified by one or more name-value pair arguments. Use any of the input arguments from the previous syntaxes before specifying the name-value pairs.
To set specific import options for your data, you can either use theopts object or you can specify name-value pairs. When you specify name-value pairs in addition to opts, then readmatrix supports only these name-value pairs:
- Text Files —
DateLocale,Encoding - Spreadsheet Files —
Sheet,UseExcel
Examples
Display the contents of basic_matrix.txt and then import the data into a matrix.
6,8,3,1 5,4,7,3 1,6,7,10 4,2,8,2 2,7,5,9
M = readmatrix('basic_matrix.txt')
M = 5×4
6 8 3 1
5 4 7 3
1 6 7 10
4 2 8 2
2 7 5 9Import numeric data from basic_matrix.xls into a matrix.
M = readmatrix('basic_matrix.xls')
M = 5×4
6 8 3 1
5 4 7 3
1 6 7 10
4 2 8 2
2 7 5 9Preview the data from a spreadsheet file and import numerical data as a matrix 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. The first eight variables in the file contain numerical data.
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 {0×0 char} 0 {0×0 char} {0×0 char} {0×0 char} {0×0 char} {0×0 char}
1996 1 12 5 1252 1245 1511 1500 {'HP'} 610 {'N905AW'} 79 75 58 11 7 {'LAX'} {'PHX'} 370 3 18 0 {0×0 char} 0 {0×0 char} {0×0 char} {0×0 char} {0×0 char} {0×0 char}
1996 1 16 2 1441 1445 1708 1721 {'HP'} 211 {'N165AW'} 87 96 74 -13 -4 {'RNO'} {'PHX'} 601 4 9 0 {0×0 char} 0 {0×0 char} {0×0 char} {0×0 char} {0×0 char} {0×0 char}
1996 1 1 1 2258 2300 2336 2335 {'HP'} 1245 {'N183AW'} 38 35 20 1 -2 {'TUS'} {'PHX'} 110 6 12 0 {0×0 char} 0 {0×0 char} {0×0 char} {0×0 char} {0×0 char} {0×0 char}
1996 1 4 4 1814 1814 1901 1910 {'US'} 683 {'N963VJ'} 47 56 34 -9 0 {'DTW'} {'PIT'} 201 6 7 0 {0×0 char} 0 {0×0 char} {0×0 char} {0×0 char} {0×0 char} {0×0 char}
1996 1 31 3 1822 1820 1934 1925 {'US'} 757 {'N912VJ'} 72 65 52 9 2 {'PHL'} {'PIT'} 267 6 14 0 {0×0 char} 0 {0×0 char} {0×0 char} {0×0 char} {0×0 char} {0×0 char}
1996 1 18 4 729 730 841 843 {'US'} 1564 {'N941VJ'} 72 73 58 -2 -1 {'DCA'} {'PVD'} 357 3 11 0 {0×0 char} 0 {0×0 char} {0×0 char} {0×0 char} {0×0 char} {0×0 char}
1996 1 26 5 1704 1705 1829 1839 {'NW'} 1538 {'N960N' } 85 94 69 -10 -1 {'DTW'} {'RIC'} 456 3 13 0 {0×0 char} 0 {0×0 char} {0×0 char} {0×0 char} {0×0 char} {0×0 char} Configure the values in the opts object to import 10 rows for the first five variables from the worksheet named '2007'.
opts.Sheet = '2007'; opts.SelectedVariableNames = [1:5]; opts.DataRange = '2:11'; M = readmatrix('airlinesmall_subset.xlsx',opts)
M = 10×5
2007 1 2 2 711
2007 1 3 3 652
2007 1 4 4 1116
2007 1 5 5 825
2007 1 7 7 1411
2007 1 8 1 1935
2007 1 9 2 2005
2007 1 11 4 1525
2007 1 12 5 1133
2007 1 13 6 922Preview the data from a spreadsheet file and import numerical data, as a matrix, 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. The first eight variables in the file contain numerical data.
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 {0×0 char} 0 {0×0 char} {0×0 char} {0×0 char} {0×0 char} {0×0 char}
1996 1 12 5 1252 1245 1511 1500 {'HP'} 610 {'N905AW'} 79 75 58 11 7 {'LAX'} {'PHX'} 370 3 18 0 {0×0 char} 0 {0×0 char} {0×0 char} {0×0 char} {0×0 char} {0×0 char}
1996 1 16 2 1441 1445 1708 1721 {'HP'} 211 {'N165AW'} 87 96 74 -13 -4 {'RNO'} {'PHX'} 601 4 9 0 {0×0 char} 0 {0×0 char} {0×0 char} {0×0 char} {0×0 char} {0×0 char}
1996 1 1 1 2258 2300 2336 2335 {'HP'} 1245 {'N183AW'} 38 35 20 1 -2 {'TUS'} {'PHX'} 110 6 12 0 {0×0 char} 0 {0×0 char} {0×0 char} {0×0 char} {0×0 char} {0×0 char}
1996 1 4 4 1814 1814 1901 1910 {'US'} 683 {'N963VJ'} 47 56 34 -9 0 {'DTW'} {'PIT'} 201 6 7 0 {0×0 char} 0 {0×0 char} {0×0 char} {0×0 char} {0×0 char} {0×0 char}
1996 1 31 3 1822 1820 1934 1925 {'US'} 757 {'N912VJ'} 72 65 52 9 2 {'PHL'} {'PIT'} 267 6 14 0 {0×0 char} 0 {0×0 char} {0×0 char} {0×0 char} {0×0 char} {0×0 char}
1996 1 18 4 729 730 841 843 {'US'} 1564 {'N941VJ'} 72 73 58 -2 -1 {'DCA'} {'PVD'} 357 3 11 0 {0×0 char} 0 {0×0 char} {0×0 char} {0×0 char} {0×0 char} {0×0 char}
1996 1 26 5 1704 1705 1829 1839 {'NW'} 1538 {'N960N' } 85 94 69 -10 -1 {'DTW'} {'RIC'} 456 3 13 0 {0×0 char} 0 {0×0 char} {0×0 char} {0×0 char} {0×0 char} {0×0 char} Import 10 rows of the first 5 variables from the worksheet named '2007'.
M = readmatrix('airlinesmall_subset.xlsx','Sheet','2007','Range','A2:E11')
M = 10×5
2007 1 2 2 711
2007 1 3 3 652
2007 1 4 4 1116
2007 1 5 5 825
2007 1 7 7 1411
2007 1 8 1 1935
2007 1 9 2 2005
2007 1 11 4 1525
2007 1 12 5 1133
2007 1 13 6 922Input Arguments
Name of the file to read, specified as a character vector or a string scalar.
Depending on the location of your file, filename can take on one of these forms.
| Location | Form |
|---|---|
| Current folder or folder on the MATLAB® path | Specify the name of the file infilename.Example: 'myFile.txt' |
| File in a folder | If the file is not in the current folder or in a folder on the MATLAB path, then specify the full or relative path name infilename.Example: 'C:\myFolder\myFile.xlsx'Example: 'dataDir\myFile.txt' |
| Internet URL | If the file is specified as an internet uniform resource locator (URL), then filename must contain the protocol type'http://' or'https://'.Example: 'http://hostname/path\_to\_file/my\_data.csv' |
| Remote Location | If the file is stored at a remote location, thenfilename must contain the full path of the file specified with the form:scheme_name://path_to_file/_my_file.ext_Based on the remote location,scheme_name can be one of the values in this table. Remote Location_scheme_name_Amazon S3™s3Windows Azure® Blob Storagewasb, wasbsHDFS™hdfsFor more information, see Work with Remote Data.Example: 's3://bucketname/path_to_file/my_file.csv' |
- If
filenameincludes 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
UseExcelproperty set tofalse, and reads only.xls, .xlsx, .xlsm, .xltx, and .xltmfiles. - For delimited text files, the importing function converts empty fields in the file to either
NaN(for a numeric variable) or an empty character vector (for a text variable). All lines in the text file must have the same number of delimiters. The importing function ignores insignificant white space in the file. - Compressed file formats are read as files. Archived file formats are treated as folders. For example, the function interprets
mydatafiles.zipas a folder, so you must specify a file within it, such asmydatafiles.zip/file1.xlsx. For files ending with the.gzextension, the function determines the file format by using the extension preceding.gz. For example,mydata.csv.gzis read as a CSV file. (since R2025a)
Data Types: char | string
File import options, specified as an SpreadsheetImportOptions,DelimitedTextImportOptions,FixedWidthImportOptions, or XMLImportOptions object created by the detectImportOptions function. Theopts object contains properties that control the data import process. For more information on the properties of each object, see the appropriate object page.
For more information on how to control your import, see Control How MATLAB Imports Your Data.
Name-Value Arguments
Specify optional pairs of arguments asName1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose Name in quotes.
Example: 'NumHeaderLines',5 indicates that the first five lines that precede the tabular data are header lines.
All Supported File Types
HTTP or HTTPS request options, specified as a weboptions object. Theweboptions object determines how to import data when the specified filename is an internet URL containing the protocol type"http://" or "https://".
Text and Spreadsheet Files
Type of file, specified as the comma-separated pair consisting of'FileType' and 'text' or'spreadsheet'.
Specify the 'FileType' name-value pair argument when thefilename does not include the file extension or if the extension is other than one of the following:
.txt,.dat, or.csvfor delimited text files.xls,.xlsb,.xlsm,.xlsx,.xltm,.xltx, or.odsfor spreadsheet files
Example: 'FileType','text'
Data Types: char | string
Data Types: single | double
Expected number of variables, specified as the comma-separated pair consisting of'ExpectedNumVariables' and a positive integer. If unspecified, the importing function automatically detects the number of variables.
Data Types: single | double
Portion of the data to read from text or spreadsheet files, specified as the comma separated pair consisting of 'Range' and a character vector, string scalar, or numeric vector in one of these forms.
| Ways to specify Range | Description |
|---|---|
| Starting Cell'Cell' or[row col] | Specify the starting cell for the data as a character vector or string scalar or a two element numeric vector. Character vector or string scalar containing a column letter and row number using ExcelA1 notation. For example,A5 is the identifier for the cell at the intersection of column A and row 5. Two element numeric vector of the form [row col] indicating the starting row and column.Using the starting cell, the importing function automatically detects the extent of the data by beginning the import at the start cell and ending at the last empty row or footer range.Example: 'A5' or [5 1] |
| Rectangular Range'Corner1:Corner2' or[r1 c1 r2 c2] | Specify the exact range to read using the rectangular range in one of these forms. 'Corner1:Corner2' — Specify the range using Corner1 andCorner2 which are the two opposing corners that define the region to read in ExcelA1 notation. For example,'C2:N15'.[r1 c1 r2 c2] — Specify the range using a four element numeric vector containing start-row, start-column, end-row, and end-column. For example, [2 3 15 13].The importing function only reads the data contained in the specified range. Any empty fields within the specified range are imported as missing cells. |
| Row Range or Column Range'Row1:Row2' or'Column1:Column2' | Specify the range by identifying the beginning and ending rows using Excel row numbers. Using the specified row range, the importing function automatically detects the column extent by reading from the first nonempty column to the end of the data, and creates one variable per column.Example: '5:500'Alternatively, specify the range by identifying the beginning and ending columns using Excel column letters or numbers.Using the specified column range, the import function automatically detects the row extent by reading from the first nonempty row to the end of the data or the footer range.The number of columns in the specified range must match the number specified in theExpectedNumVariables property.Example: 'A:K' |
| Starting Row Numbern | Specify the first row containing the data using the positive scalar row index.Using the specified row index, the importing function automatically detects the extent of the data by reading from the specified first row to the end of the data or the footer range.**Example:**5 |
| Excel’s Named Range'NamedRange' | In Excel, you can create names to identify ranges in the spreadsheet. For instance, you can select a rectangular portion of the spreadsheet and call it 'myTable'. If such named ranges exist in a spreadsheet, then the importing function can read that range using its name.Example: 'Range','myTable' |
| Unspecified or Empty'' | If unspecified, the importing function automatically detects the used range.Example: 'Range',''Note: Used Range refers to the rectangular portion of the spreadsheet that actually contains data. The importing function automatically detects the used range by trimming any leading and trailing rows and columns that do not contain data. Text that is only white space is considered data and is captured within the used range. |
Data Types: char | string | double
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
Output data type, specified as the comma-separated pair consisting of'OutputType' and a character vector or string scalar containing name of any of the data types in this table.
| Type of Data | Output data type |
|---|---|
| Numeric | 'uint8', 'int8','int16', 'int32','int64', 'uint16','uint32', 'uint64','single', or 'double' |
| Text | 'char' or 'string' |
| Other types | 'datetime', 'duration', or'categorical' |
Example: 'OutputType','uint8'
Data Types: char | string
Text Files Only
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 readmatrix 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 readmatrix 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
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:
YYis an uppercase ISO 3166-1 alpha-2 code indicating a country.xxis a lowercase ISO 639-1 two-letter code indicating a language.
This table lists some common values for the locale.
| Locale | Language | Country |
|---|---|---|
| 'de_DE' | German | Germany |
| 'en_GB' | English | United Kingdom |
| 'en_US' | English | United States |
| 'es_ES' | Spanish | Spain |
| 'fr_FR' | French | France |
| 'it_IT' | Italian | Italy |
| 'ja_JP' | Japanese | Japan |
| 'ko_KR' | Korean | Korea |
| 'nl_NL' | Dutch | Netherlands |
| 'zh_CN' | Chinese (simplified) | China |
When using the %D format specifier to read text asdatetime values, use DateLocale to specify the locale in which the importing function should interpret month and day-of-week names and abbreviations.
If you specify the DateLocale argument in addition toopts the import options, then the importing function uses the specified value for the DateLocale argument, overriding the locale defined in the import options.
Example: 'DateLocale','ja_JP'
Data Types: char | string
Data Types: char | string
Remove nonnumeric characters from a numeric variable, specified as a logical true or false.
Example: If name-value pair is specified as 'TrimNonNumeric',true, then the importing function reads '$500/-' as500.
Data Types: logical
Procedure to manage trailing delimiters in a delimited text file, specified as one of the values in this table.
| Leading Delimiters Rule | Behavior |
|---|---|
| 'keep' | Keep the delimiter. |
| 'ignore' | Ignore the delimiter. |
| 'error' | Return an error and abort the import operation. |
Spreadsheet Files Only
Data Types: char | string | single | double
Flag to start an instance of Microsoft Excel for Windows when reading spreadsheet data, specified as the comma-separated pair consisting of 'UseExcel' and either true, orfalse.
You can set the 'UseExcel' parameter to one of these values:
true— The importing function starts an instance 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 totrue.
UseExcel is not supported in noninteractive, automated environments.
Since R2024b
Rule for cells merged across columns, specified as one of the values in this table.
| Import Rule | Behavior |
|---|---|
| "placeleft" | Place the data in the leftmost cell and fill the remaining cells with the contents of the FillValue property.You can specify the FillValue property in the VariableImportOptions object of the variable being imported. For more information on setting theFillValue property, see setvaropts. |
| "placeright" | Place the data in the rightmost cell and fill the remaining cells with the contents of the FillValue property.You can specify the FillValue property in the VariableImportOptions object of the variable being imported. For more information on setting theFillValue property, see setvaropts. |
| "duplicate" | Duplicate the data in all cells. |
| "omitrow" | Omit rows where merged cells occur. |
| "error" | Display an error message and cancel the import operation. |
Since R2024b
Rule for cells merged across rows, specified as one of the values in this table.
| Import Rule | Behavior |
|---|---|
| "placetop" | Place the data in the top cell and fill the remaining cells with the contents of the FillValue property.You can specify the FillValue property in theVariableImportOptions object of the variable being imported. For more information on setting the FillValue property, see setvaropts. |
| "placebottom" | Place the data in the bottom cell and fill the remaining cells with the contents of the FillValue property.You can specify the FillValue property in the VariableImportOptions object of the variable being imported. For more information on setting theFillValue property, see setvaropts. |
| "duplicate" | Duplicate the data in all cells. |
| "omitvar" | Omit variables where merged cells occur. |
| "error" | Display an error message and cancel the import operation. |
Version History
Introduced in R2019a
You can read data from compressed and archived files as a matrix.
When importing data from spreadsheets, you can specify how readmatrix imports cells that are merged across rows and columns by using theMergedCellRowRule and MergedCellColumnRule name-value arguments.