MapReg

drizzlepac.mapreg.MapReg(input_reg, images, img_wcs_ext='sci', outpath='./regions', filter=None, refimg='', chip_reg='', catfname='', append=False, ref_wcs_ext=None, iteractive=None, verbose=None)

Primary interface to map DS9 region files given in sky coordinates.

Parameters:

input_regstring or list of strings (Default = ‘’)

Input region files that need to be mapped to image CS using WCS information from images (see below). Only region files saved in sky CS are allowed in this release. Regions specified in image-like coordinates (e.g., image, physical) will be ignored.

This parameter can be provided in any of several forms:

• filename of a single image

• comma-separated list of filenames

• @-file filelist containing list of desired input region filenames

The @-file filelist needs to be provided as an ASCII text file containing a list of filenames for all input region files with one filename on each line of the file.

imagesstring or list of strings (Default = *.fits)

FITS images onto which the region files input_reg will be mapped. These image files must contain WCS information in their headers to convert input_reg from sky coordinates to correct image coordinates.

This parameter can be provided in any of several forms:

• filename of a single image

• filename of an association (ASN) table

• wild-card specification for files in a directory (using *, ?

  etc.)

• comma-separated list of filenames

• @-file filelist containing list of desired input filenames (and optional inverse variance map filenames)

The @-file filelist needs to be provided as an ASCII text file containing a list of filenames for all input images (to which input_reg regions should be mapped) with one filename on each line of the file.

img_wcs_extstring or list of integers (Default = sci)

Extension selection for mapping. A string specifies an EXTNAME to use for every matching extension in each image (for example "SCI"). A list of integers specifies explicit extension numbers to process. The associated headers must contain valid WCS information for the transformation.

Note: Previously a tuple of strings was accepted to specify multiple EXTNAMEs; this usage is no longer supported.

outpathstring (Default = ./regions)

The directory to which the transformed regions should be saved. If the directory does not exist it will be created.

filterstring {None, ‘fast’, ‘precise’, ‘none’} (Default = None)

Specify whether or not to remove the regions in the transformed region files that are outside the image array. With the ‘fast’ method only intersection of the bounding boxes is being checked.

chip_regstring or list of strings (Default = ‘’, deprecated)

Input region files in image CS associated with each extension specified by the img_wcs_ext parameter above. These regions will be added directly (without any transformation) to the input_reg regions mapped to each extension of the input images. These regions must be specified in image-like coordinates. Typically, these regions should contain “exclude” regions to exclude parts of the image specific to the detector chip (e.g., vignetted regions due to used filters, or occulting finger in ACS/HRC images) from being used for source finding.

This parameter can be provided in one of the following forms:

• filename of a single image (if img_wcs_ext specifies a single

  FITS extension)

• comma-separated list of filenames (if img_wcs_ext specifies more

  than one extension) or None for extensions that do not need any chip-specific regions to be excluded/included

• ‘’ (empty string) or None if no chip-specific region files are

  provided

The number of regions ideally must be equal to the number of extensions specified by the img_wcs_ext parameter. If the number of chip-specific regions is less than the number of img_wcs_ext extensions then chip_reg regions will be assigned to the first extensions from img_wcs_ext (after internal expansion described in help for the img_wcs_ext parameter above). If the number of chip_reg entries is larger than the number of img_wcs_ext extensions then extra regions will be ignored.

catfnamestring (Default = exclusions_cat.txt)

The file name of the output exclusions catalog file to be created from the supplied image and region file names. This file can be passed as an input to TweakReg task. Verify that the created file is correct!

appendbool (Default = False)

Specify whether or not to append the transformed regions to the existing region files with the same name.

verbosebool (Default = False)

Specify whether or not to print extra messages during processing.

refimgstring (Default = ‘’, deprecated)

Reserved for future use. Filename of the reference image. May contain extension specifier: [extname,extver], [extname], or [extnumber].

ref_wcs_extstring (Default = ‘sci’, deprecated)

Reserved for future use. Extension name and/or version of FITS extensions in the refimg that contain WCS information that will be used to convert input_reg from image-like CS to sky CS. NOTE: Only extension name is allowed when input_reg is a list of region files that contain regions in image-like CS. In this case, the number of regions in input_reg must agree with the number of extensions with name specified by ref_wcs_ext present in the refimg FITS image.

iteractivebool (Default = False, deprecated)

Reserved for future use. This switch controls whether the program stops and waits for the user to examine any generated region files before continuing on to the next image.

Notes

NOTE 1: This task takes a region file (or multiple files) that describe(s) what regions of sky should be used for source finding (include regions) and what regions should be avoided (exclude regions) and transforms/maps this region file onto a number of image files that need to be aligned.

The idea behind this task is automate the creation of region files that then can be passed to exclusions parameter of the TweakReg task.

The same thing can be achieved manually using, for example, external FITS viewers, e.g., SAO DS9. For example, based on some image refimg.fits we can select a few small regions of sky that contain several good (bright, not saturated) point-like sources that could be used for image alignment of other images (say img1.fits, img2.fits, etc.). We can save this region file in sky coordinates (e.g., fk5) under the name input_reg.reg. We can then load a specific extension of each of the images img1.fits, img2.fits, etc. one by one into DS9 and then load onto those images the previously created include/exclude region file input_reg.reg. Now we can save the regions using image coordinates. To do conversion from the sky coordinates to image coordinates, DS9 will use the WCS info from the image onto which the region file was loaded. The MapReg() task tries to automate this process.

NOTE 2: MapReg() does not take into account pointing errors and thus the produced region files can be somewhat misaligned compared to their intended position around the sources identified in the “reference” image. Therefore, it is highly recommended that the produced region files be loaded into DS9 and their position be adjusted manually to include the sources of interest (or to avoid the regions that need to be avoided). If possible, the include or exclude regions should be large enough as to allow for most pointing errors.

Examples

Let’s say that based on some image refimg.fits we have produced a “master” reference image (master.reg) that includes regions around sources that we want to use for image alignment in task TweakReg() and excludes regions that we want to avoid being used for image alignment (e.g, diffraction spikes, saturated quasars, stars, etc.). We save the file master.reg in sky CS (e.g., fk5).

Also, let’s assume that we have a set of images img1.fits, img2.fits, etc. with four FITS extensions named ‘SCI’ and ‘DQ’. For some of the extensions, after analyzing the img*.fits images we have identified parts of the chips that cannot be used for image alignment. We create region files for those extensions and save the files in image CS as, e.g., img1_chip_sci2.reg (in our example this will be the only chip that needs “special” treatment).

Finally, let’s say we want to “replicate” the “master” region file to all SCI extensions of the img*.fits images.

To do this we run:

>>> mapreg(input_reg='master.reg', images='img*.fits', img_wcs_ext=[2,8])

This will produce region files in the ./regions subdirectory for each input image:

img1_sci2_twreg.reg,    img1_sci8_twreg.reg,

img2_sci2_twreg.reg,    img2_sci8_twreg.reg,