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
SPECTRAHDU 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>