3.1 Inputs to AE

In the extraction example below we make use of some helpful AE ``driver'' programs found in the file ae_recipe.pro. Those programs require that we establish a standard directory structure holding the usual CIAO data products that any extraction tool/recipe would require as input. Figure 1 shows an example AE directory structure. The best way to set this up is to create Unix symbolic links pointing to your various CIAO input data products as described below.

Figure 1: Example of a standard AE directory structure. Boldface directories and files are created by the observer; others are output products created by AE or by the recipe tools ae_source_manager, ae_make_catalog, ae_standard_extraction, and ae_better_backgrounds.

1. Choose a name for the observation, typically the observation ID number (e.g. ``1875''), which will be used in two places below.

2. Make an ``observation directory'' (using the naming convention obs$<$name$>$) to hold the inputs to AE. For example:

     mkdir obs1875
   

3. In the observation directory make a symbolic link named spectral.evt to a Level 2 event list that is suitable for spectral extraction (§7.3). For example:

     cd obs1875
     ln -s ../primary/acis*evt2.fits  spectral.evt
   

4. Make a symbolic link named obs.emap to a CIAO exposure map that corresponds to the field of view of the event data you are giving to AE (§7.3). For example:

     ln -s ../full_field.emap  obs.emap
   

   The CXC provides threads and scripts for constructing exposure maps. We use the tool ae_make_emap (§7.20).

5. Make a symbolic link named asphist to a directory containing aspect histogram files for each active CCD with the names ccd0.asphist, ccd1.asphist, ... Aspect histograms are required by the CIAO tool mkarf, and are a by-product of constructing an exposure map (§ 7.9). In the following example a symbolic link is made to such a directory left over from using the tool ae_make_emap (§7.20) to construct an exposure map; if you build the exposure map another way then simply make a directory named asphist and copy the aspect histograms there, using the specified naming convention. For example:

     ln -s ../asphist  asphist
   

6. Make a symbolic link named obs.asol to a CIAO aspect file covering the time range of your observation¹. You will have located this file in order to make the aspect histograms above. For example:

     ln -s ../primary/pcad*asol1.fits  obs.asol
   

7. If you wish the CIAO tools mkarf/mkwarf to apply the ``Dead Area calibration'' then make a symbolic link named obs.pbkfile to the observation's ``parameter block file''. For example:

     ln -s ../secondary/acis*pbk0.fits  obs.pbkfile
   

8. Make a symbolic link named obs.mskfile to the observation's ``mask file'', which is used by mkarf and mkwarf. For example:

     ln -s ../secondary/acis*msk1.fits  obs.mskfile
   

9. Make a copy of the CIAO parameter file ardlib.par, properly configured for your observation. There is a CIAO thread that discusses the CIAO script acis_set_ardlib. See §7.9 for instructions for configuring the parameters AXAF_ACIS?_QEU_FILE and AXAF_RMF_FILE when the event data have been through the Townsley et al. CTI corrector. For example:

     punlearn ardlib
     acis_set_ardlib primary/acis*bpix1.fits absolutepath=yes
   

10. Determine where CIAO has stored the ardlib.par you just modified, copy it to the observation directory, and protect it from accidental modification.

      cp  `paccess ardlib w` ./ardlib.par
      chmod a-w ./ardlib.par
      
      plist ./ardlib.par | more
    

11. As a sibling to the observation directory, make a directory named point_sources in which AE will be executed and to which AE will write its output. For later convenience, find on your system the directory xspec_scripts included with the AE package and make a symbolic link to it in the run directory. For example:

      cd ..
      mkdir point_sources
      cd point_sources
      ln -s /path/to/my/local/AE/package/xspec_scripts .
    

Identify point sources by whatever means you choose (e.g. wavdetect, human examination of the data, etc.). Source detection is of course a complex subject, and is beyond the scope of this manual. Read into IDL the celestial coordinates of the sources in units of decimal degrees; the specific IDL commands needed depend on how you record the source list; two examples are shown below. Be sure to use adequate precision for the coordinates; any ASCII representation of the coordinates should use 6 digits to the right of the decimal, and I/O in IDL should be done in DOUBLE precision.

For all AE runs we strongly recommend that you start IDL in such a way that all screen output is saved to a log file, e.g. via the Unix command tee shown below. Such a log file will record the CIAO commands AE runs on your data, and is very helpful for investigating problems.

  idl |& tee -a AE_simple_run.log
    
    ; For a FITS catalog from wavdetect:
    bt  = mrdfits('wavdetect_src.fits', 1)
    RA  = bt.RA
    DEC = bt.DEC
    
    
    ; OR, for an ASCII file (e.g.\ a ds9 region file) saved in decimal celestial coordinates:
    readfmt, 'catalog.reg', '8x,D,D', RA, DEC
    ; The 8x part of the format specification should be adjusted to 
    ; skip over whatever prefix appears in each row, e.g.\ "ellipse(".
    ; The "D" format codes force RA and DEC to be DOUBLE precision vectors.