Ahelp: get_sky_limits

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 S-Lang parameter library functions ("ahelp paramio").

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

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
  Checking binning of image: source.img
    Image has 1232 x 1237 pixels
    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

name	type	ftype	def	min	max	reqd
image	string	input				yes
precision	real		1	0
dmfilter	string
xygrid	string
verbose	integer		0	0	5

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:

Precision	X min	X max
0	1023	1439
1	1023.5	1439.2
2	1023.45	1439.20
3	1023.450	1439.204

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.

This parameter was not available in versions of the script prior to CIAO 3.0 (it was hard-coded to the value of 1).

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"

  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.

Synopsis

Syntax

Description

Example 1

Example 2

Parameters

Detailed Parameter Descriptions

Parameter=image `(string required filetype=input)`

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

Parameter=dmfilter `(string)`

Parameter=xygrid `(string)`

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

CHANGES IN CIAO 4.0/GET_SKY_LIMITS 1.9

NOTES

Bugs

See Also

Parameter=image (string required filetype=input)

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

Parameter=dmfilter (string)

Parameter=xygrid (string)

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

Parameter=image `(string required filetype=input)`

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

Parameter=dmfilter `(string)`

Parameter=xygrid `(string)`

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