Import Text Files

MATLAB^® can read and write numeric and nonnumeric data from delimited and formatted text files, including .csv and .txt files. Text files often contain a mix of numeric and text data as well as variable and row names. You can represent this data in MATLAB as tables, timetables, matrices, cell arrays, or string arrays.

Import data from text files either programmatically or interactively. Import programmatically to use tailored import functions and further control how your data is imported using import options. Import interactively to use the Import Tool and its user interface.

Import Data as Tables

If your text file has tabular data, you can import the data as a table. A table consists of column-oriented variables containing rows of data of the same type. Each variable in a table can hold a different data type and size, however, each variable must have the same number of rows. For more information about tables, see Create Tables and Assign Data to Them.

Import tabular data from a text file into a table using the readtable function with the file name. For example, create a table from the sample file airlinesmall.csv.

T = readtable('airlinesmall.csv');

Display the first five rows and columns of the table.

T(1:5,1:5)

ans =

  5×5 table

    Year    Month    DayofMonth    DayOfWeek    DepTime 
    ____    _____    __________    _________    ________

    1987     10          21            3        {'642' }
    1987     10          26            1        {'1021'}
    1987     10          23            5        {'2055'}
    1987     10          23            5        {'1332'}
    1987     10          22            4        {'629' }

Import Data as Timetables

If your text file has tabular data where each row is associated with a time, you can import the data as a timetable. Like tables, timetables allow you to store tabular data variables that can have different data types and sizes as long as they have the same number of rows. In addition, a timetable provides time-specific functions to align, combine, and perform calculations with time-stamped data in one or more timetables. For more information about timetables, see Create Timetables.

Import tabular data from a text file into a timetable using the readtimetable function. For example, create a timetable from the sample file outages.csv.

TT = readtimetable('outages.csv');

Display the first five rows and columns of the timetable.

TT(1:5,1:5)

ans =

  5×5 timetable

       OutageTime          Region         Loss     Customers     RestorationTime            Cause       
    ________________    _____________    ______    __________    ________________    ___________________

    2002-02-01 12:18    {'SouthWest'}    458.98    1.8202e+06    2002-02-07 16:50    {'winter storm'   }
    2003-01-23 00:49    {'SouthEast'}    530.14    2.1204e+05                 NaT    {'winter storm'   }
    2003-02-07 21:15    {'SouthEast'}     289.4    1.4294e+05    2003-02-17 08:14    {'winter storm'   }
    2004-04-06 05:44    {'West'     }    434.81    3.4037e+05    2004-04-06 06:10    {'equipment fault'}
    2002-03-16 06:18    {'MidWest'  }    186.44    2.1275e+05    2002-03-18 23:23    {'severe storm'   }

Import Data as Matrices

If your text file contains uniform data (all of the same type), you can import the data as a matrix. Importing your data into a matrix allows you to work with a minimally formatted array.

Import tabular data from a text file into a matrix using readmatrix. For example, import the data from the sample file basic_matrix.txt into a matrix.

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     9

Import Data as Cell Arrays

A cell array is a data type with indexed data containers called cells, where each cell can contain any type of data. Cell arrays commonly contain either lists of text, combinations of text and numbers, or numeric arrays of different sizes.

You can import non-uniform data (each column having a different type) from a text file into a cell array using readcell. For example, display the contents of basic_cell.txt, and then import the mixed data into a cell array.

type basic_cell.txt

1,2,3
hello,world,NaN
10-Oct-2018 10:27:56,1,

C = readcell('basic_cell.txt')

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

Alternatively, you can import formatted data from a text file into a cell array using the textscan function and a low-level I/O workflow. Low-level I/O workflows allow for the most control over importing data. This degree of control is not necessary for most workflows. For more information on importing text data with low-level I/O, see Import Text Data Files with Low-Level I/O.

Import Data as String Arrays

If your text file contains lines of plain text, you can represent the plain text in MATLAB as a string array. String arrays store pieces of text and provide a set of functions for working with text as data. For example, you can index into, reshape, and concatenate strings arrays just as you can with arrays of any other type.

Import lines of plain text in a text file into string arrays using readlines. For example, create a string array from the sample text file, badpoem.txt. Since the text file has four lines of plain text, the function creates a 4-by-1 string array.

lines = readlines("badpoem.txt")

lines = 4x1 string
    "Oranges and lemons,"
    "Pineapples and tea."
    "Orangutans and monkeys,"
    "Dragonflys or fleas."

Import Data with Import Options for Additional Control

Importing tabular data sometimes requires additional control over the import process. To customize the import process, you can create an import options object. The object has properties that you can adjust based on your import needs. For example, you can change the data types of variables or import only a subset of variables. For more information about import options, see detectImportOptions.

Import Data Interactively

If you would prefer to use the user interface, you can import data interactively into a table or other data type using the Import Tool.

To open the Import Tool, within the Home tab, in the Variable section, click Import Data . Alternatively, right-click the name of the file in the Current Folder browser and select Import Data.Then, select the file you want to import. Using the Import Tool window, set the importing options and then click Import Selection to import the data into MATLAB. For more information, see Read Text File Data Using Import Tool.