How can I define a region around a single chip?

It is often desireable to define a region in sky coordinates that covers a single ACIS CCD (the "Why filter on sky coordinates" FAQ entry contains several reasons why this is useful).

The regions can be created with the skyfov tool. This tool is used to create the sky field of view (FOV) file included in the standard data distribution for observations processed with ASCDSVER 6.9.0 or later; these files have names like acisf03519_000N001_fov1.fits.

The skyfov tool requires the event file and, optionally, the aspect solution and mask file of the observation. It creates a region file which contains a polygon describing each chip. In the example below we show how it can be used with the aspect solution; see the help file for further information on the tool.

unix% punlearn skyfov
unix% skyfov acisf00578N003_evt2.fits chips.reg aspect=pcadf052378346N003_asol1.fits 

The output file - in this example chips.reg, but the *fov1.fits also follow the same format - is a FITS-format region file with columns that look like:

unix% dmlist chips.reg cols

--------------------------------------------------------------------------------
Columns for Table Block FOV
--------------------------------------------------------------------------------
 
ColNo  Name                 Unit        Type             Range
   1   POS(X,Y)[13]         pixel        Real8(13)      -Inf:+Inf            Position
   2   SHAPE                             String[16]                          Region shape type
   3   R[2]                 pixel        Real8(2)       -Inf:+Inf            Radius
   4   ROTANG[2]            pixel        Real8(2)       -Inf:+Inf            Angle
   5   COMPONENT                         Int2           -                    Component number
   6   CCD_ID                            Int2           -                    CCD ID
 
--------------------------------------------------------------------------------
World Coord Transforms for Columns in Table Block FOV
--------------------------------------------------------------------------------
 
ColNo    Name
1:    EQPOS(RA ) = (+212.8339)[degree] +TAN[(-0.000136667)* (POS(X)-(+4096.50))]
           (DEC)   (+52.2005 )              (+0.000136667)  (   (Y) (+4096.50))

This FOV file can be viewed in ds9:

unix% ds9 acisf00578N003_evt2.fits -region chips.reg

which produces this image, and it can be used to filter files; for instance to select only those events in the S3 or S1 and S3 chips:

unix% dmcopy "acisf00578N003_evt2.fits[sky=region(chips.reg[ccd_id=7]),ccd_id=7]" ccd_s3.fits
unix% dmcopy "acisf00578N003_evt2.fits[sky=region(chips.reg[ccd_id=5,7]),ccd_id=5,7]" ccd_s13.fits

The additional "ccd_id=7/ccd_id=5,7" filter is needed because the spacecraft dither causes the chips to overlap on the sky. Including the CCD number guarantees the resulting photons are only from the specified chips.

Alternative ways of creating region files for particular CCDs include:

Using ds9

ds9 can be used by creating a "rotbox" region around the chip. For chip S3 (ccd_id=7) of ObsID 578, the region would look something like:

unix% cat chip_s3.reg 
# Region file format: CIAO version 1.0
rotbox(4208.1133,4374.8595,1058.3076,1068.9058,336.49673)

This method can be a bit frustrating, however, as it involves rotating the shape and deciding by eye where the chip boundaries are.

Using dmcoords

A more sophisticated, though more involved, method combines the CIAO tool dmcoords with Unix utilities:

unix% set roll = `dmkeypar acisf00578N003_evt2.fits ROLL_NOM echo+`
unix% dmcoords acisf00578N003_evt2.fits asolfile=pcadf052378346N003_asol1.fits \
      chip_id=7 opt=chip chipx=512.5 chipy=512.5\
      verbose=1 | grep "SKY(" | awk 'BEGIN {printf("# Region file format: CIAO version 1.0\nrotbox(")}\
      { printf("%f,%f,1024,1024,%f)\n", $2, $3, 360-'$roll')}' > chip_s3.reg

unix% cat chip_s3.reg 
# Region file format: CIAO version 1.0
rotbox(4199.130000,4370.660000,1024,1024,66.148798)

The dmcoords command finds the center of the chip in sky coordinates, then creates a 1024x1024 region that takes the roll angle (found with dmkeypar) into account. Note that the chip_id parameter may need to be changed for your observation.

The regions created by these two methods can be used just like any other ASCII region file:

unix% dmcopy "acisf00578N003_evt2.fits[sky=region(chip_s3.reg)]" filtered_evt2.fits

Finding the bounding box of a FOV file

The get_fov_limits tool is designed to make it easy to find the bounding box of a FOV file for use in making an image from an events file or determining the xygrid parameter of mkexpmap:

unix% get_fov_limits "chips.reg[ccd_id=7]"
Running: get_fov_limits
  version: 18 April 2011
  DM filter is:
    x=3504.5:4898.5:1,y=3674.5:5067.5:1
  mkexpmap xygrid value is:
    3504.5:4898.5:#1394,3674.5:5067.5:#1393
unix% pget get_fov_limits dmfilter
x=3504.5:4898.5:1,y=3674.5:5067.5:1
unix% pget get_fov_limits xygrid
3504.5:4898.5:#1394,3674.5:5067.5:#1393

If run with verbose=0 then no screen output will be created (we also change the binning factor to 2):

unix% get_fov_limits "chips.reg[ccd_id=5,7]" pixsize=2 verbose=0
unix% pget get_fov_limits dmfilter
x=2660.5:4898.5:2,y=1768.5:5068.5:2
unix% pget get_fov_limits xygrid
2660.5:4898.5:#1119,1768.5:5068.5:#1650

An example of its use is:

unix% get_fov_limits "chips.reg[ccd_id=5]" pixsize=2 verbose=0
unix% set dmf = `pget get_fov_limits dmfilter`
unix% set xyg = `pget get_fov_limits xygrid`
unix% mkexpmap asol1.fits emap5.fits xygrid=$xyg ...
unix% dmcopy "evt2.fits[energy=500:7000,ccd_id=5,sky=region(chips.reg[ccd_id=5])][bin $dmf]" img5.fits

Note that even though the image is filtered by the FOV file (to to ensure that the region subspace knows about the edge of the chip), we use the bounding box region to ensure that the image matches the exposure map created by mkexpmap.