Fermi Gamma-ray Space Telescope

Data SubSpace keywords (DSS)

The Data Subspace keywords scheme was introduced for recording data selection criteria in a systematic manner.

A filtering condition is expressed with a set of three or four keywords, DSTYP1, DSUNI1, DSVAL1, and DSREF1. For example, if we select events in a given time interval, i.e. TIME>start_time&&TIME<end_time, the filtering condition can be stored as

DSTYP1 = 'TIME'
DSUNI1 = 's   '
DSVAL1 = 'start_time:end_time'
We can put multiple ranges in DSVAL1 by deliminating each range with kamma. For instance,
DSVAL1 = 'start_time1:end_time1,start_time2:end_time2,start_time3:end_time3'
Open ranges like ENERGY>10MeV and ENERGY<100GeV are respectively expressed as
DSTYP1 = 'ENERGY'
DSUNI1 = 'MeV   '
DSVAL1 = '10:'
and
DSVAL1 = ':100000'
If there are many ranges, it is better to store them in a table and the filtering condition is described as
DSTYP1 = 'TIME'
DSUNI1 = 's   '
DSVAL1 = 'TABLE'
DSREF1 = ':GTI'
A position filtering using a REGION descriptor can be stored as
DSTYP1 = 'POS(RA,DEC)'
DSUNI1 = 'deg'
DSVAL1 = 'CIRCLE(100,120,10)'
More complicated region can be stored in a REGION extension table, and the DSS keywords are given as
DSTYP1 = 'POS(RA,DEC)'
DSUNI1 = 'deg  '
DSVAL1 = 'TABLE'
DSREF1 = ':REGION'


For a second selection condision, we can add a new element using DSTYP2, DSUNI2, DSVAL2, and DSREF2 . The selection condition of
(CLASS.eq.0).and.(ENERGY.gt.10(MeV))
can be stored as
DSTYP1 = 'CLASS'
DSVAL1 = '0'
DSTYP2 = 'ENERGY'
DSUNI2 = 'MeV'
DSVAL2 = '10:'
More general selection condision can be described by intoroducing a new component. Keywords utelized are iDSTYPj, iDSUNIj, iDSVALj, and iDSREFj, insted of DSTYPj, DSUNIj, DSVALj, and DSREFj, where I call i and j, the component and element index, respectively. Different elements belonging to the same component are combined with "AND" operation, whereas the individual components are combined with "OR" operation. For instance,
GTI(TIME).and.(CLASS.eq.0.or.CLASS.eq.1) ,
which is equivalent to
(GTI(TIME).and.CLASS.eq.0).or.(GTI(TIME).and.CLASS.eq.1) ,
is stored as
DSTYP1  = 'TIME'
DSUNI1  = 's   '
DSVAL1  = 'TABLE'
DSREF1  = ':GTI'
DSTYP2  = 'CLASS'
DSVAL2  = '0'
2DSVAL2 = '1'
The convension here is that the filter in components 2 working on the same parameter must share the same element number so that 2DSTYPj and 2DSUNIj can be omitted. If the value is also the same, 2DAVALj (and 2DAREFj) need not to be provided.

Example in LAT data analysis

  1. U1
  2. For example, a data set is extracted from the data base by specifying a circular sky region and a time interval. A new GTI should be created from the user's specified time interval and the original GTI from the data base. The event summary fits file thus created should have the DSS keywords as

    DSTYP1  = 'TIME'
    DSUNI1  = 's   '
    DSVAL1  = 'TABLE'
    DSVAL1  = ':GTI'
    DSTYP2  = 'POS(RA,DEC)'
    DSUNI2  = 'deg '
    DSVAL2  = 'CIRCLE(120.3,34.5,5.0)'
    

  3. U2
  4. Whenever a new data selection condition performed with the user-level data extractor (U2), new DSS keywords needs to be added or they need to be modified. For example, if a zenith angle cut (zenith < 40 degree) and event class selection (CLASS.eq.0.or.CLASS.eq.1) are applied, the DSS keywords may then become

    DSTYP1  = 'TIME'
    DSUNI1  = 's   '
    DSVAL1  = 'TABLE'
    DSVAL1  = ':GTI'
    DSTYP2  = 'POS(RA,DEC)'
    DSUNI2  = 'deg '
    DSVAL2  = 'CIRCLE(120.3,34.5,5.0)'
    DSTYP3  = 'ZENITH'
    DSUNI3  = 'deg '
    DSVAL3  = ':40'
    DSTYP4  = 'CLASS'
    DSVAL4  = '0'
    2DSVAL4 = '1'
    
    This indicates
    (GTI(TIME).and.CIRCLE(120.3,34.5,5.0,RA,DEC).and.ZENITH.le.40.and.CLASS.eq.0).or.
    (GTI(TIME).and.CIRCLE(120.3,34.5,5.0,RA,DEC).and.ZENITH.le.40.and.CLASS.eq.1)
    

    For some data selection condition, e.g. geomagnetic field cuts, count rate cuts, etc, only modifies the GTI, there is no need to add or modify the DSS keywords.

  5. Binning
  6. When the events are binned into histograms, additional selection may be put. When an energy spectrum is extracted from a circular region centered on a point source, e.g. CIRCLE(120.3,34.5,1.0,RA,DEC), the FITS header of the PHA file derived should look as

    DSTYP1  = 'TIME'
    DSUNI1  = 's   '
    DSVAL1  = 'TABLE'
    DSVAL1  = ':GTI'
    DSTYP2  = 'POS(RA,DEC)'
    DSUNI2  = 'deg '
    DSVAL2  = 'CIRCLE(120.3,34.5,5.0)'
    DSTYP3  = 'ZENITH'
    DSUNI3  = 'deg '
    DSVAL3  = ':40'
    DSTYP4  = 'CLASS'
    DSVAL4  = '0'
    2DSVAL4 = '1'
    DSTYP5  = 'POS(RA,DEC)'
    DSUNI5  = 'deg '
    DSVAL5  = 'CIRCLE(120.3,34.5,1.0)'
    
    Since 'CIRCLE(120.3,34.5,1.0)' is included by 'CIRCLE(120.3,34.5,5.0)', the latter selection condition may be removed from the keyword. (I don't know whether it should be done or not.)

Complicated filters

Energy dependent inclination angle cut
DSTYP1 = 'THETA(ENERGY)'
DSUNI1 = 'deg(MeV)'
DSVAL1 = ':50.0*(1+10.0*(30.0/ENERGY))'
Energy-and-inclination-angle dependent zenith angle cut
DSTYP1 = 'ZENITH_ANGLE(ENERGY,THETA)'
DSUNI1 = 'deg(MeV,deg)'
DSVAL1 = ':80.0*(1-10.0*(30.0/ENERGY))*(1-THETA/60)'
Circle with energy-dependent radius
DSTYP1 = 'POS(X,Y)(ENERGY)'
DSUNI1 = '(MeV)'
DSVAL1 = 'CIRCLE(120.3,34.5,5.0*30.0/ENERGY)'
Another possible way to express regions is to give with a table
DSTYP1 = 'POS(X,Y)'
DSVAL1 = 'TABLE'
DSREF1 = ':REGION'
The 'REGION' extension table would look like
EMIN   EMAX   SHAPE   X       Y      R    COMPONENT
30     50     CIRCLE  120.3   34.5   5.0      1
50     100    CIRCLE  120.3   34.5   4.8      2
.
.
.
.
10000  30000  CIRCLE  120.3   34.5   0.5    100