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’]
:
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’]
:
:
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]
|
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.
Run the task from PyRAF using the TEAL GUI:
--> import drizzlepac
--> epar tweakreg
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')
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()
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
