MATLAB®

Exporting Data to MAT-Files

MAT-Files

MAT-files are double-precision, binary, MATLAB^® format files. They can be created on one machine and later read by MATLAB on another machine with a different floating-point format, retaining as much accuracy and range as the different formats allow. They can also be manipulated by other programs external to MATLAB.

This section explains how to save the variables in your MATLAB session to a binary file called a MAT-file. The next section explains how to load the variables back into your MATLAB workspace.

Back to Top

Using the save Function

To export workspace variables to a binary or ASCII file, use the save function. You can save all variables from the workspace in a single operation (if you omit the filename, MATLAB uses the name matlab.mat):

save filename

or save just those variables that you specify:

save filename var1 var2 ... varN

Use the wildcard character (*) in the variable name to save those variables that match a specific pattern. For example, the following command saves all variables that start with str:

save strinfo str*

Use whos -file to examine what has been written to the MAT-file:

whos -file strinfo
  Name           Size                   Bytes  Class

  str2           1x15                      30  char array
  strarray       2x5                      678  cell array
  strlen         1x1                        8  double array

Back to Top

Saving Structures

When saving a MATLAB structure, you have the option of saving the entire structure, saving each structure field as an individual variable in the MAT-file, or saving specific fields as individual variables.

For structure S:

S.a = 12.7;  S.b = {'abc', [4 5; 6 7]};  S.c = 'Hello!';

Save the entire structure to newstruct.mat with the usual syntax:

save newstruct.mat S;

whos -file newstruct
  Name      Size                   Bytes  Class

  S         1x1                      550  struct array

Save the fields individually with the -struct option:

save newstruct.mat -struct S;

whos -file newstruct
  Name      Size                   Bytes  Class

  a         1x1                        8  double array
  b         1x2                      158  cell array
  c         1x6                       12  char array

Or save only selected fields using -struct and specifying each field name:

save newstruct.mat -struct S a c;

whos -file newstruct
  Name      Size                   Bytes  Class

  a         1x1                        8  double array
  c         1x6                       12  char array

Back to Top

Appending to an Existing File

You can add new variables to those already stored in an existing MAT-file by using save -append. When you append to a MAT-file, MATLAB first looks in the designated file for each variable name specified in the argument list, or for all variables if no specific variable names are specified. Based on that information, MATLAB does both of the following:

• For each variable that already exists in the MAT-file, MATLAB overwrites its saved value with the new value taken from the workspace.

• For each variable not found in the MAT-file, MATLAB adds that variable to the file and stores its value from the workspace.

Note   Saving with the -append option does not append additional elements to any arrays that are already saved in the MAT-file.

Back to Top

Data Compression

MATLAB compresses the data that you save to a MAT-file. Data compression can save you a significant amount of storage space when you are working with large files or working over a network.

Data compression is optional, however, and you can disable it either for an individual save operation, or for all of your MATLAB sessions. Use the -v6 option with the save function to turn off compression on a per-command basis:

save filename -v6

To disable data compression for all of your MATLAB sessions, open the Preferences dialog, select General, and then select MAT-Files. Next click the option that is equivalent to the command save -v6. See General Preferences for MATLAB in the Desktop Tools and Development Environment documentation for more information.

Note   You cannot read a compressed MAT-file with MATLAB software versions earlier than Version 7. To write a MAT-file that you will be able to read with one of these versions, save to the file with data compression disabled.

Information returned by the command whos -file is independent of whether the variables in that file are compressed or not. The byte counts returned by this command represent the number of bytes data occupies in the MATLAB workspace, and not in the file the data was saved to.

Evaluating When to Compress

You should consider both data set size and the type of data being saved when deciding whether or not to compress the data you save to a file. The benefits of data compression are greater when saving large data sets (over 3 megabytes), and are usually negligible with smaller data sets. Data that has repeating patterns or more consistent values compresses better than random data. Compressing data that has a random pattern is not recommended as it slows down the performance of save and load significantly, and offers little benefit in return.

In general, data compression and decompression slows down all save and some load operations to some extent. In most cases, however, the resulting reduction in file size is worth the additional time spent compressing or decompressing. Because loading is typically done more frequently than saving, load is considered to be the most critical of the two operations. Up to a certain threshold (relative to the size of the uncompressed MAT-file), loading a compressed MAT-File is slightly slower than loading an uncompressed file containing the same data. Beyond that threshold, however, loading the compressed file is faster.

For example, say that you have a block of data that takes up 100 megabytes in memory, and this data has been saved to both a 10 megabytes compressed file and a 100 megabytes uncompressed file. When you load each of these files back into the MATLAB workspace, the first 10 megabytes of data takes the same amount of time to load for each file. Loading the remaining 90 megabytes from the uncompressed file will take nine times as long as the first 10 megabytes, while all that remains to be done with the compressed file is to decompress the data, and this takes a relatively short amount of time.

The loading size threshold is lower for network files, and also varies depending on the type of computer being used. Network users loading compressed MAT-files generally see faster load times than when loading uncompressed files, and at smaller data sizes than users loading the same files locally.

Note   Compression and decompression during save and load is done transparently without the use of temporary files on disk. This is of significance to large dataset users in particular.

Back to Top

Unicode^® Character Encoding

MATLAB saves character data to a MAT-file using the Unicode, Inc. Unicode^® character encoding. As with data compression, Unicode character encoding is optional. If you disable it, MATLAB writes the MAT-file using the default encoding for your system. To disable Unicode character encoding on a per-command basis, use the -v6 option with the save function:

save filename -v6

To disable Unicode character encoding for all of your MATLAB sessions, open the Preferences dialog box, select General, and then select MAT-Files. Next click the option that is equivalent to the command save -v6. See General Preferences for MATLAB in the Desktop Tools and Development Environment documentation for more information.

When writing character data to a non-HDF5-based MAT-file using Unicode 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   You cannot read a Unicode encoded MAT-file with MATLAB versions earlier than Version 7. To write a MAT-file that you will be able to read with one of these versions, save to the file with Unicode character encoding disabled.

For more information on how MATLAB saves specific ASCII data formats, and on preventing loss or corruption of character data, see Writing Character Data in the MATLAB External Interfaces documentation.

Back to Top

Optional Output Formats

You can choose from any of the following formats for your output file. If you do not specify a format, MATLAB uses the binary MAT-file format.

Saving in ASCII Format

When saving in any of the ASCII formats, consider the following:

• Each variable to be saved must be either a two-dimensional double array or a two-dimensional character array. Saving a complex double array causes the imaginary part of the data to be lost, as MATLAB cannot load nonnumeric data ('i').

• To read the file with the MATLAB load function, make sure all the variables have the same number of columns. If you are using a program other than MATLAB to read the saved data, this restriction can be relaxed.

• Each MATLAB character in a character array is converted to a floating-point number equal to its internal ASCII code and written out as a floating-point number string. There is no information in the saved file that indicates whether the value was originally a number or a character.

• The values of all variables saved merge into a single variable that takes the name of the ASCII file (minus any extension). Therefore, it is advisable to save only one variable at a time.

Saving in Version 4 Format

With the -v4 option, you can save only those data constructs that are compatible with MATLAB Version 4. Therefore, you cannot save structures, cell arrays, multidimensional arrays, or objects. Variable names cannot exceed 19 characters in length. In addition, you must use filenames that are supported by MATLAB Version 4.

Back to Top

Storage Requirements

The binary formats used by save depend on the size and type of each array. Arrays with any noninteger entries and arrays with 10,000 or fewer elements are saved in floating-point formats requiring 8 bytes per real element. Arrays with all integer entries and more than 10,000 elements are saved in the formats shown, requiring fewer bytes per element.

Back to Top

Saving from External Programs

The MATLAB External Interfaces documentation provides details on reading and writing MAT-files from external C or Fortran programs. It is important to use recommended access methods, rather than rely upon the specific MAT-file format, which is likely to change in the future.

Back to Top

Accessing Files with Memory-Mapping

Importing Data From MAT-Files