STScI Logo

using_spectral xray.xspectral



using_xspectral -- introduction to the xspectral package


PROS X-ray spectral analysis involves comparing an observed spectrum with a trial spectrum that is generated by convolving a model with the calibrated telescope and instrument response. Spectral analysis currently works on Einstein IPC and MPC and ROSAT PSPC data. The input data to spectral analysis consist of model and instrument data and observed spectral table files. The table files (extensions can be generated by the user from QPOE files using the qpspec task. Spectral fitting can also be done directly on the ROSAT PSPC <seqno>_sp<no>.tab files produced by SASS and delivered on the GO data tapes. Einstein SDF files can be converted to files using the sdfspec task, and MPC data can be converted using the task mpcspec .


The spectral model is given by an ASCII model descriptor. The model descriptor is the sum of individual model components with the option of applying absorption.

The general syntax for applying absorption to a component is:
    absorption(params) * component(params)

The general syntax for multiple model components is:
    abs(params) * compnt1(params) + abs(params) * compnt2(params) + ...

Possible components and arguments are:
powerlaw          log(normalization), energy index
bremsstrahlung    log(normalization), temperature [keV]
exponential       log(normalization), temperature [keV]
blackbody         log(normalization), temperature [keV]
raymond           log(normalization), temperature [keV], abundance table,
                                        abundance percent
line model        log(normalization), line-energy [keV],
                                        line-width [FWHM, in keV]

Absorption is applied as follows:
	absorption(log galactic_NH)
	absorption(log intrinsic_NH, redshift)
	absorption(log galactic_NH, log intrinsic_NH, redshift)

Unique abbreviations are recognized (e.g. pow=powerlaw, ray=raymond, co=cosmic). Parameters are specified by a single value (fixed) or a range separated by ":" (free). Free (log) normalization of component1 is requested by omitting the normalization for component1. Normalization(s) of any subsequent component(s) is (are) specified and computed as log(fraction) of that of component1. Other parameters may be linked.

If "?" is input a short helpfile appears, and the model prompt reappears. A null string ("") will cause the previously determined best model to be taken from the file.

For more information, try help models_spectral (from the cl).


The chisquared value obtained from comparing observed data sets with the convolved input model and fixed model parameters is computed by the task singlefit . The fit task will compute the minimum chisquared with respect to free model parameters using the Simplex minimization method. These tasks display the final results and create predicted data sets as output.


Each input observed data set that is fit to a model (using tasks singlefit or fit) has a corresponding output predicted data file with the same root as the input file, and the extension "" instead of the input files "" extension. Since more than one input file can be used in a fit, more than one predicted file can be created as output.

The predicted data file contains all of the information contained in the input observed data files. In addition, three columns are added detailing the results of the fit. These are: "pred" (containing the predicted spectrum), "chisq" (containing the chi-square contribution for each channel) and "chans" (containing a "*" if that channel was used in the fit). The table may contain more than one set of predicted data, so the names of these columns are actually "pred_<N>", "chisq_<N>", and "chans_<N>", where <N> distinguishes the predicted data sets within the file (see below).

The predicted data set also contains header parameters that describe the model used in the fit (the best fit parameters), the total chi-square of the fit, and the file names of all observed data sets used in the fit.

This predicted parameter controls the creation of the predicted files. The parameter takes three possible values: "nothing", "new", or "append". If predicted is "nothing", no predicted data files are created. If the parameter value is "new", then the predicted data files are overwritten (if the clobber parameter is set to true). In this case <N> is set to 1. If the value is "append", then the predicted data columns are appended to the current predicted data file. In this case, the <N> number appended to the "pred", "chisq", and "chans" column names is incremented so that successive runs of a fit result have successive columns. For example, in the successive predicted column the names would be "pred_1", "pred_2", etc.

Additional output from the tasks singlefit or fit may be accumulated in a table whose name is specified in the xspectral package parameter chisquare . The file will contain one row of the following columns for each fit performed: "date" (the time and date of the run), "chisq" (the total chisq of the fit), "chans" (the number of channels used in the fit), "free" (the number of free parameters used in the fit), "files" (a list of predicted data files generated by the fit, along with the <N> column number within each file - see above), "model" (the best fit model).


The task counts_plot will display your results graphically. The observed spectrum will be shown as data points, and the predicted spectrum will be shown as a histogram. Once the graph is finished, you will be left in cursor input mode. This is a standard IRAF convention for many plots, enabling you to manipulate the graph (changing limits, rescaling axes, and so on). In cursor mode type a question mark ("?") to get a help menu. Type a "q" to exit the task.

The task bal_plot will draw a histogram of your current BAL information for the Einstein IPC. It will put you into cursor input mode, as the other plotting tasks do, so you will have to type a "q" to exit the task and return to the package prompt.


Several of the tasks in the xspectral package share a common set of parameters. These parameters reside in the task pkgpars . Each task in the xspectral package has a hidden parameter, of type pset, which points to the pkgpars parameter file. The parameters stored here include the observed data sets and the model descriptor, and instrument specific parameters. Each task also has its own parameter file.

To examine this common parameter file, type:

xs> lparam pkgpars | page

The task pkgpars allows the user to edit the pkgpars.par file as if they had called eparam pkgpars .

xs> pkgpars

This will allow editing the parameter file with the editor set by the choice in the or files.

It is also still valid to use the other IRAF methods to change this parameter file:

xs> eparam pkgpars


xs> pkgpars.<param>=<newvalue>

This will set the value of <param> to <newvalue>, overwriting previous values.

With this structure, the data and model are passed from one task to the next without further user intervention (they are auto parameters, which gives the user the option to make a change at any time).

Because the observed data set and the model are in the pkgpars parameter file and not in the parameter file for each task it is not possible to use these as positional arguments on the command line as with other automatic parameters. It is possible to call them from the command line using the syntax of hidden parameters (although they are not hidden). For example, to use these parameters without the user being prompted one could type:

xs> fit observed=snr model="abs(21:23)*pow(4:7)"

The observed counts and error data set contained in the table file will be the input data for spectral tasks.

Previously, when Gaussian errors were calculated, PI or PHA channels
that had zero counts, had zero error and were thus excluded from
subsequent Chi-Sq calculations.  The current default is Poisson errors
(see help explain_errors), so that zero counts, do NOT give zero errors
and these channels WILL be included in subsequent Chi-Sq calculations.
Therefore, it is REQUIRED that users specify the channels to be included
in FIT calculations, as described at the end of this section. 
Spectral fits will output a distinct table file. The user has no control over the output file name: this will have the same root as the input file, with the new extension instead of, and it will be written in the current directory by default, regardless of where the input file is stored (everything to the left of either the last "/" or "$" character in the input table name is `directory path', and it will not be part of the table name). The user has the option of changing the default output directory by setting the parameter prd_dir in the pkgpars parameter file to the desired value (null string is the current directory). Note that file names need to begin with a letter.

Since some of the spectral tasks require both the and the tables as input, but only ask for the observed data set, it is important that the `root' name remains the same, otherwise the task will not find the predicted data set.

The choice of spectral channels to be used in the fit is regulated by a hidden parameter in the pkgpars parameter file. However, they can be easily changed at run time, by specifying them within brackets (e.g. "[2:10]") at the end of the input file name.


Since some of the tasks in the xspectral package will generate graphics output, you need to set up your terminal to display this data. If you are using a Graphon-230, set up your terminal characteristics according to requirements outlined in Appendix A. If you are using a Graphon-140, then you should also refer to Appendix A. If you are using a Sun workstation, then you are all set because "gterm" will automatically create the necessary graphics window. This also holds if you are using "xterm."

If your terminal has no graphics capability, then divert the graphics output from any plotting task by using ">G filename". For example:

	xs>  grid_plot  cursor="terminate.cur"  >G gridplot

(Note that the spectral plots come up in cursor input. Therefore, we need to tell the tasks to "quit" the graphics and continue. You need to create the file "terminate.cur" containing the single letter "q".)

At a later time, you can produce a hardcopy by loading the "plot" package, if necessary, and typing:

	pl> sgikern gridplot

    Appendix A          Terminal setup characteristics.

    Graph-On 140
	Set alpha mode to VT100.
	Set alpha/graphics mode change from host via ESC sequence
		and GS/CAN/ESC FF.
	Set graphics and alphanumerics.
	Set graphics mode to 4012.
	Set GIN terminator to CR.

    Graph-On 230

	in General setup:
		Set mode switching to automatic.

	in Comm setup:
		Set baud rate to 4800.
		Set wordsize/parity to 8 bits/none.

	in Display setup:
		Set display to show both planes.

	in Alpha setup:
		Set to VT220 in VT100 mode.

	in Graphics setup:
		Set to 4014 mode.
		Set GIN report terminator to CR.


fit, pspc_fitting.

Search Form · STSDAS