use SimpleFITS;
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->status() );
... 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.
The following subsections describe each method in more detail.
open($inspec,%args) - open a file
RETURNS: new SimpleFITS object. Upon failure, $retval->status is non-zero;
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
This file closes a file. The current CFITSIO status is always ignored, so the file is always closed. RETURNS: $self.
createtab($extname) - Create empty extension
The extension initially is empty, with no rows or columns. RETURNS: $self.
delhdu($ext) - Delete the requested extension
The listed HDU is deleted and all following HDUs are moved forward. The current HDU will be reset to the next nearest HDU, either the following HDU, or if there is no following HDU, the previous HDU. RETURNS: $self.
status() - return CFITSIO status
RETURNS: the most recent CFITSIO error status code.
setstatus($value) - reset CFITSIO status
RETURNS: $self.
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($n) - return the number of HDUs in the file
RETURNS:
curhdu($n) - Return the current HDU number (1=primary HDU)
RETURNS
curhdutype($n) - Return HDU type code of the current HDU
RETURNS
nrows($n) - return the number of rows in a table or 2D image
RETURNS
ncols($n) - return the number of columns in a table or 2D image
RETURNS
imgdims() - return the dimensions of an image
RETURNS
colnum($colname) - return the column number corresponding to the given name
RETURNS: integer FITS column number.
colname($colnum) - return the name corresponding to a given column number
RETURNS: column name, or undef if not found.
move($hdu) - Move to a new HDU
Note that $hdus are numberd starting with 1 as the primary HDU.
RETURNS: $self.
readheader($header) - read entire header and return it
RETURNS: $self.
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, and undef if an error occurs. The comments are ignored. This form cannot be chained.
writekey($keyname,$value,$comment,$type) - write keyword value
RETURNS: $self.
delkey($keyname) - delete a keyword
RETURNS: $self.
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($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($column,$options,$data) - write FITS table column data
RETURNS: $self.
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($column) - Delete existing column
RETURNS: $self.
insertrows($nrows,$firstrow) - Insert new rows into a FITS table
RETURNS: $self.
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($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($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.6The 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.
$fits = SimpleFITS->open("myfile.gti", access=>"create");
die "ERROR: could not create file" if ( $fits->status() );
$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).
$fits = SimpleFITS->open("myfile.gti", access=>"readwrite", ext=>"GTI");
die "ERROR: could not open file" if ( $fits->status() );
$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.
$fits = SimpleFITS->open("myfile.gti", access=>"read", type=>"table");
die "ERROR: could not open file" if ( $fits->status() );
$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.
$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
$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)
$fits -> createtab("extname")
$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.
$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.
$fits -> delcol("colname");
$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).
$fits -> calculate("expression",$options,$data) #or
@data = $fits->calculate("expression",$options)
where "expression" is any CFITSIO calculator expression. (see calc_express)
$fits -> writecol("NAME",{rows=>$rowrange,type=>TYPE},$data)
where $data is a reference to the array of data. (i.e. $data=\@myarray)
$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.
$fits -> writekey("KEYWORD",$value,$comment,TYPE)
The meanings are the same as for readkey().
$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.