Misc(3) User Contributed Perl Documentation Misc(3)NAMEPDL::IO::Misc - misc IO routines for PDL
DESCRIPTION
Some basic I/O functionality: FITS, tables, byte-swapping
SYNOPSIS
use PDL::IO::Misc;
FUNCTIONS
bswap2
Signature: (x(); )
Swaps pairs of bytes in argument x()
bswap4
Signature: (x(); )
Swaps quads of bytes in argument x()
bswap8
Signature: (x(); )
Swaps octets of bytes in argument x()rcols()
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
PDL::Core.
Options:
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).
Usage:
($x,$y,...) = rcols( *HANDLE|"filename", { EXCLUDE => '/^!/' },
$col1, $col2, ... )
($x,$y,...) = rcols( *HANDLE|"filename", $col1, $col2, ...,
{ EXCLUDE => '/^!/' } )
($x,$y,...) = rcols( *HANDLE|"filename", "/foo/", $col1, $col2, ... )
e.g.,
$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;
Notes:
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.
wcols()
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.
Options:
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];
e.g.,
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.
swcols()
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,...;
or
$str = swcols format, pdl1,pdl2,pdl3,...;
rgrep()
Read columns into piddles using full regexp pattern matching.
Options:
UNDEFINED: This option determines what will be done for undefined
values. For instance when reading a comma-separated file of the type
"1,2,,4" where the ",," indicates a missing value.
The default value is to assign $PDL::undefval to undefined values, but
if "UNDEFINED" is set this is used instead. This would normally be set
to a number, but if it is set to "Bad" and PDL is compiled with
Badvalue support (see "" in PDL::Bad) then undefined values are set to
the appropriate badvalue and the column is marked as bad.
DEFTYPE: Sets the default type of the columns - see the documentation
for
"rcols()"
TYPES: A reference to a Perl array with types for each column - see
the documentation for "rcols()"
BUFFERSIZE: The number of lines to extend the piddle by. It might speed
up the reading a little bit by setting this to the number of lines in
the file, but in general "rasc()" is a better choice
Usage
($x,$y,...) = rgrep(sub, *HANDLE|"filename")
e.g.
($a,$b) = rgrep {/Foo (.*) Bar (.*) Mumble/} $file;
i.e. the vectors $a and $b get the progressive values of $1, $2 etc.
rdsa()
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
isbigendian()
Determine endianness of machine - returns 0 or 1 accordingly
rasc()
Simple function to slurp in ASCII numbers quite quickly, although error
handling is marginal (to nonexistent).
$pdl->rasc("filename"|FILEHANDLE [,$noElements]);
Where:
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;
$in->rasc('test.num',20);
$imm = zeroes(float,20,2);
$imm->rasc('test.num');
rcube
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.
AUTHOR
Copyright (C) Karl Glazebrook 1997 and Craig DeForest 2001, 2003. 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.
perl v5.10.0 2008-08-29 Misc(3)
