get_sky_limits

Synopsis

Find the region covered by an image in sky coordinates

get_sky_limits  image [precision] [dmfilter] [xygrid] [verbose]

Description

There are a number of times when you want to create an image - e.g. by filtering an event file or running mkexpmap - that covers the same region of sky as an existing image. Given the image, this script returns the correct expressions to use as a DM filter (see 'ahelp dmsyntax') and for the xygrid parameter of mkexpmap.

The script produces screen output describing the size of the supplied image and the sky limits (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").

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

Examples

Example 1

get_sky_limits source.fits

Here we run get_sky_limits with the source.fits file as input (which should be an image file). 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_sky_limits source.img verbose=1
Running: get_sky_limits
  version: 25 March 2011
Checking binning of image: source.img
  Image has 1232 x 1237 pixels
  Pixel size is 1.0 by 1.0
  Lower left (0.5,0.5) corner is X,Y= 3721.5, 3037.5
  Upper right (1232.5,1237.5) corner is X,Y= 4953.5, 4274.5
  DM filter is:
    X=3721.5:4953.5:#1232,Y=3037.5:4274.5:#1237
  mkexpmap xygrid value is:
    3721.5:4953.5:#1232,3037.5:4274.5:#1237

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_sky_limits dmfilter
X=3721.5:4953.5:#1232,Y=3037.5:4274.5:#1237
unix% pget get_sky_limits xygrid
3721.5:4953.5:#1232,3037.5:4274.5:#1237

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

unix% set dmf = `pget get_sky_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_sky_limits.xygrid" ...other parameters..

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

Example 2

get_sky_limits "evt2.fits[sky=region(src.reg)][bin sky=1]"

You can still use the DM virtual file syntax to filter an events file - you just need to make sure that you end up with a binning specification too.

Here we have split the filtering step from the binning one since saying

[bin sky=circle(4023,4100,54)]

would result in an 8192x8192 image (for an ACIS observation), which is unlikely to be the desired result.

Parameters

Detailed Parameter Descriptions

Parameter=image (string required filetype=input)

Image for which you want to know the binning

The name of the image (or if an event file it must contain a DM binning specification) for which you want to know the sky limits.

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

Precision [# decimal points] for output numbers

The number of decimal places to use when calculating the sky limits. So, if the x limits were 1023.45 and 1439.204 then the output would be:

It is unlikely that you need to change this parameter from its default value of 1. Although you can set the value to 0, it is not guaranteed that any filters calculated at this precision will be correct.

Parameter=dmfilter (string)

DM filter syntax to match image

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_sky_limits emap.img ver=0
unix% set filt = `pget get_sky_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 of emap.img, 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.

This expression can be used to filter images as well as event files. However note that it will not be correct if the binning of the image being filtered does not match that of the original image.

Parameter=xygrid (string)

xygrid parameter for mkexpmap to match image

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 image.

An example of its use would be:

unix% get_sky_limits src.img ver=0
unix% pset mkexpmap xygrid=")get_sky_limits.xygrid"

or

unix% get_sky_limits src.img ver=0
unix% set xyg = `pget get_sky_limits xygrid`
unix% pset mkexpmap xygrid=$xyg

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

Parameter=verbose (integer default=0 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 prduced 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 2 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.

Changes in the October 2012 Release

The script now errors out if sent a table rather than an image.

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_fov_limits