NAME

Astro::Funtools::Parse - routines to parse the output of Funtools programs

SYNOPSIS

  use Astro::Funtools::Parse qw( :all );
  use Astro::Funtools::Parse qw( parse_funcnts 
                                 parse_funcnts_file 
                                 parse_funhist
                                 parse_funhist_file
                               );

  $funcnts = parse_funcnts_file( $filename );
  $funcnts = parse_funcnts( $filehandle );
  $funcnts = parse_funcnts( $string );
  $funcnts = parse_funcnts( \@array );

  ($header, $table ) = parse_funhist_file( $filename );
  ($header, $table ) = parse_funhist( $filehandle );
  ($header, $table ) = parse_funhist( $string );
  ($header, $table ) = parse_funhist( \@array );

DESCRIPTION

This module provides subroutines which parse the output of two Funtools programs, funcnts and funhist. For more information on Funtools, see

        http://hea-www.harvard.edu/RD/funtools/

Subroutines

parse_funcnts_file, parse_funcnts

  $funcnts = parse_funcnts_file( $filename );
  $funcnts = parse_funcnts( $filehandle );
  $funcnts = parse_funcnts( $string );
  $funcnts = parse_funcnts( \@array );

These parse the funcnts output stored in the argument, and return a reference to a hash containing the results. If funcnts was run with the -i switch and more than one "interval" was used, a reference to an array consisting of references to anonymous hashes is returned, each hash corresponding to one of the intervals. The hashes will have the following keys (unless otherwise specified):

hdr

This element is a reference to a hash containing the header of the funcnts file. funcnts headers have a two level hierarchy of fields in them. The hash keys are the names of the top level; their values are references to hashes containing the names and values of the second level fields. For example, if the funcnts header is

  # source
  #   data file:          002_02_180_10000_new_evt.fits
  #   degrees/pix:        0.000136639
  # background
  #   data file:          002_02_180_10000_new_evt.fits
  # column units
  #   area:               arcsec**2
  #   surf_bri:           cnts/arcsec**2
  #   err_rate:           cnts/arcsec**2

The resultant entry in the hash returned by this function is

  'hdr' => {
      'background' => { 
         'data file' => '002_02_180_10000_new_evt.fits' 
        },
      'column units' => {
         'area' => 'arcsec**2',
         'surf_bri' => 'cnts/arcsec**2',
         'err_rate' => 'cnts/arcsec**2'
        },
      'source' => {
         'data file' => '002_02_180_10000_new_evt.fits',
         'degrees/pix' => '0.000136639'
        }
    },

source

This element is a reference to a hash containing information about the source regions. It has two elements, keyed off of table and regions. The first element is a hash reference to a table (see "Tables" ) and the second is a hash reference to a region (see "Regions")). For example (note that the contents of the hashes are not shown):

    'source' => {
                 'table'   => { ... },
                 'regions' => { ... }
                },

bkgd

This element may not always be there, depending upon how funcnts was run. It has the same format as the source element:

    'bkgd' => {
               'table'   => { ... },
               'regions' => { ... }
              },

bkgd_sub

This element is a reference to a hash containing the background subtracted results table. The format for tables is given below.

sum_bkgd_sub

This element is a reference to a hash containing the summed, background subtracted results table. It is not always present, depending upon how funcnts was run. The format for tables is given below.

parse_funhist_file, parse_funhist

  ($header, $table ) = parse_funhist_file( $filename );
  ($header, $table ) = parse_funhist( $filehandle );
  ($header, $table ) = parse_funhist( $string );
  ($header, $table ) = parse_funhist( \@array );

These parse the funhist output stored in the argument, and return reference to hashes containing the file header and data. The header keywords are used as keys into the header hash. The data are stored in the format documented in "Tables".

Tables

Tables are stored as hashes with the keys comments, names, and records. The comments element is a reference to an array containing any comments preceding the table. The names element is a reference to an array containing the column names, in the order in which they appear. The widths element is an arrayref containing the width of the column (actually the width of the separators). Finally, the records element is a reference to an array, containing references to hashes, one per record in the table. These latter hashes have as keys the names of the columns, and as values the related values for that record.

For example:

  {
    'comments' => [
                    ' background-subtracted results'
                  ],
    'widths' => [ 3, 6, 5, 10, 6, 4, 8, 8 ],
    'names' => [
                 'reg',
                 'counts',
                 'error',
                 'background',
                 'berror',
                 'area',
                 'surf_bri',
                 'err_rate'
               ],
    'records' => [
                   {
                     'error' => '95.979',
                     'reg' => '1',
                     'area' => '90.25',
                     'background' => '0.532',
                     'counts' => '9211.468',
                     'surf_bri' => '102.063',
                     'err_rate' => '1.063',
                     'berror' => '0.142'
                   },
                   {
                     'error' => '9.545',
                     'reg' => '2',
                     'area' => '275.84',
                     'background' => '1.326',
                     'counts' => '89.674',
                     'surf_bri' => '0.325',
                     'err_rate' => '0.035',
                     'berror' => '0.332'
                   }
                 ]
  }

Regions

Regions are stored as hashes with the keys title and regions. The former is a scalar containing the region's identifying string, the latter is a reference to an array, containing the region description (one element per line). For example:

   {
    'title' => 'source region(s)',
    'regions' => [
                   'annulus(4341,4096,0,22,n=2)'
                 ]
   }

EXPORT

None by default. The following symbols are available for export:

  parse_funcnts
  parse_funcnts_file                            
  parse_funhist
  parse_funhist_file

The tag :all is available to export all symbols.

LICENSE

Copyright (C) 2006 Smithsonian Astrophysical Observatory

This file is part of Astro::Funtools::Parse

Astro::Funtools::Parse is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

Astro::Funtools::Parse is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License ong with this program; if not, write to the Free Software Foundation, Inc. 51 Franklin Street, Fifth Floor Boston, MA 02110-1301, USA

AUTHOR

Diab Jerius ( djerius@cfa.harvard.edu )