The MultiDrizzle Handbook

5.3 PyDrizzle

---

5.3.1 Introduction

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 PyRAF environments, 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.

5.3.2 Parameters

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
input		ASN table or single image filename, wildcard suffix, or @list	string
output		output drizzled image	string
section		Specify the image chip to be drizzled as a fits extension	string
prodonly	yes	Only use the product from the ASN table as input	boolean [True, False]
kernel	square	Shape of the kernel function	string [square,point, gaussian,turbo, tophat,lanczos3]
units	cps	Units of the output image	string [cps, counts]
pixfrac	1.0	drop size of each pixel, in pixel units form 0->1	real
rotate	no	Specify whether the output image should be rotated	boolean [False, True]
orient	0.0	Absolute orientation on the sky of the output image y-axis	real
psize		Size of the output pixel in arcseconds	real
ra		right ascension of the output image reference pixel (override default)	real
dec		declination of the output image reference pixel (override default)	real
xsize		the size in x of the output image (override default)	integer
ysize		size in y of the output image (override default)	integer
bits_single	0	integer sum of all DQ bit values that should be used for single=yes, when each input image is drizzled separately	integer
bits_final	0	integer sum of all DQ bit values that should be used for single=no, when the final image is created	integer
wt_scl	exptime	weighting factor for the input image	string [exptime,expsq]
in_units	cps	the units of the input image	string [cps,counts] (in either dn or e-)
idckey	idctab	keyword to use for selecting the reference file which contains the distortion coefficients for the data	string
clean	yes	remove temporary files created by PyDrizzle	boolean [True,False]
save	no	specify whether to keep the original drizzle output files	boolean [False,True]
build	yes	combine the separate output images into a single multi-extension fits file	boolean [True,False]

5.3.3 Basic Examples

5.3.3.1 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

object/parameter	Description
p	the object that is returned from the PyDrizzle function, it contains all the information necessary to start drizzling the data in the ASN table
"my_asn.fits"	the name of the ASN table that tells the function which images to use and how to apply offsets
bits_single=0	ignore all pixels (set to 0) which have bit values greater than 0 in the mask
bits_final=0	ignore all pixels (set to 0) which have bit values greater than 0 in the mask
kernel="square"	the type of kernel to be applied to the input pixels
pixfrac=1.	the fractional drop size for each pixel, no change here to original pixels, there's 1 input pixel in 1 output pixel

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[0].members[0].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

5.3.3.2 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.