Saving and Loading MAT-Files :: Data Import and Export (Programming)

Programming

Saving and Loading MAT-Files

This section explains how to save the variables in your MATLAB session to a binary file called a MAT-file, and how to load them back into your MATLAB workspace. It covers the following:

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.

Exporting Data to MAT-Files

This section covers

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

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

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.

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 MAT-Files, and click Save uncompressed. 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 Version 6 or 6.5. 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 3MB), 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 MB in memory, and this data has been saved to both a 10 MB compressed file and a 100 MB uncompressed file. When you load each of these files back into the MATLAB workspace, the first 10 MB of data takes the same amount of time to load for each file. Loading the remaining 90 MB from the uncompressed file will take 9 times as long as the first 10 MB, 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.

Unicode Character Encoding

MATLAB saves character data to a MAT-file using Unicode character data encoding. As with data compression, Unicode encoding is optional. If you disable it, MATLAB writes the MAT-file using the default character set 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 encoding for all of your MATLAB sessions, open the Preferences dialog, select General and then MAT-Files, and click Local Character Set. See General Preferences for MATLAB in the Desktop Tools and Development Environment documentation for more information. When writing character data 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 Version 6 or 6.5. 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.

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.

Output File Format
Command

Binary MAT-file (default)
save filename

8-digit ASCII
save filename -ascii

8-digit ASCII, tab delimited
save filename -ascii -tabs

16-digit ASCII
save filename -ascii -double

16-digit ASCII, tab delimited
save filename -ascii -double -tabs

MATLAB Version 4 compatible
save filename -v4

Output File Format	Command
Binary MAT-file (default)	`save` `filename`
8-digit ASCII	`save` `filename` `-ascii`
8-digit ASCII, tab delimited	`save` `filename` `-ascii` `-tabs`
16-digit ASCII	`save` `filename` `-ascii` `-double`
16-digit ASCII, tab delimited	`save` `filename` `-ascii` `-double` `-tabs`
MATLAB Version 4 compatible	`save` `filename` `-v4`

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.

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.

Element Range
Bytes per Element

0 to 255
1

0 to 65535
2

-32767 to 32767
2

-2³¹ to 2³¹-1
4

Other
8

Element Range	Bytes per Element
0 to 255	1
0 to 65535	2
-32767 to 32767	2
-2³¹ to 2³¹-1	4
Other	8

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.

Supported File Formats Importing Data from MAT-Files