Subsections

• 7.2.1 Source Lists and Catalogs
• 7.2.2 Source Management Tools
• 7.2.3 Source List to Catalog

7.2 Source Management

7.2.1 Source Lists and Catalogs

The first input parameter to all stages of AE is the name of an ASCII file containing a list of sources that should be processed. Usually this list will include all the sources you're working with, but in some stages it is useful to define subsets of sources that should be processed in different ways, e.g. sets of sources to be fit with different spectral models.

For the first stage (CONSTRUCT_REGIONS) of AE, this file must be a table consisting of 5 whitespace-separated columns specifying the fundamental parameters of each source:

1. source name (e.g. ``182001.09-160717.1''); used to name the Unix directory that will hold the source's data products. A typical source name would be constructed from the coordinates with this IDL expression:
   strcompress(/REMOVE_ALL, adstring( ra, dec, 1, /TRUNCATE))

   Note that when when the ``precision'' parameter to adstring() is zero, standard CXC names of the form ``182001.9-160717'' are built. In crowded fields where those names may not be unique observers may wish to use a precision value of 1 to build names of the form ``181913.56-160129.9''.

2. RA (in degrees); 6 digits to the right of the decimal are recommended.

3. DEC (in degrees); 6 digits to the right of the decimal are recommended.

4. desired PSF fraction ($< 1.0$); controls the relative size of the extraction region.

5. ``primary'' PSF energy, i.e. energy (in keV) at which that PSF fraction is to be computed. A value of 1.5 keV is recommended for most sources since the observed spectrum generally peaks near there, however you are free to choose another energy.

We refer to this 5-column table as a ``catalog''. All other stages of AE require only a list of source names. These stages will accept either a 5-column catalog, or a 1-column list of source names, referred to as a ``source list''. In both catalogs and source lists, lines starting with a semicolon are interpreted as comments. Here's an example of the format of a catalog:

; Comments start with semicolon.
181913.56-160129.9 274.806530 -16.024992 0.90 1.4967
181913.69-160110.5 274.807070 -16.019584 0.90 1.4967
; Comments can be anywhere.
181914.42-161234.6 274.810120 -16.209638 0.90 1.4967
181922.01-160314.9 274.841730 -16.054165 0.90 1.4967

7.2.2 Source Management Tools

The overall process of identifying and extracting sources can become complex if your data are complex and you take a very careful approach. The first problem is that the catalog may need to change over time. At multiple points in the data reduction process you may identify candidate sources that you wish to remove, you may identify new sources you wish to add, and you may choose to reposition existing sources, e.g. using position estimates computed by AE (§7.17). Usually, when a source's position is changed you will want to rename it, a task that involves changing both the catalog and the source's extraction directory. In crowded fields, the second problem is figuring out suitable values for the PSF fraction column of the catalog which avoid excessive overlap of neighboring extraction regions.

Two tools that operate ``on top of'' AE are provided (in ae_recipe.pro) to help the observer manage the sources, as shown in §3. The first tool, ae_source_manager, is used to create, remove, and re-position sources. The second tool, ae_make_catalog, builds an AE catalog file with PSF fractions which avoid overlapping extractions in crowded areas.

ae_source_manager
This tool creates, removes, and re-positions sources by manipulating a master source list (stored in the file all.srclist) and by manipulating AE source extraction directories. The ways it can be used are described below. All the inputs can be either scalars or vectors to manipulate one or multiple sources.

• To create a source, use /ADD and provide the coordinates.
  ae_source_manager, /ADD, RA=ra, DEC=dec, POSITION_TYPE='wavdetect'
  • The required keyword POSITION_TYPE should be a string (or string vector) describing the method used to estimate the source position. This information becomes the POSNTYPE source property (in source.stats).

  • The optional keyword PROVENANCE can be used to provide a string (or string vector) describing how each source was detected, e.g. ``wavdetect'', ``reconstruction'', ``by eye'', etc. This information becomes the PROVENAN source property (in source.stats).

  • The optional keyword LABEL can be used to provide a string that will be used to label the source in ds9 region files. If omitted the sequence number of the source is used.
  An AE extraction directory is created for the source in order to store the information provided.

• To remove a source, use /REMOVE and identify the source either by its name or label.
  ae_source_manager, /REMOVE, NAME ='104418.06-593059.4'
ae_source_manager, /REMOVE, LABEL='154'
  • The optional keyword TRASH_DIR can be used to specify a directory to which the obsolete AE extraction directories will be archived. If omitted the directory ./trash will be used.
  Entries for obsolete sources are commented out in (not removed from) the master source list (all.srclist).

• To re-position a source, use /MOVE, identify the source either by its name or label, and provide the new coordinates.
  ae_source_manager, /MOVE, POSITION_TYPE='by_eye', RA=ra, DEC=dec, NAME ='104418.06-593059.4'
ae_source_manager, /MOVE, POSITION_TYPE='by_eye', RA=ra, DEC=dec, LABEL='154'
  • The required keyword POSITION_TYPE should be a string (or string vector) describing the method used to estimate the revised source position.

  • Normally the source is renamed using the new coordinates, both in the master source list and in the extraction directory. If /NO_RENAME is specified the original name is retained.

• To re-position a source to either the ``mean data'' or ``correlation'' or ``reconstruction'' positions computed by AE (§7.17), use /UPDATE_POSITIONS_DATA or /UPDATE_POSITIONS_CORR or /UPDATE_POSITIONS_RECON and identify the source either by its name or label.
  ae_source_manager, /UPDATE_POSITIONS_DATA, NAME ='104418.06-593059.4'
ae_source_manager, /UPDATE_POSITIONS_CORR, LABEL='154' The POSNTYPE source property is updated to reflect the type of position adopted for the source. If the position estimates you wish to apply were computed on a named merge (§7.16), then be sure to supply that merge name via the MERGE_NAME parameter.

• To sort the source list by RA and relabel by sequence number, use /SORT_RA and /SET_LABEL_AS_SEQUENCE.
  ae_source_manager, /SORT_RA
ae_source_manager, /SET_LABEL_AS_SEQUENCE

• To sort the source list by distance from the middle of the field and relabel by sequence number, use /SORT_BULLSEYE and /SET_LABEL_AS_SEQUENCE. This labeling may be more convenient for locating specific sources in ds9 during the data reduction process.
  ae_source_manager, /SORT_BULLSEYE
ae_source_manager, /SET_LABEL_AS_SEQUENCE

When sources are added, removed, or re-positioned the most straightforward strategy is to simply repeat your entire extraction recipe. Of course if you want to invest additional effort to save computer run time, you can run AE on a smaller source list containing only the sources which need to be reprocessed. Note that the de-crowding algorithm in the tool ae_make_catalog (below) cannot work properly if only a subset of the source list is processed.

ae_make_catalog
This tool uses the source information stored in AE extraction directories (by ae_source_manager) to iteratively define extractions which seek to avoid overlapping extractions in crowded areas. In the process of determining PSF fractions, the CONSTRUCT_REGIONS and EXTRACT_EVENTS stages of AE are executed. This tool requires you to have set up a set of standardized paths to the input files needed by AE, as shown in the Getting Started section (3) and example recipe. The tool requires two parameters:
ae_make_catalog, '1875', EVTFILE\_BASENAME='spectral.evt'

• The tool uses the observation name (obsname) parameter to construct a directory path ../obsXXXX/ where it expects to find various observation data products (with the standard names used by our AE recipe).
• The EVTFILE_BASENAME parameter specifies the filename for the event list (in ../obsXXXX/) from which you wish to extract background spectra.

• The optional keyword parameter SRCLIST_FILENAME can be used to specify a source list other than the default, all.srclist.
• The optional keyword parameter NOMINAL_PSF_FRAC can be used to specify a nominal PSF fraction for isolated sources other than the default, 0.90.
• The optional keyword parameter MINIMUM_PSF_FRACTION can be used to specify a minimum PSF fraction other than the default, 0.40.
• The optional keyword parameter REGION_ONLY can be used to specify that PSFs should be constructed for only the nominal energy, saving computer time.
• If the optional keyword parameter SHOW is set to zero, then the ds9 visualization normally spawned will be skipped.
• Any other keyword parameters supplied are passed on to the CONSTRUCT_REGIONS stage of AE.

Three files pertaining to the whole source list are written to the observation directory (e.g. ../obs1875/):

obs.cat

An AE catalog containing the sources observed in this ObsId, with the PSF fractions adjusted to avoid overlapping extraction regions.

extract.reg

A ds9 region file showing the positions and extraction regions for all the sources.

obs.collated

A FITS table containing all the source properties (§7.19) for the sources observed in this ObsId.

Since extraction regions have a minimum size (controlled by parameter NOMINAL_PSF_FRAC) very crowded sources will have overlapping regions. A measure of each source region's overlap with its neighbor is saved in the source property OVERLAP in obs.stats.

7.2.3 Source List to Catalog

There may be rare occasions where an observer would like to construct a catalog from the source information (position, PSF fraction, PSF energy) stored in the source extraction directories. AE includes a stage called NEW_CATALOG which does this. Recall that catalogs are observation-specific (because PSF fractions for a source could be different for each observation). In the example below the observation is named ``1875''.

  acis_extract, 'all.srclist', '1875', NEW_CATALOG='all_revised.cat'