Matlab Files

MatlabĀ® is a commercial technical computing environment originally focused primarily on linear algebra computations. MatlabĀ®'s binary file format can store a wide variety of objects, from simple vectors and matrices to rich objects and structures.

The MatlabFile and MatlabStream classes in the Numerics.NET.Data.Matlab namespace support reading from files in format version 7.0 or earlier. File is format version 7.3 or later use the HDF5 format, which is not supported at this time.

Reading Matlab files

The MatlabFile class contains static methods for reading one or multiple objects from a file in .rdata format.

Reading single objects

The ReadVector method reads a vector from a Matlab file. It takes one type argument that is required: the element type of the vector to read. The method takes one actual argument. This may be a string containing the path to the file, or a Stream that has been opened for reading. If a filename is given, it may be the path to a local file, or the uri of a resource on the Internet. This method returns the first matrix found in the file.

Optionally, a second string argument may be passed that specifies the name of the Matlab variable. This method reads objects from the file until an object with the specified name is found, and returns it as a matrix, if possible.

The optional last argument specifies whether the element type of the stored vector should match the specified element type exactly. The default is false, which means that the read operation will succeed as long as the stored element type can be cast to the requested element type.

The ReadMatrix method reads a matrix from the file. It has the same arguments and overloads as the ReadVector. The element type must be supplied as a generic type argument. The actual arguments are the path to the file or resource or the stream to read from, optionally the name of the variable, and optionally whether the element type should match exactly.

C#
var vector1 = MatlabFile.ReadVector<double>(@"c:\vector.mat");
var matrix1 = MatlabFile.ReadMatrix<double>("http://www.example.com/matrix.mat", "mat");

Reading multiple objects

The ReadVectors method reads multiple vectors from the file. It takes one type argument that is required: the element type of the vector to read. The first is a string containing the path to the file, or a Stream that has been opened for reading. If a filename is given, it may be the path to a local file, or the uri of a resource on the Internet. The second argument is a sequence of strings containing the names of the variables containing the vectors. This method returns a dictionary that maps the names of the variables to vectors.

The optional last argument specifies whether the element type of the stored vectors should match the specified element type exactly. The default is false, which means that the read operation will succeed as long as the stored element type can be cast to the requested element type. The ReadAllVectors returns a dictionary with all the vectors in the file.

The ReadMatrices method reads matrices from the file. It has the same arguments and overloads as the ReadVectors. The element type must be supplied as a generic type argument. The actual arguments are the path to the file or resource or the stream to read from, a sequence of variable names containing the matrices, and optionally whether the element type should match exactly. The ReadAllMatrices returns a dictionary with all the matrices in the file.

Using Matlab Data Streams

Matlab data streams are implemented by the MatlabStream class. This class has no constructors. Instead, use one of the methods of the MatlabFile class. Streams can be opened for reading.

Opening files for reading

The Open(String) method opens a file or stream for reading. The only argument is a string or a stream. If it is a string, it is the path to the file that should be opened, or the URI of a network or Internet resource. If it is a stream, then it specifies the data stream that the objects should be read from.

The methods for reading objects from streams are similar to those of the MatlabFile class, but without the argument that specifies the source.

Reading single objects

The ReadVector method reads a vector from a data file. It takes one type argument that is required: the element type of the vector to read. Optionally, a string argument may be passed that specifies the name of the Matlab variable. This method reads objects from the file until an object with the specified name is found, and returns it as a vector, if possible. If an object with the name was read previously, it is returned as a vector without reading more from the stream.

The optional last argument specifies whether the element type of the stored vector should match the specified element type exactly. The default is false, which means that the read operation will succeed as long as the stored element type can be cast to the requested element type.

The ReadMatrix method reads a matrix from the file. It has the same arguments and overloads as the ReadVector. The element type must be supplied as a generic type argument. The actual arguments are both optional: the name of the variable, and whether the element type should match exactly.

C#
using (var s2 = MatlabFile.Open(@"c:\sample.mat"))
{
    var vector1 = s2.ReadVector<double>();
    var matrix1 = s2.ReadMatrix<double>("mat");
}

Reading multiple objects

The ReadVectors<T> method multiple vectors from the file. It takes one type argument that is required: the element type of the vector to read. The first argument is a sequence of names of the variables in the file that contain the vectors. The optional second argument specifies whether the element type of the stored vectors should match the specified element type exactly. The default is false, which means that the read operation will succeed as long as the stored element type can be cast to the requested element type. The ReadAllVectors<T> returns a dictionary with all the vectors in the file.

The ReadMatrices<T> method reads matrices from the file. It has the same arguments and overloads as the ReadVectors<T>. The element type must be supplied as a generic type argument. The actual arguments are a sequence of variable names containing the matrices, and optionally whether the element type should match exactly. The ReadAllMatrices<T> returns a dictionary with all the matrices in the file.