matfile - Load and save parts of variables in MAT-files

Syntax

matObj = matfile(filename) matObj = matfile(filename,'Writable',isWritable)

Description

matObj = matfile(filename) constructs a matlab.io.MatFile object that can load or save parts of variables in MAT-file filename. MATLAB does not load any data from the file into memory when creating the object.

matObj = matfile(filename,'Writable',isWritable) enables or disables write access to the file for object matObj. Possible values for isWritable are logical true (1) or false (0).

Input Arguments

filename

String enclosed in single quotation marks that specifies the name of a MAT-file.

filename can include a full or partial path, otherwise matfile searches for the file along the MATLAB search path. If filename does not include an extension, matfile appends .mat.

If the file does not exist, matfile creates a Version 7.3 MAT-file on the first assignment to a variable.

matfile only supports partial loading and saving for MAT-files in Version 7.3 format (described in MAT-File Versions). If you index into a variable in a Version 7 (the current default) or earlier MAT-file, MATLAB warns and temporarily loads the entire contents of the variable.

'Writable'

Parameter to use with the isWritable argument.

isWritable

Logical value that specifies whether to allow saving to the file. Possible values:

true (1) Enable saving. If the file is read only, change the system permissions with fileattrib.

false (0) Disable saving with matfile. MATLAB does not change the system permissions.

Default: true for new files, false for existing files

Output Arguments

matObj

Object of class matlab.io.MatFile that corresponds to a MAT-file.

Access variables in the MAT-file as properties of matObj, with dot notation similar to accessing fields of structs. The syntax for loading and saving part of variable varName in the MAT-file corresponding to matObj is:

loadedData = matObj.varName(indices);    % Load into workspace
matObj.varName(indices) = dataToSave;    % Save to file

When indexing, specify indices for all dimensions. Indices can be a single value, an equally spaced range of increasing values, or a colon (:), such as

matObj.varName(100:500, 200:600)
matObj.varName(:, 501:1000)
matObj.varName(1:2:1000, 80)

Limitations

Using the end keyword as part of an index causes MATLAB to load the entire variable into memory. For very large variables, this load operation results in Out of Memory errors. Rather than using end, determine the extent of a variable with the size method, such as:
```
sizeMyVar = size(matObj,'myVar')
```
matfile does not support linear indexing. You must specify indices for all dimensions.
matfile does not support indexing into:
- Cells of cell arrays
- Fields of structs
- User-defined classes
- Sparse arrays
You cannot assign complex values to an indexed portion of a real array.
You cannot evaluate function handles using a MatFile object. For example, if your MAT-file contains function handle myfunc, the syntax matObj.myfunc() attempts to index into the function handle, and does not invoke the function.

Examples

Create myFile.mat in a temporary folder and save data to part of variable savedVar:

filename = fullfile(tempdir,'myFile.mat');
matObj = matfile(filename);
matObj.savedVar(81:100,81:100) = magic(20);

Load part of the data into variable loadVar:

loadVar = matObj.savedVar(85:94,85:94);

Load or save an entire variable by omitting the indices. For example, load variable topo from topography.mat:

filename = 'topography.mat';
matObj = matfile(filename);
topo = matObj.topo;

Determine the dimensions of a variable, and process one part of the variable at a time. In this case, calculate and store the average of each column of variable stocks in the demo file stocks.mat:

filename = 'stocks.mat';
matObj = matfile(filename);
[nrows, ncols] = size(matObj,'stocks');

avgs = zeros(1,ncols);
for idx = 1:ncols
    avgs(idx) = mean(matObj.stocks(:,idx));
end

By default, matfile only supports loading data from existing files. To enable saving, set Writable to true either during construction of the object,

filename = 'myFile.mat';
matObj = matfile(filename,'Writable',true);

or in a separate step, by setting Properties.Writable:

filename = 'myFile.mat';
matObj = matfile(filename);
matObj.Properties.Writable = true;

Search MATLAB Documentation
R2012a Documentation → MATLAB
View documentation for other releases	Learn more about MATLAB