Provided by: libpdl-io-matlab-perl_0.005-2build2_amd64 bug

NAME

       PDL::IO::Matlab -- Read and write Matlab format data files.

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 OO interface are
       provided.

       Only real, multi-dimensional arrays corresponding to PDL data types are supported.
       Compression is currently only supported when reading.

       See the section "CAVEATS" for important information on potential problems when using this
       module.

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');

FUNCTIONS

       The functional interface.

   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".

   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'.

   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.

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'.

   close
       Usage

       $mat->close;

       Close matlab file and free memory associated with $mat.

   read_next
       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.

   read_all
       Usage

        my @pdls = $mat->read_all;

       Read all remaining pdls from file associated with object $mat.

   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
           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.

       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.

   get_filename
       Usage

        $mat->get_filename

       Return name of 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'.

   print_all_var_info
       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.)

ACCESSOR METHODS

       The following are additional accessor methods for the matlab file objects PDL::IO::Matlab.

       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

CAVEATS

   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.

       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.

       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.

       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.

   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.

AUTHOR

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

       The matio library was written by Christopher C. Hulbert.

LICENSE AND COPYRIGHT

       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.