matlab.io.MatFile class

Package: matlab.io

Load and save parts of variables in MAT-files

Description

The matfile function constructs a matlab.io.MatFile object that corresponds to a MAT-File, such as

matObj = matfile('myFile.mat')

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.

Construction

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

Properties

Properties.Source

String that contains the fully qualified path to the file. Read only.

Properties.Writable

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

Methods

sizeArray dimensions
whoNames of variables in MAT-file
whosNames, sizes, and types of variables in MAT-file

You cannot access help for these methods using the help command. Find help on the methods from the command line using the doc command, such as doc matlab.io.MatFile/size.

Copy Semantics

Handle. To learn how handle classes affect copy operations, see Copying Objects in the MATLAB documentation.

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 example 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;

See Also

| | |

Was this topic helpful?