Subsections

• 7.12.1 Usage and Inputs

7.12 COLLATED_FILENAME Stage

This stage is run to collate all source parameters into a large FITS table (one source per row).

7.12.1 Usage and Inputs

acis_extract, srclist_filename, obsname, /SINGLE_ObsId, COLLATED_FILENAME=filepath, HDUNAME=name, REGION_FILE=filepath, REGION_TAG=value, LABEL_FILENAME=filepath, MATCH_EXISTING=filepath

EXAMPLE:

acis_extract, 'all.srclist', COLLATED_FILENAME='all.collated', HDUNAME='BEST_MDL', REGION_FILE='all.reg'

• The multi-ObsId source parameters in source.stats (e.g. position estimates) are reported.

• If the optional parameter obsname is supplied then the observation-specific contents of */<obsname>/obs.stats are reported. If obsname is omitted then each source reports obs.stats values from whichever observation was the deepest (largest exposure map value) for that source. The name of the deepest observation is reported in the table column PRIM_OBS.

• The source parameters in source.photometry are reported.

• The fitting results from one spectral model are reported. The optional keyword HDUNAME (FITS Header Data Unit Name) can be used to specify the preferred spectral model (name of the preferred HDU in the FITS file source.spectra) when multiple models have been run. HDUNAME can be a scalar string if the same preference applies to all sources or can be a string vector. Four types of values for HDUNAME are supported:
  1. If HDUNAME is the reserved string ``BEST_MDL'' (best model) then AE looks for the FITS keyword BEST_MDL in the Primary HDU of the file source.spectra to obtain the name of the preferred model. An interactive tool for observers to review spectral models and record preferences in BEST_MDL is provided in §7.14.

  2. If HDUNAME is a simple string (e.g. ``nogrp_tbabs_vapec'') then AE looks for a spectral model (HDU) with that name.

  3. If HDUNAME is a pattern containing wildcards recognized by the IDL routine strmatch (e.g.``*tbabs_vapec'') then the most recent spectral model with a matching name is used. This construct is handy when grouped spectra are fit since the group size prefix in the model name can vary between sources.

  4. If HDUNAME is omitted or is the empty string then the most recent spectral model (last HDU in source.spectra) is used.

• The optional REGION_FILE parameter specifies the name to use for a region file AE will construct containing extraction regions from the most crowded of the observations merged, position markers, and labels for all the sources in the catalog. The optional REGION_TAG parameter (scalar or vector string) specifies an additional ``tag'' that will be assigned to the DS9 regions.

• If the optional parameter /SINGLE_ObsId is specified then
  • observation-specific source properties (from obs.stats) take precedence over multi-ObsId properties of the same name (from source.stats).
  • Photometry and spectral fitting information (both multi-ObsId entities) are not reported.

• The optional LABEL_FILENAME parameter specifies the name of an ASCII table that will be written listing each source's name and LABEL.

• The optional MATCH_EXISTING parameter can be used to explicitly define the columns desired in the collated table, saving about half of the run time of this stage. If the specified collated filename already exists and you simply wish to update its contents then specify /MATCH_EXISTING. If you wish to use the same tables columns found in another collated file, then pass its name (e.g. MATCH_EXISTING=template.collated). If you have a template structure already defined in IDL, then pass that structure (e.g. MATCH_EXISTING=collated_table).

Some accessory tools are available for working with spectral fit results. See §7.14. The FITS binary table produced by this stage can of course be examined and manipulated by standard FITS tools, e.g. fv in HEASOFT or chips in CIAO. The Event Browser application in the TARA package can also be pressed into service for browsing any FITS binary table, e.g. the table of source parameters produced by the COLLATED_FILENAME stage. Start Event Browser with the /GENERIC keyword. The table columns can be examined in various ways, e.g.:

• plot one column as a function of another (function_1d)
• compute univariate distribution of a column (dataset_1d)
• compute bivariate distribution of two columns (dataset_2d)
• compute trivariate distribution of three columns (dataset_3d)
• compute a statistic map using three columns (dataset_3d)
• examine how the distribution of one column depends on another column (trend_1d)