NAME

Data::MATFile - read MATLAB MAT-File data

SYNOPSIS

use Data::MATFile qw/read_matfile/;
my $matfile = read_matfile ('some.mat');
# Get a matrix named "xyz":
my $matrix = $matfile->{data}->{xyz};
# Get values from it
my $value = $matrix->{array}->[0][1];

DESCRIPTION

This module provides functions to access the MAT-File format used by MATLAB and Octave.

FUNCTIONS

read_matfile

my $matfile = read_matfile ('something.mat');

This reads the entire file, converts it into Perl variables, and returns the result as a hash reference.

Keys and values of returned hash

This section lists the keys and the corresponding values of the returned hash.

descriptive_text

$matfile->{descriptive_text} contains the "descriptive text" of the MAT-File. This is the information stored in the first 116 bytes of the file.

subsys_data_offset

$matfile->{subsys_data_offset} contains the subsystem data offset of the file, if it exists. This data is completely ignored by this module.

endian

$matfile->{endian} is set to 0 if the file has the same endian-ness as the local system, or 1 if the file has the opposite endian-ness.

data

$matfile->{data} contains the data elements of the MAT-File. It is a hash reference keyed by the names of the data elements. The structure of each element is described in "Structure of a data element" below.

Structure of a data element

The hash reference which represents each data element of the MAT-File contains the following fields.

name

The name of the matrix. This may be undefined, for example for the elements of a structure.

array

The array data itself. For the case of numeric data, this is stored as a multidimensional matrix. For the case of structure data, this is stored as a hash reference, with the hash keys being the field names, and the corresponding hash values being the fields.

The array is indexed Perl-style rather than MATLAB-style, so the indices run from 0 to n - 1, where n is the dimension of the matrix.

class

The class of the array, as a number, which is equal to the MATLAB constant. This can be converted into a string using "mx2word".

dimensions

The dimensions of the array, as an array reference. This will always be of dimension at least two. For example, a two-dimensional matrix with a single cell will have dimensions

$item->{dimensions} = [1, 1]

mx2word

my $class_name = mx2word ($class);

Convert a numeric MATLAB class identifier $class into its string equivalent. For example, "1" becomes "mxCELL_CLASS".

mi2word

my $type_name = mi2word ($type);

Convert a numeric MATLAB type identifier $type into its string equivalent. For example, "1" becomes "miINT8".

BUGS

This section documents the known deficiencies of the module relative to a perfect MAT-File reader.

No incremental parsing

There is no incremental parsing of the MAT-File, all parsing is done in one shot.

No subsystem data handling

This module does not handle the subsystem data offset. The value is preserved as the field "subsys_data_offset", but not used in any way.

No endian-ness reversing yet

This module does not support reverse-endian file format.

No writing

This module does not support writing MAT-Files.

Numeric only

This module only supports numeric matrices.

No complex

This module does not support complex matrices.

Version 5 only

This module only supports the "version 5" MAT-File format described under "REFERENCES".

Only matrices at top level

This module only reads matrices at the top level. It's not clear from the reference whether things other than matrices can occur at the top level, but if one does occur, this module prints a warning message and discards the data.

These problems partly exist because the creator of the module does not have examples of MAT-Files with these characteristics. Those wishing to see development of support for the above should contact the creator of the module and supply him with an example file demonstrating the correct binary format.

SEE ALSO

mat2json - This script, provided with the distribution, converts a MAT-File into JSON format.

https://github.com/jlapeyre/PDL-IO-Matlab - This Perl module converts between the PDL (Perl Data Language) format and MATLAB files via the Matio C library.

http://matio.sourceforge.net/ - The MAT File I/O Library. This is a C library for reading and writing MAT-Files.

REFERENCES

The MATLAB MAT-File Format is described in http://www.mathworks.com/help/pdf_doc/matlab/matfile_format.pdf.

Octave is documented at http://www.gnu.org/software/octave/doc/interpreter/index.html.

AUTHOR

Ben Bullock, <bkb@cpan.org>

COPYRIGHT & LICENCE

This package and associated files are copyright (C) 2012-2014 Ben Bullock.

You can use, copy, modify and redistribute this package and associated files under the Perl Artistic Licence or the GNU General Public Licence.