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

NAME

6       PDL::IO::FITS -- Simple FITS support for PDL
7

SYNOPSIS

9        use PDL;
10        use PDL::IO::FITS;
11
12        $x = rfits('foo.fits');          # read a FITS file
13        $x->wfits('bar.fits');           # write a FITS file
14

DESCRIPTION

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
22       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
26       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
30       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

AUTHOR

39       Copyright (C) Karl Glazebrook, Craig DeForest, and Doug Burke,
40       1997-2010.  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

FUNCTIONS

47   rfits()
48       Simple ndarray FITS reader.
49
50         $pdl = rfits('file.fits');   # Read a simple FITS image
51
52       Suffix magic:
53
54         $pdl = rfits('file.fits.gz'); # Read a file with gunzip(1)
55         $pdl = rfits('file.fits.Z');  # Read a file with uncompress(1)
56
57         $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
61       Tilde expansion:
62
63         #expand leading ~ to home directory (using glob())
64         $pdl = rfits '~/filename.fits';
65
66         $hdr = rfits('file.fits',{data=>0});  # Options hash changes behavior
67
68       In list context, "rfits" reads the primary image and all possible
69       extensions, returning them in the same order that they occurred in the
70       file -- except that, by default, the primary HDU is skipped if it
71       contains no data.  In scalar context, the default is to read the first
72       HDU that contains data. One can read other HDU's by using the [n]
73       syntax.  Using the [0] syntax forces a read of the first HDU,
74       regardless of whether it contains data or no.  Currently recognized
75       extensions are IMAGE and BINTABLE.  (See the addendum on EXTENSIONS for
76       details).
77
78       "rfits" accepts several options that may be passed in as a hash ref if
79       desired:
80
81       bscale (default=1)
82          Determines whether the data are linearly scaled using the
83          BSCALE/BZERO keywords in the FITS header.  To read in the exact data
84          values in the file, set this to 0.
85
86       data (default=1)
87          Determines whether to read the data, or just the header.  If you set
88          this to 0, you will get back the FITS header rather than the data
89          themselves.  (Note that the header is normally returned as the "hdr"
90          field of the returned PDL; this causes it to be returned as a hash
91          ref directly.)
92
93       hdrcpy (default=0)
94          Determines whether the hdrcpy flag is set in the returned PDL.
95          Setting the flag will cause an explicit deep copy of the header
96          whenever you use the returned PDL in an arithmetic or slicing
97          operation.  That is useful in many circumstances but also causes a
98          hit in speed.  When two or more PDLs with hdrcpy set are used in an
99          expression, the result gets the header of the first PDL in the
100          expression.  See hdrcpy for an example.
101
102       expand (default=1)
103          Determines whether auto-expansion of tile-compressed images should
104          happen.  Tile-compressed images are transmitted as binary tables
105          with particular fields ("ZIMAGE") set.  Leaving this alone does what
106          you want most of the time, unpacking such images transparently and
107          returning the data and header as if they were part of a normal IMAGE
108          extension.  Setting "expand" to 0 delivers the binary table, rather
109          than unpacking it into an image.
110
111       afh (default=1)
112          By default rfits uses Astro::FITS::Header tied-hash objects to
113          contain the FITS header information.  This permits explicit control
114          over FITS card information, and conforms well with the FITS
115          specification.  But Astro::FITS::Header objects are about 40-60x
116          more memory intensive than comparable perl hashes, and also use ~10x
117          more CPU to manage.  For jobs where header processing performance is
118          important (e.g. reading just the headers of 1,000 FITS files), set
119          afh to 0 to use the legacy parser and get a large boost in speed.
120
121       FITS image headers are stored in the output PDL and can be retrieved
122       with hdr or gethdr.  The hdrcpy flag of the PDL is set so that the
123       header is copied to derived ndarrays by default.  (This is inefficient
124       if you are planning to do lots of small operations on the data; clear
125       the flag with "->hcpy(0)" or via the options hash if that's the case.)
126
127       The header is a hash whose keys are the keywords in the FITS header.
128       If you have the "Astro::FITS::Header" module installed, the header is
129       actually a tied hash to a FITS header object, which can give you more
130       control over card order, comment fields, and variable types.  (see
131       Astro::FITS::Header for details).
132
133       The header keywords are converted to uppercase per the FITS standard.
134       Access is case-insensitive on the perl side, provided that
135       Astro::FITS::Header is installed.
136
137       If Astro::FITS::Header is not installed, then a built-in legacy parser
138       is used to generate the header hash.  Keyword-associated comments in
139       the headers are stored under the hash key "<keyword>_COMMENT>".  All
140       HISTORY cards in the header are collected into a single multiline
141       string stored in the "HISTORY" key.  All COMMENT cards are similarly
142       collected under the "COMMENT" key.
143
144       BSCALE/BZERO
145
146       If the BSCALE and/or BZERO keywords are set, they are applied to the
147       image before it is returned.  The returned PDL is promoted as necessary
148       to contain the multiplied values, and the BSCALE and BZERO keywords are
149       deleted from the header for clarity.  If you don't want this type of
150       processing, set 'bscale=>0' in the options hash.
151
152       EXTENSIONS
153
154       Sometimes a FITS file contains only extensions and a stub header in the
155       first header/data unit ("primary HDU").  In scalar context, you
156       normally only get back the primary HDU -- but in this special case, you
157       get back the first extension HDU.  You can force a read of the primary
158       HDU by adding a '[0]' suffix to the file name.
159
160       BINTABLE EXTENSIONS
161
162       Binary tables are handled. Currently only the following PDL datatypes
163       are supported: byte, short, ushort, long, float, and double. At present
164       ushort() data is written as a long rather than as a short with
165       TSCAL/ZERO; this may change.
166
167       The return value for a binary table is a hash ref containing the names
168       of the columns in the table (in UPPER CASE as per the FITS standard).
169       Each element of the hash contains a PDL (for numerical values) or a
170       perl list (for string values).  The PDL's 0th dimension runs across
171       rows; the 1st dimension runs across the repeat index within the row
172       (for rows with more than one value).  (Note that this is different from
173       standard threading order - but it allows Least Surprise to work when
174       adding more complicated objects such as collections of numbers (via the
175       repeat count) or variable length arrays.)
176
177       Thus, if your table contains a column named "FOO" with type "5D", the
178       expression
179
180         $x->{FOO}->((2))
181
182       returns a 5-element double-precision PDL containing the values of FOO
183       from the third row of the table.
184
185       The header of the table itself is parsed as with a normal FITS HDU, and
186       is returned in the element 'hdr' of the returned hash.  You can use
187       that to preserve the original column order or access the table at a low
188       level, if you like.
189
190       Scaling and zero-point adjustment are performed as with BSCALE/BZERO:
191       the appropriate keywords are deleted from the as-returned header.  To
192       avoid this behavior, set 'bscale=>0' in the options hash.
193
194       As appropriate, TSCAL/ZERO and TUNIT are copied into each column-PDL's
195       header as BSCALE/BZERO and BUNIT.
196
197       The main hash also contains the element 'tbl', which is set to 'binary'
198       to distinguish it from an ASCII table.
199
200       Because different columns in the table might have identical names in a
201       FITS file, the binary table reader practices collision avoidance.  If
202       you have multiple columns named "FOO", then the first one encountered
203       (numerically) gets the name "FOO", the next one gets "FOO_1", and the
204       next "FOO_2", etc.  The appropriate TTYPEn fields in the header are
205       changed to match the renamed column fields.
206
207       Columns with no name are assigned the name "COL_<n>", where <n> starts
208       at 1 and increments for each no-name column found.
209
210       Variable-length arrays are supported for reading.  They are unpacked
211       into PDLs that appear exactly the same as the output for fixed-length
212       rows, except that each row is padded to the maximum length given in the
213       extra characters -- e.g. a row with TFORM of 1PB(300) will yield an
214       NAXIS2x300 output field in the final hash.   The padding uses the TNULn
215       keyword for the column, or 0 if TNULn is not present.  The output hash
216       also gets an additional field, "len_<name>", that contains the number
217       of elements in each table row.
218
219       TILE-COMPRESSED IMAGES
220
221       CFITSIO and several large projects (including NASA's Solar Dynamics
222       Observatory) now support an unofficial extension to FITS that stores
223       images as a collection of individually compressed tiles within a
224       BINTABLE extension.  These images are automagically uncompressed by
225       default, and delivered as if they were normal image files.  You can
226       override this behavior by supplying the "expand" key in the options
227       hash.
228
229       Currently, only Rice compression is supported, though there is a
230       framework in place for adding other compression schemes.
231
232       BAD VALUE HANDLING
233
234       If a FITS file contains the "BLANK" keyword (and has "BITPIX > 0"), the
235       ndarray will have its bad flag set, and those elements which equal the
236       "BLANK" value will be set bad.  For "BITPIX < 0", any NaN's are
237       converted to bad (if necessary).
238
239   rfitshdr()
240       Read only the header of a FITS file or an extension within it.
241
242       This is syntactic sugar for the "data=>0" option to rfits.
243
244       See rfits for details on header handling.  rfitshdr() runs the same
245       code to read the header, but returns it rather than reading in a data
246       structure as well.
247
248   wfits()
249       Simple PDL FITS writer
250
251         wfits $pdl, 'filename.fits', [$BITPIX], [$COMPRESSION_OPTIONS];
252         wfits $hash, 'filename.fits', [$OPTIONS];
253         $pdl->wfits('foo.fits',-32);
254
255       Suffix magic:
256
257         # Automatically compress through pipe to gzip
258         wfits $pdl, 'filename.fits.gz';
259         # Automatically compress through pipe to compress
260         wfits $pdl, 'filename.fits.Z';
261
262       Tilde expansion:
263
264         #expand leading ~ to home directory (using glob())
265         wfits $pdl, '~/filename.fits';
266
267       •  Ordinary (PDL) data handling:
268
269          If the first argument is a PDL, then the PDL is written out as an
270          ordinary FITS file with a single Header/Data Unit of data.
271
272          $BITPIX is then optional and coerces the output data type according
273          to the standard FITS convention for the BITPIX field (with positive
274          values representing integer types and negative values representing
275          floating-point types).
276
277          If $pdl has a FITS header attached to it (actually, any hash that
278          contains a "SIMPLE=>T" keyword), then that FITS header is written
279          out to the file.  The image dimension tags are adjusted to the
280          actual dataset.  If there's a mismatch between the dimensions of the
281          data and the dimensions in the FITS header, then the header gets
282          corrected and a warning is printed.
283
284          If $pdl is a slice of another PDL with a FITS header already present
285          (and header copying enabled), then you must be careful.  "wfits"
286          will remove any extraneous "NAXISn" keywords (per the FITS
287          standard), and also remove the other keywords associated with that
288          axis: "CTYPEn", "CRPIXn", "CRVALn", "CDELTn", and "CROTAn".  This
289          may cause confusion if the slice is NOT out of the last dimension:
290          "wfits($x(:,(0),:),'file.fits');" and you would be best off
291          adjusting the header yourself before calling "wfits".
292
293          You can tile-compress images according to the CFITSIO extension to
294          the FITS standard, by adding an option hash to the arguments:
295
296          compress
297             CURRENTLY UNIMPLEMENTED.  Below describes the envisioned usage.
298
299             This can be either unity, in which case Rice compression is used,
300             or a (case-insensitive) string matching the CFITSIO compression
301             type names.  Currently supported compression algorithms are:
302
303             •  RICE_1 - linear Rice compression
304
305                This uses limited-symbol-length Rice compression, which works
306                well on low entropy image data (where most pixels differ from
307                their neighbors by much less than the dynamic range of the
308                image).
309
310          tilesize (default "[-1,1]")
311             This specifies the dimension of the compression tiles, in pixels.
312             You can hand in a PDL, a scalar, or an array ref. If you specify
313             fewer dimensions than exist in the image, the last dim is
314             repeated - so "32" yields 32x32 pixel tiles in a 2-D image.  A
315             dim of -1 in any dimension duplicates the image size, so the
316             default "[-1,1]" causes compression along individual rows.
317
318          tilesize (RICE_1 only; default 32)
319             For RICE_1, BLOCKSIZE indicates the number of pixel samples to
320             use for each compression block within the compression algorithm.
321             The blocksize is independent of the tile dimensions.  For RICE
322             compression the pixels from each tile are arranged in normal
323             pixel order (early dims fastest) and compressed as a linear
324             stream.
325
326       •  Table handling:
327
328          If you feed in a hash ref instead of a PDL, then the hash ref is
329          written out as a binary table extension.  The hash ref keys are
330          treated as column names, and their values are treated as the data to
331          be put in each column.
332
333          For numeric information, the hash values should contain PDLs.  The
334          0th dim of the PDL runs across rows, and higher dims are written as
335          multi-value entries in the table (e.g. a 7x5 PDL will yield a single
336          named column with 7 rows and 5 numerical entries per row, in a
337          binary table).  Note that this is slightly different from the usual
338          concept of threading, in which dimension 1 runs across rows.
339
340          ASCII tables only allow one entry per column in each row, so if you
341          plan to write an ASCII table then all of the values of $hash should
342          have at most one dim.
343
344          All of the columns' 0 dims must agree in the threading sense. That
345          is to say, the 0th dimension of all of the values of $hash should be
346          the same (indicating that all columns have the same number of rows).
347          As an exception, if the 0th dim of any of the values is 1, or if
348          that value is a PDL scalar (with 0 dims), then that value is
349          "threaded" over -- copied into all rows.
350
351          Data dimensions higher than 2 are preserved in binary tables, via
352          the TDIMn field (e.g. a 7x5x3 PDL is stored internally as seven rows
353          with 15 numerical entries per row, and reconstituted as a 7x5x3 PDL
354          on read).
355
356          Non-PDL Perl scalars are treated as strings, even if they contain
357          numerical values.  For example, a list ref containing 7 values is
358          treated as 7 rows containing one string each.  There is no such
359          thing as a multi-string column in FITS tables, so any nonscalar
360          values in the list are stringified before being written.  For
361          example, if you pass in a perl list of 7 PDLs, each PDL will be
362          stringified before being written, just as if you printed it to the
363          screen.  This is probably not what you want -- you should use "glue"
364          to connect the separate PDLs into a single one.  (e.g.
365          "$x->glue(1,$y,$c)->mv(1,0)")
366
367          The column names are case-insensitive, but by convention the keys of
368          $hash should normally be ALL CAPS, containing only digits, capital
369          letters, hyphens, and underscores.  If you include other characters,
370          then case is smashed to ALL CAPS, whitespace is converted to
371          underscores, and unrecognized characters are ignored -- so if you
372          include the key "Au Purity (%)", it will be written to the file as a
373          column that is named "AU_PURITY".  Since this is not guaranteed to
374          produce unique column names, subsequent columns by the same name are
375          disambiguated by the addition of numbers.
376
377          You can specify the use of variable-length rows in the output,
378          saving space in the file.  To specify variable length rows for a
379          column named "FOO", you can include a separate key "len_FOO" in the
380          hash to be written.  The key's value should be a PDL containing the
381          number of actual samples in each row.  The result is a FITS P-type
382          variable length column that, upon read with "rfits()", will restore
383          to a field named FOO and a corresponding field named "len_FOO".
384          Invalid data in the final PDL consist of a padding value (which
385          defaults to 0 but which you may set by including a TNULL field in
386          the hdr specificaion).  Variable length arrays must be 2-D PDLs,
387          with the variable length in the 1 dimension.
388
389          Two further special keys, 'hdr' and 'tbl', can contain meta-
390          information about the type of table you want to write.  You may
391          override them by including an $OPTIONS hash with a 'hdr' and/or
392          'tbl' key.
393
394          The 'tbl' key, if it exists, must contain either 'ASCII' or 'binary'
395          (case-insensitive), indicating whether to write an ascii or binary
396          table.  The default is binary. [ASCII table writing is planned but
397          does not yet exist].
398
399          You can specify the format of the table quite specifically with the
400          'hdr' key or option field.  If it exists, then the 'hdr' key should
401          contain fields appropriate to the table extension being used.  Any
402          field information that you don't specify will be filled in
403          automatically, so (for example) you can specify that a particular
404          column name goes in a particular position, but allow "wfits" to
405          arrange the other columns in the usual alphabetical order into any
406          unused slots that you leave behind.  The "TFORMn", "TFIELDS",
407          "PCOUNT", "GCOUNT", "NAXIS", and "NAXISn" keywords are ignored:
408          their values are calculated based on the hash that you supply.  Any
409          other fields are passed into the final FITS header verbatim.
410
411          As an example, the following
412
413            $x = long(1,2,4);
414            $y = double(1,2,4);
415            wfits { 'COLA'=>$x, 'COLB'=>$y }, "table1.fits";
416
417          will create a binary FITS table called table1.fits which contains
418          two columns called "COLA" and "COLB". The order of the columns is
419          controlled by setting the "TTYPEn" keywords in the header array, so
420
421            $h = { 'TTYPE1'=>'Y', 'TTYPE2'=>'X' };
422            wfits { 'X'=>$x, 'Y'=>$y, hdr=>$h }, "table2.fits";
423
424          creates table2.fits where the first column is called "Y" and the
425          second column is "X".
426
427       •  multi-value handling
428
429          If you feed in a perl list rather than a PDL or a hash, then each
430          element is written out as a separate HDU in the FITS file.  Each
431          element of the list must be a PDL or a hash. [This is not
432          implemented yet but should be soon!]
433
434       •  DEVEL NOTES
435
436          ASCII tables are not yet handled but should be.
437
438          Binary tables currently only handle one vector (up to 1-D array) per
439          table entry; the standard allows more, and should be fully
440          implemented.
441
442          Handling multidim arrays implies that perl multidim lists should
443          also be handled.
444
445       For integer types (ie "BITPIX > 0"), the "BLANK" keyword is set to the
446       bad value.  For floating-point types, the bad value is converted to NaN
447       (if necessary) before writing.
448
449   fits_field_cmp
450       fits_field_cmp
451
452       Sorting comparison routine that makes proper sense of the digits at the
453       end of some FITS header fields.  Sort your hash keys using
454       "fits_field_cmp" and you will get (e.g.) your "TTYPE" fields in the
455       correct order even if there are 140 of them.
456
457       This is a standard kludgey perl comparison sub -- it uses the magical
458       $a and $b variables, rather than normal argument passing.
459
460   _rows()
461       Return the number of rows in a variable for table entry
462
463       You feed in a PDL or a list ref, and you get back the 0th dimension.
464
465   _prep_table()
466       Accept a hash ref containing a table, and return a header describing
467       the table and a string to be written out as the table, or barf.
468
469       You can indicate whether the table should be binary or ascii.  The
470       default is binary; it can be overridden by the "tbl" field of the hash
471       (if present) or by parameter.
472
473
474
475perl v5.34.0                      2021-08-16                           FITS(3)
Impressum