subspace

Context: concept

Synopsis

Describes the filtering applied to a file

Description

The subspace is a history of all filtering applied to a file (e.g. selection of a source region, flaring interval, etc.). Having this recorded in a data file header allows subsequent tools to extract appropriate calibration information. The subspace also allows users to see how the data file has been altered during analysis. All tools that use the Data Model I/O library propagate the data subspace.

An example of the subspace of an event list is shown below (as output by dmlist). As can be seen, the file only contains events on ACIS-I3 (chip_id = 3) that have a grade of 0,2,3,4 or 6. No spatial filtering has been applied to the file, since the spatial columns - e.g. chip, tdet, det, and sky - still contain the default values.


dmlist acisi3.fits subspace

------------------------------------------------------------------
Data subspace for block EVENTS: Components: 1 Descriptors: 15 	  
------------------------------------------------------------------
 
 --- Component 1 --- 
  1 time      Real8       TABLE GTI3
                          
                           68100824.64862958:   68104649.02862957
                           68104681.43862958:   68107857.61862957
                           68108862.32862958:   68111920.76850605
  2 ccd_id    Int2        3:3 
  3 node_id   Int2        0:3 
  4 expno     Int4        0:2147483647 
  5 chip      [ 1] chipx  1:1024 
  5 chip      [ 2] chipy  1:1024 
  6 tdet      [ 1] tdetx  1:8192 
  6 tdet      [ 2] tdety  1:8192 
  7 det       [ 1] detx       0.50:     8192.50 
  7 det       [ 2] dety       0.50:     8192.50 
  8 sky       [ 1] x          0.50:     8192.50 
  8 sky       [ 2] y          0.50:     8192.50 
  9 pha       Int4        0:36855 
 10 energy    Real4       0:    1000000.0 
 11 pi        Int4        1:1024 
 12 fltgrade  Int2        0:255 
 13 grade     Int2        0:0,2:2,3:3,4:4,6:6 
 14 status    Bit         
 15 phas      Int2        -4096:4095

If the event file were to be filtered using "sky=circle(4324,3676,50)", the subspace would change to (showing only the changed values):

dmlist "acisi3.fits[sky=circle(4324,3676,50)]" subspace
...
  8 sky       Real4       Rectangle(4274,3626,4374,3726)&Circle(4324,3676,50)
  8 sky       Real4       Field area = 6.71089e+07 Region area = 7853.7
	      		  
  8 sky       [ 1] x           4274.0:     4374.0 
  8 sky       [ 2] y           3626.0:     3726.0

The subspace as given above can be read as a statement that the events in the file are drawn from the intersection (logical AND) of the listed restrictions: they must have sky values in the given range AND time values in the given range AND ..., etc. In general, a complicated filter may involve unions (logical OR). The most common way this arises is when two files with different subspaces are merged. Suppose we do

dmcopy "acisi3.fits[sky=circle(4324,3676,50)]"  acisi3_circle.fits
dmcopy "acisi3.fits[energy=1000:2000]" acisi3_energy.fits
dmmerge acisi3_circle,fits,acisi3_energy.fits outfile=merge.fits
dmlist merge.fits subspace

We will now get two parts ('components') to the subspace, since the data is drawn from the union of two sets: photons which have 'sky in this circle' OR 'energy in this range'.

In particular, for ACIS data we have different time filters for each chip. This is because the frame start times for each chip are fractionally different, and because dropouts or saturation can happen at different times for different chips. Therefore, we have at least one subspace component for each chip in ACIS data; this is reflected by the presence of one GTI extension per chip (good time intervals, giving the times for that particular chip). In CIAO, the GTIs familiar to users of X-ray data from other missions are considered part of the more general idea of a data subspace. We read the event subspace as 'photons are drawn from (ccd = 3 AND time in GTI3) OR (ccd = 4 AND time in GTI4) OR ...'. If you filter the resulting event file with a simple filter like 'energy=1000:200', that filter will be intersected with each of the components. However, note that by merging two multiple-GTI ACIS event files with different filters you can generate a more complex filter which has more than one GTI per chip.

Editing the subspace

Users have the capability to delete subspace keys for specified columns, e.g.

unix% dmcopy "evt2.fits'[subspace -col1,-col2..]" evt2_subspace.fits

This is necessary, for instance, to merge two files with different EXPNO (ACIS frame exposure number) values and have accurate GTI information in the output. Use this capability carefully, though, as altering the subspace may cause the file to not work properly with other CIAO tools.

Example

(1) dmlist infile=acis_evt2.fits opt=subspace

Display the subspace of the FITS file 'acis_evt2.fits' to the screen.