The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Astro-XSPEC-TableModel-0.01
River stage zero No dependents
/ Astro::XSPEC::TableModel

NAME

Astro::XSPEC::TableModel - Create XSPEC FITS Table Models

SYNOPSIS

    use Astro::XSPEC::TableModel qw( write_table );

    @ipars = ( \%ipar1, \%ipar2 );
    @apars = ( \%apar1, \%apar2 );

    $fptr = 
      write_table( output => $output_file,
                   model  => $model_name,
                   units  => $model_units,
                   additive => 1,            # true or false
                   redshift => 0,            # true or false
                   ipars => \@ipars,
                   apars => \@apars,
                   energy => \@energy,
                   keywords => \@items );

DESCRIPTION

Astro::XSPEC::TableModel helps create table models for the XSPEC X-Ray spectral fitting package. For a thorough discussion fo XSPEC and table models, please see "SEE ALSO".

This module provides the write_table function, which is similar in purpose to the wftbmd.c provided as part of the HEASOFT distribution. It creates all of the administrative structures in the FITS file, and returns control to the calling program at the point where the actual table data (spectra) are written to the output file. The caller is required to close the output file.

In order to construct the table, write_table requires information about the "interpolation" and "additional" parameters, as well as the energy bins for the tables.

Parameter Specification

An "interpolation" or "additional" parameter is specified via a hash. "Interpolation" parameters require the following entries (key case not significant):

Name

The name of the parameter. It is truncated to 12 characters.

Method

The interpolation method: 0 if linear, 1 if logarithmic

Initial

Initial value in the fit for the parameter

Delta

Parameter delta used in fit (if negative parameter is frozen)

Minimum

Hard lower limit for parameter value

Bottom

Soft lower limit for parameter value

Top

Soft upper limit for parameter value

Maximum

Hard upper limit for parameter value

Value

The tabulated parameter values, as an arrayref.

"Additional" parameters require the same entries except for Value and Method.

Energy grid

XSPEC requires that energy bins be contiguous (i.e., the upper bound of a bin is the same as the lower bound of the next). Since adjoining bins share a common boundary value, a single array suffices to describe the bins. If there are $n bins, the array should have $n+1 elements, with element $energy[0] being the lower bound of the first bin, elements @energy[1..$n-1] doing dual duty as lower and upper bound values and element @energy[$n] being the upper bound of the last bin.

Writing models

After write_table returns, the application must finish writing the table by writing the spectra to the file. The SPECTRA HDU is structured such that each row in the table represents the evaluation of the model for a given set of parameter values. The first element (or "cell" in FITS speak) should contain a vector with the parameter values for that instance of the model. The next element(s) should contain vector(s) for the "interpolation" parameters' spectra, and the final elements(s) (if any) should contain vectors for the "additional" parameters' spectra. As an example, consider a model with two parameters, both interpolated, which has been evaluated on a 3x3 grid of parameter values:

  X\Y 0 1 2
  0   . . .
  1   . . .
  2   . . .

There will be nine rows in the table. The first row will have a parameter value vector of [0,0], the next C[0,1], etc. Assuming the function model($x, $y, \@energy) returns an array containing the model evaluated at @energy - 1 energies (see above for the definition of the energy grid), then the application could fill the table with the following code:

  my $row = 0;
  my $npars = 2;
  my $nbins = @energy - 1;
  for my $x ( 0, 1, 2 )
  {
      for my $y ( 0, 1, 2 )
      {
        $row++;
        my @spectrum = model( $x, $y, \@energy );
        my @pars = ( $x, $y );
        $fits->write_col_dbl( 1, $row, 1, $npars, \@pars, $status );
        $fits->write_col_dbl( 2, $row, 1, $nbins, \@spectrum, $status );
      }
  }

(In real code, check $status. Use Astro::FITS::CFITSIO::CheckStatus to do it automatically). "Additional" parameter spectra would be written directly after the "interpolated" parameters.

The spectra should be ordered with the last parameter changing most quickly.

INTERFACE

Astro::XSPEC::TableModel provides a single exportable function

write_table
    $fits = write_table( output => $output, ... );

write_table creates a FITS table, initializing the structures required for an XSPEC table model. It returns a reference to an Astro::FITS::CFITSIO file pointer, with the SPECTRA HDU as the current header unit. The calling application should use that to write the individual spectra into the FITS file, then should close the file.

write_table takes the following mandatory, named arguments

outfile

The name of the file to which to write the FITS table. If it exists it will be overwritten.

model

The name of the model. It will be truncated to 12 characters.

units

The model units. It will be truncated to 12 characters.

ipars

A reference to an array of interpolation parameter specification hashes, as described in "Parameter Specification".

energy

A reference to a hash containing the energy bins. energy => { type => ARRAYREF },

The following named arguments are optional:

additive

If true, the model is additive. It defaults to false, or multiplicative.

redshift

If true, the XSPEC should include a redshift parameter. It defaults to false.

apars

A reference to an array of "additional" parameter specification hashes, as described in "Parameter Specification".

keywords

A reference to an array of Astro::FITS::Header::Item objects, which will be written to the primary HDU.

EXAMPLES

A simple example with one integration parameter.

  use Astro::XSPEC::TableModel;
  use Astro::FITS::CFITSIO::CheckStatus;

  # energy grid
  my @energy = ( 0..1024 );

  # interpolation parameters
  my @ipars = ( {
                 name => 'overlayer',
                 method => 0,
                 initial => 0,
                 delta => 1,
                 minimum => 0,
                 bottom => 0,
                 top => 10,
                 maximum => 10,
                 value => [ 0..10 ],
                }
              );

  # create the table
  my $fptr =
    write_table( output => 'table.fits',
                 model  => 'test',
                 units  => 'pints_of_ale/hr',
                 ipars  => \@ipars,
                 energy => \@energy,
               );

  # Fake some spectra.

  tie my $status, 'Astro::FITS::CFITSIO::CheckStatus';

  my $row = 0;
  my $npars = 1;
  my $nbins = @energy - 1;
  for my $ol ( 0..10 )
  {
      $row++;
      my @spectrum = map {  1 + $ol**2 * $_ } @energy;
      $fptr->write_col_dbl( 1, $row, 1, $npars, [ $ol ], $status );
      $fptr->write_col_dbl( 2, $row, 1, $nbins, \@spectrum, $status );
  }

  $fptr->close_file( $status )

DIAGNOSTICS

Astro::XSPEC::TableModel will croak upon error.

%s parameter %s: missing attributes: %s

The parameter specification is incomplete and is missing the listed attributes.

%s parameter %s: illegal extra attributes: %s

The parameter specification has extra, unrecognized attributes.

Error creating %s: %s

CFITSIO was unable to create the file for the given reason.

Error creating %s HDU: %s

CFITSIO was unable to create the specified HDU for the given reason.

Some error messages will be returned directly from the CFITSIO FITS library; see its documentation for their meaning.

CONFIGURATION AND ENVIRONMENT

Astro::XSPEC::TableModel requires no configuration files or environment variables.

DEPENDENCIES

List::Util, Params::Validate, Astro::FITS::CFITSIO, Astro::FITS::CFITSIO::CheckStatus, Astro::FITS::Header.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-astro-xspec-tablemodel@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Astro-XSPEC-TableModel.

SEE ALSO

XSPEC is documented at http://heasarc.nasa.gov/docs/xanadu/xspec/.

The XSPEC Table Model is documented at ftp://legacy.gsfc.nasa.gov/caldb/docs/memos/ogip_92_009/.

ACKNOWLEDGEMENTS

The code in wftbmd.c (shipped with XSPEC) was invaluable.

VERSION

Version 0.01

LICENSE AND COPYRIGHT

Copyright (c) 2008 The Smithsonian Astrophysical Observatory

Astro::XSPEC::TableModel 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 3 of the License, or (at your option) any later version.

This program 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 along with this program. If not, see <http://www.gnu.org/licenses/>.

AUTHOR

Diab Jerius <djerius@cpan.org>