Table of Contents
This document describes the basic steps in configuring and running yaxx to perform X-ray spectral analysis of Chandra data. It combines a step-by-step tutorial with discussion of some of the most common user options. It is assumed that yaxx has been successfully installed and tested as described in the installation guide.
The different environments used in X-ray analysis by have the potential to conflict if not initialized in the correct order (e.g. CIAO and FTOOLS). To minimize problems, yaxx does the analysis environment initialization internally (in the correct order) and expects that the user has not done any initialization.
To proceed with this quick start example, ensure that you have a "clean" environment by opening a new terminal window. If your shell initialization script (e.g. ~/.csrch) automatically does environment setup (e.g. FTOOLS) then you may experience problems running yaxx.
Next set the $YAXX variable to point to the yaxx installation directory. For instance, if you installed yaxx in your home directory as shown in the installation guide, you would do (for csh or tcsh):
set YAXX=~/yaxx
Yaxx is run from an analysis root directory that should be distinct from the $YAXX source directory. For instance:
mkdir ~/yaxx_analysis cd ~/yaxx_analysis
Spectral analysis of Chandra data with yaxx requires (at a minimum) ACIS event data and aspect solution data, both of which are found in the primary data products for an ObsId. These input data can be stored either outside the analysis directory (e.g. in a raw data repository) or within the analysis directory in a structure that meshes with the output spectral analysis results. Here we demonstrate the latter, using data provided in the yaxx installation.
mkdir obs3102 cp $YAXX/Test/Data/Obs3102/acisf03102_evt2.fits obs3102/ cp $YAXX/Test/Data/Obs3102/pcadf*_asol1.fits obs3102/
The directory location of both the input Chandra data and the output analysis results are configurable.
The list of X-ray sources to be processed by yaxx is specified as tabular data in the object list file. Each table row contains data such as the source ObsId and position. The format of this file can be FITS, RDB, or ASCII (with several common column delimiters supported).
To create an object list file for this example, create a new file named sample.dat and insert the following lines:
obsid src redshift X Y object 3102 1 0.32 4167 4085 Q1250+568
This indicates that just one source named Q1250+568 with physical sky coordinates (4167,4085) will be extracted. Any fits that rely on a redshift will use 0.32.
The operation of yaxx is controlled by configuration files named yaxx.cfg. The key configuration files are:
For the tutorial example, copy the yaxx installation User/yaxx.cfg file into the analysis directory:
cp $YAXX/User/yaxx.cfg ./yaxx.cfg
Examine this file and note some of the options specified such as the input data and output directories, mission and thread, the object list file, fit methods and statistics, source extraction parameters, fit rules, and model definitions.
Details for all parameters are given in the yaxx reference manual.
From your analysis root directory run yaxx by entering:
$YAXX/yaxx
If you have installed the yaxx launcher script somewhere in your search path you can simply run:
yaxx
You will then see yaxx processing ObsId 3102. At the end of a processing run yaxx will declare SUCCESS if all steps succeeded. The key processing steps are:
Each processing step is run only if the output files for that step are non-existent or older than the input files. The typical way to force reprocessing from a particular step is to tell yaxx to delete certain files before processing using the C<-preclean> option. For instance, to re-do the spectral fitting:
yaxx -preclean fit
Since the report summary depends on the fit results, it will also be regenerated.
Assuming the processing is successful, examine the results with:
firefox report_index.html
where firefox can be replaced by the name of your favorite web browser. This shows the yaxx report index which links to report pages for the individual sources. The report page shows a summary of the source parameters, an image of the source and the extraction regions used, a table of spectral fit results, and plots of the spectral model fits. In this tutorial there is only one source, but if there are multiple sources then individual reports are linked together by the arrows in the upper left corner of each report.
The analysis data files associated with yaxx processing in this example have the structure:
<output_dir>/obs<obsid>/src<src>
The files unique to an ObsId are within the obs<obsid> directory, and those unique to the particular source are in the src<src> (i.e. the "source" directory). Some of the more useful files in the source directory are:
acis*.pi : Various pi (or pha) spectral files for fitting acis.rmf : RMF acis.arf : ARF <fit_model>.in : Sherpa script used to fit <fit_model>, e.g. pl.in report.html : Final fit summary report (HTML) log : Processing log. log.<n> files are old logs
The default source and background regions generated by yaxx can be adjusted by doing:
cd obs3102/src1 emacs src.reg # or your favorite editor emacs bkg.reg
Once the region files have been edited appropriately simply re-run yaxx. During processing yaxx will reprocess only steps that depend on the region files. Yaxx will never overwrite an existing source or background region file, so one can also manually create the region files before starting yaxx. This requires making the files in the expected output directories.
The <fit_model>.in file is a very useful starting point for doing more detailed or interactive spectral fitting of a particular source. For the simple powerlaw model in this example one can exactly recreate the yaxx fitting steps in sherpa by doing:
cd obs3102/src1 sherpa use pl.in