The MultiDrizzle Handbook
PyDrizzle provides a semi-automated interface for computing the parameters necessary for running drizzle. PyDrizzle performs the task of determining the parameters necessary for aligning images based on the WCS information in the input image headers, as well as any supplemental alignment information provided in shift files (Section 5.5.2), and combines the images onto the same WCS. It does not identify cosmic rays, however, it has the ability to ignore pixels flagged as bad, such as pixels identified by other programs as affected by cosmic rays. If you have data for which cosmic ray rejection needs to be performed, please consider using MultiDrizzle (Section 5.4). This task was written using Python and may be run in either the Python or
PyRAFenvironments, although PyRAF is still necessary in order to have access to the EPAR interface.
The task understands how to work with single images, sub-array images, dither associations and mosaic associations for WFPC2, WFC3, STIS, NICMOS and ACS observations. Processing dithered or mosaic data with PyDrizzle gets handled through the use of association tables (Section 5.5.2). These are simple binary FITS tables with a few columns to specify the input exposures and the rootname of the output exposure, along with any residual offset or rotation relative to the headers WCS information necessary to get precise alignment when drizzling the data together. The offset information is applied to the shifts PyDrizzle (Section 5.3) calculates which are based on the WCS information contained in the header of each image.
Another PyRAF task, buildasn (Section 5.5.2), was written as part of the IRAF dither package to help a user build an association table from a set of observations in a user's directory. This can then be used as input to PyDrizzle to combine all the specified observations in one step.
PyDrizzle only aligns and combines images and still includes parameters for controlling the specifics of how this is accomplished, including exactly how to specify the output product's size, pixel scale, center and orientation. The full set of PyDrizzle parameters are described in the following table (Table 5.4).
Table 5.4: Input Parameters for PyDrizzle
Parameter Default Value Description Format
5.3.3 Basic Examples
22.214.171.124 Running in Pure Python
The following serves as a basic example of how to import and use PyDrizzle to process a dataset. This can be done in either a Python or PyRAF session, but this example is explicit for Python syntax. For an example in the PyRAF environment see the section on Real-World Examples Chapter 6 or simply type "epar pydrizzle" from the PyRAF command line and fill in the available parameters. If you have not created an association table yet, see the section on the buildasn (Section 5.5.2) function. For more information on the Python environment see the Python Web page:
- http://www.python.org/>import pydrizzle (then you can create the PyDrizzle object by calling the following) >p=pydrizzle.PyDrizzle("my_asn.fits", bits_single=0, bits_final=0, kernel="square", pixfrac=1.)
Table 5.5: Input Parameters for PyDrizzle
You can now run PyDrizzle on the data by issuing the command:>p.run()
Or, you can view and edit any of the objects values before executing the pydrizzle command, like the WCS information:>print p.observation.members.members.geometry.wcs WCS Keywords for j8bt06nyq_flt.fits[sci,1]: CD_11 CD_12: -7.3535609783668304e-06 1.85500817458759e-06 CD_21 CD_22: 2.8810562653901852e-06 6.6471909533171463e-06 CRVAL : 6.0271483333329998 -72.083511111110013 CRPIX : 512.0 512.0 NAXIS : 1024 1024 Plate Scale : 0.0284321026605 ORIENTAT : 15.5926361388 CTYPE : 'RA---TAN' 'DEC--TAN' PA Telescope: 15.79167
126.96.36.199 Running in the PyRAF Environment
If you prefer using the PyRAF environment, all you need to do is open up the task parameters using the EPAR interface. First, make sure all the necessary packages have been loaded by typing the following:stsdas dither
Now you can open the epar interface by typing "epar pydrizzle". You should see a window which looks similar to Figure 5.1.Figure 5.1: Snapshot of the PyDrizzle epar Window
Snapshot of the PyDrizzle epar window.
From here, you can enter the information necessary to drizzle your input images to a common frame.
5.3.4 Output Product File Format
The output from PyDrizzle is a single multi-extension FITS file with the suffix `_drz.fits'. The first extension contains the science (SCI) image which is corrected for distortion and dither-combined (or mosaiced), if applicable. The drizzled SCI image is typically in units of electrons per second, which is the default for ACS images. The user can choose to have the output in either electrons, electrons per second, data numbers (DN) or DN per second, some of these options retain the natural units of the instrument. For all options, the units chosen by the user are carried through the entire calculation. All pixels have equal area on the sky and equal photometric normalization across the field of view, giving an image which is both photometrically and atrometricaly accurate for point and extended sources. The dimensions of the output image will be computed on-the-fly by PyDrizzle and the default output plate scale will be read from the IDCTAB. These parameters, however, may be chosen by the user during reprocessing to best suit the actual data.
The second extension of the output image contains the weight (WHT) image. It gives the relative weight of the output pixels and can be considered an effective exposure time map. The data quality map created by the instrument calibration pipelines is used by PyDrizzle in creating the weight image.
The third extension of the PyDrizzle output image contains the context (CTX) image which encodes information about which input image contributes to a specific output pixel. This is done using a bitmask for each output pixel, where `bit set' means that the image, in the order it was combined, contributed with non-zero weight to that output pixel. The context image starts as a single 32-bit integer image but is extended to a cube with additional 32-bit deep planes as required to handle all the input images.
NICMOS users should note that this may seem further complicated by the nature of NICMOS data. Since the final science level NICMOS images that come out of calnica are really mathematical fits to the ramp of observations, the true exposure time varies across the calibrated science image. The default output from calnica is to have unitcorr set to perform, which divides the pixel counts by the full exposure time for that pixel, producing an output image in units of data numbers/second. NICMOS _cal.fits images contain a TIME extension which details the true exposure level of the image, pixel-by-pixel, after the individual reads have been combined into the ramp image and after cosmic ray rejection, which includes read rejection, has been done on the image. Since the calibrated image represents the actual countrate the pixel should have reported in the absence of defects in any of the individual reads, multiplying this final image by the full exposure time of the dataset (using the exptime keyword value) is an acceptable practice to convert the science image back into relative counts. The [TIME] extension in the output _cal file should only be used as a processing reference by the user.
Space Telescope Science Institute
Voice: (410) 338-1082