FITS(3) User Contributed Perl Documentation FITS(3)NAMEPDL::IO::FITS-- Simple FITS support for PDL
SYNOPSIS
use PDL;
use PDL::IO::FITS;
$a = rfits('foo.fits'); # read a FITS file
$a->wfits('bar.fits'); # write a FITS file
DESCRIPTION
This module provides basic FITS support for PDL, in the sense of
reading and writing whole FITS files. (For more complex operations,
such as prefiltering rows out of tables or performing operations on the
FITS file in-place on disk), you can use the Astro::FITS::CFITSIO
module that is available on CPAN.
Basic FITS image files are supported, along with BINTABLE and IMAGE
extensions. ASCII Table support is planned, as are the HEASARC
bintable extensions that are recommended in the 1999 FITS standard.
Table support is based on hashes and named columns, rather than the
less convenient (but slightly more congruent) technique of perl lists
of numbered columns.
The principle interface routines are "rfits" and "wfits", for reading
and writing respectively. FITS headers are returned as perl hashes or
(if the module is present) Astro::FITS::Header objects that are tied to
perl hashes. Astro::FITS::Header objects provide convenient access
through the tied hash interface, but also allow you to control the card
structure in more detail using a separate method interface; see the
Astro::FITS::Header documentation for details.
AUTHOR
Copyright (C) Karl Glazebrook, Craig DeForest, and Doug Burke,
1997-2010. There is no warranty. You are allowed to redistribute
and/or modify this software 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 pasted into
in this file.
FUNCTIONSrfits()
Simple piddle FITS reader.
$pdl = rfits('file.fits'); # Read a simple FITS image
Suffix magic:
$pdl = rfits('file.fits.gz'); # Read a file with gunzip(1)
$pdl = rfits('file.fits.Z'); # Read a file with uncompress(1)
$pdl = rfits('file.fits[2]'); # Read 2nd extension
$pdl = rfits('file.fits.gz[3]'); # Read 3rd extension
@pdls = rfits('file.fits'); # Read primary data and extensions
$hdr = rfits('file.fits',{data=>0}); # Options hash changes behavior
In list context, "rfits" reads the primary image and all possible
extensions, returning them in the same order that they occurred in the
file -- except that, by default, the primary HDU is skipped if it
contains no data. In scalar context, the default is to read the first
HDU that contains data. One can read other HDU's by using the [n]
syntax. Using the [0] syntax forces a read of the first HDU,
regardless of whether it contains data or no. Currently recognized
extensions are IMAGE and BINTABLE. (See the addendum on EXTENSIONS for
details).
"rfits" accepts several options that may be passed in as a hash ref if
desired:
bscale (default=1)
Determines whether the data are linearly scaled using the
BSCALE/BZERO keywords in the FITS header. To read in the exact data
values in the file, set this to 0.
data (default=1)
Determines whether to read the data, or just the header. If you set
this to 0, you will get back the FITS header rather than the data
themselves. (Note that the header is normally returned as the "hdr"
field of the returned PDL; this causes it to be returned as a hash
ref directly.)
hdrcpy (default=0)
Determines whether the hdrcpy flag is set in the returned PDL.
Setting the flag will cause an explicit deep copy of the header
whenever you use the returned PDL in an arithmetic or slicing
operation. That is useful in many circumstances but also causes a
hit in speed. When two or more PDLs with hdrcpy set are used in an
expression, the result gets the header of the first PDL in the
expression. See hdrcpy for an example.
expand (default=1)
Determines whether auto-expansion of tile-compressed images should
happen. Tile-compressed images are transmitted as binary tables
with particular fields ("ZIMAGE") set. Leaving this alone does what
you want most of the time, unpacking such images transparently and
returning the data and header as if they were part of a normal IMAGE
extension. Setting "expand" to 0 delivers the binary table, rather
than unpacking it into an image.
afh (default=1)
By default rfits uses Astro::FITS::Header tied-hash objects to
contain the FITS header information. This permits explicit control
over FITS card information, and conforms well with the FITS
specification. But Astro::FITS::Header objects are about 40-60x
more memory intensive than comparable perl hashes, and also use ~10x
more CPU to manage. For jobs where header processing performance is
important (e.g. reading just the headers of 1,000 FITS files), set
afh to 0 to use the legacy parser and get a large boost in speed.
FITS image headers are stored in the output PDL and can be retrieved
with hdr or gethdr. The hdrcpy flag of the PDL is set so that the
header is copied to derived piddles by default. (This is inefficient
if you are planning to do lots of small operations on the data; clear
the flag with "->hcpy(0)" or via the options hash if that's the case.)
The header is a hash whose 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, which can give you more
control over card order, comment fields, and variable types. (see
Astro::FITS::Header for details).
The header keywords are converted to uppercase per the FITS standard.
Access is case-insensitive on the perl side, provided that
Astro::FITS::Header is installed.
If Astro::FITS::Header is not installed, then a built-in legacy parser
is used to generate the header hash. Keyword-associated comments in
the headers are stored under the hash key "<keyword>_COMMENT>". All
HISTORY cards in the header are collected into a single multiline
string stored in the "HISTORY" key. All COMMENT cards are similarly
collected under the "COMMENT" key.
BSCALE/BZERO
If the BSCALE and/or BZERO keywords are set, they are applied to the
image before it is returned. The returned PDL is promoted as necessary
to contain the multiplied values, and the BSCALE and BZERO keywords are
deleted from the header for clarity. If you don't want this type of
processing, set 'bscale=>0' in the options hash.
EXTENSIONS
Sometimes a FITS file contains only extensions and a stub header in the
first header/data unit ("primary HDU"). In scalar context, you
normally only get back the primary HDU -- but in this special case, you
get back the first extension HDU. You can force a read of the primary
HDU by adding a '[0]' suffix to the file name.
BINTABLE EXTENSIONS
Binary tables are handled. Currently only the following PDL datatypes
are supported: byte, short, ushort, long, float, and double. At present
ushort() data is written as a long rather than as a short with
TSCAL/ZERO; this may change.
The return value for a binary table is a hash ref containing the names
of the columns in the table (in UPPER CASE as per the FITS standard).
Each element of the hash contains a PDL (for numerical values) or a
perl list (for string values). The PDL's 0th dimension runs across
rows; the 1st dimension runs across the repeat index within the row
(for rows with more than one value). (Note that this is different from
standard threading order - but it allows Least Surprise to work when
adding more complicated objects such as collections of numbers (via the
repeat count) or variable length arrays.)
Thus, if your table contains a column named "FOO" with type "5D", the
expression
$a->{FOO}->((2))
returns a 5-element double-precision PDL containing the values of FOO
from the third row of the table.
The header of the table itself is parsed as with a normal FITS HDU, and
is returned in the element 'hdr' of the returned hash. You can use
that to preserve the original column order or access the table at a low
level, if you like.
Scaling and zero-point adjustment are performed as with BSCALE/BZERO:
the appropriate keywords are deleted from the as-returned header. To
avoid this behavior, set 'bscale=>0' in the options hash.
As appropriate, TSCAL/ZERO and TUNIT are copied into each column-PDL's
header as BSCALE/BZERO and BUNIT.
The main hash also contains the element 'tbl', which is set to 'binary'
to distinguish it from an ASCII table.
Because different columns in the table might have identical names in a
FITS file, the binary table reader practices collision avoidance. If
you have multiple columns named "FOO", then the first one encountered
(numerically) gets the name "FOO", the next one gets "FOO_1", and the
next "FOO_2", etc. The appropriate TTYPEn fields in the header are
changed to match the renamed column fields.
Columns with no name are assigned the name "COL_<n>", where <n> starts
at 1 and increments for each no-name column found.
Variable-length arrays are supported for reading. They are unpacked
into PDLs that appear exactly the same as the output for fixed-length
rows, except that each row is padded to the maximum length given in the
extra characters -- e.g. a row with TFORM of 1PB(300) will yield an
NAXIS2x300 output field in the final hash. The padding uses the TNULn
keyword for the column, or 0 if TNULn is not present. The output hash
also gets an additional field, "len_<name>", that contains the number
of elements in each table row.
TILE-COMPRESSED IMAGES
CFITSIO and several large projects (including NASA's Solar Dynamics
Observatory) now support an unofficial extension to FITS that stores
images as a collection of individually compressed tiles within a
BINTABLE extension. These images are automagically uncompressed by
default, and delivered as if they were normal image files. You can
override this behavior by supplying the "expand" key in the options
hash.
Currently, only Rice compression is supported, though there is a
framework in place for adding other compression schemes.
BAD VALUE HANDLING
If a FITS file contains the "BLANK" keyword (and has "BITPIX > 0"), the
piddle will have its bad flag set, and those elements which equal the
"BLANK" value will be set bad. For "BITPIX < 0", any NaN's are
converted to bad (if necessary).
rfitshdr()
Read only the header of a FITS file or an extension within it.
This is syntactic sugar for the "data=>0" option to rfits.
See rfits for details on header handling. rfitshdr() runs the same
code to read the header, but returns it rather than reading in a data
structure as well.
wfits()
Simple PDL FITS writer
wfits $pdl, 'filename.fits', [$BITPIX], [$COMPRESSION_OPTIONS];
wfits $hash, 'filename.fits', [$OPTIONS];
$pdl->wfits('foo.fits',-32);
Suffix magic:
# Automatically compress through pipe to gzip
wfits $pdl, 'filename.fits.gz';
# Automatically compress through pipe to compress
wfits $pdl, 'filename.fits.Z';
· Ordinary (PDL) data handling:
If the first argument is a PDL, then the PDL is written out as an
ordinary FITS file with a single Header/Data Unit of data.
$BITPIX is then optional and coerces the output data type according
to the standard FITS convention for the BITPIX field (with positive
values representing integer types and negative values representing
floating-point types).
If $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.
If $pdl is a slice of another PDL with a FITS header already present
(and header copying enabled), then you must be careful. "wfits"
will remove any extraneous "NAXISn" keywords (per the FITS
standard), and also remove the other keywords associated with that
axis: "CTYPEn", "CRPIXn", "CRVALn", "CDELTn", and "CROTAn". This
may cause confusion if the slice is NOT out of the last dimension:
"wfits($a(:,(0),:),'file.fits');" and you would be best off
adjusting the header yourself before calling "wfits".
You can tile-compress images according to the CFITSIO extension to
the FITS standard, by adding an option hash to the arguments:
compress
This can be either unity, in which case Rice compression is used,
or a (case-insensitive) string matching the CFITSIO compression
type names. Currently supported compression algorithms are:
· RICE_1 - linear Rice compression
This uses limited-symbol-length Rice compression, which works
well on low entropy image data (where most pixels differ from
their neighbors by much less than the dynamic range of the
image).
tilesize (default "[-1,1]")
This specifies the dimension of the compression tiles, in pixels.
You can hand in a PDL, a scalar, or an array ref. If you specify
fewer dimensions than exist in the image, the last dim is
repeated - so "32" yields 32x32 pixel tiles in a 2-D image. A
dim of -1 in any dimension duplicates the image size, so the
default "[-1,1]" causes compression along individual rows.
tilesize (RICE_1 only; default 32)
For RICE_1, BLOCKSIZE indicates the number of pixel samples to
use for each compression block within the compression algorithm.
The blocksize is independent of the tile dimensions. For RICE
compression the pixels from each tile are arranged in normal
pixel order (early dims fastest) and compressed as a linear
stream.
· Table handling:
If you feed in a hash ref instead of a PDL, then the hash ref is
written out as a binary table extension. The hash ref keys are
treated as column names, and their values are treated as the data to
be put in each column.
For numeric information, the hash values should contain PDLs. The
0th dim of the PDL runs across rows, and higher dims are written as
multi-value entries in the table (e.g. a 7x5 PDL will yield a single
named column with 7 rows and 5 numerical entries per row, in a
binary table). Note that this is slightly different from the usual
concept of threading, in which dimension 1 runs across rows.
ASCII tables only allow one entry per column in each row, so if you
plan to write an ASCII table then all of the values of $hash should
have at most one dim.
All of the columns' 0 dims must agree in the threading sense. That
is to say, the 0th dimension of all of the values of $hash should be
the same (indicating that all columns have the same number of rows).
As an exception, if the 0th dim of any of the values is 1, or if
that value is a PDL scalar (with 0 dims), then that value is
"threaded" over -- copied into all rows.
Data dimensions higher than 2 are preserved in binary tables, via
the TDIMn field (e.g. a 7x5x3 PDL is stored internally as seven rows
with 15 numerical entries per row, and reconstituted as a 7x5x3 PDL
on read).
Non-PDL Perl scalars are treated as strings, even if they contain
numerical values. For example, a list ref containing 7 values is
treated as 7 rows containing one string each. There is no such
thing as a multi-string column in FITS tables, so any nonscalar
values in the list are stringified before being written. For
example, if you pass in a perl list of 7 PDLs, each PDL will be
stringified before being written, just as if you printed it to the
screen. This is probably not what you want -- you should use glue
to connect the separate PDLs into a single one. (e.g.
"$a->glue(1,$b,$c)->mv(1,0)")
The column names are case-insensitive, but by convention the keys of
$hash should normally be ALL CAPS, containing only digits, capital
letters, hyphens, and underscores. If you include other characters,
then case is smashed to ALL CAPS, whitespace is converted to
underscores, and unrecognized characters are ignored -- so if you
include the key "Au Purity (%)", it will be written to the file as a
column that is named "AU_PURITY". Since this is not guaranteed to
produce unique column names, subsequent columns by the same name are
disambiguated by the addition of numbers.
You can specify the use of variable-length rows in the output,
saving space in the file. To specify variable length rows for a
column named "FOO", you can include a separate key "len_FOO" in the
hash to be written. The key's value should be a PDL containing the
number of actual samples in each row. The result is a FITS P-type
variable length column that, upon read with "rfits()", will restore
to a field named FOO and a corresponding field named "len_FOO".
Invalid data in the final PDL consist of a padding value (which
defaults to 0 but which you may set by including a TNULL field in
the hdr specificaion). Variable length arrays must be 2-D PDLs,
with the variable length in the 1 dimension.
Two further special keys, 'hdr' and 'tbl', can contain meta-
information about the type of table you want to write. You may
override them by including an $OPTIONS hash with a 'hdr' and/or
'tbl' key.
The 'tbl' key, if it exists, must contain either 'ASCII' or 'binary'
(case-insensitive), indicating whether to write an ascii or binary
table. The default is binary. [ASCII table writing is planned but
does not yet exist].
You can specify the format of the table quite specifically with the
'hdr' key or option field. If it exists, then the 'hdr' key should
contain fields appropriate to the table extension being used. Any
field information that you don't specify will be filled in
automatically, so (for example) you can specify that a particular
column name goes in a particular position, but allow "wfits" to
arrange the other columns in the usual alphabetical order into any
unused slots that you leave behind. The "TFORMn", "TFIELDS",
"PCOUNT", "GCOUNT", "NAXIS", and "NAXISn" keywords are ignored:
their values are calculated based on the hash that you supply. Any
other fields are passed into the final FITS header verbatim.
As an example, the following
$a = long(1,2,4);
$b = double(1,2,4);
wfits { 'COLA'=>$a, 'COLB'=>$b }, "table1.fits";
will create a binary FITS table called table1.fits which contains
two columns called "COLA" and "COLB". The order of the columns is
controlled by setting the "TTYPEn" keywords in the header array, so
$h = { 'TTYPE1'=>'Y', 'TTYPE2'=>'X' };
wfits { 'X'=>$a, 'Y'=>$b, hdr=>$h }, "table2.fits";
creates table2.fits where the first column is called "Y" and the
second column is "X".
· multi-value handling
If you feed in a perl list rather than a PDL or a hash, then each
element is written out as a separate HDU in the FITS file. Each
element of the list must be a PDL or a hash. [This is not
implemented yet but should be soon!]
· DEVEL NOTES
ASCII tables are not yet handled but should be.
Binary tables currently only handle one vector (up to 1-D array) per
table entry; the standard allows more, and should be fully
implemented. This means that PDL::Complex piddles currently can not
be written to disk.
Handling multidim arrays implies that perl multidim lists should
also be handled.
For integer types (ie "BITPIX > 0"), the "BLANK" keyword is set to the
bad value. For floating-point types, the bad value is converted to NaN
(if necessary) before writing.
fits_field_cmp
fits_field_cmp
Sorting comparison routine that makes proper sense of the digits at the
end of some FITS header fields. Sort your hash keys using
"fits_field_cmp" and you will get (e.g.) your "TTYPE" fields in the
correct order even if there are 140 of them.
This is a standard kludgey perl comparison sub -- it uses the magical
$a and $b variables, rather than normal argument passing.
_rows()
Return the number of rows in a variable for table entry
You feed in a PDL or a list ref, and you get back the 0th dimension.
_prep_table()
Accept a hash ref containing a table, and return a header describing
the table and a string to be written out as the table, or barf.
You can indicate whether the table should be binary or ascii. The
default is binary; it can be overridden by the "tbl" field of the hash
(if present) or by parameter.
perl v5.18.1 2013-09-24 FITS(3)
