MATLAB®

Using MAT-Files

Introduction

MAT-files, the data file format MATLAB^® software uses for saving data to your disk, provide a convenient mechanism for moving data between platforms and for importing and exporting data to stand alone MATLAB applications.

To simplify your use of MAT-files in applications outside of the MATLAB environment, we have developed a library of access routines with a mat prefix that you can use in your own C or Fortran programs to read and write MAT-files. Programs that access MAT-files also use the mx prefixed API (application program interface) routines discussed in Creating C Language MEX-Files and Creating Fortran MEX-Files.

Back to Top

Importing Data into the MATLAB^® Workspace

The best method for importing data into MATLAB depends on how much data there is, whether the data is already in machine-readable form, and what format the data is in. Here are some choices; select the one that best meets your needs.

• Enter the data at the MATLAB command prompt.

  For small amounts of data, less than 10-15 elements, type the data at the command prompt using brackets []. This method is awkward for large amounts of data because you can't edit your input.

• Create data in an M-file.

  With a text editor, create an M-file to enter data as an explicit list of elements. Use this method when the data is not already in computer-readable format and must be typed in. Use the editor to change the data or correct mistakes, then rerun the M-file to reenter the data.

• Load data from an ASCII flat file.

  A flat file stores data in ASCII format, with fixed-length rows terminated by new lines (carriage returns) and with spaces separating the numbers. Edit ASCII flat files using a text editor and use the load command to read them directly into the workspace. MATLAB creates a variable with the same name as the file name.

• Read data using MATLAB I/O functions.

  Use fopen, fread, and other low-level MATLAB I/O functions to read data. This method allows you to load data files from applications that have their own file formats.

• Write a MEX-file to read the data.

  Use this method when you have subroutines for reading data files from other applications. For more information, see Using MEX-Files to Call C and Fortran Programs.

• Write a program to translate your data.

  Write programs in C or Fortran to translate your data into MAT-file format. Use the load command to read the MAT-file into the workspace. Refer to the section, Reading and Writing MAT-Files, for more information.

Back to Top

Exporting Data from the MATLAB^® Workspace

There are several methods for exporting MATLAB data.

• Create a diary file.

  For small matrices, use the diary command to create a diary file, a log of keyboard input and the resulting text output. You can use a text editor to modify the file. The diary file displays the variables and includes the MATLAB commands used during the session, which can be used in documents and reports.

• Use the save command.

  Save data in ASCII format using the save command with the -ascii option. For example:

  A = rand(4,3);
  save temp.dat A -ascii

  creates an ASCII file called temp.dat, which may look something like this:

  1.3889088e-001  2.7218792e-001  4.4509643e-001
  2.0276522e-001  1.9881427e-001  9.3181458e-001
  1.9872174e-001  1.5273927e-002  4.6599434e-001
  6.0379248e-001  7.4678568e-001  4.1864947e-001

  The -ascii option supports two-dimensional double and character arrays only. Multidimensional arrays, cell arrays, and structures are not supported.

• Use MATLAB I/O functions.

  Write the data in a special format using fopen, fwrite, and other low-level file I/O functions. Use this method for writing data files in file formats required by other applications. For more information, see Using Low-Level File I/O Functions.

• Create a MEX-file to write the data.

  Use this method if you have subroutines for writing data files in the form needed by other applications. For more information, see Using MEX-Files to Call C and Fortran Programs.

• Translate data from a MAT-file.

  Write data into a MAT-file using the save command, then write a program in C or Fortran to translate the MAT-file into your own special format. For more information, see Reading and Writing MAT-Files.

Back to Top

Exchanging Data Files Between Platforms

You can work with MATLAB software on different computer systems and send MATLAB applications to users on other systems. MATLAB applications consist of M-files containing functions and scripts, and MAT-files containing binary data.

Both types of files can be transported directly between machines: M-files because they are platform independent and MAT-files because they contain a machine signature in the file header. MATLAB checks the signature when it loads a file and, if a signature indicates that a file is foreign, performs the necessary conversion.

Using MATLAB across different machine architectures requires a facility for exchanging both binary and ASCII data between the machines. Examples of this type of facility include FTP, NFS, and Kermit. When using these programs, be careful to transmit MAT-files in binary file mode and M-files in ASCII file mode. Failure to set these modes correctly corrupts the data.

Back to Top

Reading and Writing MAT-Files

Use the save function to save MATLAB arrays currently in memory to a binary file called a MAT-file. MAT-files have the extension .mat. The load command reads MATLAB arrays from a MAT-file on disk back into the MATLAB workspace.

A MAT-file contains one or more of the data types supported in MATLAB version 5 or later, including strings, matrices, multidimensional arrays, structures, and cell arrays. MATLAB writes the data sequentially onto disk in a continuous byte stream.

MAT-File Interface Library

The MAT-file interface library contains routines for reading and writing MAT-files. You can call these routines from your own C and Fortran programs. Use these routines, rather than attempt to write your own code, to perform these operations, since using the library insulates your applications from future changes to the MAT-file structure.

Functions in the MAT-file library begin with the three-letter prefix mat. These tables list and describe the MAT-functions.

C MAT-File Routines

Fortran MAT-File Routines

Back to Top

Writing Character Data

By default, MATLAB writes character data to MAT-files using Unicode^® character encoding. To override this setting and use your system's default encoding instead, do one of the following:

• From the command line or a MATLAB function, save your data to the MAT-file using the command save -nounicode.

• From a C mex file, open the MAT-file you will write the data to using the command matOpen -wL.

See the individual reference pages for these functions for more information.

You can also set a save preference for all MATLAB sessions. For more information, see MAT-Files Preferences in the "General Preferences for MATLAB" section of the Desktop Tools and Development Environment documentation.

ASCII Data Formats

When writing character data using Unicode character encoding (the default), MATLAB checks if the data is 7-bit ASCII. If it is, MATLAB writes the 7-bit ASCII character data to the MAT-file using 8 bits per character (UTF-8 format), thus minimizing the size of the resulting file. Any character data that is not 7-bit ASCII is written in 16-bit Unicode form (UTF-16). This algorithm operates on a per-string basis.

Note   Level 4 MAT-files support only ASCII character data. You cannot write a Level 4 MAT-file containing non-ASCII character data. If you create a Level 4 MAT-file with such character data, the original representation of the characters is not preserved.

Converting Character Data

Writing character data to MAT-files using Unicode character encoding enables you to share data with users that have systems with a different default system character encoding scheme, without character data loss or corruption. Although conversion between Unicode encoding and other encoding forms is often lossless, there are scenarios in which round-trip conversions can result in loss of data. The following guidelines may reduce your chances of data loss or corruption.

In order to prevent loss or corruption of character data, all users sharing the data must have at least one of the following in common:

• They exchange Unicode-based MAT-files, and use a version of MATLAB that supports these files.

• Their computer systems all use the same default encoding, and all character data in the MAT-file was written using the -nounicode option

For example, if one user on a Japanese language operating system writes ASCII data having more than 7 bits per character to a MAT-file, another user running MATLAB version 6.5 on an English language operating system will be unable to read the data accurately. However, if both have MATLAB version 7, the information can be shared without corruption or loss of data.

Back to Top

Finding Associated Files

A collection of files associated with reading and writing MAT-files is located on your disk. The following table, MAT-Function Subdirectories, lists the path to the required subdirectories for importing and exporting data using MAT-functions. The term matlabroot refers to the root directory of your MATLAB installation.

MAT-Function Subdirectories

Include Files

The include subdirectory holds header files containing function declarations with prototypes for the routines that you can access in the API Library. These files are the same for both Windows and UNIX systems. The subdirectory contains:

• The matrix.h header file that defines MATLAB array access and creation methods

• The mat.h header file that defines MAT-file access and creation methods

Libraries

The libraries subdirectory, that contains shared (dynamically linkable) libraries for linking your programs, is platform dependent.

Shared Libraries on Windows^® Systems.   The bin subdirectory contains the shared libraries for linking your programs:

• The libmat.dll library of MAT-file routines (C and Fortran)

• The libmx.dll library of array access and creation routines

Shared Libraries on UNIX^® Systems.   The bin/$arch subdirectory, where $arch is your machine's architecture, contains the shared libraries for linking your programs. For example, on Sun™ Solaris™ systems, the subdirectory is bin/sol64:

• The libmat.so library of MAT-file routines (C and Fortran)

• The libmx.so library of array access and creation routines

Example Files

The examples/eng_mat subdirectory contains C and Fortran source code for a number of example files that demonstrate how to use the MAT-file routines. The source code files are the same for both Windows and UNIX systems.

C and Fortran Examples

For more information about MATLAB API files and directories, see Additional Information.

^[a] UNIX is a registered trademark of The Open Group in the United States and other countries.

Back to Top

Importing and Exporting Data

Examples of MAT-Files