Data::MATFile - read MATLAB MAT-File data
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];
This documents Data::MATFile version 0.04 corresponding to git commit 11e02bd58bd534675225c99b6ef15db86f03b846 released on Tue Feb 21 10:27:20 2017 +0900.
This module provides functions to access the MAT-File format used by MATLAB and Octave.
my $matfile = read_matfile ('something.mat');
This reads the entire file, converts it into Perl variables, and returns the result as a hash reference.
This section lists the keys and the corresponding values of the returned hash.
$matfile->{descriptive_text} contains the "descriptive text" of the MAT-File. This is the information stored in the first 116 bytes of the file.
$matfile->{descriptive_text}
$matfile->{subsys_data_offset} contains the subsystem data offset of the file, if it exists. This data is completely ignored by this module.
$matfile->{subsys_data_offset}
$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.
$matfile->{endian}
$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.
$matfile->{data}
The hash reference which represents each data element of the MAT-File contains the following fields.
The name of the matrix. This may be undefined, for example for the elements of a structure.
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.
The class of the array, as a number, which is equal to the MATLAB constant. This can be converted into a string using "mx2word".
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]
my $class_name = mx2word ($class);
Convert a numeric MATLAB class identifier $class into its string equivalent. For example, "1" becomes "mxCELL_CLASS".
$class
my $type_name = mi2word ($type);
Convert a numeric MATLAB type identifier $type into its string equivalent. For example, "1" becomes "miINT8".
$type
This section documents the known deficiencies of the module relative to a perfect MAT-File reader.
There is no incremental parsing of the MAT-File, all parsing is done in one shot.
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.
This module does not support reverse-endian file format.
This module does not support writing MAT-Files.
This module only supports numeric matrices.
This module does not support complex matrices.
This module only supports the "version 5" MAT-File format described under "REFERENCES".
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.
mat2json - This script, provided with the distribution, converts a MAT-File into JSON format.
PDL::IO::Matlab - This Perl module converts between the PDL (Perl Data Language) format and MATLAB files via the Matio C library (see below).
http://matio.sourceforge.net/ - The MAT File I/O Library which is used by the above Perl module. This is a C library for reading and writing MAT-Files.
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.
Since I (Ben Bullock) don't use the MATFile format at the moment, this module is available for adoption. People who are interested in improving this module and taking over maintenance should email the current maintainer at the email address below.
Ben Bullock, <bkb@cpan.org>
This package and associated files are copyright (C) 2012-2017 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.
To install Data::MATFile, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Data::MATFile
CPAN shell
perl -MCPAN -e shell install Data::MATFile
For more information on module installation, please visit the detailed CPAN module installation guide.