.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Matlab 3pm"
.TH Matlab 3pm "2014-08-16" "perl v5.20.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
PDL::IO::Matlab \-\- Read and write Matlab format data files.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides routines to read and write pdls to and from
data files in Matlab formats. The module uses the matio C library.
Both functional and \s-1OO\s0 interface are provided.
.PP
Only real, multi-dimensional arrays corresponding to \s-1PDL\s0 data types are supported.
Compression is currently only supported when reading.
.PP
See the section \*(L"\s-1CAVEATS\*(R"\s0 for important information on potential problems when using
this module.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& use PDL;
\& use PDL::IO::Matlab qw( matlab_read matlab_write matlab_print_info);
\&
\& # write two pdls in matlab 5 format
\& matlab_write(\*(Aqfile.dat\*(Aq, $x, $y);
\&
\& # read an array of piddles 
\& # from file in matlab 4, 5, or 7.3 format.
\& my @pdls =  matlab_read(\*(Aqfile.dat\*(Aq);
\& 
\& # write pdl in matlab 7.3 format.
\& matlab_write(\*(Aqfile.dat\*(Aq, \*(AqMAT73\*(Aq, $x);
\&
\& matlab_print_info(\*(Aqfile.dat\*(Aq);
.Ve
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
The functional interface.
.SS "\fBmatlab_read\fP"
.IX Subsection "matlab_read"
\fIUsage\fR
.IX Subsection "Usage"
.PP
Return all arrays in \f(CW$filename\fR
.PP
.Vb 2
\& @pdls = matlab_read($filename);
\& @pdls = matlab_read($filename, {OPTIONS});
.Ve
.PP
Return first array in \f(CW$filename\fR
.PP
.Vb 1
\& $x = matlab_read($filename);
.Ve
.PP
Do not automatically convert \f(CW\*(C`1xn\*(C'\fR and \f(CW\*(C`nx1\*(C'\fR arrays
to 1\-d arrays.
.PP
.Vb 1
\& @pdls = matlab_read($filename, { onedr => 0 } );
.Ve
.PP
Reads all data in the file \f(CW$filename\fR.
Formats 4, 5, and 7.3 are supported. Options
are passed to "\fBnew\fR".
.SS "\fBmatlab_write\fP"
.IX Subsection "matlab_write"
\fIUsage\fR
.IX Subsection "Usage"
.PP
.Vb 2
\& matlab_write($filename,$x1,$x2,...);
\& matlab_write($filename,$format,$x1,$x2,...);
.Ve
.PP
Automatically convert \f(CW\*(C`n\*(C'\fR element, 1\-d piddles to \f(CW\*(C`1xn\*(C'\fR matlab
variables.
.PP
.Vb 1
\& matlab_write($filename,$x1,$x2,..., {onedw => 1} );
.Ve
.PP
Automatically convert to \f(CW\*(C`nx1\*(C'\fR matlab
variables.
.PP
.Vb 1
\& matlab_write($filename,$x1,$x2,..., {onedw => 2} );
.Ve
.PP
Use zlib compression
.PP
.Vb 1
\& matlab_write($filename,$x1,$x2,..., {compress => 1} );
.Ve
.PP
This method writes pdls \f(CW$x1\fR, \f(CW$x2\fR,.... If present, \f(CW$format\fR
must be either \f(CW\*(AqMAT5\*(Aq\fR or \f(CW\*(AqMAT73\*(Aq\fR.
.SS "\fBmatlab_print_info\fP"
.IX Subsection "matlab_print_info"
\fIUsage\fR
.IX Subsection "Usage"
.PP
.Vb 6
\& # 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 );
.Ve
.PP
Print information about the contents of the matlab file \f(CW$filename\fR,
including the name, dimension and class type of the variables.
.SH "METHODS"
.IX Header "METHODS"
.SS "\fBnew\fP"
.IX Subsection "new"
\fIUsage\fR
.IX Subsection "Usage"
.PP
.Vb 2
\& # open for writing
\& $mat = PDL::IO::Matlab\->new(\*(Aqfile.dat\*(Aq, \*(Aq>\*(Aq, {format => \*(AqMAT5\*(Aq});
\&
\& # default format is MAT5
\& $mat = PDL::IO::Matlab\->new(\*(Aqfile.dat\*(Aq, \*(Aq>\*(Aq);
\&
\& # may use \*(Aqw\*(Aq or \*(Aq>\*(Aq
\& $mat = PDL::IO::Matlab\->new(\*(Aqfile.dat\*(Aq, \*(Aqw\*(Aq);
\&
\& # supply header
\& $mat = PDL::IO::Matlab\->new(\*(Aqfile.dat\*(Aq, \*(Aq>\*(Aq, { header => \*(Aqsome text\*(Aq} );
\&
\& # read\-write  with rw or <>
\& $mat = PDL::IO::Matlab\->new(\*(Aqfile.dat\*(Aq, \*(Aqrw\*(Aq);  
\&
\& # open for reading
\& $mat = PDL::IO::Matlab\->new(\*(Aqfile.dat\*(Aq, \*(Aq<\*(Aq);
.Ve
.PP
\fIOptions\fR
.IX Subsection "Options"
.IP "format" 4
.IX Item "format"
Either \f(CW\*(AqMAT5\*(Aq\fR or \f(CW\*(AqMAT73\*(Aq\fR.
.IP "compress" 4
.IX Item "compress"
Either \f(CW1\fR for yes, or \f(CW0\fR for no.
.IP "header" 4
.IX Item "header"
A header (a string) to write into the file.
.IP "namekey" 4
.IX Item "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 '\s-1NAME\s0'. Thus, the name can be accessed
via \f(CW\*(C`$pdl\->hdr\->{NAME}\*(C'\fR.
.IP "varbasew" 4
.IX Item "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.
.PP
The option \f(CW\*(C`compress\*(C'\fR enables zlib compression if the zlib library
is available and if the data file format is \f(CW\*(AqMAT5\*(Aq\fR.
.SS "\fBclose\fP"
.IX Subsection "close"
\fIUsage\fR
.IX Subsection "Usage"
.PP
\&\f(CW$mat\fR\->close;
.PP
Close matlab file and free memory associated with \f(CW$mat\fR.
.SS "\fBread_next\fP"
.IX Subsection "read_next"
\fIUsage\fR
.IX Subsection "Usage"
.PP
.Vb 2
\& my $x = $mat\->read_next;
\& print "End of file\en" unless ref($x);
\&
\& my ($err,$x) = $mat\->read_next;
\& print "End of file\en" if $err;
.Ve
.PP
Read one pdl from file associated with object \f(CW$mat\fR.
.SS "\fBread_all\fP"
.IX Subsection "read_all"
\fIUsage\fR
.IX Subsection "Usage"
.PP
.Vb 1
\& my @pdls = $mat\->read_all;
.Ve
.PP
Read all remaining pdls from file associated with object \f(CW$mat\fR.
.SS "\fBwrite\fP"
.IX Subsection "write"
\fIUsage\fR
.IX Subsection "Usage"
.PP
.Vb 1
\& $x2\->hdr\->{NAME} = \*(Aqvariablename\*(Aq;
\&
\& $mat\->write($x1,$x2,...);
\&
\& $mat\->write($x1,$x2,...,{OPTIONS});
.Ve
.PP
Append pdls to open file associated with \f(CW$mat\fR.
.PP
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 \f(CW\*(C`$pdl\->{namekey}\*(C'\fR,
with default value \f(CW\*(AqNAME\*(Aq\fR. If the name is not in
the piddle's header, then a default value will be used.
.PP
\fIOptions\fR
.IX Subsection "Options"
.IP "onedw" 4
.IX Item "onedw"
If \f(CW\*(C`onedw\*(C'\fR is \f(CW1\fR then a 1\-d pdl of length n is written as a
as an \f(CW\*(C`nx1\*(C'\fR pdl (a \f(CW\*(C`1xn\*(C'\fR matlab variable). If \f(CW\*(C`onedw\*(C'\fR is \f(CW2\fR
then the output piddle is \f(CW\*(C`1xn\*(C'\fR and the matlab variable \f(CW\*(C`nx1\*(C'\fR.
If \f(CW\*(C`onedw\*(C'\fR 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.
.IP "compress" 4
.IX Item "compress"
If \f(CW\*(C`compress\*(C'\fR is \f(CW1\fR then zlib compression is used, if the library
is available and if the format is \f(CW\*(AqMAT5\*(Aq\fR.
.SS "\fBrewind\fP"
.IX Subsection "rewind"
\fIUsage\fR
.IX Subsection "Usage"
.PP
.Vb 1
\& $mat\->rewind
.Ve
.PP
Reset pointer to the head of the file.
.SS "\fBget_filename\fP"
.IX Subsection "get_filename"
\fIUsage\fR
.IX Subsection "Usage"
.PP
.Vb 1
\& $mat\->get_filename
.Ve
.PP
Return name of file associated with \f(CW$mat\fR.
.SS "\fBget_format\fP"
.IX Subsection "get_format"
\fIUsage\fR
.IX Subsection "Usage"
.PP
.Vb 1
\& $mat\->get_format
.Ve
.PP
Return matlab data file format for file associated with
\&\f(CW$mat\fR. One of \f(CW\*(AqMAT4\*(Aq\fR, \f(CW\*(AqMAT5\*(Aq\fR, or \f(CW\*(AqMAT73\*(Aq\fR.
.SS "\fBprint_all_var_info\fP"
.IX Subsection "print_all_var_info"
\fIUsage\fR
.IX Subsection "Usage"
.PP
.Vb 1
\& $mat\->print_all_var_info;
\&
\& # also print a small amount of data from each variable.
\& $mat\->print_all_var_info( data => 1 );
.Ve
.PP
Print a summary of all data in the file associated
with \f(CW$mat\fR (starting from the next unread variable.)
.SH "ACCESSOR METHODS"
.IX Header "ACCESSOR METHODS"
The following are additional accessor methods for the matlab file objects
PDL::IO::Matlab.
.PP
get_handle set_handle get_mode set_mode get_filename set_filename get_format set_format get_header set_header get_varbasew set_varbasew get_onedw set_onedw get_onedr set_onedr get_namekey set_namekey get_wvarnum set_wvarnum get_compress set_compress
.SH "CAVEATS"
.IX Header "CAVEATS"
.SS "complicating factors"
.IX Subsection "complicating factors"
There are two complicating factors when using matlab files with \s-1PDL.\s0
First, matlab does not support one-dimensional vectors. Thus, a 1\-d pdl
must be represented as either a \f(CW\*(C`1 x n\*(C'\fR of a \f(CW\*(C`n x 1\*(C'\fR matlab variable. Second,
matlab stores matrices in column-major order, while pdl stores them
in row-major order.
.IP "\fBone-dimensional pdls\fR" 4
.IX Item "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 "\fBwrite\fR" for how this is handled.
.IP "\fBcolumn\- vs. row major\fR" 4
.IX Item "column- vs. row major"
Data written by Octave (\s-1PDL\s0) will be read by \s-1PDL \s0(Octave) with indices transposed.
On the todo list is an option to physically or logically transpose the data on
reading and writing.
.IP "\fBOctave requires distinct matlab variable names\fR" 4
.IX Item "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 \s-1MAT5\s0
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 "\fBwrite\fR".
.Sp
Trying to write two pdls with the same matlab variable name in \s-1MAT73\s0 format will cause
an error.
.SS "other missing features, bugs"
.IX Subsection "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.
.PP
Random access of variables in a file is on the todo list. The underlying \fBmatio\fR
library supports this.
.PP
This module is currently built with some hardcoded data from a \s-1PDL\s0 installation, that
may contain platform-specific (linux) features. It may fail to
build or function correctly when used on other platforms.
.SH "AUTHOR"
.IX Header "AUTHOR"
John Lapeyre, \f(CW\*(C`<jlapeyre at cpan.org>\*(C'\fR
.PP
The matio library was written by Christopher C. Hulbert.
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright 2012 John Lapeyre.
.PP
This program is free software; you can redistribute it and/or modify it
under the terms of either: the \s-1GNU\s0 General Public License as published
by the Free Software Foundation; or the Artistic License.
.PP
See http://dev.perl.org/licenses/ for more information.
.PP
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.