PDL::IO::Misc - misc IO routines for PDL


PDL::IO::Misc - misc IO routines for PDL


A mixture of basic I/O functionality


 use PDL::IO::Misc;



Simple piddle FITS reader.

  $pdl = rfits('file.fits');

Suffix magic:

  # Automatically uncompress via gunzip pipe
  $pdl = rfits('file.fits.gz');
  # Automatically uncompress via uncompress pipe
  $pdl = rfits('file.fits.Z');
  $pdl = rfits('file.fits[2]'); # Read HDU extension #2
  $pdl = rfits('file.fits.gz[3]'); # Read HDU extension #3

The default is to read the primary HDU. One can read other HDU's by using the [n] syntax, the second one is [1]. This works as long as they are IMAGE extensions - this module does not do FITS tables!

FITS Headers are stored in the piddle and can be retrived with $a->gethdr. The hdrcpy flag of the piddle is set so that the header is copied to new piddles.

This header is a reference to a hash where the hash keys are the keywords in the FITS header. If you have the ``Astro::FITS::Header'' module installed, the header is actually a tied-hash to a FITS header object. The tied-hash interface is designed so that it emulates the legacy PDL support: keyword/value pairs are accessed as with an ordinary hash. But for more precise control of the FITS header you can access the underlying Astro::FITS::Header object using the perl ``tied'' builtin (see the Astro::FITS::Header manpage for details).

Keywords are converted to uppercase; this is part of the FITS standard; but access is case-insensitive on the perl side, provided that Astro::FITS::Header is intalled.

Comments in headers are stored as $$h{COMMENT}{<Keyword>} where $h is the header retrieved with $a->gethdr. History entries in the header are stored as $$h{HISTORY}, which is an anonymous array for each HISTORY entry in the header.


Piddle FITS writer

  wfits $pdl, 'filename.fits', [$BITPIX];

Suffix magic:

  # Automatically compress through pipe to gzip
  wfits $pdl, 'filename.fits.gz';
  # Automatically compress through pipe to compress 
  wfits $pdl, 'filename.fits.Z';

$BITPIX is optional and coerces the output format.

Header handling:

If C<$pdl> has a FITS header attached to it (actually, any hash that
contains a SIMPLE=>T keyword), then that FITS header is written out to the
file.  The image dimension tags are adjusted to the actual dataset.
If there's a mismatch between the dimensions of the data and the 
dimensions in the FITS header, then the header gets corrected and a 
warning is printed.


Read ASCII whitespaced cols from a file into piddles and perl arrays (also see rgrep()).

There are two calling conventions - the old version, where a pattern can be specified after the filename/handle, and the new version where options are given as as hash reference. This reference can be given as either the second or last argument.

The default behaviour is to ignore lines beginning with a # character and lines that only consist of whitespace. Options exist to only read from lines that match, or do not match, supplied patterns, and to set the types of the created piddles.

Can take file name or *HANDLE, and if no columns are specified, all are assumed. For the allowed types, see Datatype_conversions in the PDL::Core manpage.


EXCLUDE or IGNORE - ignore lines matching this pattern (default '/^#/').

INCLUDE or KEEP - only use lines which match this pattern (default '').

LINES - which line numbers to use. Line numbers start at 0 and the syntax is 'a:b:c' to use every c'th matching line between a and b (default '').

DEFTYPE - default data type for stored data (if not specified, use the type stored in $PDL::IO::Misc::deftype, which starts off as double).

TYPES - reference to an array of data types, one element for each column to be read in. Any missing columns use the DEFTYPE value (default []).

PERLCOLS - an array of column numbers which are to be read into perl arrays rather than piddles. References to these arrays are returned after the requested piddles (default undef).

    ($x,$y,...) = rcols( *HANDLE|"filename", { EXCLUDE => '/^!/' }, 
                         $col1, $col2, ... )
    ($x,$y,...) = rcols( *HANDLE|"filename", $col1, $col2, ..., 
                         { EXCLUDE => '/^!/' } )
    ($x,$y,...) = rcols( *HANDLE|"filename", "/foo/", $col1, $col2, ... )

  $x      = PDL->rcols 'file1';
  ($x,$y) = rcols *STDOUT;
  # read in lines containing the string foo, where the first
  # example also ignores lines that with a # character.
  ($x,$y,$z) = rcols 'file2', 0,4,5, { INCLUDE => '/foo/' };
  ($x,$y,$z) = rcols 'file2', 0,4,5, 
                 { INCLUDE => '/foo/', EXCLUDE => '' };
  # ignore the first 27 lines of the file, reading in as ushort's
  ($x,$y) = rcols 'file3', { LINES => '27:-1', DEFTYPE => ushort };
  ($x,$y) = rcols 'file3', 
              { LINES => '27:', TYPES => [ ushort, ushort ] };
  # read in the first column as a perl array and the next two as piddles
  ($x,$y,$name) = rcols 'file4', 1, 2, { PERLCOLS => [ 0 ] };
  printf "Number of names read in = %d\n", 1 + $#$name;


1. Quotes are required on patterns.

2. Columns are separated by whitespace by default, use $PDL::IO::Misc::colsep to specify an alternate separator.

3. For PDL-2.003, the meaning of the 'c' value in the LINES option has changed: it now only counts matching lines rather than all lines as in previous versions of PDL.

4. LINES => '-1:0:3' may not work as you expect, since lines are skipped when read in, then the whole array reversed.


Write ASCII whitespaced cols into file from piddles efficiently.

If no columns are specified all are assumed. Will optionally only process lines matching a pattern. Can take file name or *HANDLE, and if no file/filehandle is given defaults to STDOUT.


HEADER - prints this string before the data. If the string is not terminated by a newline, one is added (default '').

 Usage: wcols $piddle1, $piddle2,..., *HANDLE|"outfile", [\%options];


  wcols $x, $y+2, 'foo.dat';
  wcols $x, $y+2, *STDERR;
  wcols $x, $y+2, '|wc';
  wcols $a,$b,$c; # Orthogonal version of 'print $a,$b,$c' :-)
  wcols "%10.3f", $a,$b; # Formatted
  wcols "%10.3f %10.5g", $a,$b; # Individual column formatting
  wcols $a,$b, { HEADER => "#   a   b" };

Note: columns are separated by whitespace by default, use $PDL::IO::Misc::colsep to specify an alternate separator.


generate string list from sprintf format specifier and a list of piddles

swcols takes an (optional) format specifier of the printf sort and a list of 1d piddles as input. It returns a perl array (or array reference if called in scalar context) where each element of the array is the string generated by printing the corresponding element of the piddle(s) using the format specified. If no format is specified it uses the default print format.

 Usage: @str = swcols format, pdl1,pdl2,pdl3,...;
        $str = swcols format, pdl1,pdl2,pdl3,...;


Read columns into piddles using full regexp pattern matching.


 ($x,$y,...) = rgrep(sub, *HANDLE|"filename")


 ($a,$b) = rgrep {/Foo (.*) Bar (.*) Mumble/} $file;

i.e. the vectors $a and $b get the progressive values of $1, $2 etc.


Read a FIGARO/NDF format file.

Requires non-PDL DSA module. Contact Frossie (frossie@jach.hawaii.edu) Usage:

 ([$xaxis],$data) = rdsa($file)
 $a = rdsa 'file.sdf'

Not yet tested with PDL-1.9X versions


Determine endianness of machine - returns 0 or 1 accordingly


Simple function to slurp in ASCII numbers quite quickly, although error handling is marginal (to nonexistent).

  $pdl->rasc("filename"|FILEHANDLE [,$noElements]);
        filename is the name of the ASCII file to read or
          open file handle
        $noElements is the optional number of elements in the file to read.
            (If not present, all of the file will be read to fill up $pdl).
        $pdl can be of type float or double for more precision.
  #  (test.num is an ascii file with 20 numbers. One number per line.)
  $in = PDL->null;
  $num = 20;
  $imm = zeroes(float,20,2);


Read list of files directly into a large data cube (for efficiency)

 $cube = rcube \&reader_function, @files;
 $cube = rcube \&rfits, glob("*.fits");

This IO function allows direct reading of files into a large data cube, Obviously one could use cat() but this is more memory efficient.

The reading function (e.g. rfits, readfraw) (passed as a reference) and files are the arguments.

The cube is created as the same X,Y dims and datatype as the first image specified. The Z dim is simply the number of images.


  Signature: (x(); )

Swaps pairs of bytes in argument x()


  Signature: (x(); )

Swaps quads of bytes in argument x()


  Signature: (x(); )

Swaps octets of bytes in argument x()


Copyright (C) Karl Glazebrook 1997. All rights reserved. There is no warranty. You are allowed to redistribute this software / documentation under certain conditions. For details, see the file COPYING in the PDL distribution. If this file is separated from the PDL distribution, the copyright notice should be included in the file.

 PDL::IO::Misc - misc IO routines for PDL