TWEAKREG: Alignment of Images — drizzlepac 1.0.6 (14-Aug-2012) documentation

### Navigation

- index
- modules |
- next |
- previous |
- drizzlepac 1.0.6 (14-Aug-2012) documentation »

# TWEAKREG: Alignment of Images

Combining images using astrodrizzle requires that the WCS information in the headers of each input image align to within sub-pixel accuracy. The ‘tweakreg’ task allows the user to align sets of images to each other and/or to and external astrometric reference frame or image.

ImageReg - A replacement for IRAF-based ‘tweakshifts’

`drizzlepac.tweakreg.` `TweakReg`(files=None, editpars=False, configobj=None, imagefindcfg=None, **input_dict)

  tweakreg Version 1.0.2 updated on 11-Apr-2012

  Tweakreg provides an automated interface for computing residual shifts between input exposures being combined using AstroDrizzle. The offsets computed by Tweakreg correspond to pointing differences after applying the WCS information from the input image’s headers. Such errors would, for example, be due to errors in guide-star positions when combining observations from different observing visits or from slight offsets introduced upon re-acquiring the guide stars in a slightly different position.

  Parameters :
  > | input : str or list of str Input files (passed in from files parameter) 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 with one filename on each line of the file. If inverse variance maps have also been created by the user and are to be used (by specifying ‘IVM’ to the parameter ‘final_wht_type’ described further below), then these are simply provided as a second column in the filelist, with each IVM filename listed on the same line as a second entry, after its corresponding exposure filename. [Default value: ‘*flt.fits’] refimage : str Filename of reference image. Sources derived from this image will be used as the reference for matching with sources from all input images. [Default value: ‘’] exclusions: string : This parameter allows the user to specify a set of files which contain regions in the image to ignore when finding sources. This file MUST have 1 line for each input image with the name of the input file in the first column. Subsequent columns would be used to specify an exclusion file for each chip in ‘SCI,<n>’ index order. If a chip does not require an exclusion file, the string ‘None’ or ‘INDEF’ can be used as a placeholder for that chip. Each chip’s exclusion file should conform to the ‘region’ file format generated by DS9, and currently, only ‘circle()’ regions are interpreted and used and only with units for the positions of the exclusion center of ‘fk[4|5]’ and ‘image’. Support for additional region file options will be added at a later date. [Default value: ‘’] updatewcs : bool Update WCS keywords of input images? [Default value: No] writecat : bool Specify whether or not to write out the source catalogs generated for each input image by the built-in source extraction algorithm. [Default value: Yes] clean : bool Specify whether or not to remove the temporary files created by ‘tweakreg’, including any catalog files generated for the shift determination. [Default value = No] verbose : bool Specify whether or not to print extra messages during processing. [Default value = No] runfile : string Specify the filename of the processing log. [Default value = ‘tweakreg.log’] *UPDATE HEADER* : updatehdr : bool Specify whether or not to update the headers of each input image directly with the shifts that were determined. This will allow the input images to be combined by AstroDrizzle without having to provide the shiftfile as well. [Default value = No] wcsname : str Name of updated WCS. [Default value = ‘TWEAK’] *HEADERLET CREATION* : headerlet: bool : Specify whether or not to generate a headerlet from the images at the end of the task? If turned on, this will create a headerlet from the images regardless of the value of the ‘updatehdr’ parameter. [Default value = No] attach: bool : If creating a headerlet, choose whether or not to attach the new headerlet to the input image as a new extension. [Default value = Yes] hdrfile: string : Filename to use for writing out headerlet to a separate file. If the name does not contain ‘.fits’, it will create a filename from the rootname of the input image, the value of this string, and it will end in ‘_hlet.fits’. For example, if only ‘hdrlet1’ is given, the full filename created will be ‘j99da1f2q_hdrlet1_hlet.fits’ when creating a headerlet for image ‘j99da1f2q_flt.fits’. [Default value = ‘’] clobber: bool : If a headerlet with ‘hdrfile’ already exists on disk, specify whether or not to overwrite that previous file. [Default value = No] hdrname: string : Unique name to give to headerlet solution. This name will be used to identify this specific WCS alignment solution contained in the headerlet. [Default value = ‘’] author: string, optional : Name of the creator of the headerlet. [Default value = ‘’] descrip: string, optional : Short (1-line) description to be included in headerlet as ‘DESCRIP’ keyword. This can be used to provide a quick look description of the WCS alignment contained in the headerlet. [Default value = ‘’] catalog: string, optional : Name of reference catalog used as the basis for the image alignment. [Default value = ‘’] history: string, optional : Filename of a file containing detailed information regarding the history of the WCS solution contained in the headerlet. This can include information on the catalog used for the alignment, or notes on processing that went into finalizing the WCS alignment stored in this headerlet. This information will be reformatted as 70-character wide FITS HISTORY keyword section. [Default value = ‘’] *OPTIONAL SHIFTFILE OUTPUT* : shiftfile : bool Create output shiftfile? [Default value: No] outshifts : str The name for the output shift file created by ‘tweakreg’. This shiftfile will be formatted for use as direct input to AstroDrizzle. [Default value: ‘shifts.txt’] outwcs : str Filename to be given to the OUTPUT reference WCS file created by ‘tweakreg’. This reference WCS defines the WCS from which the shifts get measured, and will be used by AstroDrizzle to interpret those shifts. This reference WCS file will be a FITS file that only contains the WCS keywords in a Primary header with no image data itself. The values will be derived from the FIRST input image specified. [Default value: ‘shifts_wcs.fits’] *COORDINATE FILE DESCRIPTION* : catfile : str Name of file that contains a list of input images and associated catalog files generated by the user. Each line of this file will contain the name of an input image in the first column. The remaining columns will provide the names of the source catalogs for each chip in order of the science extension numbers ((SCI,1), (SCI,2), ...). [Default value: ‘’] A sample catfile, with one line per image would look like:
  >     image1_flt.fts  cat1_sci1.coo  cat1_sci2.coo
  >     image2_flt.fts  cat2_sci1.coo  cat2_sci2.coo
  xcol : int Column number of X position from the user-generated catalog files specified in the catfile. [Default value = 1] ycol : int Column number of Y position from the user-generated catalog files specified in the catfile. [Default value = 2] fluxcol : int Column number for the flux values from the user-generated catalog files specified in the catfile. These values will only be used if a flux limit has been specified by the user using the ‘fluxmax’ or ‘fluxmin’ parameters. [Default value = None] fluxmax : float Limiting flux value for selecting valid objects in the input image’s catalog. If specified, this flux will serve as the upper limit of a range for selecting objects to be used in matching with objects identified in the reference image. If the value is set to None, all objects with fluxes brighter than the minimum specified in ‘fluxmin’ will be used. If both values are set to None, all objects will be used. [Default value = None] fluxmin : float Limiting flux value for selecting valid objects in the input image’s catalog. If specified, this flux value will serve as the lower limit of a range for selecting objects to be used in matching with objects identified in the reference image. If the value is set to None, all objects fainter than the limit specified by ‘fluxmax’ will be used. If both values are set to None, all objects will be used. [Default value = None] fluxunits : str {‘counts’, ‘cps’, ‘mag’} This allows the task to correctly interpret the flux limits specified by ‘fluxmax’ and ‘fluxmin’ when sorting the object list for trimming of fainter objects. [Default value = ‘counts’] xyunits : str {‘pixels’, ‘degrees’} Specifies whether the positions in this catalog are already sky pixel positions, or whether they need to be transformed to the sky. [Default value = ‘pixels’] nbright : int The number of brightest objects to keep after sorting the full object list. If nbright is set equal to None, all objects will be used. [Default value = None] *REFERENCE CATALOG DESCRIPTION* : refcat : str Name of the external reference catalog file to be used in place of the catalog extracted from one of the input images. [Default value = ‘’] refxcol : int Column number of RA in the external catalog file specified by the refcat. [Default value = 1] refycol : int Column number of Dec in the external catalog file specified by the refcat. [Default value = 2] refxyunits : str {‘pixels’,’degrees’} Units of sky positions. [Default value = ‘degrees’] rfluxcol : int Column number of flux/magnitude values in the external catalog file specified by the refcat. [Default value = None] rfluxmax : float Limiting flux value used to select valid objects in the external catalog. If specified, the flux value will serve as the upper limit of a range for selecting objects to be used in matching with objects identified in the reference image. If the value is set to None, all objects with fluxes brighter than the minimum specified in ‘rfluxmin’ will be used. If both values are set to None, all objects will be used. [Default value = None] rfluxmin : float Limiting flux value used to select valid objects in the external catalog. If specified, the flux will serve as the lower limit of a range for selecting objects to be used in matching with objects identified in the reference image. If the value is set to None, all objects fainter than the limit specified by ‘rfluxmax’ will be used. If both values are set to None, all objects will be used. [Default value = None] rfluxunits : {‘counts’, ‘cps’, ‘mag’} This allows the task to correctly interpret the flux limits specified by ‘rfluxmax’ and ‘rfluxmin’ when sorting the object list for trimming of fainter objects. [Default value = ‘mag’] refnbright : int Number of brightest objects to keep after sorting the full object list. If refnbright is set to None, all objects will be used. Used in conjunction with refcat. [Default value = None] *OBJECT MATCHING PARAMETERS* : minobj : int Minimum number of identified objects from each input image to use in matching objects from other images. [Default value = 15] searchrad : float The search radius for a match. [Default value = 1.0] searchunits : str Units for search radius. [Default value = ‘arcseconds’] use2dhist : bool Use 2d histogram to find initial offset? [Default value = Yes] see2dplot : bool See 2d histogram for initial offset? [Default value = Yes] tolerance : float The matching tolerance in pixels after applying an initial solution derived from the ‘triangles’ algorithm. This parameter gets passed directly to xyxymatch for use in matching the object lists from each image with the reference image’s object list. [Default value = 1.0] separation : float The minimum separation for objects in the input and reference coordinate lists. Objects closer together than ‘separation’ pixels are removed from the input and reference coordinate lists prior to matching. This parameter gets passed directly to xyxymatch for use in matching the object lists from each image with the reference image’s object list. [Default value = 0.0] xoffset : float Initial estimate for the offset in X between the images and the reference frame. This offset will be used for all input images provided. If the parameter value is set to None, no offset will be assumed in matching sources in ‘xyxymatch’. [Default value = 0.0] yoffset : float Initial estimate for the offset in Y between the images and the reference frame. This offset will be used for all input images provided.If the parameter value is set to None, no offset will be assumed in matching sources in ‘xyxymatch’. [Default value = 0.0] *CATALOG FITTING PARAMETERS* : fitgeometry : str {‘shift’, ‘rscale’} The fitting geometry to be used in fitting the matched object lists. This parameter is used in fitting the offsets, rotations and/or scale changes from the matched object lists. [Default value = ‘rscale’] residplot : str {‘No plot’, ‘vector’, ‘residuals’, ‘both’} Plot residuals from fit? [Default value = ‘both’] If ‘both’ is selected, the ‘vector’ and ‘residuals’ plots will be displayed in separate plotting windows at the same time. nclip : int Number of clipping iterations in fit. [Default value = 3] sigma : float Clipping limit in sigma units. [Default value = 3.0]

  See also

  `astrodrizzle`

  Notes

  Tweakreg supports the use of calibrated, distorted images (such as FLT images for ACS and WFC3, or _c0m.fits images for WFPC2) as input images. All coordinates for sources derived from these images (either by this task or as provided by the user directly) will be corrected for distortion using the distortion model information specified in each image’s header. This eliminates the need to run ‘astrodrizzle’ on the input images prior to running tweakreg.

  Note

  All calibrated input images must have been updated using ‘updatewcs’ from the STWCS package, or as run by ‘astrodrizzle’, to include the full distortion model in the header.

  This task will use catalogs, and catalog-matching, based on the ‘xyxymatch’ algorithm to determine the offset between the input images. The primary mode of operation will be to extract a catalog of source positions from each input image using either a ‘DAOFIND-like’ algorithm or SExtractor (if the user has SExtractor installed). Alternatively, the user can provide their catalogs of source positions derived from each input chip.

  The reference frame will be defined either by:

  > - the first input image (and associated catalog),

  > - a catalog derived from a reference image specified by the user, or

  > - a catalog of undistorted sky positions (RA/Dec) and fluxes

  >     provided by the user.

  For a given observation, the distortion model is applied to all distorted input positions, and the sources from each chip are then combined into a single catalog of undistorted positions.

  The undistorted positions for each observation then get passed to ‘xyxymatch’ for matching to objects from the reference catalog.

  The source lists from each image will generally include cosmic-rays as detected sources, which can at times significantly confuse object identification between images. Observations that include long exposures often have more cosmic-ray events than source objects. As such, isolating the cosmic-ray events in those cases would significantly improve the efficiency of common source identification between images. One such method for trimming potential false detections from each source list would be to set a flux limit to exclude detections below that limit. As the fluxes reported in the default source object lists are provided as magnitude values, setting the fluxmax or fluxmin parameter value to a magnitude- based limit, and then setting the ascend parameter to True, will allow for the creations of catalogs trimmed of all sources fainter than the provided limit. The trimmed source list can then be used in matching sources between images and in establishing the final fitting for the shifts.

  A fit can then be performed on the matched set of positions between the input and the reference to produce the ‘shiftfile’. If the user is confident that the solution will be correct, the header of each input image can be updated directly with the fit derived for that image. Otherwise, the ‘shiftfile’ can be passed to AstroDrizzle for aligning the images.

  Format of Exclusion Catalog

  The format for the exclusions catalog requires 1 line in the file for every input image, regardless of whether or not that image has any defined exclusion regions. A sample file would look like:

      j99da1emq_flt.fits
      j99da1f2q_flt.fits test_exclusion.reg

  This file specifies no exclusion files for the first image, and only an regions file for SCI,1 of the second image. Should an exclusion regions file only be needed for the second chip in the second image, the file would need to look like:

      j99da1emq_flt.fits
      j99da1f2q_flt.fits None test_sci2_exclusion.reg

  The value ‘None’ could also be replaced by ‘INDEF’ if desired, but either string needs to be present to signify no regions file for that chip while the code continues parsing the line to find a file for the second chip.

  Format of Region Files

  The format of the exclusions catalogs referenced in the ‘exclusions’ file defaults to the format written out by DS9 using the ‘DS9/Funtools’ region file format. A sample file with circle() regions will look like:

      # Region file format: DS9 version 4.1
      # Filename: j99da1f2q_flt.fits[SCI]
      global color=green dashlist=8 3 width=1 font="helvetica 10 normal roman" select=1 highlite=1 dash=0 fixed=0 edit=1 move=1 delete=1 include=1 source=1
      image
      circle(3170,198,20)
      circle(3269,428,20)
      circle(3241.1146,219.78132,20.000014)

  This task can also work with regions files which have a much simpler format for each region with 2 values for the source center and a third value for the radius of the region. The units of all the values can either pixels or sky coordinates (either sexagesimal RA/Dec or decimal degrees RA/Dec plus radius in arcseconds). The values on each line can be separated either by spaces or commas.

  A sample file with free formatted regions would look like:

      image
      3170,198,20
      3269 428 20
      3241.1146,219.78132,20.000014

  The first (non-comment) line in the file will specify what units were used for specifying the regions. Supported options are:

  - ‘image’
  - ‘physical’
  - ‘pixel’
  - ‘fk5’
  - ‘fk4’
  - ‘sky’

  The terms ‘image’, ‘physical’, and ‘pixel’ all refer to values in pixels, while the remaining naturally refer to values specified in sky coordinates. A default units of ‘pixels’ will be assumed should the units line not be found at the beginning of the regions file.

  The format of the regions can actually be different from one line to the next, in case multiple regions files written out in different formats need to be merged. So, regions from the second example could be included in the first examples file if needed.

  Examples

  The tweakreg task can be run from either the TEAL GUI or from the command-line using PyRAF or Python. These examples illustrate the various syntax options available.

  Example 1: Align a set of calibrated (_flt.fits) images using IMAGEFIND, a built-in source finding algorithm based on DAOPHOT. Auto-detect the sky sigma value and select sources > 200 sigma. (Auto-sigma is computed from the first input exposure as: 1.5 * imstat(image,nclip=3,fields=’stddev’). ) Set the convolution kernel width to ~2x the value of the PSF FWHM. Save the residual offsets (dx, dy, rot, scale, xfit_rms, yfit_rms) to a text file.

  1. Run the task from PyRAF using the TEAL GUI:

         --> import drizzlepac
         --> epar tweakreg

  2. Run the task from PyRAF using the command line.

         --> import drizzlepac
         --> from drizzlepac import tweakreg
         --> tweakreg.TweakReg('*flt.fits', updatehdr=False, fwhmpsf=3.5, threshold=200, \
                               shiftfile=True, outshifts='shift.txt')

     Or, run the same task from the PyRAF command line, but specify all parameters in a config file named “myparam.cfg”:

         --> tweakreg.TweakReg('*flt.fits', configobj='myparam.cfg')

  3. Run the task directly from Python:

         >>> from drizzlepac import tweakreg
         >>> tweakreg.TweakReg('*flt.fits', updatehdr=False, fwhmpsf=3.5, threshold=200, \
                               shiftfile=True, outshifts='shift.txt')

     Alternately, edit the imagefind parameters in a TEAL GUI window prior to running the task:

         >>> tweakreg.edit_imagefindpars()

  4. Help can be accessed via the “Help” pulldown menu in the TEAL GUI. It can also be accessed from the PyRAF command-line and saved to a text file:

         --> from drizzlepac import tweakreg
         --> tweakreg.help()

     or:

         --> tweakreg.help(file='help.txt')
         --> page help.txt

`drizzlepac.tweakreg.` `help`(file=None)

  Print out syntax help for running tweakreg

### Navigation

- index
- modules |
- next |
- previous |
- drizzlepac 1.0.6 (14-Aug-2012) documentation »