Matlab(3pm)

📦
version 0.006 · 6 versions
, in debian trixie, ubuntu questing

💖 Matlab 💖

okay so bestie, this is PDL::IO::Matlab from the User Contributed Perl Documentation collection — it's the module that lets you read and write Matlab format data files, and honestly? it's giving ✨interoperability✨.

🌸 NAME 🌸

PDL::IO::Matlab — Read and write Matlab format data files. that's it, that's the whole vibe 🎀

🦋 DESCRIPTION 🦋

okay so this module hands you routines to read and write pdls to and from data files in Matlab formats. it does this by using the matio C library, no cap. and you get both a functional interface AND an OO interface, because she's versatile like that 💅

only real, multi-dimensional arrays corresponding to PDL data types are supported, jsyk. compression for both reading and writing? supported. slay. 💖

bestie please go read the "CAVEATS" section, there's important info in there about potential problems when you use this module. like, actually important. don't skip it 🙈

✨ SYNOPSIS ✨

use PDL;
use PDL::IO::Matlab qw( matlab_read matlab_write matlab_print_info);

# write two pdls in matlab 5 format
matlab_write('file.dat', $x, $y);

# read an array of piddles
# from file in matlab 4, 5, or 7.3 format.
my @pdls =  matlab_read('file.dat');

# write pdl in matlab 7.3 format.
matlab_write('file.dat', 'MAT73', $x);

matlab_print_info('file.dat');

like look at that. gorgeous. no notes. 🌈

👑 FUNCTIONS 👑

this is the functional interface, the chill one, the one you text when you don't wanna deal with objects.

🍓 matlab_read

Usage

Return all arrays in $filename:

@pdls = matlab_read($filename);
@pdls = matlab_read($filename, {OPTIONS});

Return first array in $filename:

$x = matlab_read($filename);

Do not automatically convert 1xn and nx1 arrays to 1-d arrays:

@pdls = matlab_read($filename, { onedr => 0 } );

Reads all data in the file $filename. Formats 4, 5, and 7.3 are supported. Options are passed to "new". periodt 💅

🧚 matlab_write

Usage

matlab_write($filename,$x1,$x2,...);
matlab_write($filename,$format,$x1,$x2,...);

Automatically convert n element, 1-d piddles to 1xn matlab variables:

matlab_write($filename,$x1,$x2,..., {onedw => 1} );

Automatically convert to nx1 matlab variables:

matlab_write($filename,$x1,$x2,..., {onedw => 2} );

Use zlib compression:

matlab_write($filename,$x1,$x2,..., {compress => 1} );

This method writes pdls $x1, $x2,.... If present, $format must be either 'MAT5' or 'MAT73'. those are your only two options bestie, don't try anything else 💀

💜 matlab_print_info

Usage

# print names and dimensions of variables.
matlab_print_info($filename);
# also print a small amount of the data.
matlab_print_info($filename, { data => 1 });
# This does the same thing.
matlab_print_info($filename,  data => 1 );

Print information about the contents of the matlab file $filename, including the name, dimension and class type of the variables. it's the "let me peek inside real quick" function 🫶

💅 METHODS 💅

🌟 new

Usage

# open for writing
$mat = PDL::IO::Matlab->new('file.dat', '>', {format => 'MAT5'});

# default format is MAT5
$mat = PDL::IO::Matlab->new('file.dat', '>');

# may use 'w' or '>'
$mat = PDL::IO::Matlab->new('file.dat', 'w');

# supply header
$mat = PDL::IO::Matlab->new('file.dat', '>', { header => 'some text'} );

# read-write  with rw or <>
$mat = PDL::IO::Matlab->new('file.dat', 'rw');

# open for reading
$mat = PDL::IO::Matlab->new('file.dat', '<');

Options

  • format — Either 'MAT5' or 'MAT73'.
  • compress — Either 1 for yes, or 0 for no.
  • header — A header (a string) to write into the file.
  • namekey — A hash key that will be used to store the matlab name for a variable read from a file in the header of a piddle. The default value is 'NAME'. Thus, the name can be accessed via $pdl->hdr->{NAME}.
  • varbasew — The base of the default matlab variable name that will be written in the matlab file along with each piddle. An integer will be appended to the base name. This integer is initialized to zero and is incremented after writing each variable.

The option "compress" enables zlib compression if the zlib library is available and if the data file format is 'MAT5'. iykyk 🔥

🌸 close

Usage

$mat->close;

Close matlab file and free memory associated with $mat. bye bestie, memory reclaimed 💖

Usage

my $x = $mat->read_next;
print "End of file\n" unless ref($x);

my ($err,$x) = $mat->read_next;
print "End of file\n" if $err;

Read one pdl from file associated with object $mat. one at a time, we're being patient ✨

🎀 read_all

Usage

my @pdls = $mat->read_all;

Read all remaining pdls from file associated with object $mat. the "just give me everything" option, iconic 👑

⭐ write

Usage

$x2->hdr->{NAME} = 'variablename';

$mat->write($x1,$x2,...);

$mat->write($x1,$x2,...,{OPTIONS});

Append pdls to open file associated with $mat.

If a piddle has a matlab name stored in the header it will be used as the matlab name written to the file with this piddle. The key is in $pdl->{namekey}, with default value 'NAME'. If the name is not in the piddle's header, then a default value will be used.

Options

  • onedw — In order to write a file that is compatible with Matlab and Octave, onedw must be either 1 or 2. If onedw is 1 then a 1-d pdl of length n is written as a as an nx1 pdl (a 1xn matlab variable). If onedw is 2 then the output piddle is 1xn and the matlab variable nx1. If onedw is zero (the default), then the 1-d pdl is written as a 1-d piddle. In the last case, Octave will print an error and fail to read the variable. 😭 so like, pick 1 or 2 if you care about Octave, fr fr.
  • compress — If compress is 1 then zlib compression is used, if the library is available and if the format is 'MAT5'.

🌈 rewind

Usage

$mat->rewind

Reset pointer to the head of the file. back to the start, we go 💫

🍓 get_filename

Usage

$mat->get_filename

Return name of file associated with $mat.

💜 get_header

Usage

$mat->get_header

Return the header string from the matlab data file associated with $mat.

🧚 get_format

Usage

$mat->get_format

Return matlab data file format for file associated with $mat. One of 'MAT4', 'MAT5', or 'MAT73'. three formats, three moods 💅

Usage

$mat->print_all_var_info;

# also print a small amount of data from each variable.
$mat->print_all_var_info( data => 1 );

Print a summary of all data in the file associated with $mat (starting from the next unread variable.) it's like a lil recap episode for your data 🎬

👑 ACCESSOR METHODS 👑

The following are additional accessor methods for the matlab file objects PDL::IO::Matlab. getters and setters, the whole squad, all here:

get_handle set_handle get_mode set_mode get_filename set_filename get_format set_format get_varbasew set_varbasew get_onedw set_onedw get_onedr set_onedr get_namekey set_namekey get_wvarnum set_wvarnum get_compress set_compress

😭 CAVEATS 😭

okay bestie this is the part where we sit down and have a serious little chat. grab a snack. 🍓

💀 complicating factors

There are two complicating factors when using matlab files with PDL. First, matlab does not support one-dimensional vectors. Thus, a 1-d pdl must be represented as either a 1 x n of a n x 1 matlab variable. Second, matlab stores matrices in column-major order, while pdl stores them in row-major order. two whole problems. we're dealing with them.

🌸 one-dimensional pdls

You can write 1-d pdls to a file with this module. This module can then read the file. But, Octave will fail to read the file and print an error message. See "write" for how this is handled.

so like. your own module can read it back. Octave cannot. it will simply ✨perish✨. plan accordingly 🙈

🦋 column- vs. row major

Data written by Octave (PDL) will be read by PDL (Octave) with indices transposed. On the todo list is an option to physically or logically transpose the data on reading and writing. it's on the list bestie, it's on the list 💜

🎀 Octave requires distinct matlab variable names

With this module, you may write more than one variable, each with the same name, (the matlab name; not the pdl identifier, or variable, name), to a file in MAT5 format. This module is then able to read all pdls from this file. But, Octave, when reading this file, will overwrite all but the last occurrence of the variable with the last occurrence. See the method "write".

Trying to write two pdls with the same matlab variable name in MAT73 format will cause an error. like, an actual error. not a vibe. 💀

⭐ other missing features, bugs

When trying to read an unsupported matlab data type from a file, this module will throw an error. Supporting other data types or optionally skipping them is on the todo list.

Random access of variables in a file is on the todo list. The underlying matio library supports this.

This module is currently built with some hardcoded data from a PDL installation, that may contain platform-specific (linux) features. It may fail to build or function correctly when used on other platforms.

yeah so, hardcoded linux-ish stuff. portability is lowkey not guaranteed here. just so you know. 🫶

💖 AUTHOR 💖

John Lapeyre, "<jlapeyre at cpan.org>"

The matio library was written by Christopher C. Hulbert.

Copyright 2012 John Lapeyre.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

The matio library included here is Copyright 2011 Christopher C. Hulbert. All rights reserved. See the file matio-1.5/COPYING in the source distribution of this module.

and that's the whole thing bestie!! 🌈✨ this page came to you courtesy of perl v5.40.1, dated 2025-03-07, and it's the Matlab(3pm) page. go forth and read those .dat files, you absolute icon 👑💅🦋

📦 where this page comes from