Save and Load Parts of Variables in MAT Files

You can use the matfile function to save and load parts of variables directly in MATLAB® without loading them into memory. The primary advantage of using the matfile function over the load or save functions is that you can process parts of very large data sets that are otherwise too large to fit in memory. When working with these large variables, read and write as much data into memory as possible at a time. Otherwise, repeated file access can negatively impact the performance of your code.

Save and Load Using the matfile Function

Open Live Script

This example shows how to load, modify, and save part of a variable in an existing MAT file using the matfile function.

Create a Version 7.3 MAT file with two variables, A and B.

A = rand(5);
B = magic(10);
save example.mat A B -v7.3
clear A B

Construct a MatFile object from the MAT file, example.mat. The matfile function creates a MatFile object that corresponds to the MAT file. By default, the matfile function permits loading only from existing MAT files.

exampleObject = matfile("example.mat");

To enable saving, call matfile with the Writable name-value argument.

exampleObject = matfile("example.mat",Writable=true);

Alternatively, construct the object and set Properties.Writable in separate steps.

exampleObject = matfile("example.mat");
exampleObject.Properties.Writable = true;

Load the first row of B from example.mat into variable firstRowB and modify the data. When you index into objects associated with Version 7.3 MAT files, MATLAB® loads only the part of the variable that you specify.

firstRowB = exampleObject.B(1,:);
firstRowB = 2*firstRowB;

Update the values in the first row of variable B in example.mat using the values stored in firstRowB.

exampleObject.B(1,:) = firstRowB;

For very large files, the best practice is to read and write as much data into memory as possible at a time. Otherwise, repeated file access negatively impacts the performance of your code. For example, suppose that your file contains many rows and columns, and that loading a single row requires most of the available memory. Rather than updating one element at a time, update each row.

[nrowsB,ncolsB] = size(exampleObject,'B');
for row = 1:nrowsB
  exampleObject.B(row,:) = row * exampleObject.B(row,:);
end

If memory is not a concern, you can update the entire contents of a variable at a time.

exampleObject.B = 10 * exampleObject.B;

Alternatively, update a variable by calling the save function with the -append option. The -append option requests that the save function replace only the specified variable, B, and leave other variables in the file intact. This method always requires that you load and save the entire variable.

load("example.mat","B")
B(1,:) = 2 * B(1,:);
save("example.mat","-append","B")

Add a variable to the file using the MatFile object.

exampleObject.C = magic(8);

You also can add the variable by calling the save function with the -append option.

C = magic(8);
save("example.mat","-append","C")
clear C

Load Parts of Variables Dynamically

Open Live Script

This example shows how to access parts of variables from a MAT file dynamically. This technique is useful when working with MAT files whose variable names are not all known.

Construct a MatFile object that corresponds to the sample file topography.mat. Use the who function to store the variable names from the file in the cell array varlist.

exampleObject = matfile("topography.mat");
varlist = who(exampleObject)
varlist = 3×1 cell
    {'topo'    }
    {'topomap1'}
    {'topomap2'}

The second and third variables, topomap1 and topomap2, are both three-column matrices containing colormap data. Load the colormap data from the third column of each of these two variables into a field of a structure S. For each field, specify a field name that is the original variable name prepended by "colormap_". Then access the data in each variable as properties of exampleObject. Because varName is a variable, enclose it in parentheses.

for index = 2:3
    varName = varlist{index};
    S.("colormap_"+varName) = exampleObject.(varName)(:,3);
end

View the contents of the structure. The structure has two fields, colormap_topomap1 and colormap_topomap2, and each contains a column vector.

S
S = struct with fields:
    colormap_topomap1: [64×1 double]
    colormap_topomap2: [128×1 double]

Avoid Inadvertently Loading Entire Variables

Open Live Script

When you do not know the size of a large variable in a MAT file and want to load only parts of that variable at a time, avoid using the end keyword and avoid referring to the variable with syntax of the form matObj.varName without indexing. Both of these actions temporarily load the entire contents of the variable into memory. For very large variables, loading takes a long time and can generate an Out of Memory error. Instead, use the size method for MatFile objects to find the size of the variable, and then index into the desired part of the variable.

For example, create a MatFile object for a random 100-by-100 matrix B.

B = rand(100);
save example.mat B -v7.3
clear B
exampleObject = matfile("example.mat");

Suppose you do not know the size of this variable but want to load its final column into your workspace. To avoid loading the entire variable into memory, first use the size method for MatFile objects (instead of using the size function) to get the size of the variable.

[nrows,ncols] = size(exampleObject,'B');

Then, use ncols to index into the variable in order to load the final column of B into your workspace without loading the entire variable into memory.

lastColB = exampleObject.B(:,ncols);

Partial Loading and Saving Requires Version 7.3 MAT Files

Any load or save operation that uses a MatFile object associated with a Version 7 or earlier MAT file temporarily loads the entire variable into memory.

Use the matfile function to create files in Version 7.3 format. For example, this code creates a MAT file that supports partial loading and saving.

newfileObject = matfile("newfile.mat");

However, by default, the save function creates Version 7 MAT files. Convert existing MAT files to Version 7.3 by calling the save function with the -v7.3 option, such as:

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

To change your settings to save new files in Version 7.3 format, go to the Home tab, and in the Environment section, click Settings. Select MATLAB > General > MAT and FIG Files and then select from the available options.

See Also

| |

Topics