Documentation Center

  • Trial Software
  • Product Updates

readtable

Create table from file

Syntax

  • T = readtable(filename) example
  • T = readtable(filename,Name,Value) example

Description

example

T = readtable(filename) creates a table by reading column oriented data from a file.

readtable determines the file format from the file name's extension:

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

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

readtable creates one variable in T for each column in the file and reads variable names from the first row of the file. By default, the variables created are double if the entire column is numeric, or cell arrays of strings if any element in a column is not numeric.

example

T = readtable(filename,Name,Value) creates a table from a file with additional options specified by one or more Name,Value pair arguments.

For example, you can specify not to read the first row of the file as variable names.

Examples

expand all

Create Table from Text File

Create a file, myCsvTable.dat, that contains the following comma-separated column oriented data.

LastName,Gender,Age,Height,Weight,Smoker
Smith,M,38,71,176,1
Johnson,M,43,69,163,0
Williams,F,38,64,131,0
Jones,F,40,67,133,0
Brown,F,49,64,119,0

Create a table from the comma-separated text file.

T = readtable('myCsvTable.dat')
T = 

     LastName     Gender    Age    Height    Weight    Smoker
    __________    ______    ___    ______    ______    ______

    'Smith'       'M'       38     71        176       1     
    'Johnson'     'M'       43     69        163       0     
    'Williams'    'F'       38     64        131       0     
    'Jones'       'F'       40     67        133       0     
    'Brown'       'F'       49     64        119       0     

T contains one variable for each column in the file and readtable the entries in first line of the file as variable names.

Create Table from Text File without Column Headings

Create a file, mySpaceDelimTable.txt, that contains the following space delimited, column oriented data.

M 45 45 NY true
F 41 32 CA false
M 40 34 MA false

Create a table from the space delimited text file that does not contain variable names as column headings.

T = readtable('mySpaceDelimTable.txt',...
    'Delimiter',' ','ReadVariableNames',false)
T = 

    Var1    Var2    Var3    Var4     Var5  
    ____    ____    ____    ____    _______

    'M'     45      45      'NY'    'true' 
    'F'     41      32      'CA'    'false'
    'M'     40      34      'MA'    'false'

T contains default variable names.

Create and Format Table from Text File

Create a file, myCsvTable.dat, that contains the following comma-separated column oriented data.

LastName,Gender,Age,Height,Weight,Smoker
Smith,M,38,71,176,1
Johnson,M,43,69,163,0
Williams,F,38,64,131,0
Jones,F,40,67,133,0
Brown,F,49,64,119,0

Create a table from the comma-separated text file. Format the first two variables as strings, the third variable as uint32, and the next two variables as double-precision, floating-point numbers. Format the last variable as a string.

T = readtable('myCsvTable.dat','Format','%s%s%u%f%f%s')
T = 

     LastName     Gender    Age    Height    Weight    Smoker
    __________    ______    ___    ______    ______    ______

    'Smith'       'M'       38     71        176       '1'   
    'Johnson'     'M'       43     69        163       '0'   
    'Williams'    'F'       38     64        131       '0'   
    'Jones'       'F'       40     67        133       '0'   
    'Brown'       'F'       49     64        119       '0'   

The conversion specifiers are %s for a cell array of strings, %f for double, and %u for uint32.

Create Table from Spreadsheet Including Row Names

Create a table from a spreadsheet that contains variable names in the first row and row names in the first column.

T = readtable('patients.xls','ReadRowNames',true);

Display the first five rows and first four variables of the table.

T(1:5,1:4)
ans = 

                 Gender     Age             Location              Height
                ________    ___    ___________________________    ______

    Smith       'Male'      38     'County General Hospital'      71    
    Johnson     'Male'      43     'VA Hospital'                  69    
    Williams    'Female'    38     'St. Mary's Medical Center'    64    
    Jones       'Female'    40     'VA Hospital'                  67    
    Brown       'Female'    49     'County General Hospital'      64    

View the DimensionNames property of the table.

T.Properties.DimensionNames
ans = 

    'LastName'    'Variable'

'LastName' is the name in the first column of the first row of the spreadsheet.

Read Specific Range of Data from Spreadsheet

Create a table from the 5-by-3 rectangular region between the two corners C2 and E6 on the spreadsheet patients.xls. Do not use the first row of this region as variable names.

T = readtable('patients.xls',...
    'Range','C2:E6',...
    'ReadVariableNames',false)
T = 

    Var1               Var2                Var3
    ____    ___________________________    ____

    38      'County General Hospital'      71  
    43      'VA Hospital'                  69  
    38      'St. Mary's Medical Center'    64  
    40      'VA Hospital'                  67  
    49      'County General Hospital'      64  

T contains default variable names.

Input Arguments

expand all

filename — Name of file to readstring

Name of the file to read, specified as a string. If filename includes the file extension, then readtable 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, readtable reads any Excel spreadsheet file format recognized by your version of Excel. If your system does not have Excel for Windows, readtable operates in basic import mode, and reads only XLS, XLSX, XLSM, XLTX, and XLTM files.

For a delimited text file, readtable converts empty fields in the file to either NaN (for a numeric variable) or the empty string (for a string-valued variable). All lines in the text file must have the same number of delimiters. readtable ignores insignificant white space in the file.

Example: 'myFile.xlsx'

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'ReadVariableNames',false indicates that the first row of the file does not correspond to variable names.

'FileType' — Type of file'text' | 'spreadsheet'

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

You must specify the 'FileType' name-value pair argument if the filename input argument 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'

'ReadVariableNames' — Indicator for reading first row as variable namestrue (default) | false | 1 | 0

Indicator for reading the first row as variable names, specified as the comma-separated pair consisting of 'ReadVariableNames' and either true, false, 1, or 0.

true

The first row of the region to read contains the variable names for the table. This is the default behavior.

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

false

The first row of the region to read contains the first row of data in the table.

readtable creates default variable names of the form 'Var1',...,'VarN', where N is the number of variables.

'ReadRowNames' — Indicator for reading the first column as row namesfalse (default) | true | 0 | 1

Indicator for reading first column as row names, specified as the comma-separated pair consisting of 'ReadRowNames' and either false, true, 0, or 1.

false

The first column of the region to read contains the first variable in the table. It does not contain the row names for the table. This is the default behavior.

true

The first column of the region to read contains the row names for the table.

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

'TreatAsEmpty' — Strings to treat as empty valuestring | cell array of strings

Strings to treat as empty value, specified as the comma-separated pair consisting of 'TreatAsEmpty' and a string or a cell array of strings. Table elements corresponding to these are set to NaN.

'TreatAsEmpty' only applies to numeric columns in the file, and readtable does not accept numeric literals, such as '-99'.

Example: 'TreatAsEmpty','N/A' sets N/A within numeric columns to NaN.

Example: 'TreatAsEmpty',{'.','NA','N/A'} sets ., NA and N/A within numeric columns to NaN.

'Delimiter' — Field delimiter characterstring

Field delimiter character, specified as the comma-separated pair consisting of 'Delimiter' and one of the following strings:

','

'comma'

Comma. This is the default behavior.

' '

'space'

Space

'\t'

'tab'

Tab

';'

'semi'

Semicolon

'|'

'bar'

Vertical bar

You can use the 'Delimiter' name-value pair only with delimited text files.

Example: 'Delimiter','space'

'HeaderLines' — Number of lines to skip at beginning of file0 (default) | positive integer

Number of lines to skip at beginning of file, specified as the comma-separated pair consisting of 'HeaderLines' and a positive integer.

You can use the 'HeaderLines' name-value pair only with delimited text files.

Data Types: single | double

'Format' — Format of columns in filestring of one or more conversion specifiers

Format of the columns in the file, specified as the comma-separated pair consisting of 'Format' and a string of one or more conversion specifiers.

By default, the variables created are either double, if the entire column is numeric, or cell arrays of strings, if any element in a column is not numeric.

The conversion specifiers are the same as those accepted by the textscan function. If you specify the 'Format' name-value pair argument, you can specify any of the name-value pair arguments accepted by the textscan function.

Specifying the format can significantly improve speed for some large files.

You can use the 'Format' name-value pair only with delimited text files.

'Sheet' — Worksheet to read1 (default) | positive integer indicating worksheet index | string containing worksheet name

Worksheet to read, specified as the comma-separated pair consisting of 'Sheet' and a positive integer indicating the worksheet index or a string containing the worksheet name. The worksheet name string cannot contain a colon (:). To determine the names of sheets in a spreadsheet file, use [status,sheets] = xlsfinfo(filename).

You can use the 'Sheet' name-value pair only with spreadsheet files.

Example: 'Sheet',2

'Range' — Rectangular portion of worksheet to readstring

Rectangular portion of the worksheet to read, specified as the comma-separated pair consisting of 'Range' and a string.

Specify the range using the syntax 'Corner1:Corner2', where Corner1 and Corner2 are two opposing corners that define the region to read. For example, 'D2:H4' represents the 3-by-5 rectangular region between the two corners D2 and H4 on the worksheet. The 'Range' name-value pair argument is not case sensitive, and uses Excel A1 reference style (see Excel help).

If the spreadsheet contains figures or other nontablular information, use the 'Range' name-value pair argument to read only the tabular data. By default, readtable reads data from a spreadsheet contiguously out to the right-most column that contains data, including any empty columns that precede it.

You can use the 'Range' name-value pair only with spreadsheet files.

Example: 'Range','D2:H4'

'Basic' — Indicator for reading in basic modetrue | false | 1 | 0

Indicator for reading in basic mode, specified as the comma-separated pair consisting of 'Basic' and either true, false, 1, or 0.

basic mode is the default for systems without Excel for Windows. In basic mode, readtable:

  • Reads XLS, XLSX, XLSM, XLTX, and XLTM files only.

  • Does not support the 'Range' name-value pair argument when reading XLS files.

  • Imports all dates as Excel serial date numbers. Excel serial date numbers use a different reference date than MATLAB® date numbers.

You can use the 'Basic' name-value pair only with spreadsheet files.

Output Arguments

expand all

T — Output tabletable

Output table, returned as a table. The table can store metadata such as descriptions, variable units, variable names, and row names. For more information, see Table Properties.

See Also

| |

Was this topic helpful?