1Misc(3)               User Contributed Perl Documentation              Misc(3)
2
3
4

NAME

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

DESCRIPTION

9       Some basic I/O functionality: FITS, tables, byte-swapping
10

SYNOPSIS

12        use PDL::IO::Misc;
13

FUNCTIONS

15       bswap2
16
17         Signature: (x(); )
18
19       Swaps pairs of bytes in argument x()
20
21       bswap4
22
23         Signature: (x(); )
24
25       Swaps quads of bytes in argument x()
26
27       bswap8
28
29         Signature: (x(); )
30
31       Swaps octets of bytes in argument x()
32
33       rcols()
34
35       Read ASCII whitespaced cols from a file into piddles and perl arrays
36       (also see "rgrep()").
37
38       There are two calling conventions - the old version, where a pattern
39       can be specified after the filename/handle, and the new version where
40       options are given as as hash reference. This reference can be given as
41       either the second or last argument.
42
43       The default behaviour is to ignore lines beginning with a # character
44       and lines that only consist of whitespace. Options exist to only read
45       from lines that match, or do not match, supplied patterns, and to set
46       the types of the created piddles.
47
48       Can take file name or *HANDLE, and if no columns are specified, all are
49       assumed. For the allowed types, see "Datatype_conversions" in
50       PDL::Core.
51
52       Options:
53
54       EXCLUDE or IGNORE - ignore lines matching this pattern (default
55       '/^#/').
56
57       INCLUDE or KEEP - only use lines which match this pattern (default '').
58
59       LINES - which line numbers to use. Line numbers start at 0 and the syn‐
60       tax is 'a:b:c' to use every c'th matching line between a and b (default
61       '').
62
63       DEFTYPE - default data type for stored data (if not specified, use the
64       type stored in $PDL::IO::Misc::deftype, which starts off as double).
65
66       TYPES - reference to an array of data types, one element for each col‐
67       umn to be read in.  Any missing columns use the DEFTYPE value (default
68       []).
69
70       PERLCOLS - an array of column numbers which are to be read into perl
71       arrays rather than piddles. References to these arrays are returned
72       after the requested piddles (default undef).
73
74         Usage:
75           ($x,$y,...) = rcols( *HANDLE⎪"filename", { EXCLUDE => '/^!/' },
76                                $col1, $col2, ... )
77           ($x,$y,...) = rcols( *HANDLE⎪"filename", $col1, $col2, ...,
78                                { EXCLUDE => '/^!/' } )
79           ($x,$y,...) = rcols( *HANDLE⎪"filename", "/foo/", $col1, $col2, ... )
80
81       e.g.,
82
83         $x      = PDL->rcols 'file1';
84         ($x,$y) = rcols *STDOUT;
85
86         # read in lines containing the string foo, where the first
87         # example also ignores lines that with a # character.
88         ($x,$y,$z) = rcols 'file2', 0,4,5, { INCLUDE => '/foo/' };
89         ($x,$y,$z) = rcols 'file2', 0,4,5,
90                        { INCLUDE => '/foo/', EXCLUDE => '' };
91
92         # ignore the first 27 lines of the file, reading in as ushort's
93         ($x,$y) = rcols 'file3', { LINES => '27:-1', DEFTYPE => ushort };
94         ($x,$y) = rcols 'file3',
95                     { LINES => '27:', TYPES => [ ushort, ushort ] };
96
97         # read in the first column as a perl array and the next two as piddles
98         ($x,$y,$name) = rcols 'file4', 1, 2, { PERLCOLS => [ 0 ] };
99         printf "Number of names read in = %d\n", 1 + $#$name;
100
101       Notes:
102
103       1. Quotes are required on patterns.
104
105       2. Columns are separated by whitespace by default, use
106       $PDL::IO::Misc::colsep to specify an alternate separator.
107
108       3. For PDL-2.003, the meaning of the 'c' value in the LINES option has
109       changed: it now only counts matching lines rather than all lines as in
110       previous versions of PDL.
111
112       4. LINES => '-1:0:3' may not work as you expect, since lines are
113       skipped when read in, then the whole array reversed.
114
115       wcols()
116
117       Write ASCII whitespaced cols into file from piddles efficiently.
118
119       If no columns are specified all are assumed.  Will optionally only
120       process lines matching a pattern.  Can take file name or *HANDLE, and
121       if no file/filehandle is given defaults to STDOUT.
122
123       Options:
124
125       HEADER - prints this string before the data. If the string is not ter‐
126       minated by a newline, one is added (default '').
127
128        Usage: wcols $piddle1, $piddle2,..., *HANDLE⎪"outfile", [\%options];
129
130       e.g.,
131
132         wcols $x, $y+2, 'foo.dat';
133         wcols $x, $y+2, *STDERR;
134         wcols $x, $y+2, '⎪wc';
135         wcols $a,$b,$c; # Orthogonal version of 'print $a,$b,$c' :-)
136
137         wcols "%10.3f", $a,$b; # Formatted
138         wcols "%10.3f %10.5g", $a,$b; # Individual column formatting
139
140         wcols $a,$b, { HEADER => "#   a   b" };
141
142       Note: columns are separated by whitespace by default, use
143       $PDL::IO::Misc::colsep to specify an alternate separator.
144
145       swcols()
146
147       generate string list from "sprintf" format specifier and a list of pid‐
148       dles
149
150       "swcols" takes an (optional) format specifier of the printf sort and a
151       list of 1d piddles as input. It returns a perl array (or array refer‐
152       ence if called in scalar context) where each element of the array is
153       the string generated by printing the corresponding element of the pid‐
154       dle(s) using the format specified. If no format is specified it uses
155       the default print format.
156
157        Usage: @str = swcols format, pdl1,pdl2,pdl3,...;
158         or
159               $str = swcols format, pdl1,pdl2,pdl3,...;
160
161       rgrep()
162
163       Read columns into piddles using full regexp pattern matching.
164
165       Options:
166
167       UNDEFINED: This option determines what will be done for undefined val‐
168       ues. For instance when reading a comma-separated file of the type
169       "1,2,,4" where the ",," indicates a missing value.
170
171       The default value is to assign $PDL::undefval to undefined values, but
172       if "UNDEFINED" is set this is used instead. This would normally be set
173       to a number, but if it is set to "Bad" and PDL is compiled with Bad‐
174       value support (see PDL::Bad) then undefined values are set to the
175       appropriate badvalue and the column is marked as bad.
176
177       DEFTYPE: Sets the default type of the columns - see the documentation
178       for
179        "rcols()"
180
181       TYPES:   A reference to a Perl array with types for each column - see
182       the documentation for "rcols()"
183
184       BUFFERSIZE: The number of lines to extend the piddle by. It might speed
185       up the reading a little bit by setting this to the number of lines in
186       the file, but in general "rasc()" is a better choice
187
188       Usage
189
190        ($x,$y,...) = rgrep(sub, *HANDLE⎪"filename")
191
192       e.g.
193
194        ($a,$b) = rgrep {/Foo (.*) Bar (.*) Mumble/} $file;
195
196       i.e. the vectors $a and $b get the progressive values of $1, $2 etc.
197
198       rdsa()
199
200       Read a FIGARO/NDF format file.
201
202       Requires non-PDL DSA module. Contact Frossie (frossie@jach.hawaii.edu)
203       Usage:
204
205        ([$xaxis],$data) = rdsa($file)
206
207        $a = rdsa 'file.sdf'
208
209       Not yet tested with PDL-1.9X versions
210
211       isbigendian()
212
213       Determine endianness of machine - returns 0 or 1 accordingly
214
215       rasc()
216
217       Simple function to slurp in ASCII numbers quite quickly, although error
218       handling is marginal (to nonexistent).
219
220         $pdl->rasc("filename"⎪FILEHANDLE [,$noElements]);
221             Where:
222               filename is the name of the ASCII file to read or
223                 open file handle
224               $noElements is the optional number of elements in the file to read.
225                   (If not present, all of the file will be read to fill up $pdl).
226               $pdl can be of type float or double for more precision.
227
228         #  (test.num is an ascii file with 20 numbers. One number per line.)
229         $in = PDL->null;
230         $num = 20;
231         $in->rasc('test.num',20);
232         $imm = zeroes(float,20,2);
233         $imm->rasc('test.num');
234
235       rcube
236
237       Read list of files directly into a large data cube (for efficiency)
238
239        $cube = rcube \&reader_function, @files;
240
241        $cube = rcube \&rfits, glob("*.fits");
242
243       This IO function allows direct reading of files into a large data cube,
244       Obviously one could use cat() but this is more memory efficient.
245
246       The reading function (e.g. rfits, readfraw) (passed as a reference) and
247       files are the arguments.
248
249       The cube is created as the same X,Y dims and datatype as the first
250       image specified. The Z dim is simply the number of images.
251

AUTHOR

253       Copyright (C) Karl Glazebrook 1997 and Craig DeForest 2001, 2003.  All
254       rights reserved. There is no warranty. You are allowed to redistribute
255       this software / documentation under certain conditions. For details,
256       see the file COPYING in the PDL distribution. If this file is separated
257       from the PDL distribution, the copyright notice should be included in
258       the file.
259
260
261
262perl v5.8.8                       2006-12-02                           Misc(3)