NAME

SimpleFITS - Perl library for manipulating FITS files

USAGE

use SimpleFITS;

TABLE of CONTENTS

  1. NAME
  2. USAGE
  3. DESCRIPTION
  4. METHOD REFERENCE
  5. EXAMPLES
  6. LAST MODIFIED

DESCRIPTION

SimpleFITS is a perl library which simplifies using the Perl-CFITSIO interface. It is basically an object which wraps around the cumbersome CFITSIO library calls to make mundane things simpler. It supports creating, writing and reading FITS tables and images. This module requires that Astro::FITS::CFITSIO already be installed.

SimpleFITS focusses on handling the basic FITS operations so that the Perl programmer can work at a higher level. Methods for opening a file use standard Perl notation, and can be used to perform common operations at once such as skipping to a desired FITS extension. Methods for reading and writing columns, for example, allow the programmer to specify the column name, and internally SimpleFITS determines which column number to use. SimpleFITS also automatically determines data types for column and keyword values, unless overridden by the programmer.

SimpleFITS calls should start with the SimpleFITS->open() method call to open an existing file or create a new one. Files can be created, opened read-write or opened read-only. SimpleFITS->open() returns a SimpleFITS object reference that can be used in subsequent method calls. The object lifecycle should end with a close() method call. Here is a simple example of opening and closing a FITS file, with basic error checking.

   # Open myfile.fits read-only
   $fits = SimpleFITS->open("<myfile.fits");
   die "ERROR" if (! $fits );
   ... operations on $fits ...
   $fits->close();

SimpleFITS function calls can be chained together for compact programming notation. For example, to write several keywords at once to the $fits object,

 
   $fits->writekey("MJDREF",54910,"Reference time in MJD")
        ->writekey("TIMESYS","TT","Time system of file")
        ->writekey("TIMEUNIT","s","Time unit of file");
Each method call returns self, allowing chaining to occur. Like CFITSIO, SimpleFITS maintains an internal status variable for each object. If a function call fails, then this internal variable will be set, and further function calls will not take effect. The method call $fits->status() will return the CFITSIO status code. Thus, the above example of chaining keywords should really end like this,
 
   $fits->writekey("MJDREF",54910,"Reference time in MJD")
        ->writekey("TIMESYS","TT","Time system of file")
        ->writekey("TIMEUNIT","s","Time unit of file");
   die "ERROR: could not write time keywords" if ($fits->status());
The FITS I/O operations will proceed until there is an error, and subsequent operations will not execute. For non-fatal errors, the programmer can reset the status variable to zero with $fits->setstatus(0).

See below for examples of how to use SimpleFITS.

METHOD REFERENCE

SimpleFITS File and HDU Access Routines

  1. open - open or create a file
  2. close - close an already-opened file
  3. move - Move to a new HDU
  4. createtab - Create empty table extension

SimpleFITS Informational Routines

  1. status - return CFITSIO status
  2. setstatus - reset CFITSIO status
  3. handle - return CFITSIO file handle
  4. nhdu - return the number of HDUs in the file
  5. curhdu - Return the current HDU number (1=primary HDU)
  6. curhdutype - Return HDU type code of the current HDU
  7. nrows - return the number of rows in a table or 2D image
  8. ncols - return the number of columns in a table or 2D image
  9. imgdims - return the dimensions of an image
  10. colnum - return the column number corresponding to the given name
  11. colname - return the name corresponding to a given column number

SimpleFITS Header and Keyword Access Routines

  1. readkey - Read keyword value
  2. writekey - write keyword value
  3. delkey - delete a keyword
  4. readheader - read entire header and return it

SimpleFITS Table and Image Data Access Routines

  1. readcol - read FITS table column data
  2. writecol - write FITS table column data
  3. insertcol - Insert new column
  4. delcol - Delete existing column
  5. insertrows - Insert new rows into a FITS table
  6. delrows - Delete rows of a FITS table
  7. calculate - calculate column-based expression
  8. loadtable - load a FITS table into an array of hash references

The following subsections describe each method in more detail.

open - open or create a file

   open($inspec,%args) - open a file

RETURNS: new SimpleFITS object, or zero upon failure.

The method call open() opens an existing file for reading and/or writing, or creates a new file. Use standard Perl open() notation for opening or creating files, or use the access

  readonly("filename")   - open file read-only
  readwrite("filename")  - open a file for reading and writing
  create("filename")     - create a new file

These are short-cut routines that do not require the "<" or ">" syntax for opening files.

RETURNS: a SimpleFITS object reference.

close - close an already-opened file

  close() - close an already-opened file

This file closes a file. The current CFITSIO status is always ignored, so the file is always closed. RETURNS: $self.

createtab - Create empty table extension

  createtab($extname) - Create empty extension

The extension initially is empty, with no rows or columns. RETURNS: $self.

status - return CFITSIO status

  status() - return CFITSIO status

RETURNS: the most recent CFITSIO error status code.

setstatus - reset CFITSIO status

  setstatus($value) - reset CFITSIO status

RETURNS: $self.

handle - return CFITSIO file handle

  handle() - return CFITSIO file handle.

Retrieving the CFITSIO handle can be useful when the programmer needs to access any underlying Astro::FITS::CFITSIO subroutines. RETURNS: the CFITSIO file handle.

nhdu - return the number of HDUs in the file

  nhdu($n) - return the number of HDUs in the file

RETURNS:

curhdu - Return the current HDU number (1=primary HDU)

  curhdu($n) - Return the current HDU number (1=primary HDU)

RETURNS

curhdutype - Return HDU type code of the current HDU

  curhdutype($n) - Return HDU type code of the current HDU

RETURNS

nrows - return the number of rows in a table or 2D image

  nrows($n) - return the number of rows in a table or 2D image

RETURNS

ncols - return the number of columns in a table or 2D image

  ncols($n) - return the number of columns in a table or 2D image

RETURNS

imgdims - return the dimensions of an image

  imgdims() - return the dimensions of an image

RETURNS

colnum - return the column number corresponding to the given name

  colnum($colname) - return the column number corresponding to the given name

RETURNS: integer FITS column number.

colname - return the name corresponding to a given column number

  colname($colnum) - return the name corresponding to a given column number

RETURNS: column name, or undef if not found.

move - Move to a new HDU

  move($hdu) - Move to a new HDU

Note that $hdus are numberd starting with 1 as the primary HDU.

RETURNS: $self.

readheader - read entire header and return it

  readheader($header) - read entire header and return it

RETURNS: $self.

readkey - Read keyword value

  readkey($keyname,$value,$comment,$type) - Read keyword value

RETURNS: $self. Note that if the read fails, then $value and/or $comment are not changed upon return.

Alternate calling sequence:

  $value = readkey($keyname)

In this alternate sequence, the data value is returned explicitly. The comments are ignored. This form cannot be chained.

writekey - write keyword value

  writekey($keyname,$value,$comment,$type) - write keyword value

RETURNS: $self.

delkey - delete a keyword

  delkey($keyname) - delete a keyword

RETURNS: $self.

readpix - read pixel data

  readpix($options,$data) - read pixel data

Read pixel values from image HDU. The user can specify the range of each dimension. The default is to read the entire image. Pixel values use the FITS convention where the first pixel is labeled as 1.

RETURNS: $self.

Alternate calling sequence:

  @data = $fits->readcol($options)
where @data is the data array. This form cannot be chained.

readcol - read FITS table column data

  readcol($column,$options,$dataref) - read FITS table column data

RETURNS: $self.

Alternate calling sequence:

  @data = $fits->readcol("NAME",$options)
where @data is the data array. This form cannot be chained.

writecol - write FITS table column data

  writecol($column,$options,$data) - write FITS table column data

RETURNS: $self.

insertcol - Insert new column

  insertcol($colkeys,$column) - Insert new column

where

At least TTYPE and TFORM are required, but other keywords like TUNIT, TLMAX can be specified. The task automatically adds the column number. See the example at the top of this module on how to add columns.

The user may optionally specify an initialization expression for the column using the special descriptor "=". See 'fhelp calc_express' for allowed calculator expressions.

RETURNS: $self.

delcol - Delete existing column

  delcol($column) - Delete existing column

RETURNS: $self.

insertrows - Insert new rows into a FITS table

  insertrows($nrows,$firstrow) - Insert new rows into a FITS table

RETURNS: $self.

delrows - Delete rows of a FITS table

  delrows($nrows,$firstrow) - Delete rows of a FITS table
  delrows([a,b]) - delete row range [a,b] (inclusive)
  delrows([a])   - delete row a only

RETURNS: $self.

calculate - calculate column-based expression

  calculate($expr,$options,$dataref) - calculate column-based expression

RETURNS: $self.

Alternate calling sequence:

  @data = $fits->calculate("expr",$options)
where @data is the calculated data array.

loadtable - load a FITS table into an array of hash references

  loadtable($dataref) - load a FITS table into an array of hash references

The keys of the hashes are the upper cased column names. Example: given a FITS table

	NAME	RA	DEC
	Alpha	13.3	-4.3
	Beta	150.1	5.6
The passed array reference will have these two hash references
	{ NAME => 'Alpha', RA => 13.3, DEC => -4.3 },
	{ NAME => 'Beta', RA => 150.1, DEC => 5.6 },
added on output.

EXAMPLES

Complete Example: Create a file

This example creates a FITS binary table containing two columns, START and STOP. It is assumed that the user already has two arrays, @start and @stop which contain the desired table values.
      $fits = SimpleFITS->open("myfile.gti", access=>"create");
      die "ERROR: could not create file" if ( ! $fits );
      $fits
 	->createtab("GTI")
	->writekey("MJDREF", 54910.000135)
 	->insertcol({TTYPE => ["START", "GTI Start Time"], 
 		     TFORM => "1D", TUNIT => "s"})
 	->insertcol({TTYPE => ["STOP",  "GTI Stop Time"],
 		     TFORM => "1D", TUNIT => "s"})
 	->writecol("START",{grow=>1},\@start)
 	->writecol("STOP", {},\@stop)
      die "ERROR: could not write file" if ( $fits->status() );
      $fits->close();
The method createtab() creates an empty table, and two columns are created. Note that "grow=>1" is required to enlarge the empty table. Instead of using grow, one can use insertrows() to insert the required number of rows, and then fill them (see next example).

Complete Example: append rows to existing table

This example takes the existing table above, and appends more rows to the end of the table. The new data is taken from the arrays @newstart and @newstop.
      $fits = SimpleFITS->open("myfile.gti", access=>"readwrite", ext=>"GTI");
      die "ERROR: could not open file" if ( ! $fits );
      
      $nrows = $fits->nrows();      # Old number of rows
      $newrows = scalar(@newstart); # Number of rows to append

      $fits
         ->insertrows($newrows)
         ->writecol("START", {rows=>[$nrows+1,$nrows+$newrows]}, \@newstart)
         ->writecol("STOP", {rows=>[$nrows+1,$nrows+$newrows]}, \@newstop);
      die "ERROR: could not write file" if ( $fits->status() );
      $fits->close();
In this case, insertrows() is used to preallocate the required number of rows. Then writecol() is used with explicit row numbers to fill in those new rows.

Complete Example: Read tabular data

In this example, we open the file as described above and read the data. We also calculate a derived quantity, the average of START and STOP, using the CFITSIO expression calculator.
      $fits = SimpleFITS->open("myfile.gti", access=>"read", type=>"table");
      die "ERROR: could not open file" if (! $fits); 
      $fits -> readcol( "START", {}, $rstart );  # $rstart is array ref
      @start = @$rstart;                     # Dereference to get array
      @stop = $fits -> readcol( "STOP" );

      @cent = $fits -> calculate("(START+STOP)/2");
      $fits->close();

This example demonstrates the alternate syntaxes for readcol(). The first syntax returns a Perl array reference in $rstart, which can be dereferenced to get the full array. This syntax can be useful when retrieving a large number of columns at one time because multiple readcols() can be chained in one statement. The second usage of readcol() uses the alternate syntax which returns a Perl array directly.

The calculator expression, "(START+STOP)/2" is computed on the fly and the value is returned in the @cent array.

Open a file

      $fits = SimpleFITS->open("<file");  # read-only access to existing file
      $fits = SimpleFITS->open(">file");  # create a file
      $fits = SimpleFITS->open("+<file"); # read-write access to existing file

Moving to an extension

      $fits -> move("NAME")  # Move to named extension
      $fits -> move(1)       # Move to extension number 1 (absolute)
      $fits -> move("+1")    # Move to next extension (relative)
      $fits -> move("-1")    # Move to previous extension (relative)

Create a new table

      $fits -> createtab("extname")  

Add column to table

      $fits -> insertcol({TTYPE => ["NAME", "Description"], # TTYPEn keyword
                          TFORM => "1D",                    # TFORMn keyword
                          Tkey  => [value, "Comment", TYPE]}) # Tkeyn keywords

All keywords will have the column number appended. TYPE is the (optional) CFITSIO data type of the *keyword*, such as TDOUBLE. The data type of the column is given by the TFORMn keyword.

Insert column using a calculator expression

      $fits -> insertcol({TTYPE => "RADIUS", # TTYPEn keyword
                          TFORM => "1D",     # TFORMn keyword
			  TUNIT => "m",
			  '='   => "X^2 + Y^2"});
In this case, RADIUS is calculated from the existing columns X and Y, and given units of meters.

Delete column from table

      $fits -> delcol("colname");

Read column from table

      $fits -> readcol("NAME",{rows=>$rowrange,type=>TYPE},$data) 
            ($data is a reference to the data array)               # or
      @data = $fits->readcol("NAME",{rows=>$rowrange,type=>TYPE})
            (@data is the data array)
Both "rows" and "type" are optional and can be omitted (see readcol for more detailed documentation).

Calculate any derived quantity using CFITSIO calculator

     $fits -> calculate("expression",$options,$data)  #or
      @data = $fits->calculate("expression",$options)
where "expression" is any CFITSIO calculator expression. (see calc_express)

Write column to FITS table

      $fits -> writecol("NAME",{rows=>$rowrange,type=>TYPE},$data)
where $data is a reference to the array of data. (i.e. $data=\@myarray)

Read keywords

      $fits -> readkey("KEYWORD",$value,$comment,TYPE) # or
      $value = $fits -> readkey("KEYWORD")
$value is the keyword value, $comment is the comment string TYPE is optional; and allows typecasting from the native keyword type.

Write keywords

      $fits -> writekey("KEYWORD",$value,$comment,TYPE)
The meanings are the same as for readkey().

Read pixel value from an image HDU

      $fits -> readpix(...options..., $data)
            ($data is a reference to the data array)               # or
      @data = $fits->readpix(...options...)
            (@data is the data array)
where the "...options..." is a hash which gives pixel ranges for each dimension, optional data type, optional null value. See documentation below for more detailed information. The default, if no pixel ranges are specified, is to read the entire image.

LAST MODIFIED

Sep 2013

  1. NAME
  2. USAGE
  3. DESCRIPTION
  4. METHOD REFERENCE
  5. EXAMPLES
  6. LAST MODIFIED