MatFile - Access and change variables in MAT-file without loading file into memory - MATLAB (original) (raw)

Access and change variables in MAT-file without loading file into memory

Description

Use a MAT-file object to access and change variables in a MAT-file without loading the file into memory. You can load or save parts of variables. Partial loading and saving of variables using a MAT-file object requires less memory than the load and save commands.

Creation

Syntax

Description

`matObj` = matfile([filename](#mw%5Fbd7a1619-1edf-4550-a4cc-ae0c894872a9)) creates a matlab.io.MatFile object connected to the MAT-file specified byfilename.

The MAT-file object allows you to access and change variables directly in a MAT-file, without having to load the variables into memory.

example

`matObj` = matfile([filename](#mw%5Fbd7a1619-1edf-4550-a4cc-ae0c894872a9),"Writable",[isWritable](#mw%5F28531250-df03-4465-afe1-148aff9e6d39)) enables or disables write access to the file. Specify isWritable astrue or false.

example

Input Arguments

expand all

filename — Name of MAT-file

string scalar | character vector

Name of MAT-file, specified as a string scalar or character vector.

If filename has no extension (that is, does not end with a period followed by text), matfile searches for a file whose name is filename with .mat appended to it. If the file does not exist, matfile creates a Version 7.3 MAT-file on the first assignment to a variable.

Depending on the location of your MAT-file, filename can be in one of these forms.

isWritable — Enable write access

true | false

Enable write access, specified as true or false. The default value is true for new files, false for existing files.

• true — Enable write access to the MAT-file from the MAT-file object. If the file is read-only, change the system permissions by using the fileattrib function.
• false — Disable write access to the MAT-file from the MAT-file object.

Properties

expand all

Access MAT-File Object Properties

Access MAT-file object properties using the syntax _`ObjectName`_.Properties._`PropertyName`_, where _`PropertyName`_ is the name of a property. For example, you can access the source file path of the MAT-file connected to the MAT-file object mObj using the syntax mObj.Properties.Source.

Source — File path

character vector

File path, returned as character vector containing the fully qualified path to the MAT-file.

Writable — Write access status

true | false

Write access status of the MAT-file object, returned as either true or false.

• true — MAT-file object has write access to the MAT-file.
• false — MAT-file object has read-only access to the MAT-file.

Object Functions

Examples

collapse all

Create MAT-file Object

Create a MAT-file object for your file. The matfile function constructs a matlab.io.MatFile object that corresponds to a MAT-File.

matObj = matfile('myFile.mat')

Enable Write Access to MAT-file

Enable write access to the MAT-file, myFile.mat, when you create the object.

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

Alternatively, you can enable write access after you create the MAT-file object by setting the Writable property.

m.Properties.Writable = true;

Load Entire Variable

Open the sample MAT-file topography.mat. Read the variable topo from the file using the MAT-file object. MATLAB® loads the entire variable, topo, into the workspace.

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

Save Entire Variable to Existing MAT-file

Create a MAT-file containing an array and then add another array to the file using the MAT-file object.

Create a MAT file by generating a 20-by-20 array, x, and saving it to myFile.mat.

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

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

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

Generate another 15-by-15 array, y. Save y to the MAT-file using the MAT-file object. Specify the variable in the MAT-file using dot notation similar to accessing fields of structure arrays. 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 parts of a variable in a MAT-file using the MAT-file object. For example, you can save data to a subset of a variable in a MAT-file or read a subset of a variable into the MATLAB® workspace.

Save data to a subset of a variable y in the file myFile2.mat using the MAT-file object. First, create the MAT-file object m.

m = matfile('myFile2.mat');

Next, create and save an array to part of the variable y. Specify the variable in the MAT-file using dot notation similar to accessing fields of structure arrays. MATLAB® inserts the 20-by-20 array into the elements of y specified by the indices (81:100,81:100).

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

Read a subset of array y into a new workspace variable, z. 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

Resize Variable

Change the size of a variable in a MAT-file.

Create a variable and save it to a MAT-file.

x = magic(20); save myFile.mat x whos -file myFile.mat

Name Size Bytes Class Attributes

x 20x20 3200 double

Open the MAT-file and resize the variable.

m = matfile("myFile.mat",Writable=true); m.x = magic(30); whos -file myFile.mat

Name Size Bytes Class Attributes

x 30x30 7200 double

Resize the variable again, this time making it smaller than it originally was.

m.x = magic(10); whos -file myFile.mat

Name Size Bytes Class Attributes

x 10x10 800 double

Limitations

• When accessing parts of variables in MAT-files by indexing:
  • Linear indexing is not supported. You must specify indices for all dimensions.
  • Assigning complex values to indexed portions of a real array is not supported.
• For sparse arrays in a MAT-file, the MAT-file object:
  • Supports reading a subset of a sparse array by indexing.
  • Does not support writing (assigning values) to a subset of a sparse array by indexing.
• The MAT-file object does not support indexing into:
  • Variables of tables
  • Cells of cell arrays
  • String arrays
  • datetime arrays
  • duration arrays
  • Fields of structure arrays
  • User-defined classes
• The MAT-file object does not support evaluating 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.
• When saving a handle object, MATLAB saves a copy of the object, not a copy of the handle. Therefore, modifying the object via its handle in the workspace from which the object was saved does not modify the saved handle object.

Tips

• 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 an existing MAT-file named durer.mat to Version 7.3, call:
  load('durer.mat');
  save('mycopy_durer.mat','-v7.3');
• 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:
  sizeMyVar = size(matObj,'myVar')

Version History

Introduced in R2011b

expand all

R2023b: Work with remote MAT-files

You can work with MAT-files stored in remote locations, such as Amazon S3 and Windows Azure Blob Storage.