DSS keywords

We use these keywords to store information in our FITS headers about the cuts that have been applied to the data. Here is a description of the DSS keywords prepared by Yasushi Ikebe. (This page links to documents from Jonathan McDowell at the Chandra X-ray Center, but the link is broken. Here is the new location of those documents. In particular, see section 1.13 of SDS07. Note that the CXC descriptions are not our specifications. Those are given here and in Yasushi's page.)

Implementation

A set of classes to manage data cuts has been implemented in the dataSubselector package. These classes are now used by the observationSim and Likelihood packages for managing the data selections. Use of these classes has several consequences:

• Since the cut information is encoded in the DSS FITS header keywords, there is now a mechanism for verifying that the various files used in any given analysis, e.g., event files, maps of live time, Likelihood's exposure maps, have been created assuming a consistent set of data selections. This checking is being performed by the Likelihood applications.

• Likelihood requires a specific set of DSS selections for its analysis:
  • exactly one event class cut
  • exactly one acceptance cone cut
  • exactly one energy range cut
  • time range cuts encoded in the GTI extension
    Downstream cuts maybe applied to an FT1 file with existing cuts, and as long as the net effect of all of the cuts can be represented by the above list, the resulting FT1 file will be valid for analysis. Fully nested acceptance cone cuts can be represented completely by just the innermost acceptance cone and would thus be OK, but two acceptance cone cuts of the same radius but not centered on the same sky location cannot be represented by a single cut and would thus not be valid for analysis.

• Other cuts may be applied (e.g., via fcopy), but likelihood may not check for them or use them in the analysis, so the user still has to understand the consequences of applying other cuts.

• In gtobssim, one can specify an acceptance cone on the sky for filtering the events that are output to the FT1 file(s). There are now also hidden emin, emax parameters for gtobssim, and a GTI extension, comprising the full simulation time, is written to the FT1 file output. So if an acceptance cone is specified, these form a complete set of cuts for likelihood.

• If an acceptance cone is not specified in gtobssim (or by any other means, e.g., via such selection using the GSSC data server), one must use the gtselect tool to specify the ROI for likelihood.

• In gtselect, the application of the data selections are made using the extended filename format of cfitsio.
  • For Pass 6 data, event class cuts were specified in via a filter string like this:

    "EVENT_CLASS >= 2"

    This was possible because the event classes were nested and the desired events could be selected using this filter.
  • For Pass7 data, the event classes are not nested at the less restrictive event selections, so it was decided that the EVENT_CLASS field would instead be interpreted as a bit field, with each bit indicating membership of an event to the corresponding event class. To select a given event class, a bit mask with the corresponding bit set is applied to the EVENT_CLASS variable:

    "((EVENT_CLASS/4)%2 == 1)"

    cfitsio does have the ability to apply a bit mask using "EVENT_CLASS & 4", but that requires the column in the FT1 file to be defined as a bit field. In the current definition, it is an integer.

Examples

• Acceptance cone cut centered at RA, Dec = 166.1138, 38.2088 J2000 degrees with a 15 deg radius:

  DSTYP1 = 'POS(RA,DEC)' DSUNI1 = 'deg ' DSVAL1 = 'CIRCLE(166.1138,38.2088,15)'

• Time range cuts. These are encoded in the GTI extension.

  DSTYP2 = 'TIME ' DSUNI2 = 's ' DSVAL2 = 'TABLE ' DSREF2 = ':GTI '

• Event class selection. The bit-mask selection is defined using this "BIT_MASK" function that has three arguments:
  • FT1 column name
  • Bit to set in the mask
  • Pass version as given in the PASS_VER keyword in the FT1 EVENTS extension. This needs to be encoded in the BIT_MASK function designation so that it is propagated to downstream files (such as exposure maps) so that the IRF handling code can determine the IRFs to use based on the event selection and the
    information in CALDB.

    DSTYP3 = 'BIT_MASK(EVENT_CLASS,2,P7V6)' DSUNI3 = 'DIMENSIONLESS' DSVAL3 = '1:1 '

• Energy range selection.

  DSTYP4 = 'ENERGY ' DSUNI4 = 'MeV ' DSVAL4 = '100:300000'

• Zenith angle cut. This is needed by gtmktime to determine the time intervals in the FT2 file for which the the acceptance cone is completely contained within the maximum zenith angle. The accepted intervals are then expressed as GTIs. This cut is not strictly required by the likelihood tools (aside from gtmktime), but it is generally needed to remove Earth limb contamination.

  DSTYP5 = 'ZENITH_ANGLE' DSUNI5 = 'deg ' DSVAL5 = '0:105 '