Astro::XSPEC::TableModel - Create XSPEC FITS Table Models
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 );
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.
An "interpolation" or "additional" parameter is specified via a hash. "Interpolation" parameters require the following entries (key case not significant):
NameThe name of the parameter. It is truncated to 12 characters.
MethodThe interpolation method: 0 if linear, 1 if logarithmic
InitialInitial value in the fit for the parameter
DeltaParameter delta used in fit (if negative parameter is frozen)
MinimumHard lower limit for parameter value
BottomSoft lower limit for parameter value
TopSoft upper limit for parameter value
MaximumHard upper limit for parameter value
ValueThe tabulated parameter values, as an arrayref.
"Additional" parameters require the same entries except for Value and Method.
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.
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.
Astro::XSPEC::TableModel provides a single exportable function
$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
outfileThe name of the file to which to write the FITS table. If it exists it will be overwritten.
modelThe name of the model. It will be truncated to 12 characters.
unitsThe model units. It will be truncated to 12 characters.
iparsA reference to an array of interpolation parameter specification hashes, as described in "Parameter Specification".
energyA reference to a hash containing the energy bins. energy => { type => ARRAYREF },
The following named arguments are optional:
additiveIf true, the model is additive. It defaults to false, or multiplicative.
redshiftIf true, the XSPEC should include a redshift parameter. It defaults to false.
aparsA reference to an array of "additional" parameter specification hashes, as described in "Parameter Specification".
keywordsA reference to an array of Astro::FITS::Header::Item objects, which will be written to the primary HDU.
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 )
Astro::XSPEC::TableModel will croak upon error.
%s parameter %s: missing attributes: %sThe parameter specification is incomplete and is missing the listed attributes.
%s parameter %s: illegal extra attributes: %sThe parameter specification has extra, unrecognized attributes.
Error creating %s: %sCFITSIO was unable to create the file for the given reason.
Error creating %s HDU: %sCFITSIO 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.
Astro::XSPEC::TableModel requires no configuration files or environment variables.
List::Util, Params::Validate, Astro::FITS::CFITSIO, Astro::FITS::CFITSIO::CheckStatus, Astro::FITS::Header.
None reported.
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.
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/.
The code in wftbmd.c (shipped with XSPEC) was invaluable.
Version 0.01
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/>.
Diab Jerius <djerius@cpan.org>
