Region mapping for TweakReg

This module provides functions for mapping DS9 region files given in sky coordinates to DS9 region files specified in image coordinates of multiple images using the WCS information from the images.

Authors:Mihai Cara
License:LICENSE
drizzlepac.mapreg.MapReg(input_reg, images, img_wcs_ext='sci', refimg='', ref_wcs_ext='sci', chip_reg='', outpath='./regions', filter='', catfname='', iteractive=False, append=False, verbose=True)[source]

MapReg() provides an automated interface for converting a region file to the image coordinate system (CS) of multiple images (and their extensions) using WCS information from the image(s) header(s). This conversion does not take into account pointing errors and, therefore, an examination and adjustment (if required) of output region files is highly recommended. This task is designed to simplify the creation of the exclusions and/or inclusions region files used with TweakReg() task for sources finding.

Parameters:
input_reg : string 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 paramater 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.

images : string 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 in order to convert input_reg from sky coordinates to correct image coordinates. This paramater 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 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_ext : string or list of strings (Default = SCI)

Extension name, extension name and version, or extension number of FITS extensions in the images to which the input regions input_reg should be mapped. The header of each extension must contain WCS information that will be used to convert input_reg from sky CS to image-like CS. Multiple extensions must be separated by semicolon while extension name and version (if present) must be separated by comma, e.g., 'SCI;DQ,1;0'. When specifying the extension name only, internally it will be expanded into a list of extension names and versions for each version of that extension name present in the input images. For example, if a FITS file has four SCI and four DQ extensions, then 'SCI;DQ,1;0' will be expanded into 'SCI,1;SCI,2;SCI,3;SCI,4;DQ,1;0'.

refimg : string (Default = ‘’)

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

Note

This parameter is reserved for future use and it is not available through TEAL interface.

ref_wcs_ext : string (Default = SCI)

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.

Note

This parameter is reserved for future use and it is not available through TEAL interface.

chip_reg : string or list of strings (Default = ‘’)

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 paramater 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’ is larger than the number of img_wcs_ext extensions then extra regions will be ignored.

outpath : string (Default = ./regions)

The directory to which the transformed regions should be saved.

filter : string {‘None’, ‘fast’, or ‘precise’ } (Default = ‘None’)

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

Note

The 'precise' method is not implemented in this release and, if specified, defaults to ‘fast’. The 'precise' option is not available through the TEAL interface.

catfname : string (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!

append : bool (Default = False)

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

interactive : bool (Default = False)

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

Note

This parameter is reserved for future use and it is not available through TEAL interface.

verbose : bool (Default = False)

Specify whether or not to print extra messages during processing.

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

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), e.g., 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() relies on the pyregion package for region file parsing and coordinate transformation. Unfortunately, as of writing, pyregion does not consider distortion corrections when performing coordinate transformations. Therefore, there might be a slight discrepancy between the regions produced by MapReg() and the DS9 regions obtained as described in the NOTE 1 above.

NOTE 3: 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. Threfore, 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 analizing the img*.fits images we have identified parts of the chips that cannot be used for image alighnment. 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 exctensions of the img*.fits images as well as to the 2nd DQ extension and to the 8th extension of the img*.fits images.

To do this we run:

>>> mapreg(input_reg = 'master.reg', images='img*.fits',
...        img_wcs_ext='sci;dq,2;8', chip_reg='None,
...        img1_chip_sci2.reg,None,None,None,None')

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

``img1_sci1_twreg.reg``,    ``img1_sci2_twreg.reg``,    ``img1_sci3_twreg.reg``,
``img1_sci4_twreg.reg``,    ``img1_dq2_twreg.reg``,     ``img1_extn8_twreg.reg``
...

``img2_sci1_twreg.reg``,    ``img2_sci2_twreg.reg``,    ``img2_sci3_twreg.reg``,
``img2_sci4_twreg.reg``,    ``img2_dq2_twreg.reg``,     ``img2_extn8_twreg.reg``
...
drizzlepac.mapreg.map_region_files(input_reg, images, img_wcs_ext='sci', refimg=None, ref_wcs_ext='sci', chip_reg=None, outpath='./regions', filter=None, catfname=None, iteractive=False, append=False, verbose=True)[source]
drizzlepac.mapreg.help(file=None)[source]

Print out syntax help for running astrodrizzle

Parameters:
file : str (Default = None)

If given, write out help to the filename specified by this parameter Any previously existing file with this name will be deleted before writing out the help.