5.4 The DrizzlePac Package

drizzlepac is a Python package containing tasks that allow users to align HST images, combine them, and perform coordinate transformations on source positions.

astrodrizzle uses image WCS information to combine images. For the most part, this works well for images taken in the same orbit. Images in one visit over several orbits usually adequately aligned because the same guide star pair is used, but they should be carefully inspected to check for very small offsets due to guide star re-aquisition anomalies.

Images from different visits, however, cannot be aligned based on WCS alone because guide star catalog positions have uncertainties as high as 0.3 to 0.5 arcseconds. Therefore, the tweakreg task was developed to fine-tune the alignments, using point sources common to each image to determine x and y offsets, and rotations. Other tasks in drizzlepac complement astrodrizzle and tweakreg, providing functions that would be useful, such as coordinate transformations. All these tasks rely on the same distortion information required by astrodrizzle, and also depend on other tasks from the stwcs and fitsblender packages (described later) to perform many of their operations.

Detailed information is available in the Python help files and the Read the Docs page.

DrizzlePac Tasks

A brief description of the tasks in drizzlepac:

Detailed information on how to run these tasks are available in their respective help files. Tasks that handle coordinate transformations–pixtopix, pixtosky, skytopix–are relatively straightforward and won’t be covered in this document (please consult the help file).

Data that has been manually reprocessed through the calibration pipelines (e.g. CALACS) has to be updated for compatibility with drizzlepac tasks. WFC3 and ACS images should be processed with the updatewcs task from the stwcs package to update SIP and other distortion keywords. 

tweakreg (which calls the imagefindpars sub-task) is used for aligning images. Please see Section 7.2.3 for a description of the task.

tweakback is used for additional image alignment applications; when tweakreg has been used to align drizzled products (i.e., different filters, pointings, or detectors), the tweakback task can be used to propagate the updated WCS back to the original flc.fits/flt.fits images. astrodrizzle can then be used to process those updated flc.fits/flt.fits. Note that tweakback only aligns the WCS in the image headers. 

blendheaders, a task that’s also run in the pipeline for ACS and WFC3 data, collects important keyword information from AstroDrizzle input images for inclusion in the final drizzle-combined image.

Aligning Images with TweakReg and ImageFindPars

Overview of the TweakReg Software

TweakReg provides an automated interface for computing residual shifts between images before they’re combined by AstroDrizzle. It is especially useful for combining images taken in different visits.

WCS information for each image is related to the guide star pairs used during telescope guiding. For images taken in the same visit and orbit, the alignment between images are generally very accurate, to about two to five milliarcseconds. For images in the same visit but across several orbit, guide star reaquisition could potentially introduce very small offsets between five to 20 milliarcseconds. However, for images taken at different visits using different guide stars, residual offsets that remain after the images are aligned based on their WCS information are due to uncertainties in the guide star catalog positions, which can be as large as 0.3 to 0.5 arcseconds. For more information about HST pointing stability, please see Section 4.4.

TweakReg can be used to align sets of images if there are enough point sources to make reliable matches, in the following way.

1. Using flat-field calibrated images (flc.fits/flt.fits or c0m.fits) as input, TweakReg can generate source catalogs for each image using an algorithm similar to daofind. Exclusion files, in the form of ds9 regions files or simple target-radius specifications, can be used to instruct TweakReg to avoid certain parts of the image for source detection. The software also accepts user-provided catalogs for each input image.
2. For each image, its distortion model is used to correct source positions. (Therefore, it is unnecessary to make drizzled products before obtaining source positions, as was the case for MultiDrizzle.)
3. A reference frame is determined that can contain all the input images, and to which all images will be aligned to. This reference frame could be an image in the input list (by default, the first image), a user-specified reference image, or undistorted sky coordinates (R.A., Dec.) and fluxes provided by the user. The offsets between each image and the reference frame are determined using a catalog-matching algorithm similar to xyxymatch. Matching sources between images can be severely exacerbated by cosmic rays, especially for long exposures. imagefindpars (called by tweakreg) parameters may be adjusted to impose flux detection ranges to exclude likely cosmic ray events. For pre-determined catalogs with magnitude values, potential matches that don’t fall in a reasonable magnitude range could also be discarded as a false match. Alternately, detections can also be performed on cosmic ray-cleaned images.
4. With the culling of false detections over several iterations of parameter adjustments, TweakReg should be able to converge on an acceptable RMS for the offset solution fits. Plots showing the quality of the fits can be displayed for each reference-image offset solution.

When the user is satisfied with the result, TweakReg is run one last time with those final parameters to update the WCS information in the images to a common reference frame, making it ready for AstroDrizzle processing.

imagefindpars Parameter Details

The task imagefindpars can be optionally called by tweakreg to fine-tune object detection settings. Its algorithm is similar to that used by daofind, and has parameter names that resemble those in the IRAF version of daofind. However, the skysigma and threshold parameters are not defined identically to those in daofind. The computesig parameter attempts to automatically determine the value of skysigma for each image, but it is prone to failure for images with low background such as those containing globular cluster regions and nebula. In those situations, a user-defined skysigma can be used for all input images.

A Note About “Difficult” Images

Discussions in this handbook assume images with enough stellar point sources to allow alignment using the daofind-like source-finding algorith in TweakReg. There are images, however, that are filled primarily with nebulosity, or with small faint galaxies and not much else, certainly not with enough stars useful for tweaking the alignment.

What can one do in such situations? In the case of nebulosity or high galactic latitude fields with few stars, direct cross-correlation can be done on prominent features in the nebulosity. But while cross-correlation is reliable and easy to use when there are only x- and y-shifts, it is far less adept at dealing with rotations or differences in scale.

For fields with lots of small galaxies, software such as SExtractor could be used to generate catalogs for input to TweakReg. This will require removing cosmic rays first, but if there are a few images that are reasonably well-aligned (such as those taken within a single visit), then cosmic ray-cleaned images could be used as a first pass in AstroDrizzle.

The CANDLES Treasury program has settled on a hybrid approach (Ferguson, H., Koekemoer, A., private communications). Catalogs are used to obtain the rotation and scale between images to do a first estimate of the shift. Rotation and scale are then fixed, and the shift is further refined using cross-correlation. At present, there are no straightforward ways for users to give the software a delta-shift and have it immediately translated into a change in header WCS. Users wanting to do this will need to update the headers themselves (by changing the CRVAL* keywords in their images, for instance). 

TweakBack

Drizzled images are distortion-corrected, making it easy to perform a fit between drizzled images using TweakReg to calculate the overall offset, rotation, and scale differences between the drizzled images. While applying a fit to align two drizzled images can be done very simply due to the lack of distortion, the input images which were combined to create those drizzled images still contain distortion, so a fit computed using drizzled images cannot be applied to those input images in a simple manner. This typically results in the user updating the drizzled image headers with the results of a fit without any means of updating the original distorted input images.

TweakBack takes the WCS information from a drizzled image, one that has been aligned to another drizzled image, and propagates the newly updated WCS information back to all the input images used to create the drizzled images. This will allow those input images to be combined again to produce new aligned drizzled products.

When to Use TweakBack

Some situations require alignment of drizzled images, such as:

• Aligning images taken in one filter to those taken in another filter
• Aligning long-exposure sets of images (that are dominated by cosmic rays) taken in different visits
• Aligning mosaics of a sparse field to an external astrometric catalog

Creating combined drizzled images for each filter results in images free of cosmic rays and detector defects, making it ideal for finding and matching sources. These cosmic ray-free drizzled images can therefore maximize the number of sources detected and minimize the work needed to find matches between sources, resulting in the best possible fit between the images using the most possible sources. Alignment of these drizzled images using TweakReg will result in highly reliable and accurate updates to the drizzled image headers that can then be passed back to the original input images.

TweakBack Algorithm

Any update to the WCS information of an image should only be done after copying the original WCS keyword values as an alternate WCS (using FITS Paper I standards). This gets done automatically when using TweakReg to update the headers of images, and the task also provides a means to recover the original alignment if errors are made in the new WCS keyword values. This task relies on the presence of the original WCS and the newly-updated WCS to be recorded in the drizzled image’s header as the last two alternate WCSs. The difference between the previous WCS values and the newly updated WCS values will be used as the basis for computing the changes that need to be applied to each distorted input image.

The algorithm used by this function follows these steps:

1. Verify or determine a list of distorted images that need to be updated with the final solution from the drizzled images.
   - The D00*DATA keywords from the PRIMARY header of the drizzled image will be used to build a list of input images that will need to be updated with the new WCS solution.
   - If no D00*DATA keywords can be found in the drizzled image PRIMARY header, then the user must provide a list of filenames for the images that need to be updated.
   - If the user does not specify a list of images and no D00*DATA keywords can be found, this task will report an error and quit.
2. Read in HSTWCS objects for last two alternate WCS solutions.
   - The last two alternate WCS solutions (as generated when tweakreg updates an image header with a new WCS solution) represent the drizzled images starting WCS and the newly updated WCS.
3. Generate footprints using the STWCS .calcFootprint() method for each WCS.
   - Each footprint corresponds to the location of the corner pixel from the drizzled image as it appears on the sky.
4. The sky positions of the corners of the drizzled image get computed using the new updated WCS solution and using the original WCS solution.
   - The pixel positions for corners of each WCS get computed by running the .wcs_sky2pix() method for the last (updated) WCS.
   - These pixel positions will be used to do a fit between the corner positions for the updated WCS and the drizzled image’s original corner positions.

5. Perform linear “rscale” fit between the two sets of X,Y coordinates.
   - The results of this fit will represent the correction applied to the original WCS to get the new updated WCS.
   

6. Update each input image WCS with the fit using updatehdr=yes code in tweakreg

This algorithm essentially backs out the correction that would have been applied by TweakReg if it had been run on two distorted input (flc.fits/flt.fits) images instead of drizzled images, then applies that correction to the distorted images just as TweakReg does itself. This means that input images updated using TweakBack will use the same conventions for keeping track of multiple WCS solutions in the input image headers just as if TweakReg was run.

This process has been tested on both ACS/WFC and WFC3/UVIS datasets and have demonstrated that this process can update images to as low as 0.001 pixels depending on the number of sources.

Updating Manually Reprocessed Images

Data that has been manually reprocessed through the calibration pipelines (e.g. CALACS) has to be updated for compatibility with drizzlepac tasks. The task updatewcs, in the STWCS package, is used to insert and format linear and polynomial distortion information into the image header for HST images, such as WFC3 and even STIS data. The updatewcs task can be run any number of times afterwards as needed to reset the WCS solution to the default solution generated by the pipeline.

Handling WCS Information With stwcs

DrizzlePac relies on STWCS, another software package within STScI_Python, to manage all WCS-related operations. stwcs supports not only reading in the WCS information from FITS images as WCS objects in memory, but allows users to perform coordinate transformations using the full distortion model from the image header, among many other operations, with those WCS objects.

This software also provides the capabilities to package a WCS solution and save it as a file of its own for application to a copy of the original image; more specifically, it defines and supports the use of headerlets.

The STWCS package, in turn, relies on the generally available pywcs package which provides a Python interface to the C library WCSLIB which serves as the definitive implementation of all the approved FITS standards for WCS information. In short, any operation in any DrizzlePac task (such as astrodrizzle or tweakreg) dealing with the WCS gets performed by calling the stwcs package and its tasks.

STWCS consists of two primary subpackages: updatewcs and wcsutil. The task updatewcs (from the stwcs.updatewcs package) performs corrections to the basic WCS and includes other distortion information in the science files as header keywords or file extensions. The stwcs.wcsutil package implements many tasks including the most basic HSTWCS object which extends default FITS standard implementation of the WCS (as implemented by the pywcs.WCS object) as well as all the headerlet related tasks. The HSTWCS Python object provides HST instrument-specific WCS support as well as methods for coordinate transformations and serves as the primary in-memory implementation of the WCS information used by all the tasks in the DrizzlePac package. The coordinate transformation tasks in the DrizzlePac package (pixtosky, skytopix, pixtopix) all rely on the HSTWCS object implemented in the stwcs package for performing the actual computations of the requested coordinate transformations. The wcsutil package also provides functions for manipulating alternate WCS descriptions in the headers. 

The tasks available in the STWCS package are:

More detailed information and API on these tasks can be found at the STWCS Read The Docs page.

blendheaders

A fundamental problem exists when trying to combine multiple images into a single product; namely, how to account for the header information from all the input images that went into generating the output product. The operation of drizzling multiple input images together to create a single output product of higher scientific value runs into this problem every time. 

The solution implemented for AstroDrizzle is the blendheaders task. This task creates a final output image header which contains a more complete record of all the keyword values from all the input images along with a table extension (called HDRTAB) that records values which change from one input image to another while eliminating keywords that no longer apply to drizzle products. This solution relies on rules specified by the user, or by the instrument teams for pipeline use, that describe what should be done with each keyword from every input image.

Some keywords from the input images can be merged into a reasonable single value for the output image using a simple operation such as mean, or first value, or last value based on the full list of input values from all input images. Other keywords, however, vary from one image to another and can not be combined into a reasonable single value and those keywords get flagged by the rules for population of a new table extension with the name HDRTAB. This table has a column for each keyword, and each row corresponds to the values derived from each science extension (not file). This allows the user to get a full record of, for example, how the CRVAL values varied for all the input images.

The merging of headers into a new header and a HDRTAB table extension has been implemented as the blendheaders task in the new fitsblender package. 

Anyone running AstroDrizzle has the option of defining their own set of rules for combining the headers, and use that set of rules to create a new drizzle product header and table that would be different from the default header generated by AstroDrizzle. For most users, though, the default rules should be sufficient as they were designed to account for the majority of keywords found in most HST imaging data. 

This software was designed primarily to support merging headers of images which all share the same basic FITS structure. For example, blendheaders could be run on a list of images that have a PRIMARY header and two SCI extensions, or on a list where all inputs are simple FITS files with only a PRIMARY header. It may be possible to combine images with differing numbers of science FITS extensions with missing information being represented with values of INDEF or NaN in the summary table.

Drizzled Image Header Summary Table

The summary table in the drizzled image contains a table of useful header keyword parameters that characterize each input image. The table itself consists of a single row for each SCI array (chip) that was combined to create the final image product. Each column of the table represents a keyword from the PRIMARY and SCI extension of each chip. The names of the columns, by default, will match the names of the original keyword from each input header. However, the rules can rename those columns (more about that later) to whatever meets the needs of the software generating the final combined product. Renaming the columns, though, introduces a level of indirection when trying to map the values in the table to original header keywords and should only be done sparingly.

This table will get written out (by blendheader) as a binary table (pyfits.BinTableHDU) extension with EXTNAME of type HDRTAB. The header for this table will only contain the column definitions for the table and other required FITS keywords for the binary table.

blendheaders Rules

The operation of blendheaders relies, as implied earlier, on a set of rules that specifies what to do with all the input values for each keyword in the input file headers. The rules which define how to manage specific keywords need to be specified as a list defining which keyword arguments are to be aggregated and how.

The default set of rules for all HST instruments are included with the package using the filename convention <instrument>_header.rules. Any local file with an extension of *.rules will be read in as a user-supplied set of rules if it meets the formatting requirements described in this section.

• Each element in the list should be a sequence with two to five elements
• First element: name of the keyword from the input header
• Second element: name of the keyword that will be used to report the output value, or the name of a table column to record all the input values
• Third element: if given, it specifies a function to be used on the list of input values for a keyword to generate a new output value
• Fourth and fifth elements: these specify how to deal with error conditions and what value to report when an error occurs in processing a set of input values

These rules have been refined for specification in ASCII files, as opposed to using direct Python syntax. The format for the rules file has been defined as: