/ ciao4.16 / ahelp / apply_fov_limits.html

Jump to: Description · Examples · Parameters · Changes in the scripts 4.16.0 (December 2023) release · Changes in the scripts 4.12.2 (April 2020) release · Changes in the scripts 4.8.1 (December 2015) release · Changes in the scripts 4.7.2 (April 2015) release · Changes in the scripts 4.7.1 (December 2014) release · About Contributed Software · Bugs · See Also

AHELP for CIAO 4.16

apply_fov_limits

Context: Tools::Utilities

Synopsis

Create an image that matches the FOV file for the observation

Syntax

apply_fov_limits  infile outfile [binsize] [fovfile] [datatype]
[tmpdir] [clobber] [verbose]

Description

The apply_fov_limits tool takes an event file and creates an image from it in SKY coordinates, calculating the limits from the Field-Of-View (FOV) file for the observation. The default mode is to create the FOV based on the aspect solution of the observation, filtered by the GTI of the event file, but a FOV file can also be given. It is essentially get_fov_limits followed by a dmcopy call; the help file for get_fov_limits describes how the limits are calculated.

Thread

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

Examples

Example 1

unix% apply_fov_limits evt2.fits img.fits

The tool creates the file img.fits, which is an image of the data in evt2.fits, binned to cover the spatial extent of the observation. The default binning is used (8 pixels for ACIS and 32 for HRC) and, as no Data Model filters were applied to the event file, all the data will be included in the output image. For an example ACIS-S dataset, the output is

Running: apply_fov_limits
  version: 08 September 2023
Observation: ObsId 5437 - ACIS-235678
Using ccd_id=2,3,5,6,7,8 from evt2.fits
Calculating FOV file using:
  Aspect solution pcadf233357758N003_asol1.fits
  Mask file       acisf05437_000N003_msk1.fits

The output image will have 322 by 529 pixels, pixel size of 3.936 arcsec,
    and cover x=2160.5:4736.5:8,y=2192.5:6424.5:8.

Created: img.fits

Note that the aspect solution and mask file have been automatically identified from the header of the event file.

Example 2

unix% apply_fov_limits "repro/acisf05437_repro_evt2.fits[ccd_id=7]" \
chip7.img bin=1

Here we restrict the event file to ACIS-S3 only, and reduce the bin size to 1, which changes the output image sky range and number of pixels compared to the first example.

Running: apply_fov_limits
  version: 08 September 2023
Observation: ObsId 5437 - ACIS-235678
Using ccd_id=7 from repro/acisf05437_repro_evt2.fits[ccd_id=7]
Calculating FOV file using:
  Aspect solution repro/pcadf233357758N003_asol1.fits
  Mask file       repro/acisf05437_000N003_msk1.fits

The output image will have 1102 by 1102 pixels, pixel size of 0.492 arcsec,
    and cover x=3529.5:4631.5:1,y=3238.5:4340.5:1.

Created: chip7.img

Example 3

unix% apply_fov_limits "evt2.fits[energy=500:900,ccd_id=7]" \
chip7.img bin=1 verbose=0

In this example an energy filter has also been applied.

Example 4

unix% apply_fov_limits evt2.fits img.out fovfile=fov.fits

In this example the FOV file is explicitly given, rather than created by the script from the aspect solution and mask file.

Example 5

unix% dmcopy "evt2.fits[sky=region(src.reg)]" src.fits
unix% apply_fov_limits src.fits src.img

Since the event file sent to apply_fov_limits has already been filtered, then the output image area is determined by the intersection of the existing spatial filter with those from the FOV file.

Parameters

name	type	ftype	def	min	max	reqd
infile	string	input				yes
outfile	string	output				yes
binsize	real		INDEF	0
fovfile	file
datatype	string		i4
tmpdir	string		${ASCDS_WORK_PATH}
clobber	boolean		no
verbose	integer		1	0	5

Detailed Parameter Descriptions

Parameter=infile (string required filetype=input)

Input event file

The event file to bin up. Use Data Model filters to select the required rows, such as a chip and energy filter:

evt2.fits[ccd_id=0:3,energy=500:7000]

Note that if the event file has been spatially filtered, then this information - taken from the data subspace of the file - will be combined with the filter from the FOV file. This means that the output image may not cover the full chip area.

Parameter=outfile (string required filetype=output)

Output image

The name of the image created by this script.

Parameter=binsize (real default=INDEF min=0)

Image binning factor

When set to INDEF a default value is used: 8 for ACIS data and 32 for HRC data. The binning factor has units of the SKY pixel (0.492" for ACIS and 0.1318" for HRC), so binsize=4 for an ACIS observation will create images with 1.968 arcsecond pixels. The value need not be an integer, and can be less than 1 if you want to look at small-scale structure near the aim point of the observation; in this case it is strongly suggested that a ccd_id filter is used to ensure manageable file sizes.

Parameter=fovfile (file)

Input FOV file

If the parameter is not empty then it gives the name of the FOV file to use; this can either be generated using skyfov or the *fov1.fits from the archive used.

If the parameter is empty then the ASOLFILE and MASKFILE keywords in the event file (the infile parameter) will be used to find the aspect solution and mask file, and these are then passed to the skyfov tool to create a FOV file (with the aspect solution being time filtered to match the GTI of the event file). Note that the file, or files, pointed to by the ASOLFILE are required but the MASKFILE is optional; a warning will be displayed if it can not be found, and the full chip size will be used in calculating the bounding box.

Parameter=datatype (string default=i4)

Data type for outfile

The output image will use this DataModel option to decide the data type of the output image. The options are:

i4 (default), 32-bit integer
i2, 16-bit integer

Parameter=tmpdir (string default=${ASCDS_WORK_PATH})

Directory for temporary files.

Directory for storing temporary files that require further processing before becoming useful. If the directory does not exist then it will be created for use by the script, and then deleted.

Parameter=clobber (boolean default=no)

OK to overwrite existing output file?

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 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 1 or higher.

Changes in the scripts 4.16.0 (December 2023) release

New parameter: datatype

Earlier versions defaulted to creating images with a 16-bit integer type (the Data Model [opt type=i2] syntax). This could lead to data overflow for bright images or large pixel sizes. The default is now to use the i4 type (32-bit integer type) to reduce the chance for an overflow, but if the file sizes are too large setting the datatype=i2 option will switch back to the old behaviour.

Changes in the scripts 4.12.2 (April 2020) release

The script has been updated to support aspect solutions produced in the DS 10.8.3 release (or later). These files have a CONTENT keyword of ASPSOLOBI (earlier releases use ASPSOL), and can be used with skyfov when method=convexhull.

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 scripts 4.7.2 (April 2015) release

The output image is no-longer created with the dmcopy option=all parameter, which means that some of the metadata of the output file (such as position of the image block and the subspace of the file) may change. This should make no difference for most uses of the output image.

Changes in the scripts 4.7.1 (December 2014) release

The mask file is now optional

The script will now no-longer exit if the file pointed to by the MASKFILE keyword in the infile can not be found; instead, a warning will be displayed as resulting bounds may be too large (for example, if a sub-array was used). This is only relevant when the fovfile parameter is not set.

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

Size of image too large: This script may sometimes create an image larger than expected. When a CCD_ID filter is used, the intent of the script is to create an image just as big as needed to enlose the chips listed. However, for some datasets, the image produced may be larger and include area covered by additional CCDs. This only affect the size of the image, not the image pixel values.