7.2 Verifying TweakReg Solutions After User Reprocessing

How can the quality of TweakReg image alignment results be assessed?

In general, the first step in manual reprocessing is running TweakReg to improve the relative alignment of the WCS in the image headers. By default, this task runs in an interactive mode by producing a number of plots and figures for inspection. Users are strongly encouraged to verify the quality of the solutions as described below.

Examine the Fit Residuals

While running TweakReg, the results of the fit (residual shift, rotation, and scale), and the fit RMS are printed to STDOUT (computer monitor) or to an optional "shift file." These solutions should be inspected for accuracy before proceeding to drizzling the images.

Does the solution make sense?

Observations obtained within a single visit should, in general, require no residual rotation (less than 0.001 degrees) and a very small shift (less than a few tenths of a pixel.) The exception to this rule is when very large POSTARGs are specified to offset the telescope from the commanded R.A. & Dec. In these cases, small residual rotations on the order of a few thousands of a degree are expected. On the other hand, when images are obtained in separate visits, the target may have been reacquired with a different set of guide stars, and this will limit the accuracy of the relative alignment to about 0.3 to 0.5 arcseconds. For more information on pointing repeatability, see Section 4.4.

To estimate the residual offsets before running TweakReg, users may display the images in ds9, align by WCS, and then blink the different frames. For more details on inspecting the WCS alignment, refer to section 3 in this notebook.

By default, TweakReg will solve for a residual shift, rotation, and scale between images (fitgeometry='rscale'). When the solution suggests a very small residual rotation, users are encouraged to rerun the task with fitgeometry set to shift. If the RMS of the fit is roughly the same, then the residual rotation is likely not real and the shift-only solution is recommended. (In other words, the simplest solution is usually the best one, and the rotation is likely not significant.) Additionally, if TweakReg computes a residual shift that is smaller than the fit RMS then the results are not significant compared to the errors and the user may proceed to drizzling without updating the image headers.

For images with long exposure times and low signal-to-noise sources (for example, narrow-band images), TweakReg may detect more cosmic rays than actual sources. When this happens, the fit may give a result that makes no sense.

If imagefindpars (used by TweakReg) is unable to produce source catalogs suitable for image alignment,  it may be necessary for the user to import their own custom cosmic ray-free catalogs generated using tasks like DAOFIND or SExtractor. These catalogs may be given to Tweakreg as input via the catfile parameter. 

Is the fit RMS small?

For a good solution with a large number of sources (a few hundred at least), the RMS of the fit is generally better than ~0.1 pixels (and as good as 0.03 pixels). When fewer astronomical sources (stars, compact objects like HII regions, or small galaxies) are available for centering, the RMS of the fit may be slightly larger. Users are encouraged to inspect the three TweakReg plots described below to verify the quality of the solutions.

Examine the Astrometric Residuals

Is there any remaining slope in residuals plot?

The four-panel residuals plot gives the x and y components of the residuals vs. x- and y-axis position, and is useful for spotting subtle and/or large scale alignment issues. A good fit gives flat residuals with typical RMS values less than 0.1 pixels. A residuals slope in the astrometric residuals plot may indicate that the true rotation or scale between images has not been adequately fit. Users can try changing the parameter fitgeometry from rscale to shift to see if this improves the solution; For example, a solution with a smaller fit RMS or a residual plot with a less obvious slope.

For ACS data, a small time-dependent skew in the geometric distortion has been corrected via improved distortion solutions. While the effect has largely been corrected, a small residual skew (+/- 0.05 pixels) may still remain and this may show up as a slope in the astrometric residual plots. This is a known limitation in the distortion calibration and does not indicate a problem with TweakReg. Users may also experiment with the clipping parameters nclip and sigma to see if removing outliers allows TweakReg to compute a more accurate solution (with a fit RMS ~0.1 pixels). Determining the optimal level of clipping is a judgment call, and users are advised to use care to not clip the residuals too aggressively. While more aggressive clipping may give a better fit RMS, an examination of the plots may show that the solution has been artificially over-constrained, showing a hard edge in the distribution and no outliers. A slightly larger fit RMS is better than a small fit RMS and an unintentionally biased solution.

Examine the Vector Plot

Are there any obvious "flow" patterns in the vectors?

The vector plot is an alternate way of viewing the four-panel astrometric residuals plot. In the vector plot, source magnitude and direction of residuals are plotted as a function of location. This is useful for spotting localized systematic deviations in image alignment. A good image alignment produces a vector plot that appears as small randomly-oriented vectors with no clear organized flows or structures. Any obvious "flow" patterns may indicate that the true rotation or scale between images has not been accurately fit.

Are sources detected over the entire field of view (for sparse fields or star clusters)? If not, are they detected in the regions expected (for example, a small galaxy which does not fill the image)?

To verify whether the fit is being based on "real" objects and not artifacts, users are encouraged to display the calibrated FITS images and over plot the matched source lists - an example of how to do this can be seen in step 2f of the Align Multiple Visits notebook. If sources are only matched in one portion of the detector, this may indicate that the sigma clipping parameters nclip and sigma were assigned too aggressively. Alternately, if sources were only detected in the sky surrounding the target (and not in the target itself), it may be necessary to adjust the imagefindpars parameters threshold and skysigma.

Are there "clumps" of sources detected near very bright stars?

Saturated (or very bright stars) may cause imagefindpars to detect a large number of sources in the halo of the star, in the diffraction spikes, or in bleeding pixels. To avoid biasing the TweakReg solution, users may define one or more "exclusion" regions such that sources within that area are not included in the fit. For more details on defining Exclusion Catalogs, see Section 5.4.2.

Examine the 2-Dimensional Histogram

Is the peak clearly defined?

TweakReg will display a two-dimensional histogram with an initial guess of the offsets between each image. A good fit will produce a 2D histogram with a single bright peak. When this fails, the user should examine the four-panel residual plot. If the fit does not appear to include the majority of sources, clustered tightly around zero residual, then it is possible that the fit has not been based on the position of astronomical objects, but instead on cosmic rays or detector artifacts, like hot pixels. To verify this, users are encouraged to display the calibrated FITS images and over plot the matched source lists to ensure that the fit is based on "real" objects and not artifacts. 

Alternately, a poorly-defined peak may suggest that the user needs to be more (or less aggressive) in clipping sources using the parameters nclip and sigma.

Is the fit crosshair centered on the peak?

When the fit crosshair is offset from the brightest pixel in the two-dimensional histogram, this may indicate a need to increase the search radius of the fit. By default, searchrad=1.0 arcsecond, but when images are obtained in different visits, especially for older data where the guide star catalogs have larger positional uncertainty, offsets of several arcseconds may be found.

Verify the Number of Matches Used to Compute the Solution

Does TweakReg crash with the message "not enough matches found?"

When TweakReg finds fewer than 15 objects in the final matched source catalog, it will report an error. When this happens, the user is advised to either decrease the minobj parameter, to increase the searchrad parameter, or to modify the clipping parameters nclip and sigma.

Users are also advised to inspect the number of objects in the initial (unmatched) source catalogs (with file naming convention sci*xy_catalog.coo), one of several intermediate processing files that are created by TweakReg. If the catalogs do not contain a sufficient number of sources (ideally a few hundred), the imagefindpars parameter threshold may be decreased to look for fainter sources. Since imagefindpars is not able to select for "sharpness," many of these sources will be cosmic rays or detector artifacts, so creating catalogs that are slightly larger than necessary for the final match will ensure that a sufficient number of true sources remain for computing the residual offsets between images.