get_fov_limits

Synopsis

Find the region (bounding box) covered by a FOV file in sky coordinates

get_fov_limits  infile [dmfilter] [xygrid] [pixsize] [verbose]

Description

The get_fov_limits tool returns the region of sky covered by a FOV file (the fov1 file found in the primary/ directory of an observation or one created by the skyfov tool). The range is returned in both the format used by the xygrid of mkexpmap and for use as a DM filter (see 'ahelp dmsyntax'). It is similar in purpose to the get_sky_limits tool.

The script produces screen output describing the xygrid and dmfilter values, as long as the verbose parameter is not 0. The results can be read from the screen, but they are also stored in the "dmfilter" and "xygrid" parameters of the parameter file (whatever the verbose setting). These can then be accessed using the pget tool ("ahelp tools pget") or parameter library functions ("ahelp paramio").

Which chips are used in the calculation?

The tool will display the bounding box of all the regions in the FOV file. A ccd_id filter should be used to filter out unwanted chips, as shown in the examples. The ccd_id filter is also used for HRC-S data (where it has values of 0, 1 or 2) and for HRC-I data (but it only has the value of 0 in this case).

How is the bounding-box calculated?

The minimum and maximum SKY coordinates for each region - i.e. each ccd_id value - are found, and then combined to form the output bounding box. The edges are adjusted to match the standard Chandra grid and to ensure that the width and height are an integer number of sky pixels (only relevant when the pixsize is greater than 1). The region is therefore only as good as the FOV file; several reasons for discrepancies are:

• if the events file has been reprojected or the aspect solution has been adjusted then the FOV file should be re-created by running skyfov;
• the limits may appear slightly generous since they include the edges where the spacecraft dither means that the effective exposure time is less than at the aimpoint;
• HRC FOV files do not exclude some "bad" pixels, as discussed in the skyfov ahelp file.

Thread

See the Match the Binning of an Image thread on the CIAO web site for more information.

Examples

Example 1

unix% get_fov_limits fov1.fits

Here we run the tool on all the chips in the FOV file fov1.fits. With the default verbose level (of 1), the following output will be displayed to the screen (the values depend on the input file):

unix% get_fov_limits fov1.fits
Running: get_fov_limits
  version: 15 April 2011
  DM filter is:
    x=917.5:3263.5:1,y=2858.5:6582.5:1
  mkexpmap xygrid value is:
    917.5:3263.5:#2346,2858.5:6582.5:#3724

The output information is contained in the last four lines, and is also stored in the parameter file in the "dmfilter" and "xygrid" parameters:

unix% pget get_fov_limits dmfilter
x=917.5:3263.5:1,y=2858.5:6582.5:1
unix% pget get_fov_limits xygrid
917.5:3263.5:#2346,2858.5:6582.5:#3724

You can store these values in shell variables - e.g. for csh/tcsh users:

unix% set dmf = `pget get_fov_limits dmfilter`
unix% dmcopy "evt2.fits[energy=500:2000][bin $dmf]" img.500-2000

- or by using the redirection capabilities of the parameter interface -

unix% mkexpmap xygrid=")get_fov_limits.xygrid" ...other parameters..

See "ahelp parameter" for more information on the capabilities of the parameter interface.

Example 2

unix% get_fov_limits "fov1.fits[ccd_id=0:3]" pixsize=4 verbose=0

Here we restrict the bounding box to cover the ACIS-I chips (ie ccd_id of 0, 1, 2 and 3) and increase the pixel size to 4 (~2 arcseconds). The screen output is suppressed so the only way to access the ranges is via the parameter interface, namely:

unix% pget get_fov_limits xygrid

Example 3

unix% get_fov_limits "fov1.fits[ccd_id=7]" pixsize=0.2

In this example we get the bounding box for ccd_id=7 (ACIS-S3) and use a "sub-pixel" binning scheme.

Parameters

Detailed Parameter Descriptions

Parameter=infile (string required filetype=input)

The FOV file to use

The name of the FOV file to use. Use a ccd_id filter to exclude unwanted chips: e.g.

fov1.fits[ccd_id=0,3]

Parameter=dmfilter (string)

DM filter syntax to match FOV file

When the script has finished this parameter will contain the DM filter expression (see "ahelp dmsyntax") needed to filter an events file (or image) to match the input image.

An example of its use would be (using csh/tcsh syntax):

unix% get_fov_limits fov1.fits ver=0
unix% set filt = `pget get_fov_limits dmfilter`
unix% echo $filt
X=3721.5:4953.5:#1232,Y=3037.5:4274.5:#1237
unix% dmcopy "evt2.fits[bin $filt]" match.img

Here we run the script to find out the limits, with verbose set to 0 to avoid any screen output, and then store the DM filter expression in the shell variable filt. This is then used in the dmcopy call to bin an event file, creating the file match.img.

Parameter=xygrid (string)

xygrid parameter for mkexpmap to match FOV file

Set the xygrid parameter of mkexpmap to this value so as to create an exposure map that covers the same area of sky as the input.

An example of its use would be:

unix% get_fov_limits "fov1.fits[ccd_id=7]" ver=0
unix% pset mkexpmap xygrid=")get_fov_limits.xygrid"

or

unix% get_fov_limits "fov1.fits[ccd_id=7]" ver=0
unix% set xyg = `pget get_fov_limits xygrid`
unix% pset mkexpmap xygrid=$xyg

In the first example we use parameter indirection (see "ahelp parameter") to set the xygrid parameter of mkexpmap equal to that of get_fov_limits. This requires that mkexpmap is run before the get_fov_limits parameter file is changed; a safer alternative is shown in the second example (using csh/tcsh syntax).

Parameter=pixsize (real default=1 min=0)

Pixel size

The pixel size to use for the grids. A value of 1 (the default) is the native pixel scale for the instrument and the value can be either larger or smaller than this.

Parameter=verbose (integer default=1 min=0 max=5)

Verbose level

If set to a non-zero value then the tool will print information to the screen when it is run. The extra information produced when verbose is greater than 1 is only likely to be useful when debugging the script.

The script version is displayed when the verbose parameter is set to 1 or higher.

Changes in the scripts 4.8.1 (December 2015) release

The code has been updated to avoid warning messages from NumPy version 1.9. There is no difference to how the script behaves.

About Contributed Software

This script is not an official part of the CIAO release but is made available as "contributed" software via the CIAO scripts page. Please see this page for installation instructions - such as how to ensure that the parameter file is available.

Bugs

There are no known bugs for this tool.

See Also

dm

dmbinning

tools::core

dmcopy, dmextract

tools::gratings

tgextract, tgextract2

tools::image

dmfilth, dmimghist, dmregrid

tools::table

dmgroup

tools::utilities

apply_fov_limits, get_sky_limits