Documentation Center (Beta)

Recommended Methods for Importing Data

Caution   When you import data into the MATLAB workspace, the new variables you create overwrite any existing variables in the workspace that have the same name.

Tools that Import Multiple File Formats

The easiest way to import data into MATLAB from a disk file or the system clipboard is to use the Import Wizard, a graphical user interface. The Import Wizard helps you find a file and define the variables to use in the MATLAB workspace.

To import data from a file, start the Import Wizard, using one of these methods:

• Select File > Import Data.

• Double-click a file name in the Current Folder browser.

• Click the Import Data button in the Workspace browser.

• Call uiimport.

To import data from the clipboard, start the Import Wizard, using one of these methods:

• Select Edit > Paste to Workspace.

• Call uiimport.

To import without invoking a graphical user interface, the easiest option is to use the importdata function.

The Import Wizard reads all supported file formats, except netCDF, HDF5, Motion JPEG 2000, and platform-specific video. The importdata function reads all formats supported by the Import Wizard, except HDF4.

For more information, see Tips for Using the Import Wizard.

Importing Specific File Formats

MATLAB includes functions tailored to import these specific file formats:

• MAT-files

• Text (ASCII) data

• Spreadsheets

• Scientific data

• Images

• Audio and video

• Data in Extensible Markup Language (XML)

• Data created using the Data Acquisition Toolbox (see daqread)

Consider using format-specific functions instead of the Import Wizard or importdata when:

• The Import Wizard or importdata produces unexpected results.

  The Import Wizard makes assumptions about which functions to call, and which input parameters to use. Select and call the format-specific functions directly for more control over the inputs. For example, use textscan to import data from a text data file that includes character data (see Import Mixed Text and Numeric Data from a Text File).

• You want to import only a portion of a file.

  Many of the format-specific functions provide options for selecting ranges or portions of data. Alternatively, for binary data files, consider memory-mapping.

For a complete list of the format-specific functions, see Supported File Formats.

Importing Data in Other Formats

If the Import Wizard, importdata, and format-specific functions cannot read your data, use low-level I/O functions such as fscanf or fread. Low-level functions allow the most control over reading from a file, but require detailed knowledge of the structure of your data. For more information, see:

• Import Text Data Files with Low-Level I/O

• Importing Binary Data with Low-Level I/O

Alternatively, MATLAB toolboxes perform specialized import operations. For example, use Database Toolbox™ software for importing data from relational databases. Refer to the documentation on specific toolboxes to see the available import features.

Finding Files

To find a specific file on the MATLAB search path, use the which function. If the file is not in the current folder, include the full or partial path with the file name in calls to import functions.

For example, to locate and load myfile.mat:

fullname = which('myfile.mat');
load(fullname);

For more information, see:

• Finding Files and Folders

• Path Names in MATLAB

• Using the MATLAB Search Path

Processing a Sequence of Files

To import or export multiple files, create a control loop to process one file at a time. When constructing the loop:

• To build sequential file names, use sprintf.

• To find files that match a pattern, use dir.

• Use function syntax to pass the name of the file to the import or export function. (For more information, see Command vs. Function Syntax in the Programming Fundamentals documentation, or the syntax reference page.)

For example, to read files named file1.txt through file20.txt with importdata:

numfiles = 20;
mydata = cell(1, numfiles);

for k = 1:numfiles
  myfilename = sprintf('file%d.txt', k);
  mydata{k} = importdata(myfilename);
end

To read all files that match *.jpg with imread:

jpegFiles = dir('*.jpg'); 
numfiles = length(jpegFiles);
mydata = cell(1, numfiles);

for k = 1:numfiles 
  mydata{k} = imread(jpegFiles(k).name); 
end

Tips for Using the Import Wizard

Start the Import Wizard by selecting File > Import Data or calling uiimport.

The Import Wizard provides the following options for reading text files, images, audio, or video data:

• Viewing the Contents of a File

• Specifying Variables

• Generating Reusable MATLAB Code

Note   For information on importing spreadsheets or comma-separated value (CSV) files, see Select Spreadsheet Data Interactively. For information on importing HDF4 files, see Using the HDF Import Tool.

Viewing the Contents of a File

For text files, the Import Wizard automatically displays a preview of the data in the file.

To view images or video, or to listen to audio, click the Back button on the first window that the Import Wizard displays.

The right pane of the new window includes a preview tab. Click the button in the preview tab to show an image or to play audio or video.

Specifying Variables

The Import Wizard generates default variable names based on the format and content of your data. You can change the variables in any of the following ways:

• Renaming or Deselecting Variables

• Importing to a Structure Array

The default variable name for data imported from the system clipboard is A_pastespecial.

If the Import Wizard detects a single variable in a file, the default variable name is the file name. Otherwise, the Import Wizard uses default variable names that correspond to the output fields of the importdata function. For more information on the output fields, see the importdata function reference page.

Renaming or Deselecting Variables.  To override the default variable name, select the name and type a new one.

To avoid importing a particular variable, clear the check box in the Import column.

Importing to a Structure Array.  To import data into fields of a structure array rather than as individual variables, start the Import Wizard by calling uiimport with an output argument. For example, the demo file durer.mat contains three variables: X, caption, and map. If you issue the command

durerStruct = uiimport('durer.mat')

and click the Finish button, the Import Wizard returns a scalar structure with three fields:

durerStruct = 
          X: [648x509 double]
        map: [128x3 double]
    caption: [2x28 char]

To access a particular field, use dot notation. For example, view the caption field:

disp(durerStruct.caption)

MATLAB returns:

Albrecht Durer's Melancolia.
Can you find the matrix?  

For more information, see Structures.

Generating Reusable MATLAB Code

To create a function that reads similar files without restarting the Import Wizard, select the Generate MATLAB code check box. When you click Finish to complete the initial import operation, MATLAB opens an Editor window that contains an unsaved function. The default function name is importfile.m or importfileN.m, where N is an integer.

The function in the generated code includes the following features:

• For text files, if you request vectors from rows or columns, the generated code also returns vectors.

• When importing from files, the function includes an input argument for the name of the file to import, fileToRead1.

• When importing into a structure array, the function includes an output argument for the name of the structure, newData1.

However, the generated code has the following limitations:

• If you rename or deselect any variables in the Import Wizard, the generated code does not reflect those changes.

• If you do not import into a structure array, the generated function creates variables in the base workspace. If you plan to call the generated function from within your own function, your function cannot access these variables. To allow your function to access the data, start the Import Wizard by calling uiimport with an output argument. Call the generated function with an output argument to create a structure array in the workspace of your function.

• For text files, the generated code can include specified values for the delimiter or number of header lines. If other files require different values for these parameters, modify the generated code.

MATLAB does not automatically save the function. To save the file, select File > Save. For best results, use the function name with a .m extension for the file name.

Example — Generating Code to Import a Text File.  Consider the file grades.txt discussed in Import Data with Headers Interactively. The file contains the following data:

   John    Ann     Martin  Rob
   88.4    91.5    89.2    77.3
   83.2    88.0    67.8    91.0
   77.8    76.3    78.1    92.5
   92.1    96.4    81.2    84.6

Use the Import Wizard to create column vectors, select the Generate MATLAB code check box, and click Finish. MATLAB generates code similar to the following excerpt, and opens the code in the Editor.

function importfile(fileToRead1)
%IMPORTFILE(FILETOREAD1)
%  Imports data from the specified file
%  FILETOREAD1:  file to read
...

Save the function. Create a file new_grades.txt that contains the following data:

   Michael  Juan    Nita    Steve   Lynn
   76.3     89.0    93.1    72.4    81.7
   81.9     93.4    90.5    81.8    76.7
   80.3     97.8   100.0    89.2    79.6

Import the data using the generated function:

importfile1('new_grades.txt')

The workspace includes the following variables:

  Name         Size            Bytes  Class     Attributes

  Juan         3x1                24  double              
  Lynn         3x1                24  double              
  Michael      3x1                24  double              
  Nita         3x1                24  double              
  Steve        3x1                24  double