Subsections

• 7.20.1 Convert source labels to source names
• 7.20.2 Constructing Exposure Maps
• 7.20.3 Grouping
• 7.20.4 Time-resolved extractions
• 7.20.5 Comparing data and PSF
• 7.20.6 Interface to ChaRT
• 7.20.7 Printing spectra
• 7.20.8 Reviewing spectral fits
• 7.20.9 Catalog matching
• 7.20.10 L^ATEX table generation
• 7.20.11 Adding source properties
• 7.20.12 Performing a spectral fit using an existing script
• 7.20.13 Scanning for Residual Afterglow Events

7.20 Accessory Tools

7.20.1 Convert source labels to source names

The ae_make_catalog tool (§7.2.2) assigns a LABEL property to each source for use in several contexts as a shorter source identifier than the source name. Given a source name, one can easily find its LABEL by examining its source.stats FITS file. Given a source LABEL, to find the source name one must consult a table that lists LABELs and names for the entire catalog.

The collated FITS table itself can be searched for a list of LABELs using the tool ae_label2name.

Usage and Inputs
ae_label2name, labels, collated_filename, catalog_names, indexes

EXAMPLE:
.run acis_extract_tools

ae_label2name, ['101','202','303'], 'all.collated' ae_label2name, 3, 'all.collated' The parameter labels can either be a string array, or an integer. If an integer is supplied, then the tool prompts for you to enter the specified number labels.

Alternatively, such a table can be constructed in ASCII form using the LABEL_FILENAME option to the Collate Stage (§7.19), and then searched for a specific LABEL either manually or with grep. For example, if the Collate Stage has produced the ASCII table label.txt then this shell alias would change directories to the source with the specified label:

alias asl 'setenv LINE `grep -i "(\!:1)" label.txt`; echo $LINE; if ( "$LINE" != "" ) pushd `echo $LINE | cut -c 1-18`;'

7.20.2 Constructing Exposure Maps

Exposure maps can be conveniently constructed using the tool ae_make_emap.

Usage and Inputs
ae_make_emap, obsdata_fn, scene_name, CCD_LIST=value, ARDLIB_FILENAME=filepath, ASPECT_FN=filepath, PBKFILE=filepath, MASKFILE=filepath, MONOENERGY=value, SPECTRUM_FN=filepath, MATCHFILE=filepath, /ONLYTIME, /REUSE_ASPHIST, /REUSE_INSTMAP

EXAMPLE:
; Create an emap at 1 keV named 'fullfield_1' using six CCDs and an emap named 'iarray_1' using only ACIS-I.
.run acis_extract_tools

ae_make_emap, 'acis.evts', ['fullfield_1','iarray_1'], CCD_LIST=['012367','0123'], ARDLIB_FILENAME='./ardlib.par', ASPECT_FN='acis.asol1', PBKFILE='acis.pbk0', MASKFILE='acis.msk1', MONOENERGY=1.0

• A sub-directory asphist is created to hold aspect histogram and instrument map files.

• A pixel size of 1 sky pixel is normally used in the exposure maps. We recommend using the CIAO tool reproject_image to resample this high-resolution emap when you need an emap to match a specific field of view and binning scheme used in an image. However if you wish to directly compute an emap on a specific pixel grid, then supply a template image via the MATCHFILE parameter.

• Any event list containing exposure-related FITS keywords and the DETNAM keyword can be supplied as obsdata_fn.

• The name(s) of the exposure maps desired are supplied via the string scalar or vector scene_name.

• The list of CCDs to be used in each emap are supplied via the string scalar or vector keyword CCD_LIST. If omitted all CCDs are used.

• The ardlib.par file (configured for your observation), aspect file, parameter block file, and mask file required by the CIAO tools mkinstmap and mkexpmap are supplied via the keywords ARDLIB_FILENAME, ASPECT_FN, PBKFILE, and MASKFILE.

• For a mono-energy emap supply MONOENERGY (in keV) or let it default to 1.0. Alternatively you can pass a spectrum to mkinstmap via the keyword SPECTRUM_FN.

• If /ONLYTIME is specified then mkexpmap is told to model the HRMA and ACIS with a perfect QE, resulting in an exposure map the represents only the geometric effects of dithered chip edges and bad pixels.

• If /REUSE_ASPHIST is specified then any aspect histograms found from a previous run of the tool are re-used.
• If /REUSE_INSTMAP is specified then any instrument maps found from a previous run of the tool are re-used.

7.20.3 Grouping

AE's spectral grouping algorithm (§5.7) is available as a tool (ae_group_spectrum) that can be used to manually group a spectrum. The parameters of this routine are shown below:

Usage and Inputs
ae_group_spectrum, src_spectrum_fn, bkg_spectrum_fn, grouped_spectrum_fn, CHANNEL_RANGE=[value,value], SNR_RANGE=[value,value], NUM_GROUPS_RANGE=[value,value]

EXAMPLE:
.run acis_extract

ae_group_spectrum, '182029.89-161044.4.pi', '182029.89-161044.4_bkg.pi', '', SNR_RANGE=[5,10]

• The input (ungrouped) spectrum file name is specified as src_spectrum_fn.

• If you want group significance calculations to use the background, supply the background file name via bkg_spectrum_fn; otherwise supply the empty string.

• The output (grouped) spectrum file name is specified as grouped_spectrum_fn; set to the empty string to use an auto-generated name.

• The optional CHANNEL_RANGE, SNR_RANGE, and NUM_GROUPS_RANGE parameters are described in §7.18.

7.20.4 Time-resolved extractions

Time-resolved extractions can be performed with the tool ae_timerange_extract. The parameters of this tool are shown below:

Usage and Inputs
ae_timerange_extract, sourcename, obsname, time_filter, extraction_name

EXAMPLE:
.run acis_extract_tools
ae_timerange_extract, '182029.80-161045.5', '6420', '270786808.58:270854668.99', '6420.1'
ae_timerange_extract, '182029.80-161045.5', '6420', '270854678.71:270897521.73', '6420.2'
ae_timerange_extract, '182029.80-161045.5', '6420', '270897531.45:270938175.77', '6420.3'

• The time_filter input should be a string array of CIAO time specifications of the form "tstart:tstop".

• The extraction_name input should be a corresponding string array of names for the extractions.

7.20.5 Comparing data and PSF

The spatial distribution between a source's data and PSF can be visually compared with the tool ae_radial_profile. The tool's many parameters have appropriate default values when run from a single-ObsId extraction directory, e.g. <sourcename>/<obsname>/. However, with appropriate inputs you can run it on AE's multi-ObsId PSF and neighborhood event list.

EXAMPLE:
cd 182029.80-161045.5/6420/
idl
.run acis_extract_tools
ae_radial_profile

The KS_PSF value reported by the tool is the 1-sided KS probability, computed on the observed and model (PSF) encircled energy distributions via the AstroLib routine prob_ks. For example, a KS_PSF value of 0.90 means that if the parent distribution of the data is the same as the model, then 90% of observations (with the specified number of counts) should show a deviation from the model larger than what you actually observed. Thus, a very small value of KS_PSF is evidence that your source is NOT point-like.

If you look at the code for ae_radial_profile in acis_extract.pro you'll see a parameter ENERGY_RANGE (default = [1,2]) which specifies an energy filter applied to the data before analysis. Another parameter you might change is SRC_RADIUS, the size (in skypixels) of the circular aperture in which the data and PSF are compared.

The algorithm tries to put the analysis apertures at the centroid of the data and at the centroid of the PSF, i.e. it does not assume that the PSF you have constructed aligns perfectly with the data. Alignment is really important of course in radial profiles since a misplaced reference point will skew the profile.

Note that application of the CXC thread ``Improving the Astrometry of your Data: Correct for a Known Processing Offset'' will induce an offset between your data and the MARX PSF. We do not understand the header magic involved here, but fortunately this thread in not applicable to data re-processed after 2004.

7.20.6 Interface to ChaRT

I don't wish to speculate whether ChaRT-generated PSFs are significantly better than MARX-generated PSFs. One problem with ChaRT is that the number of rays you can obtain in one session is rather limited whereas MARX can easily provide a very large number of rays. A second problem arises from the fact that when ChaRT rays are fed through MARX one is forced to use MARX's internal dither model rather than your observation's actual aspect file (because ChaRT rays have no time tags). Although the celestial coordinates on the two results are the same, the detector coordinates are generally not the same (i.e. the source dithers over a different part of ACIS under the two simulations). The important effect seems to be non-zero values of dy and dz in the aspect file which (I think) represent motion of the SIM with respect to the HRMA. When the source is far from the edges of CCDs none of this matters, but when the actual source dithers across edges then it's vital that the simulated source dither the same way, something that the ChaRT work flow cannot reproduce.

Running ChaRT is not easy, but we've written a tool (ae_chart_interface) that calculates the ChaRT parameters you need, downloads the rays, and processes them into an AE-compatible set of PSF images. The ChaRT PSF is blurred by the same method used in AE (§5.1.2). For example, to create ChaRT PSFs for observation ``4495'' at the location of the source ``104357.47-593251.3'':

idl
  .run acis_extract_tools         
  ae_chart_interface, '104357.47-593251.3', '4495'

Supply the optional parameters /PIPELINE_RANDOMIZATION and/or /S_AIMPOINT, described in §7.6, as appropriate.

Then, cd to the source's observation directory and create a symbolic link that will cause the ChaRT PSFs to be used by AE:

cd 104357.47-593251.3/4495
mv source.psf AE_source.psf
ln -s chart_source.psf source.psf.

7.20.7 Printing spectra

The AE package includes a little Perl program plot_spectra.pl (originally developed by Franz Bauer) to print PostScript spectra produced by the AE fitting scripts, laid out 12 to a page.

EXAMPLE:
plot_spectra.pl 18*/nogrp_tbabs_vapec/ldata.ps

7.20.8 Reviewing spectral fits

The IDL program ae_spectra_viewer provides a graphical user interface to help the observer conduct a source-by-source review of multiple spectral models produced by multiple sessions of the FIT_SPECTRA stage. The observer is shown the fits results (parameter values, luminosities, and spectral plots) for all the models available for a given source, and the observer is able to designate the preferred model. That preference is stored in a FITS keyword (BEST_MDL) in the file holding the spectral models (source.spectra) and a symbolic link pointing to the preferred model is created; the preferred models can then be referenced in the COLLATED_FILENAME stage (§7.19).

This tool is a re-implementation of the Perl tool spectra_viewer.pl developed by Konstantin Getman. The X Windows program gv is used to display the Postscript spectra produced by XSPEC. You must have the GNU implementation of gv (version 3.6.1 or higher) in your Unix path.

Usage and Inputs
ae_default_model_preference, srclist_filename, hduname, /FORCE
ae_spectra_viewer, srclist_filename

EXAMPLE:
.run acis_extract_tools

; Set the default ``best model'' to ``nogrp_tbabs_vapec'' for all sources.
; Use /FORCE keyword to override any existing BEST_MDL values.
ae_default_model_preference, 'all.srclist', 'nogrp_tbabs_vapec'

; Interactively review each source.
ae_spectra_viewer, 'all.srclist'

; Collate the ``best model'' results.
acis_extract, 'all.srclist', COLLATED_FILENAME='best_model.collated', HDUNAME='BEST_MDL'

By careful construction of the source list passed to ae_spectra_viewer the observer can review the sources in whatever order is most convenient, or review only a subset of the catalog. For example you might collate (§7.19) the fit results from a standard model for the whole catalog, and then make a list of the sources with suspicious fit results for interactive review.

7.20.9 Catalog matching

The TARA package includes a tool (match_xy.pro) to match catalogs using positional uncertainties for individual sources and a match significance threshold, rather than using a fixed matching radius as is commonly employed. This tool can be used to match catalogs from different observatories, or can be used to find the intersection of Chandra source lists obtained from multiple source detection runs. (See §10.1 of the TARA User's Guide)

7.20.10 L^ATEX table generation

The long and complex IDL program hmsfr_tables (in acis_extract_tools.pro) produces several L^ATEX tables of AE results that we find useful in our star formation research. Stubs of these are shown in Figures 2, 3, and 4. Several IDL ``.sav'' files holding various source parameters are also produced. The main input is the FITS table containing collated AE results produced in §7.19; other inputs are briefly described in the code comments. This program has not yet been adequately documented, although the code comments give some information and it is used in our example recipe (§7.1).

7.20.11 Adding source properties

The little program ae_poke_source_property (in acis_extract_tools.pro) will ``poke'' a FITS keyword into the source.stats or obs.stats file for each source in the srclist. (Obviously this could be done with CIAO or HEASOFT tools as well.) Some observers might use such keywords to carry ancillary information about sources.

7.20.12 Performing a spectral fit using an existing script

The code the AE fitting stage uses to spawn XSPEC and manage the data products produced has been pulled out into a separate routine ae_perform_fit which can be used to execute an existing XSPEC script created by the fitting stage. This might be useful if you have hand-edited the script for some reason.

EXAMPLE:
.run acis_extract
ae_perform_fit, '181948.82-160624.2', 'nogrp_tbabs_vapec'

• The first input is the name of an AE source.
• The second input is the name of the XSPEC script (without the .xcm extension), assumed to be in <source>/spectral_models/.

7.20.13 Scanning for Residual Afterglow Events

An example of using the tool ae_afterglow_report is shown in recipe.txt.