readcell

Create cell array from file

Syntax

C = readcell(filename)

C = readcell(filename,Name,Value)

C = readcell(filename,opts)

C = readcell(filename,opts,Name,Value)

Description

C = readcell(filename) creates a cell array by reading column-oriented data from a text or spreadsheet file.

C = readcell(filename,Name,Value) specifies options using one or more name-value arguments. For example, you can specify the number of header lines in the file, the expected number of variables or columns, or a range of data to read.

C = readcell(filename,opts) creates a cell array using the options specified by the import options object opts. Use an import options object to configure how readcell interprets your file. Compared to the previous two syntaxes, an import options object provides more control, better performance, and reusability of the file import configuration.

C = readcell(filename,opts,Name,Value) creates a cell array using both an import options object and name-value arguments. If you specify name-value arguments in addition to an import options object, then readcell supports only the DateLocale and Encoding name-value arguments for text files, and the Sheet and UseExcel name-value arguments for spreadsheet files.

Examples

Read from Text File

Import the contents of a text file into a cell array. readcell imports each element of the text file as a cell in the output cell array.

C = readcell("basic_cell.txt")

C=3×3 cell array
    {[                   1]}    {[    2]}    {[        3]}
    {'hello'               }    {'world'}    {[      NaN]}
    {[10-Oct-2018 10:27:56]}    {[    1]}    {[<missing>]}

Read from Spreadsheet

Import tabular data from a spreadsheet file into a cell array.

C = readcell("basic_cell.xls")

C=3×3 cell array
    {[                   1]}    {[    2]}    {[        3]}
    {'hello'               }    {'world'}    {[<missing>]}
    {[10-Oct-2018 10:27:56]}    {[    1]}    {[<missing>]}

Read Specific Range from Spreadsheet

Import data from a specified sheet and range into a cell array.

The airlinesmall_subset.xlsx spreadsheet file contains data in multiple worksheets for years between 1996 and 2008. Each sheet in the spreadsheet file has data for a given year.

Import 10 rows of data from columns G, H, and I from the sheet named "2007". The Excel® range "G2:I11" represents the region of data defined by columns G through I and rows 2 to 11 (the first 10 rows after the header row).

C = readcell("airlinesmall_subset.xlsx","Sheet","2007","Range","G2:I11")

C=10×3 cell array
    {[ 935]}    {[ 935]}    {'WN'}
    {[1041]}    {[1040]}    {'WN'}
    {[1430]}    {[1500]}    {'WN'}
    {[ 940]}    {[ 950]}    {'WN'}
    {[1515]}    {[1515]}    {'WN'}
    {[2042]}    {[2035]}    {'WN'}
    {[2116]}    {[2130]}    {'WN'}
    {[1604]}    {[1605]}    {'WN'}
    {[1258]}    {[1230]}    {'WN'}
    {[1134]}    {[1145]}    {'WN'}

Detect and Use Import Options for Text File

Import a subset of variables from a text file using an import options object.

Use the detectImportOptions function to detect aspects of your text file, including the variable names and types, delimiters, and white-space characters. The import options object opts stores the detected file aspects as properties.

opts = detectImportOptions("airlinesmall.csv")

opts = 
  DelimitedTextImportOptions with properties:

   Format Properties:
                    Delimiter: {','}
                   Whitespace: '\b\t '
                   LineEnding: {'\n'  '\r'  '\r\n'}
                 CommentStyle: {}
    ConsecutiveDelimitersRule: 'split'
        LeadingDelimitersRule: 'keep'
       TrailingDelimitersRule: 'ignore'
                EmptyLineRule: 'skip'
                     Encoding: 'ISO-8859-1'

   Replacement Properties:
                  MissingRule: 'fill'
              ImportErrorRule: 'fill'
             ExtraColumnsRule: 'addvars'

   Variable Import Properties: Set types by name using setvartype
                VariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more}
                VariableTypes: {'double', 'double', 'double' ... and 26 more}
        SelectedVariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more}
              VariableOptions: [1-by-29 matlab.io.VariableImportOptions] 
	Access VariableOptions sub-properties using setvaropts/getvaropts
           VariableNamingRule: 'modify'

   Location Properties:
                    DataLines: [2 Inf]
            VariableNamesLine: 1
               RowNamesColumn: 0
            VariableUnitsLine: 0
     VariableDescriptionsLine: 0 
	To display a preview of the table, use preview

Specify the subset of variables to import and the end-of-line character by modifying the import options object.

opts.SelectedVariableNames = ["Year","Month","DayofMonth"];
opts.LineEnding = "\n";

Import the subset of data using readcell with the import options object.

C = readcell("airlinesmall.csv",opts);

Input Arguments

filename — Name of file to read

string scalar | character vector

Name of the file to read, specified as a string scalar or character vector. You can specify one of these file formats:

• Delimited text file or fixed-width text file with a .txt, .dat, or .csv extension.

  • For delimited text files and fixed-width text files, readcell converts empty fields to missing values.

  • All lines in the text file must have the same number of delimiters.

  • readcell ignores insignificant white space in the file.

• Spreadsheet file with a .xls, .xlsb, .xlsm, .xlsx, .xltm, .xltx, or .ods extension.

  • On Windows^® systems with Microsoft^® Excel^®, readcell 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™, readcell reads only .xls, .xlsm, .xlsx, .xltm, and .xltx files.

If filename does not include an extension, use the FileType name-value argument to indicate the file format.

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

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. The table shows the properties of each import options object that readcell applies when importing data.

File Type	Import Options Object	Applied Properties
Delimited text files	DelimitedTextImportOptions object	SelectedVariableNames DataLines Delimiter Whitespace LineEnding CommentStyle ConsecutiveDelimitersRule LeadingDelimitersRule TrailingDelimitersRule Encoding MissingRule EmptyLineRule ExtraColumnsRule
Fixed-width text files	FixedWidthImportOptions object	SelectedVariableNames DataLines VariableWidths Whitespace LineEnding CommentStyle Encoding PartialFieldRule EmptyLineRule MissingRule ExtraColumnsRule
Spreadsheet files	SpreadsheetImportOptions object	SelectedVariableNames Sheet DataRange MissingRule ImportErrorRule

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.

Example: readcell(filename,NumHeaderLines=5) indicates that the first five lines of the specified file are header lines.

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

Example: readcell(filename,"NumHeaderLines",5) indicates that the first five lines of the specified file are header lines.

Text Files

FileType — Type of file

"text" | "spreadsheet"

Type of file, specified as "text" or "spreadsheet".

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

• .txt, .dat, or .csv for delimited or fixed-width text files

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

Example: "FileType","text"

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",[";","*"]

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.

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

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.

NumHeaderLines — Number of header lines

positive integer

Number of header lines in the file, specified as a positive integer. If unspecified, readcell automatically detects the number of header lines in the file.

Example: "NumHeaderLines",7

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"

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

Value	Description
"datetime"	MATLAB datetime data type For more information, see datetime.
"text"	The type for imported date and time data depends on the value specified in the TextType argument: If TextType is set to "string", then readcell returns dates as an array of strings. If TextType is set to "char", then readcell returns dates as a cell array of character vectors.

ExpectedNumVariables — Expected number of variables or columns

positive integer

Expected number of variables or columns, specified as a positive integer. If unspecified, readcell automatically detects the number of variables or columns.

Range — Portion of data to read

string scalar | character vector | numeric vector

Portion of the data to read from text files, specified as a string scalar, character vector, 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: String scalar or character vector 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, readcell 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" or [5 1]
Rectangular range "Corner1:Corner2" or [r1 c1 r2 c2]	Specify the exact region to read using a rectangular range in one of these forms: "Corner1:Corner2" — Specify the range using 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 the start-row, start-column, end-row, and end-column. For example, [2 3 15 13]. readcell reads only the data contained in the specified range. readcell imports any empty fields within the specified range as empty 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, readcell automatically detects the column extent by reading from the first nonempty column to the end of the data. readcell creates one cell array column for each column of data in the file. 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, readcell 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, readcell 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 a spreadsheet. For instance, you can select a rectangular portion of the spreadsheet and name it "myTable". If such named ranges exist in a spreadsheet, then readcell can read a range using its name. Example: "Range","myTable"
Unspecified or empty ""	If unspecified or empty, readcell automatically detects the used range. Example: "Range","" Note: Used range refers to the rectangular portion of the spreadsheet that actually contains data. readcell 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.

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

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

"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, readcell 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, then readcell 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.

DurationType — Output data type of duration data

"duration" (default) | "text"

Output data type of duration data from text files, specified as one of the values in this table.

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

DateLocale — Locale for reading dates

string scalar | character vector

Locale for reading dates, specified as a string scalar or a 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.

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 readcell should interpret month and day-of-week names and abbreviations.

If you specify the DateLocale argument in addition to an import options object, then readcell uses the specified value for the DateLocale argument, overriding the locale defined in the import options.

Example: "DateLocale","ja_JP"

Spreadsheet Files

FileType — Type of file

"text" | "spreadsheet"

Type of file, specified as "text" or "spreadsheet".

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

• .txt, .dat, or .csv for delimited or fixed-width text files

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

Example: "FileType","text"

NumHeaderLines — Number of header lines

positive integer

Number of header lines in the file, specified as a positive integer. If unspecified, readcell automatically detects the number of header lines in the file.

Example: "NumHeaderLines",7

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 the values in this table.

Value	Description
"datetime"	MATLAB datetime data type For more information, see datetime.
"text"	The type for imported date and time data depends on the value specified in the TextType argument: If TextType is set to "string", then readcell returns dates as an array of strings. If TextType is set to "char", then readcell returns dates as a cell array of character vectors.
"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.

ExpectedNumVariables — Expected number of variables or columns

positive integer

Expected number of variables or columns, specified as a positive integer. If unspecified, readcell automatically detects the number of variables or columns.

Sheet — Sheet to read from

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

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

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

Range — Portion of data to read

string scalar | character vector | numeric vector

Portion of the data to read from spreadsheet files, specified as a string scalar, character vector, 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: String scalar or character vector 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, readcell 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" or [5 1]
Rectangular range "Corner1:Corner2" or [r1 c1 r2 c2]	Specify the exact region to read using a rectangular range in one of these forms: "Corner1:Corner2" — Specify the range using 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 the start-row, start-column, end-row, and end-column. For example, [2 3 15 13]. readcell reads only the data contained in the specified range. readcell imports any empty fields within the specified range 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, readcell automatically detects the column extent by reading from the first nonempty column to the end of the data. readcell creates one cell array column for each column of data in the file. 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, readcell 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, readcell 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 a spreadsheet. For instance, you can select a rectangular portion of the spreadsheet and name it "myTable". If such named ranges exist in a spreadsheet, then readcell can read a range using its name. Example: "Range","myTable"
Unspecified or empty ""	If unspecified or empty, readcell automatically detects the used range. Example: "Range","" Note: Used range refers to the rectangular portion of the spreadsheet that actually contains data. readcell 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.

DurationType — Output data type of duration data

"duration" (default) | "text"

Output data type of duration data from spreadsheet files, specified as one of the values in this table.

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

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

UseExcel — Flag to start instance of Microsoft Excel for Windows

false or 0 (default) | true or 1

Flag to start an instance of Microsoft Excel for Windows when reading spreadsheet data, specified as one of these values:

• 1 (true) — Start an instance of Microsoft Excel when reading the file.

• 0 (false) — Do not start an instance of Microsoft Excel when reading the file. When operating in this mode, readcell 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

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 readcell imports cells that are merged across rows and columns by using the MergedCellRowRule and MergedCellColumnRule name-value arguments.