Make a field-of-view region in sky coordinates
skyfov infile outfile [logfile] [kernel] [aspect] [mskfile] [geompar] [clobber] [verbose]
The skyfov program creates a region file that describes the edges of each instrument chip. This region file - which consists of a polygon per chip - can then be used to filter event files or images. The program can be run with only an event file, with the aspect solution and mask file of the observation as optional parameters.
The aspect solution
If an aspect solution is supplied, the dither of the telescope is taken into account, and so each polygon is a little larger than the physical chip. Without an aspect solution, the nominal aspect is used and fiducial light offsets are not taken into account.
The mask file
If a mask file is provided, active CHIP regions are taken into account, otherwise a full ccd region per chip is used.
The region file
Each chip is described by a polygon. When the output kernel is set to FITS, the region file will contain a CCD_ID column which can be used to select a single chip, or range of chips. For the ASCII kernel, each chip is written out on a separate line.
Note on HRC sky FOV files
For HRC, the active area described by the mask is much larger than the "good" area. This is because the HRC bad pixel files have large regions marked bad around the edge. skyfov only knows about the mask, so the FOV file for an HRC observation ends up being too large.
One could take the HRC bad pixel file, select the first four rows which define this large outer region, and use that to create a new mask file to feed into skyfov.
skyfov evt2.fits region.fits
Makes a CXC-style FITS region file (region.fits) which describes the location of each chip (or HRC segment) in the input event file (evt2.fits).
skyfov evt2.fits region.reg kernel=ascii
Makes a DS9-style ASCII region file describing the location of each chip (or HRC segment) in the input event file.
skyfov evt2.fits region.fits dmcopy "region.fits[ccd_id=3]" chip3.fits
A FITS region file is made, then dmcopy is used to extract the region of chip I3 (ccd_id=3) alone.
skyfov evt2.fits region.reg kernel=ascii dmmakereg "bounds(region(region.reg))" outfile=bounds.reg kernel=ascii dmcopy "evt2.fits[sky=region(bounds.reg)][bin sky=::1]" img.fits
Here we create a region file (bounds.reg), in ASCII format, which describes the rectangular region which bounds all the chips present in evt2.fits. This region is then used to create an image of the data at full resolution.
skyfov evt2.fits fov.fits dmmakereg region="region(fov.fits[cols ra,dec,shape,component])" outfile=fov_radec.fits kernel=fits
Create a field-of-view file (fov.fits), then convert it to WCS format with dmmakereg. This file cannot be displayed directly in ds9. To do that requires writing out the output as an ASCII region and tweaking the coordinate system information.
dmmakereg region="region(fov[cols ra,dec,shape,component])" outfile=fov.reg kernel=ascii sed 's,^physical,fk5,' fov.reg > fov_fk5.reg
The sed command is used to change the region coordinate system from 'physical' (now incorrect) with 'fk5'. The file 'fov_fk5.reg' can then be loaded into ds9.
Detailed Parameter Descriptions
Parameter=infile (file required filetype=input)
The name of a Chandra event file. Other missions are not supported.
Parameter=outfile (file required filetype=output)
The output region name.
Parameter=logfile (file filetype=output default=STDOUT)
A log file only used for debugging; can be left blank.
Parameter=kernel (string default=FITS)
The output region format, FITS or ASCII.
The ascii region format is a variant supported by the DS9 imager, and is useable as a filter in the CIAO tools.
Parameter=aspect (file filetype=input default=)
The aspect solution
This should be a "pcad...asol1.fits" type file, or a stack of them. It may be omitted if you only need an approximate region of interest.
Parameter=mskfile (file filetype=input default=)
The mask file to contain active windows of instrument CCD.
The mask file (msk1.fits) for the observation. The mask file is needed in particular when a window or subarray was used. A value of "NONE" indicates that no mask file will be applied.
More information on the mask file is available in the CIAO Dictionary.
Parameter=geompar (file default=geom)
The name of the Pixlib Geometry parameter file.
Parameter=clobber (boolean default=no)
Clobber existing output with the same name?
Boolean that specifies whether an existing output with the same name will be clobbered or not.
Parameter=verbose (integer default=0 min=0 max=5)
Verbosity level of terminal display information to user.
ACIS exclusion windows
If an ACIS observation was taken with an exclusion window, why isn't the window excluded from the FOV file?
Strictly speaking, ACIS doesn't support "exclusion windows". It supports a window that can have an arbitrary event sampling (SAMP_CYC). A setting of 0 happens to exclude all events, but settings > 1 also excludes events, but not all events (a "grey" filter). The windows also need not filter events based on rate-of-occurrence, but can filter events on energy/pulse height. None of this generality can be expressed in the simple FITS region exclude operator.
The CXC definition of the FOV is the outer-convex hull around the corners of the window at some set of RA/DEC/ROLLs. The regions are 'generous' and always bound the data, but don't necessarily bound it "tightly".
For regions with SAMP_CYC != 1, there are really 3 regions of interest: outside the region, the area covered by the dither pattern where some fraction of the SAMP_CYC is applied, and the area entirely inside the dither pattern. The skyfov output is the middle region. There are definitely events inside the region (and thus the 'include' is appropriate), but the full SAMP_CYC filter is seen at some distance from the edge.
From a footprint point of view, it's the inner region that's more of interest than the outer edge.
- Incorrect results when running with reprojected datasets without supplying the aspect solution file.
If the aspect file is omitted, the original tangent point is used with will result in a shift of the field-of-view region file with respect to the data.
- Incorrect results with marxasp generated aspect solution files.
skyfov uses the min() and max() values from the RA, DEC, and ROLL columns in the input aspect solution file. The marxasp simulated aspect solution files have a constant value for the ROLL column. This results in a degenerate set of data points (min(ROLL)==max(ROLL)). This degeneracy then results in incorrect FOV calculations.
One possible work around it to introduce a tiny amount of random jitter to the marxasp asol file
unix% dmtcalc asol.fits asol_jitter.fits exp="roll=(roll+((#trand-0.5)*0.0001))"