1FITS(3) User Contributed Perl Documentation FITS(3)
2
6 PDL::IO::FITS -- Simple FITS support for PDL
7
9 use PDL;
10 use PDL::IO::FITS;
11 $a = rfits('foo.fits'); # read a FITS file
13 $a->wfits('bar.fits'); # write a FITS file
14
16 This module provides basic FITS support for PDL, in the sense of
17 reading and writing whole FITS files. (For more complex operations,
18 such as prefiltering rows out of tables or performing operations on the
19 FITS file in-place on disk), you can use the Astro::FITS::CFITSIO
20 module that is available on CPAN.
21 Basic FITS image files are supported, along with BINTABLE and IMAGE
23 extensions. ASCII Table support is planned, as are the HEASARC
24 bintable extensions that are recommended in the 1999 FITS standard.
25 Table support is based on hashes and named columns, rather than the
27 less convenient (but slightly more congruent) technique of perl lists
28 of numbered columns.
29 The principle interface routines are "rfits" and "wfits", for reading
31 and writing respectively. FITS headers are returned as perl hashes or
32 (if the module is present) Astro::FITS::Header objects that are tied to
33 perl hashes. Astro::FITS::Header objects provide convenient access
34 through the tied hash interface, but also allow you to control the card
35 structure in more detail using a separate method interface; see the
36 Astro::FITS::Header documentation for details.
37
39 Copyright (C) Karl Glazebrook, Craig DeForest, and Doug Burke,
40 1997-2004. There is no warranty. You are allowed to redistribute
41 and/or modify this software under certain conditions. For details, see
42 the file COPYING in the PDL distribution. If this file is separated
43 from the PDL distribution, the copyright notice should be pasted into
44 in this file.
45
47 rfits()
48 Simple piddle FITS reader.
49 $pdl = rfits('file.fits'); # Read a simple FITS image
51 Suffix magic:
53 $pdl = rfits('file.fits.gz'); # Read a file with gunzip(1)
55 $pdl = rfits('file.fits.Z'); # Read a file with uncompress(1)
56 $pdl = rfits('file.fits[2]'); # Read 2nd extension
58 $pdl = rfits('file.fits.gz[3]'); # Read 3rd extension
59 @pdls = rfits('file.fits'); # Read primary data and extensions
60 $hdr = rfits('file.fits',{data=>0}); # Options hash changes behavior
62 In list context, "rfits" reads the primary image and all possible
64 extensions, returning them in the same order that they occurred in the
65 file. In scalar context, the default is to read the primary HDU. One
66 can read other HDU's by using the [n] syntax, the second one is [1].
67 Currently recognized extensions are IMAGE and BINTABLE. (See the
68 addendum on EXTENSIONS for details).
69 "rfits" accepts several options that may be passed in as a hash ref if
71 desired:
72 bscale (default=1)
74 Determines whether the data are linearly scaled using the
75 BSCALE/BZERO keywords in the FITS header. To read in the exact data
76 values in the file, set this to 0.
77 data (default=1)
79 Determines whether to read the data, or just the header. If you set
80 this to 0, you will get back the FITS header rather than the data
81 themselves. (Note that the header is normally returned as the "hdr"
82 field of the returned PDL; this causes it to be returned as a hash
83 ref directly.)
84 hdrcpy (default=0)
86 Determines whether the hdrcpy flag is set in the returned PDL.
87 Setting the flag will cause an explicit deep copy of the header
88 whenever you use the returned PDL in an arithmetic or slicing
89 operation. That is useful in many circumstances but also causes a
90 hit in speed.
91 FITS image headers are stored in the output PDL and can be retrieved
93 with hdr or gethdr. The hdrcpy flag of the PDL is set so that the
94 header is copied to derived piddles by default. (This is inefficient
95 if you are planning to do lots of small operations on the data; clear
96 the flag with "->hcpy(0)" or via the options hash if that's the case.)
97 The header is a hash whose keys are the keywords in the FITS header.
99 If you have the "Astro::FITS::Header" module installed, the header is
100 actually a tied hash to a FITS header object, which can give you more
101 control over card order, comment fields, and variable types. (see
102 Astro::FITS::Header for details).
103 The header keywords are converted to uppercase per the FITS standard.
105 Access is case-insensitive on the perl side, provided that
106 Astro::FITS::Header is installed.
107 If Astro::FITS::Header is not installed, then a built-in legacy parser
109 is used to generate the header hash. Keyword-associated comments in
110 the headers are stored under the hash key "<keyword>_COMMENT>". All
111 HISTORY cards in the header are collected into a single multiline
112 string stored in the "HISTORY" key. All COMMENT cards are similarly
113 collected under the "COMMENT" key.
114 BSCALE/BZERO
116 If the BSCALE and/or BZERO keywords are set, they are applied to the
118 image before it is returned. The returned PDL is promoted as necessary
119 to contain the multiplied values, and the BSCALE and BZERO keywords are
120 deleted from the header for clarity. If you don't want this type of
121 processing, set 'bscale=>0' in the options hash.
122 EXTENSIONS
124 Sometimes a FITS file contains only extensions and a stub header in the
126 first header/data unit ("primary HDU"). In scalar context, you
127 normally only get back the primary HDU -- but in this special case, you
128 get back the first extension HDU. You can force a read of the primary
129 HDU by adding a '[0]' suffix to the file name.
130 BINTABLE EXTENSIONS
132 Binary tables are handled. Currently only the following PDL datatypes
134 are supported: byte, short, ushort, long, float, and double. At present
135 ushort() data is written as a long rather than as a short with
136 TSCAL/ZERO; this may change.
137 The return value for a binary table is a hash ref containing the names
139 of the columns in the table (in UPPER CASE as per the FITS standard).
140 Each element of the hash contains a PDL (for numerical values) or a
141 perl list (for string values). The PDL's 0th dimension runs across
142 rows; the 1st dimension runs across the repeat index within the row
143 (for rows with more than one value).
144 Thus, if your table contains a column named "FOO" with type "5D", the
146 expression
147 $a->{FOO}->((2))
149 returns a 5-element double-precision PDL containing the values of FOO
151 from the third row of the table.
152 The header of the table itself is parsed as with a normal FITS HDU, and
154 is returned in the element 'hdr' of the returned hash. You can use
155 that to preserve the original column order or access the table at a low
156 level, if you like.
157 Scaling and zero-point adjustment are performed as with BSCALE/BZERO:
159 the appropriate keywords are deleted from the as-returned header. To
160 avoid this behavior, set 'bscale=>0' in the options hash.
161 As appropriate, TSCAL/ZERO and TUNIT are copied into each column-PDL's
163 header as BSCALE/BZERO and BUNIT.
164 The main hash also contains the element 'tbl', which is set to 'binary'
166 to distinguish it from an ASCII table.
167 Because different columns in the table might have identical names in a
169 FITS file, the binary table reader practices collision avoidance. If
170 you have multiple columns named "FOO", then the first one encountered
171 (numerically) gets the name "FOO", the next one gets "FOO_1", and the
172 next "FOO_2", etc. The appropriate TTYPEn fields in the header are
173 changed to match the renamed column fields.
174 Columns with no name are assigned the name "COL_<n>", where <n> starts
176 at 1 and increments for each no-name column found.
177 If a FITS file contains the "BLANK" keyword (and has "BITPIX > 0"), the
179 piddle will have its bad flag set, and those elements which equal the
180 "BLANK" value will be set bad. For "BITPIX < 0", any NaN's are
181 converted to bad (if necessary).
182 rfitshdr()
184 Read only the header of a FITS file or an extension within it.
185 This is syntactic sugar for the "data=>0" option to rfits.
187 See rfits for details on header handling. rfitshdr() runs the same
189 code to read the header, but returns it rather than reading in a data
190 structure as well.
191 wfits()
193 Simple PDL FITS writer
194 wfits $pdl, 'filename.fits', [$BITPIX];
196 wfits $hash, 'filename.fits', [$OPTIONS];
197 $pdl->wfits('foo.fits',-32);
198 Suffix magic:
200 # Automatically compress through pipe to gzip
202 wfits $pdl, 'filename.fits.gz';
203 # Automatically compress through pipe to compress
204 wfits $pdl, 'filename.fits.Z';
205 · Ordinary (PDL) data handling:
207 If the first argument is a PDL, then the PDL is written out as an
209 ordinary FITS file with a single Header/Data Unit of data.
210 $BITPIX is then optional and coerces the output data type according
212 to the standard FITS convention for the BITPIX field (with positive
213 values representing integer types and negative values representing
214 floating-point types).
215 If $pdl has a FITS header attached to it (actually, any hash that
217 contains a "SIMPLE=>T" keyword), then that FITS header is written
218 out to the file. The image dimension tags are adjusted to the
219 actual dataset. If there's a mismatch between the dimensions of the
220 data and the dimensions in the FITS header, then the header gets
221 corrected and a warning is printed.
222 If $pdl is a slice of another PDL with a FITS header already present
224 (and header copying enabled), then you must be careful. "wfits"
225 will remove any extraneous "NAXISn" keywords (per the FITS
226 standard), and also remove the other keywords associated with that
227 axis: "CTYPEn", "CRPIXn", "CRVALn", "CDELTn", and "CROTAn". This
228 may cause confusion if the slice is NOT out of the last dimension:
229 "wfits($a(:,(0),:),'file.fits');" and you would be best off
230 adjusting the header yourself before calling "wfits".
231 · Table handling:
233 If you feed in a hash ref instead of a PDL, then the hash ref is
235 written out as a binary table extension. The hash ref keys are
236 treated as column names, and their values are treated as the data to
237 be put in each column.
238 For numeric information, the hash values should contain PDLs. The
240 0th dim of the PDL runs across rows, and higher dims are written as
241 multi-value entries in the table (e.g. a 7x5 PDL will yield a single
242 named column with 7 rows and 5 numerical entries per row, in a
243 binary table). ASCII tables only allow one entry per column in each
244 row, so if you plan to write an ASCII table then all of the values
245 of $hash should have at most one dim.
246 All of the column dims must agree in the threading sense. That is to
248 say, the 0th dimension of all of the values of $hash should be the
249 same (indicating that all columns have the same number of rows). As
250 an exception, if the 0th dim of any of the values is 1, or if that
251 value is a PDL scalar (with 0 dims), then that value is "threaded"
252 over -- copied into all rows.
253 Data dimensions higher than 2 are not possible in ordinary FITS
255 tables, so dims higher than 1 are clumped. (e.g. a 7x5x3 PDL will
256 yield a single named column with 7 rows and 15 numerical entries per
257 row). If $PDL::Verbose is set, this condition causes a warning
258 message to be printed. [There is a multidim extension that is not
259 yet implemented but should be].
260 Non-PDL Perl scalars are treated as strings, even if they contain
262 numerical values. For example, a list ref containing 7 values is
263 treated as 7 rows containing one string each. There is no such
264 thing as a multi-string column in FITS tables, so any nonscalar
265 values in the list are stringified before being written. For
266 example, if you pass in a perl list of 7 PDLs, each PDL will be
267 stringified before being written, just as if you printed it to the
268 screen. This is probably not what you want -- you should use glue
269 to connect the separate PDLs into a single one. (e.g.
270 "$a->glue(1,$b,$c)->mv(1,0)")
271 The column names are case-insensitive, but by convention the keys of
273 $hash should normally be ALL CAPS, containing only digits, capital
274 letters, hyphens, and underscores. If you include other characters,
275 then case is smashed to ALL CAPS, whitespace is converted to
276 underscores, and unrecognized characters are ignored -- so if you
277 include the key "Au Purity (%)", it will be written to the file as a
278 column that is named "AU_PURITY". Since this is not guaranteed to
279 produce unique column names, subsequent columns by the same name are
280 disambiguated by the addition of numbers.
281 Two special keys, 'hdr' and 'tbl', can contain meta-information
283 about the type of table you want to write. You may override them by
284 including an $OPTIONS hash with a 'hdr' and/or 'tbl' key.
285 The 'tbl' key, if it exists, must contain either 'ASCII' or 'binary'
287 (case-insensitive), indicating whether to write an ascii or binary
288 table. The default is binary. [ASCII table writing is planned but
289 does not yet exist].
290 You can specify the format of the table quite specifically with the
292 'hdr' key or option field. If it exists, then the 'hdr' key should
293 contain fields appropriate to the table extension being used. Any
294 field information that you don't specify will be filled in
295 automatically, so (for example) you can specify that a particular
296 column name goes in a particular position, but allow "wfits" to
297 arrange the other columns in the usual alphabetical order into any
298 unused slots that you leave behind. The "TFORMn", "TFIELDS",
299 "PCOUNT", "GCOUNT", "NAXIS", and "NAXISn" keywords are ignored:
300 their values are calculated based on the hash that you supply. Any
301 other fields are passed into the final FITS header verbatim.
302 As an example, the following
304 $a = long(1,2,4);
306 $b = double(1,2,4);
307 wfits { 'COLA'=>$a, 'COLB'=>$b }, "table1.fits";
308 will create a binary FITS table called table1.fits which contains
310 two columns called "COLA" and "COLB". The order of the columns is
311 controlled by setting the "TTYPEn" keywords in the header array, so
312 $h = { 'TTYPE1'=>'Y', 'TTYPE2'=>'X' };
314 wfits { 'X'=>$a, 'Y'=>$b, hdr=>$h }, "table2.fits";
315 creates table2.fits where the first column is called "Y" and the
317 second column is "X".
318 · multi-value handling
320 If you feed in a perl list rather than a PDL or a hash, then each
322 element is written out as a separate HDU in the FITS file. Each
323 element of the list must be a PDL or a hash. [This is not
324 implemented yet but should be soon!]
325 · DEVEL NOTES
327 ASCII tables are not yet handled but should be.
329 Binary tables currently only handle one vector (up to 1-D array) per
331 table entry; the standard allows more, and should be fully
332 implemented. This means that PDL::Complex piddles currently can not
333 be written to disk.
334 Handling multidim arrays implies that perl multidim lists should
336 also be handled.
337 For integer types (ie "BITPIX > 0"), the "BLANK" keyword is set to the
339 bad value. For floating-point types, the bad value is converted to NaN
340 (if necessary) before writing.
341 fits_field_cmp
343 fits_field_cmp
344 Sorting comparison routine that makes proper sense of the digits at the
346 end of some FITS header fields. Sort your hash keys using
347 "fits_field_cmp" and you will get (e.g.) your "TTYPE" fields in the
348 correct order even if there are 140 of them.
349 This is a standard kludgey perl comparison sub -- it uses the magical
351 $a and $b variables, rather than normal argument passing.
352 _rows()
354 Return the number of rows in a variable for table entry
355 You feed in a PDL or a list ref, and you get back the 0th dimension.
357 _prep_table()
359 Accept a hash ref containing a table, and return a header describing
360 the table and a string to be written out as the table, or barf.
361 You can indicate whether the table should be binary or ascii. The
363 default is binary; it can be overridden by the "tbl" field of the hash
364 (if present) or by parameter.
365perl v5.12.3 2009-10-24 FITS(3)