**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]

interactive : bool
    This switch controls whether the program stops and waits for the user to
    examine any generated plots before continuing on to the next image.  If
    turned off, plots will still be displayed, but they will also be saved to
    disk automatically as a PNG image with an autogenerated name without
    requiring any user input.  [Default value = Yes]

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]


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


See Also
--------
astrodrizzle
