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. The hash 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

This software is released under the GNU General Public License. You may find a copy at

   http://www.fsf.org/copyleft/gpl.html

AUTHOR

Diab Jerius ( djerius@cfa.harvard.edu )

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