Documentation Center

  • Trial Software
  • Product Updates
我们为许可用户提供了部分翻译好的中文文档。您只需登录便可查阅这些文档

matfile

Access and change variables directly in MAT-files, without loading into memory

Syntax

  • m = matfile(filename) example
  • m = matfile(filename,'Writable',isWritable) example

Description

example

m = matfile(filename) creates a MAT-file object, m, connected to the MAT-file named filename. The object allows you to access and change variables directly in a MAT-file, without having to load the variables into memory.

The partial loading and saving that the matfile function provides requires less memory than the load and save commands, which always operate on entire variables.

example

m = matfile(filename,'Writable',isWritable) enables or disables write access to the file.

Examples

expand all

Load Entire Variable

Load variable topo from the example file, topography.mat.

Open the example MAT-file, topography.mat.

filename = 'topography.mat';
m = matfile(filename);

Read the variable topo from the MAT-file.

topo = m.topo;

MATLAB® loads the entire variable, topo, into the workspace.

Save Entire Variable to Existing MAT-file

Generate a 20-by-20 example array, x, and save it to a MAT-file called myFile.mat.

x = magic(20);
save('myFile.mat','x');

Create a MAT-file object connected to the existing MAT-file named myFile.mat. Enable write access to the MAT-file by setting Writable to true.

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

Generate a 15-by-15 example array, y.

y = magic(15);

Save y to the MAT-file. Specify the variable in the MAT-file using dot notation similar to accessing fields of structure arrays.

m.y = y;

MATLAB adds a variable named y to the file.

Display all variables stored in the MAT-file, myFile.mat.

whos('-file','myFile.mat')
  Name       Size            Bytes  Class     Attributes

  x         20x20             3200  double              
  y         15x15             1800  double  

Load and Save Parts of Variables

Access specific elements of a MAT-file variable.

Open a new MAT-file, myFile2.mat.

m = matfile('myFile2.mat');

Save a 20-by-20 example array to part of a variable, y, in myFile2.mat. Specify the variable in the MAT-file using dot notation similar to accessing fields of structure arrays.

m.y(81:100,81:100) = magic(20);

MATLAB inserts the 20-by-20 array into the elements of y specified by the indices (81:100,81:100).

Read a subset of array y into a new workspace variable, z.

z = m.y(85:94,85:94);

MATLAB reads the 10-by-10 subarray specified by the indices (85:94,85:94) from the MAT-file into workspace variable z.

Determine Size of Variables

Determine the size of a variable, and then calculate the average of each column.

Open the example MAT-file, stocks.mat.

filename = 'stocks.mat';
m = matfile(filename);

Determine the size of the variable, stocks, in stocks.mat.

[nrows,ncols] = size(m,'stocks');

Compute the average of each column of the variable stocks.

avgs = zeros(1,ncols);
for i = 1:ncols
    avgs(i) = mean(m.stocks(:,i));
end

Enable Write Access to MAT-file

Enable write access to the MAT-file, myFile.mat, by setting Writable to true when you open the MAT-file.

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

Alternatively, set Properties.Writable in a separate step after you open the MAT-file.

m.Properties.Writable = true;

Input Arguments

expand all

filename — Name of MAT-filestring

Name of a MAT-file, specified as a string. If the file is not in the current folder, filename must include a full or a relative path. If filename does not include an extension, then matfile appends .mat.

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

matfile only supports efficient partial loading and saving for MAT-files in Version 7.3 format. 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.

Example: 'myFile.mat'

Data Types: char

isWritable — Write access to MAT-filetrue | false

Write access to the MAT-file, specified as either true or false.

  • true enables saving to the MAT-file. If the file is read only, MATLAB changes the system permissions with the fileattrib function.

  • false disables saving to the MAT-file. MATLAB does not change the system permissions.

The default value is true for new files, and false for existing files.

Data Types: logical

Output Arguments

expand all

m — MAT-file objectmatlab.io.MatFile object

MAT-file object connected to a MAT-file.

Access variables in the MAT-file with dot notation similar to accessing fields of structure arrays:

  • To load part of variable varName from the MAT-file corresponding to m, call:

    loadedData = m.varName(indices);
  • To save part of variable varName to the MAT-file corresponding to m, call:

    m.varName(indices) = dataToSave;

When accessing variables, specify indices for all dimensions. Indices can be a single value, an equally spaced range of increasing values, or a colon (:); for example:

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

Limitations

  • matfile does not support linear indexing. You must specify indices for all dimensions.

  • matfile does not support indexing into:

    • Variables of tables

    • Cells of cell arrays

    • Fields of structure arrays

    • User-defined classes

    • Sparse arrays

  • You cannot assign complex values to an indexed portion of a real array.

  • You cannot evaluate function handles using the m output. For example, if your MAT-file contains function handle myfunc, the syntax m.myfunc() attempts to index into the function handle, and does not invoke the function.

  • Efficient partial loading and saving requires Version 7.3 MAT-files. To create a Version 7.3 MAT-file, call the save function with the '-v7.3' option. For example, to convert and existing MAT-file named durer.mat to Version 7.3, call:

    load('durer.mat');
    save('mycopy_durer.mat','-v7.3');

More About

expand all

Tips

  • 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, myVar, with the size method, such as:

    sizeMyVar = size(m,'myVar')

See Also

| | |

Was this topic helpful?