Describes the filtering applied to a file
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.
(1) dmlist infile=acis_evt2.fits opt=subspace
Display the subspace of the FITS file 'acis_evt2.fits' to the screen.
- coords, level, pileup, times
- autoname, ciao, ciao-install, ciaorc, history, parameter, stack
- dm, dmascii, dmbinning, dmfiltering, dmmasks, dmopt, dmregions
- dither_region, dmcontour, dmcoords, dmcopy, dmextract, dmgroupreg, dmimgdist, dmimgfilt, dmimghull, dmimglasso, dmlist, dmmakereg, dmstat, get_src_region, mkbgreg, mksubbgreg, roi, splitroi, tg_create_mask