Astro::FITS::CFITSIO::Simple

This module presents an uncomplicated interface to reading (and
eventually writing) FITS files with the CFITSIO library. It attempts to
perform the intuitive action when left to its own devices, but much of
its behavior can be controlled by an application.

  Reading FITS files

rdfits reads numeric FITS data into PDL objects (piddles). String data
(from tables) are stored in ordinary Perl arrays; references to those
are returned. It recognizes image (primary or extension) and binary or
ASCII tables.

rdfits pays attention to what it is asked to read as well as the context
in which it was called (i.e., whether an array or a scalar was
requested). The default behavior when reading data from a single HDU
(the default) is as follows:

*       An image is always returned as a single piddle, regardless of
        the calling context.

          $img = rdfits( 'image.fits' );

*       Table data are returned as a hash if no column names are
        specified.

          %table = rdfits( 'table.fits' );

        In this case all columns are returned. However, if a list of
        column names prefixed by the "-" character is given, these
        columns will *not* be returned. For example:

          %table = rdfits( 'table.fits', qw/ -status -boring / );

        "Subtractive" column designations may not be mixed with
        "additive" column designations.

*       Table data are returned as a list if column names are specified
        and rdfits was called in an array (list) context.

          @coldata = rdfits( 'table.fits', 'col1', 'col2' );

*       If a single column is read and rdfits is called in a scalar
        context, the data are returned as a scalar (piddle or arrayref,
        depending upon data type).

          $coldata = rdfits( 'table.fits', 'col1' );

Some of this behavior may be changed using the "rethash" option.

Normally rdfits maps the FITS column type (double, long, etc) to the
best matched PDL type. This may be overridden (for instance to promote
floats to doubles) using the "dtypes" or "defdtype" options. Bit columns
are a bit different. (See "Reading Bit Data").

rdfits can optionally return the full FITS header. If an image is read,
the resultant piddle's header is set to a hash tied to a
Astro::FITS::Header object. For most intents and purposes, this is just
like an ordinary piddle header.

  $pdl = rdfits( 'image.fits' );
  print $pdl->gethdr->{HDUNAME};

Retrieving the header for table data is a little more complicated. See
the rethdr option below for more information.

See Astro::FITS::Header for more information on its representation of
FITS headers.

   Reading Bit Data

Table data with type BIT are by default mapped onto a PDL type which
best matches the FITS element size, with the packing of the bits
preserved. The user may override this type using the "dtypes" or
"defdtype" options (see the description under "Table Options" below).

Another option is to treat each bit as an independent quantity, with
each bit stored in its own piddle element. This may be accomplished by
specifying the PDL type (via "dtypes" or "defdtype") as the string
"logical". Bits will then be stored as bytes, with each byte
representing a bit.

  Functions

rdfits
    rdfits takes a single mandatory parameter which is either a file
    name or a CFITSIO file pointer. With no other information provided,
    it reads data from the first available (and recognizable) HDU. If
    additional scalar values are provided, they are assumed to be column
    names, and rdfits will search only for tables. The data are stored
    as described in "Reading FITS files".

    rdfits "croak()'s" upon error.

    rdfits's behavior can be controlled via a hashref passed in as the
    last argument:

      rdfits($file, [...], \%opts );

    There are three categories of options: those which affect how rdfits
    finds an HDU to read; those which affect reading tables; and those
    which affect reading of columns.

    HDU options

        extname This may be set to the exact name of the HDU to read.

        extver  This may be set to the version of the HDU to read. It
                requires that "extname" be set as well.

        hdunum  The index of the HDU in the file. This may also be
                appended to the file name in brackets, i.e. "file[1]".

        hdutype The type of HDU to read. This may be one of the
                following strings:

                    img image      - read an image
                    binary bintbl  - read a binary table
                    ascii          - read an ascii table
                    table          - read any type of table
                    any            - read any type of data

                If a particular HDU is requested and the HDU type
                doesn't match, rdfits will croak.

        resethdu
                This takes a boolean value. If true, and rdfits was
                passed a CFITSIO file pointer, the HDU pointer is stored
                and reset just before rdfits returns. Defaults to false.

    Table Options
        These options are accepted only when reading tables. They will
        cause an error otherwise.

        dtypes
        defdtype
                Normally, rdfits will create the best fit PDL type for
                each column read. A default datatype for all columns can
                be set with "defdtype". Individual columns' datatypes
                can be set with "dtypes".

                "defdtype" takes a single value, a PDL::Type object.

                   %data = rdfits( $file, { defdtype => double } );

                "dtypes" takes a reference to a hash whose keys are the
                column names and whose values are "PDL::Type" objects of
                the type wanted. For example:

                  ($a,$b,$c) =
                    rdfits( $file, qw/ a b c /,
                             { dtypes=>{ a=>float, c=>short } } );

                This will force the PDL type of $a to float, and $c to
                short, while choosing the best match datatype for $b. It
                is not possible for the user to specify dtypes for
                "LOGICAL" and "ASCII" type columns. "BIT" columns are
                special; see "Reading Bit Data" above.

        ninc    The number of rows to read incrementally. By default,
                this number is set according to "fits_get_rowsize()" for
                the table being read. This is best left unset.

        nullval The value with which to fill in null data values. If PDL
                has been built with bad value support, it defaults to
                the bad value for the data type. If not, it defaults to
                0, which signals CFITSIO to ignore null pixels.

        rethash
                  %data = rdfits('foo.fits', @cols, { rethash=>1 });

                Normally when rdfits is invoked with a list of columns
                to read, it returns a list of piddles. This Boolean
                option indicates that it should return a hash (not a
                hashref) whose keys are the lower-cased column names
                with the corresponding piddles for values. This is the
                default mode if no columns are specified.

        rethdr  This Boolean option indicates that the HDU's header
                should be returned as well as the data.

                *   If the data are returned in a list, the header will
                    be the first element of the list:

                      ($hdr, @data ) =
                        rdfits( 'foo.fits', @cols, { rethdr => 1 } );

                    The header is returned as an Astro::FITS::Header
                    object.

                *   If the data are returned as a hash, an additional
                    element in the hash is added, with a key of "_hdr".

                      # return the HDU header
                      %hash = rdfits( 'foo.fits', @cols,
                                      { rethash => 1, rethdr => 1 } );
                      $hdr = $hash{_hdr};

                    The header is returned as an Astro::FITS::Header
                    object.

                *   If a single column is requested, and it is returned
                    in a scalar, the returned piddle's header is set to
                    a hash tied to a Astro::FITS::Header object. For
                    most intents and purposes, this is just like an
                    ordinary piddle header.

                      $pdl = rdfits( 'foo.fits', $col,
                                     { rethdr => 1 } );
                      print $pdl->gethdr->{HDUNAME};

                    See Astro::FITS::Header for more information on
                    tieing to that class.

        retinfo
                  %data = rdfits('foo.fits', @cols, { retinfo=>1 });

                This option specifies that the data will be returned as
                a hash, keyed off of the lowercased column names. The
                values in the hash are themselves hashes, with these
                elements:

                data
                    The data read from the file

                idx The index of the column in the file (unary based)

                hdr A hashref containing the FITS keywords which are
                    specific to the column (e.g., "TTYPE", "TLMAX",
                    "TUNIT", etc.). The keys for these are the keyword
                    names without the trailing column index.

                For example,

                  %data = rdfitsTable('foo.fits', 'x', { retinfo => 1 });

                might result in the equivalent hash of

                  $data{'x'} = {
                            idx  => 11,
                            data => PDL...,
                            hdr => {
                                ttype => 'x',
                                cuni  => 'deg',
                                tlmax => '8.1925000E+03',
                                tcdlt => '-1.3666666666667E-04',
                                tunit => 'pixel',
                                tform => '1E',
                                tlmin => '5.0000000E-01',
                                tcrvl => '3.2972102733253E+02',
                                tcrpx => '4.0965000000000E+03',
                                tctyp => 'RA---TAN',
                            },
                          };

        rfilter
                  %data = rdfitsTable('foo.fits', 'x',
                                      { rfilter => 'X < 3' } });

                This specifies a CFITSIO-style row filtering
                specification. Only the rows matching this filter will
                be in the output variables. The filter has access to
                *all* of the columns in the HDU, not just the ones being
                read out. This can radically reduce memory requirements
                if a complicated row selection is made.

        status  This option indicates that progress status should be
                output. status can take one of the following values:

                a scalar
                    If true, a progress bar is written to the standard
                    error stream. If the Term::ProgressBar module is
                    available, a fairly nice one is emitted. (The more
                    primitive style may be forced by setting the value
                    to -1).

                a file glob
                    In this case output is sent to the specified file
                    handle.

                an object reference
                    If the object supports the print() and flush()
                    methods, these are called to output the progress
                    status. (Nice objects are, for example IO::File
                    objects).

                a code reference
                    The code reference is called with two parameters:
                    the number of rows read, and the total number to be
                    read.

                Typically output is produced approximately at 1%
                increment steps.

    Image Options
        These options are accepted only when reading images. They will
        cause an error otherwise.

        dtype   Normally, rdfits will create the best fit PDL type for
                the image data. The application can override the output
                datatype with this option. The argument should be a
                "PDL::Type" object. For example:

                  $float_img = rdfits( $file, { dtype => float } );

        nullval The value with which to fill in null data values. If PDL
                has been built with bad value support, it defaults to
                the bad value for the data type. If not, it defaults to
                0, which signals CFITSIO to ignore null pixels.

rdfitstbl
    This is a thin wrapper around rdfits which forces a single table to
    be read. It is equivalent to invoking rdfits with the options.

      { hdutype => 'table' }

    It has the same calling convention as rdfits.

rdfitsimg
    This is a thin wrapper around rdfits which forces a single table to
    be read. It is equivalent to invoking rdfits with the options

      { hdutype => 'image' }

    It has the same calling convention as rdfits.

INSTALLATION

This is a Perl module distribution. It should be installed with whichever
tool you use to manage your installation of Perl, e.g. any of

  cpanm .
  cpan  .
  cpanp -i .

Consult http://www.cpan.org/modules/INSTALL.html for further instruction.
Should you wish to install this module manually, the procedure is

  perl Build.PL
  ./Build
  ./Build test
  ./Build install

COPYRIGHT AND LICENSE

This software is Copyright (c) 2008 by Smithsonian Astrophysical
Observatory.

This is free software, licensed under:

  The GNU General Public License, Version 3, June 2007
