Space Telescope Science Institute
DrizzlePac 2012 Handbook
help@stsci.edu
Table of Contents Previous Next Index Print


The DrizzlePac Handbook > Chapter 4: DrizzlePac Package > 4.2 AstroDrizzle: The New Drizzle Workhorse

4.2
Note Regarding WFC3/IR Images
 
Note for Experienced MultiDrizzle Users: astrodrizzle parameters are essentially the same as those in multidrizzle. There are, however, three new parameters: stepsize, resetbits, and num_cores. Please refer to their descriptions in Table 4.1
AstroDrizzle uses flat-field calibrated images (flt.fits, c0m.fits for WFPC2, flc.fits for CTE-corrected ACS images) as input files. There are two main components to the process: (1) create mask files for bad pixels and cosmic rays; (2) drizzle-combine the input images using the mask files, while applying geometric distortion corrections, to create a “clean” distortion-free combined image.
There are three components to mask files used by AstroDrizzle. Information about bad pixels flagged in the input images data quality array are taken into account. A “static pixel mask” is created by identifying pixels with abnormally low values in each image.
The third component is cosmic ray masks, one for each input flt.fits image. Creating cosmic ray masks are a major part of AstroDrizzle, so they are briefly described below (with more detailed information available later in this section):
Each input flt.fits image is drizzled to create an undistorted copy in the output frame, where the WCS information in the single-drizzled image header is used to align it with respect to a reference image.
The aligned single-drizzled images are combined to create a “clean” median image that approximates the appearance of a clean distortion-free combined image.
By comparing each flt.fits file with its counterpart median image, cosmic rays and other bad pixels can be identified and stored in a mask file.
These mask files are used in the final step where each input image is drizzle-combined to create a clean distortion-free output image. Depending on the number of images and type of observations, users can elect to adjust parameters to improve the quality of the final drizzle-combined image.
Note Regarding WFC3/IR Images
For IR images, the steps “Create Median Image,” “Blot back the Median Image,” and “Remove Cosmic Rays with Deriv, Driz-CR” in astrodrizzle may be turned off since cosmic rays are flagged in calwfc3 as part of the “up-the-ramp fitting.” However, it may be useful to run those steps (using a different bit flag, like 8192, for “cosmic rays” found during AstroDrizzle processing) to flag additional detector artifacts not present in the data quality arrays of the calibrated images. Note that it is very important to subtract the sky prior to drizzing the final image, or the science array will be compromised by increased noise.
Detailed Description of the AstroDrizzle Steps
4.2.1
Several initialization steps are performed by AstroDrizzle to set some preferences on how the code will execute and to insure the input data files have the correct format. These include specifying the input files, providing a name and format for the output image, and resetting cosmic ray flags in the data quality arrays of input images. In pipeline processing, AstroDrizzle is instructed to use specific task parameter values stored in the MDRIZTAB reference file, and the WCS is always updated to account for distortion corrections.
Parameter Details
Initialization parameters in astrodrizzle are listed below. Text in Arial font are supplemental comments to the descriptions in the astrodrizzle configuration file. Additional information is available in the astrodrizzle help file.
For several input images, provide a wildcard followed by a suffix (e.g., *flt.fits) or a comma separated list of filenames.
If a user specifies “final_wht_type=IVM”, the input file list can have two columns, one for the image and the second for the user-generated inverse variance maps (IVM) file If no IVM files are specified, astrodrizzle will automatically generate it for each input image.
If build=False, these individual data products are created: science image (e.g.,final_drz_sci.fits), weight image (e.g., final_drz_wht.fits), and if context=True, the context image (e.g., final_drz_ctx.fits).
If build=True one image with three extensions will be created (e.g., final_drz.fits). The first extension is the drizzled science image, the second is the weight image, and if context=True, the third extension is the context image. If context=False, the third extension is empty.
Button in the Teal window, "Update from MDRIZTAB"
Clicking on this button tells astrodrizzle to populate its parameters using values that were pre-determined and stored in the reference file named in the input image header keyword MDRIZTAB. In the pipeline, AstroDrizzle uses this reference file to populate parameters for different types of association.
As astrodrizzle runs, comments about its progress are displayed on the window. This file captures those comments, making it a useful resource for tracking down problems.
updatewcs, a task in the stwcs package, updates the values of basic WCS keywords and SIP convention keywords that hold astrometric information about an image. Use of this parameter requires the availability of the IDCTAB distortion reference file. After a file has been updated in the pipeline with this step, the IDCTAB distortion reference file is no longer needed when running AstroDrizzle for reprocessing data, as was the case for MultiDrizzle. In most instances, the default setting False should be used since updatewcs was already run for images retrieved after AstroDrizzle was installed in the pipeline. (For post-pipeline combining of images from multiple visits, WCS information can be updated using tweakreg.)
This value, a string, is the label of a WCS solution to be used when doing post-pipeline AstroDrizzle processing. Every time a WCS gets recorded as a new solution in an image, it is assigned a label stored in the keyword WCSNAME*. If this parameter is used, all input images are required to have the same WCS key value. (These WCS updates are done following FITS Paper I alternate WCS standards.)
By default, AstroDrizzle uses units specified by the BUNIT keyword in flt.fits and flc.fits headers. For ACS and WFC3, units are specified in electrons. For WFPC2, unit are in DN.
The default, True, tells AstroDrizzle to use distortion keyword values stored in the header.
The context image uses each bit (power of 2) in a 32-bit integer to record what input image contributed to the final value of the output pixel. For instance, the bits are set as follows: image 1/chip 1 = 1, image 1/chip 2 = 2, image 2/chip 1 = 4, image 2/chip 2 = 8, image 3/chip 1 = 16, and image 3/chip 2 =32, and so on. Each pixel in the context image is an additive combination of some of these values, depending on which images were used. If the user combines three UVIS images, a pixel with contributions from image1/chip1, image2/chip2, and image3/chip3 as the sum of the integer values 1, 4, and 16 respectively, for a total value of 21.  Should more than 32 chips be combined into a final output image, this context array will be "expanded" by creating another complete 32-bit integer array of the same size and layer, on top of the original to create a three-dimensional array with 2 layers. The new layer would then be used to keep track of the next 32 chips, with additional layers being created for further sets of 32 chips as needed.  
By default, all detector extensions in a FITSs file are processed. To drizzle only one chip, specify the group number for that image. For example, drizzling only chip 2 in ACS/WFC could be specified as 1 or sci,1.
If build=False three separate data products are created: science image (e.g.,rootname_drz_sci.fits), weight image (e.g., rootname_drz_wht.fits), and context image (e.g., rootname_drz_ctx.fits).
If build=True one image with three extensions, a multi-extension FITS file, will be created (e.g., rootname_drz.fits). The first extension is the drizzled science image, the second is the weight image, and the third extension is the context image.
When AstroDrizzle combines several images, whether its associated images in the pipeline or during post-pipeline processing, cosmic rays identified during processing are flagged in the input flt.fits data quality (DQ) extensions. In the HST pipeline, the DQ bit value used for cosmic rays is 4096.
stepsize1
This default value of 10 means that geometric distortion corrections are directly performed for every 10th pixel in x and y. For pixels between pairs of pixels with directly-calculated distortion corrections, interpolation between the pair is used to determine their distortion corrections values.
In the pipeline, AstroDrizzle updates the flt.fits data quality (DQ) arrays to flag cosmic rays found when combining associated flt.fits images. During reprocessing, these cosmic ray bits should be reset by the user to 0 (good pixels), so cosmic rays can be re-identified using user-specified astrodrizzle parameter values. Re-identification of cosmic rays is also needed for multi-visit image combination due to misaligned WCSs (caused by different guide star pairs used for each visit) that require realignment using tweakreg. This parameter can be used to reset any or all bit values found in the input images' data quality arrays.

1
New parameters in astrodrizzle.

Table 4.2: Parameters for astrodrizzle: “State of Input Files”
When set to the default value, True, astrodrizzle creates a subdirectory called OrIg_files to store a copy of the input flt.fits files before they're modified by AstroDrizzle. If OrIg_files already exists, the files in it are not overwritten.
If the directory OrIg_files already exists, this parameter allows users to overwrite the directory contents with input data for the current astrodrizzle run.
Intermediate files created by AstroDrizzle are automatically removed after processing by setting this parameter to True. For trouble-shooting purposes, setting this parameter to False could allow users to track down processing problems, or the files could be useful to new users who would like to inspect the intermediate products.
This is a useful option if astrodrizzle is re-run from scratch in the same directory using original input files in directory OrIg_files.
4.2.2
A detector-based static mask is created to flag bad pixels in the input images. First, severely negative or low value pixels are identified in each image to create individual bad pixel masks. For each detector in the list of input images1, the individual masks are combined to create a master-mask file for use in the final drizzle step.
If the AstroDrizzle static mask creation step is turned on, a static mask is created that identifies pixels with abnormally low values which could be due to over-subtraction of bad pixel values when applying the dark image correction in routine calibrations, or from post-pipeline over-subtraction of high sky levels. The clipping level for identifying bad pixels is an integer multiple of the RMS below the image’s mode. That number is given by the astrodrizzle parameter static_sig.
How the Static Mask is Used in Subsequent astrodrizzle Steps
The bad pixel mask used in the single-drizzle step in AstroDrizzle contains the static mask created as described in the previous paragraph, combined with any user supplied static mask as specified in the staticfile parameter, along with a mask of bad pixels described in the input image’s data quality arrays as flagged by the parameter driz_sep_bits.
The bad pixel mask used in the final drizzle-combining step in AstroDrizzle contains all bad pixels from all input images as used in the single-drizzle step, as well as the mask of pixels identified as cosmic rays as determined from running the driz_cr step. This allows AstroDrizzle to ignore all recognizable bad pixels during processing, including the bad pixels generated as a result of detector sensitivity issues (as identified in the static mask or data quality mask), as well as all user-identified bad pixels (through the staticfile mask).
Users should consider the details of their science image and decide if creating this mask is appropriate for the resulting science. For instance, if the image field is very crowded, or if it contains mostly nebulous or extended objects, the statistics used to create the static mask could be heavily skewed resulting in a mask that flags sources as bad pixels.
Parameter Details
Text in Arial are supplemental comments to the descriptions in the astrodrizzle configuration file. Additional information is available in the astrodrizzle help file.
Table 4.3: Parameters for astrodrizzle: “Static Mask” Creation
Abnormally low pixel values that deviate by more than a value of static_sig sigma below the image median are flagged as bad pixels in the static pixel mask. These are generally caused by bad pixel oversubtraction in the dark image during calibration.
4.2.3
In the pipeline, AstroDrizzle sky computation is based on the statistical distribution of pixel values in an input image. It is performed by iterative sigma-clipping, starting with the full range of pixel intensity values, to calculate the standard deviation. By default, pixel values deviating from the median value (specified by parameter skystat) by over four sigma are rejected, and this operation is repeated for a total of five iterations. The median value of the final distribution is used as the sky value, stored in the header keyword MDRIZSKY in the original flt.fits image (the original input images themselves are NOT sky-subtracted at this stage).
The default method provides good results for a wide range of datasets. However, the sky is occasionally slightly overestimated, and such cases can be improved in post-pipeline AstroDrizzle processing.
If the sky in a field is strongly affected by bright sources, the primary purpose of a background measurement is to ensure that there are no additional varying offset levels in the exposures prior to combination. Here, the varying “sky” levels may be due to any number of external sources (i.e., bright earth limb), but in a field of view dominated by bright source, there would not be enough sky pixels beyond the source to accurately determine the true sky. This leads to the possibility that sky variations from one exposure to the next could ultimately make the true background difficult or potentially impossible to determine.
Flat-field calibrated images (flt.fits, c0m.fits for WFPC2, flc.fits for CTE-corrected ACS images) delivered to users from the Archive are not sky-subtracted. However, the sky values calculated by AstroDrizzle in the pipeline are held in the group header keyword MDRIZSKY. The computed sky value is subtracted from a copy of the input image; these sky-subtracted image copies are later used in the final image combination step.
For cameras with multiple detectors (four in WFPC2, two each in ACS/WFC and WFC3/UVIS), sky values in an image are measured separately for each detector. The lowest measured detector sky value is adopted for all detectors for that exposure. This is based on the premise that the pixel intensity distribution will be higher in one or more detectors with extended or bright objects, thereby overestimating their sky value. In other words, the sky value in the detector least affected by bright or extended objects would provide a more realistic sky determination.
In the pipeline, sky subtraction is performed for broad-band data, and turned off for narrow-band data and UV observations that are “dark” (i.e., those that have no geocoronal emission in the filter bandpass). This is done for the following reasons:
These observations are often extended diffuse emission-line targets with flux that is much higher than the background. In such situations, the automated sky calculations by AstroDrizzle will lead to the introduction of errors larger that the background value. However, if the user is able to determine an accurate background level for such images, from parts of the image with measurable sky, then a user-specified sky value may be used to propagate those values directly to AstroDrizzle.
Sky subtraction is generally recommended for optimal flagging and removal of cosmic rays, when the sky background is more than a few electrons. However, for some science applications where the sky should not be removed, the final drizzle step can be performed with no sky subtraction (skysub set to False in astrodrizzle). If sky subtraction is turned off, then the final_pixfrac parameter should also be set to 1; otherwise, variations in sky between images will add noise to the data.
Methodology
Steps for determining sky value for each image:
1.
For each chip in the input image, obtain an estimate of the sky background by computing the clipped statistics (set by the parameters skyclip, skystat, skylsigma, and skyusigma).
2.
The lowest sky value relative to area on the sky (in units of electrons/square-arcsecond) among all the chips is then adopted for all chips in the image. That value is then rescaled to the plate scale of each chip to become the sky value for that chip.
3.
4.
Sky subtraction is not applied to the flt.fits images. Instead, the sky value is subtracted from the chip, on-the-fly, during the process of drizzling the image.
The default estimate of the sky background relies on computing the clipped median for each input chip. Offline processing by the user, however, could use a number of statistical operations to independently estimate the sky background, including the mode, mean and median.
A user-determined sky value, already subtracted from the input image, can be entered as a new keyword in the input file header–this keyword name is given by the astrodrizzle skyuser parameter. This user-supplied value will then get used, instead of AstroDrizzle’s computed sky value, when the sky-subtraction step is run.
However, if the sky subtraction step is turned off, AstroDrizzle will still use the sky value recorded in the MDRIZSKY keyword when performing single-image drizzling and cosmic ray identification, as it provides the only indication of the background sky level needed for the statistical computations used to identify cosmic rays.
Parameter Details
Text in Arial are supplemental comments to the descriptions in the astrodrizzle configuration file. Additional information is available in the astrodrizzle help file.
Table 4.4: Parameters for astrodrizzle: “Sky Subtraction”
Name of file containing user-computed sky values for use with each input image. This ASCII file should only contain two columns: (1) image filename in column 1; (2) sky value in column 2. The sky value should be provided in units that match the units of the input image. For multichip images, the same value will be applied to all chips.
4.2.4
Each input image is drizzled to create an undistorted copy in the output frame2. These images are registered with respect to a reference image (by default, the first image in the input list) using the WCS information in their headers, and will be used in the next three steps to create cosmic ray masks for each input image.
These single-drizzled images are generated using the full WCS information provided by each of the input images. Any WCS offsets will show up as misaligned sources in the single-drizzled images. In post-pipeline processing, these images can be used for refining the image registration for each of the input images, if the user decides to use image registration software other than the tweakreg task.
The default values in this step will define the output frame that will ideally include all input pixels from all the WCS-registered single-drizzled input images. But like the final drizzle step, the output frame may be redefined at this step using different parameter settings
Parameter Details
Text in Arial are supplemental comments to the descriptions in the astrodrizzle configuration file. Additional information is available in the astrodrizzle help file.
This parameter specifies whether or not to drizzle each input image onto separate output images. The separate output images will be corrected for geometric distortion and aligned to the reference image based on their WCS. These images are used to create the median image, needed for the cosmic ray rejection step.
The default turbo kernel function is only used in the “drizzle separate images” step, not in the final drizzling step. It specifies the form of the kernel function used to distribute flux onto the separate output images. Several options are available:
square: original classic drizzling kernel which maps each corner of the input pixel (scaled in size by the driz_sep_pixfrac parameter) to its position in the output image.
point: a point so each input pixel can only contribute to the single pixel that is closest to the output position. It's equivalent to the limit pixfrac-->0 and is very fast.
gaussian: this is a circular gaussian with FWHM equal to the value of pixfrac, measured in input pixels.
turbo: this is similar to the square kernel, but the box is always the same shape and size on the output grid, and always aligned with the X and Y axes. This results in a significant increase in speed.
tophat: the kernel is a circular "top hat" shape of width pixfrac. Flux from the input pixel gets distributed only to the output pixels within pixfrac/2 of the output position.
lanczos3: a Lanczos-style kernel extending 3 pixels from the center. The Lanczos kernel is a damped bounded form of the sinc interpolator and is very effective for resampling single images when drizzing is in the native scale and pixfrac=1. It leads to less resolution loss than the other kernels, and also less correlated noise in outputs. It is however much slower. It should never be used for pixfrac != 1.0 and is not recommended for scale != native scale.
NOTE: The default value for this parameter is turbo since it is much faster than square, and it is quite satisfactory for the purposes of generating the median image.
If set to exptime, the scaling value will be set equal to the exposure time found in the image header. This is the default recommended behavior. It is also possible to give driz_sep_wt_scl=expsq for weighting by the square of exposure time, which is optimal for read noise-dominated images. A final option would be to specify a specific numeric scaling factor (floating point value) that should be applied as-is when drizzling the images.
Fraction by which the input pixels are "shrunk" before being drizzled onto the output image grid, given as a real number between 0 and 1. This specifies the size of the footprint, or drop size of a pixel in units of the input pixel size. (If pixfrac is set to less than 0.001, the kernel will be reset to point for more efficient processing.) For the “drizzle separate images” step, a default value of 1.0 is recommended in order to ensure that each output drizzled image is fully populated with pixels from the input image.
Value assigned to output pixels that did not receive flux from any input pixels during drizzling. The default setting is None. If the weight in both the input and output images for a given pixel are zero, the output pixel will be set to the value it would have had if the input had a non-zero weight. Otherwise, if a numerical value is provided (for example, 999), then these pixels will be set to that value.
This parameter holds data quality (DQ) bit values of anomalous pixels in the flt.fits images that should be considered as good. All pixels flagged as good (bit value 0), and those with flags specified in this parameter, are used to create the single drizzle science image and define its associated weight images. If there are several flags that should be considered good, either the sum of their values or a comma-separated list of values can be entered.DQ flag values for different instruments are located in their Data Handbooks.
Table 4.6: Parameters for astrodrizzle: “Custom WCS for Separate Outputs”
Position angle of output image’s Y-axis relative to North. A value of 0.0 orients the drizzled image with North at the top of the drizzled image. The default, INDEF, specifies that the images will not be rotated, but drizzled in the camera’s default orientation (where the drizzled image’s x and y axes corresponding approximately to the detector axes). The INDEF option conserves disk space, making it the optimal choice for single drizzled images used in the intermediate step of creating a median image.
Linear pixel size in arcseconds/pixel for the separately drizzled images (that will be used in creating the median image for cosmic ray rejection). The default value of INDEF specifies that the undistorted pixel scale of the first input image will be used as the pixel scale for all the output images.
Size, in pixels, of the X axis for the separately drizzled output images. If no value is specified, it will use the smallest size that can accommodate the full dithered field.
Size, in pixels, of the Y axis for the separately drizzled output images. If no value is specified, it will use the smallest size that can accommodate the full dithered field.
4.2.5
Single-drizzled WCS-aligned images created from the previous step are combined to create a median image with statistical rejection of bad pixels from the image stack. It serves as an approximation of a combined distortion-free “clean” image with most cosmic rays and hot pixels removed. This median combination gets performed section-by-section from the input single-drizzled images. Each section corresponds to a contiguous set of lines from each image taking up no more than 1 Mb in memory, so that combining 10 input images would only require 10 Mb of memory for this step. This median image will then be used in the next two steps for creating cosmic ray and bad pixel masks.
Parameter Details
Text in Arial are supplemental comments to the descriptions in the astrodrizzle configuration file. Additional information is available in the astrodrizzle help file.
The median image, created using single-drizzled images from the previous step, will be used as a clean distortion-free “truth” image for cosmic ray rejection.
These masks are generated from weight files created in the previous step (drizzling each input image to create a single drizzled image, as well as a weight image based on the flt.fits DQ array). The bad pixels flagged in those mask files will be excluded when calculating the median. Generally this step should be set to True, unless the user has reasons to want to include bad pixels in the median.
This parameter allows the user to choose method for creating the median image. Valid options are: median, mean, minmed, imedian, imean, and iminmed.
The mean and median options set the calculation type when running numcombine, a numpy1 method for median-combining arrays to create the median image.
The minmed option will produce an image that is generally the same as the median, except in cases where the median is significantly higher than the minimum good pixel value. In this case, minmed will choose the minimum value. The sigma thresholds for this decision is provided by the combine_nsigma parameter. However, when a large number of images are being combined with this method, and many of the values for a pixel exceed the combine_nsigma threshold, minmed will pick the minimum value, biasing the pixel in that median image towards a low value. minmed is highly recommended for three images, and is good for four to six images, but should be avoided for ten or more images.
A value of median is the recommended method for a large number of images, and works equally well as minmed down to approximately four images. However, the user should set the combine_nhigh parameter to a value of 1 when using median with four images, and consider raising this parameter’s value for larger numbers of images. When the number of values being considered for calculating a median value is even, the two inner values are averaged. This could bias the median value. Therefore, the user may want to have an odd number for the total number of images minus combine_nhigh.
The options starting with i, such as imedian, works just like the normal median operation except when dealing with a pixel where all the values are flagged as “bad.” In this case, the i functions to return the last pixel in the stack as if it were good. This will, for instance, prevent saturated pixels in the image from leaving holes in the middle of the stars.
When combine_type is minmed, these are the sigma values used for accepting minimum values instead of median values. For the two values specified, the first value is used in the initial choice between selecting the median and minimum value for a pixel. Pixels adjacent to those flagged as cosmic rays are more prone to being affected by cosmic rays as well. This gets accounted for by specifying a second value for this parameter. This second value specifies a more stringent criteria for identifying a pixel as a cosmic ray and will be used to reject additional pixels around those identified in the first step. If only one value is specified, then it is used in both steps.
When combine_type is set to median, this parameter sets the number of low value pixels to automatically reject during image combination.
When combine_type is set to median, this parameter sets the number of high value pixels to automatically reject during image combination.
Sets the lower threshold for clipping input pixel values from the generated median image which are more than this number of sigma below the median for each pixel. This floating-point value, when specified, gets passed directly to the imcombine function used by AstroDrizzle for use in creating the median image. The default setting of None specifies that no thresholds be used to clip the values used to create the median image.
Sets the upper threshold in sigma for clipping input pixel values from the median image which are more than this number of sigma above the median value for each pixel. This floating-point value, when specified, gets passed directly to the imcombine function used by AstroDrizzle for use in creating the median image.The default setting of None specifies that no thresholds be used to clip the values used to create the median image.

1
NumPy is a Python extension that provides support for large, multi-dimensional arrays and matrices, including a large library of mathematical functions for operating on arrays.

4.2.6
The blot software takes a distortion-corrected image and applies (not removes) the full distortion model to recreate the original distorted input image. In other words, a drizzled image is “reverse-drizzled” to recreate the original distorted image.
In the previous step, a median image was created by combining the distortion-corrected single-drizzled images to generate an initial guess for the cosmic ray-cleaned combined output image. In this step, the median image is “blotted” to create clean versions of each input image at each of their respective dither locations.
This is done so that in the next step, these blotted images will be directly compared to their counterpart original distorted input images for detection of bad pixels, hot pixels, and cosmic rays to create bad pixel masks.
Parameter Details
Text in Arial are supplemental comments to the descriptions in the astrodrizzle configuration file. Additional information is available in the astrodrizzle help file.
Table 4.8: Parameters for Astrodrizzle: “Blot Back the Median Image”
Perform the blot operation on the median image. The output will be median-smoothed images that match each input chip location. These images will be used in the cosmic ray rejection step.
nearest: Nearest neighbor
linear: Bilinear interpolation in x and y
poly3: Third order interior polynomial in x and y
poly5: Fifth order interior polynomial in x and y
sinc: Sinc interpolation; accurate but slow
The poly5 interpolation method has been chosen as the default because it is relatively fast and accurate compared to the other options. If sinc interpolation has been selected, then it will use the value of the parameter blot_sinscl to specify the size of the sinc interpolation kernel.
Size of the sinc interpolation kernel in pixels.
Restore a sky value (subtracted from the input image during the drizzle step) using the MDRIZSKY value from the header. If True, the blot_skyval parameter is ignored. This allows the output blot image to have the same background sky level as its counterpart original input image.
4.2.7
In this step, the software compares each blotted image with its counterpart original flt.fits image to detect spurious pixels such as cosmic rays and hot pixels. The spurious pixels are flagged in cosmic ray masks that will be used in the final drizzle-combine step. Spurious pixels are identified by comparing the original input flt.fits image and its corresponding cleaned blot image, and blot derivative image. (A derivative image provides a measure of how sharp the edges of sources are in the image.)
The process of identifying cosmic rays and other bad pixels requires the following operations:
Take the spatial derivative of each blotted image from the previous step. This derivative image is used to estimate the degree to which the value of the blotted estimate has been distorted by errors in the image offset (computed from the WCS of each input image), and the blurring effect of taking the median.
Compare each original image with the corresponding blotted image. Where the difference is larger than what would be expected from noise statistics or an error in the shift, the suspect pixel is masked. The statistical limit gets set by the user through the first term of the driz_cr_snr parameter.
Repeat the previous step on pixels adjacent to pixels already masked, using a more stringent comparison criterion specified by the second term of the driz_cr_snr parameter.
The deriv algorithm uses the blotted median image to compute the absolute value of the difference between each pixel and its four surrounding neighbors; for each pixel, the largest of these four values is then used by the driz_cr algorithm to flag cosmic rays and other blemishes, such as satellite trails. Where the difference is larger than can be explained by noise statistics, the flattening effect of taking the median, or an error in the shift (the latter two effects are estimated using the image derivative), the suspect pixel is masked.Cosmic rays are flagged using the following rule:
|data_image - blotted_image| > scale x deriv + SNR x noise
where scale is defined as the multiplicative factor applied to the derivative, deriv.
This expression is used to determine if the difference between the data image and the blotted image is large enough to require masking. noise is calculated using a combination of the detector read noise and the poisson noise of the blotted median image, plus the sky background.
The user must specify two cut-off signal-to-noise (SNR) values for determining whether a pixel should be masked: the first for detecting the primary cosmic ray, and the second for masking lower-level bad pixels adjacent to those found in the first pass.
Since cosmic rays often extend across several pixels, the adjacent pixels make use of a slightly lower SNR threshold. If desired, a third-pass cosmic ray rejection can be carried out by “growing” the cosmic rays via the driz_cr_grow parameter.
When driz_cr_corr is set to yes, the task will create both a cosmic ray mask image (suffix sci?_crmask.fits where “?” is the extension number) and a clean version of the original input images (suffix crclean.fits), where flagged pixels are replaced by pixels from the blotted median. The cosmic ray masks are multiplied by the static pixel mask from the first step and masks created from pixels flagged as “bad” in the flt.fits DQ array, to create a final mask for each image. The optional parameter crbit allows the user to assign an alternate flag value to cosmic rays, and this flag will be written to the DQ array of each input image.
Parameter Details
Text in Arial are supplemental comments to the descriptions in the astrodrizzle configuration file. Additional information is available in the astrodrizzle help file.
Table 4.9: Parameters for astrodrizzle: “Remove Cosmic Rays with deriv, driz_cr”
Perform cosmic ray detection? If set to True, it will detect cosmic rays and create cosmic ray masks using the driz_cr algorithm.
When set to True, two images per input image are created: a cosmic ray-cleaned input image with suffix _cor.fits, generated directly from the input image, and a corresponding file with suffix _crmask.fits that documents the pixels detected affected by cosmic rays.
4.2.8
In the final step, the original input images are drizzle-combined, using the DQ, static, and cosmic ray masks to exclude bad pixels, hot pixels, and cosmic rays from the final image computation. The resulting drizzle-combined image is a registered, cosmic ray-cleaned, distortion-free, photometrically flat science image with associated weight and context images. By default, the output image will be written out as a single multi-extension FITS file, but the user could have them written out as separate simple FITS images.
The output frame, just like the single drizzle step, can be redefined using specific parameter settings; otherwise, default values will be used to include all the input pixels from all the WCS-registered input images.
Parameter Details
Text in Arial are supplemental comments to the descriptions in the astrodrizzle configuration file. Additional information is available in the astrodrizzle help file.
If True, AstroDrizzle combines the input images, while applying the static and cosmic ray masks, to create a final cleaned, distortion-corrected image.
EXP: the final image is weighted by the input image exposure times. This option is provided as the default since it produces reliable weighting for all types of data, including older instruments (eg., WFPC2) where more sophisticated options may not be available. This weighting is a good approximation in the regime where the sky noise dominates.
ERR: for ACS and STIS datasets, this option is generally recommended as the most accurate type of weighting for producing the final drizzle-combined image. The final drizzled image is weighted according to the inverse variance of each pixel in the input images, calculated from the data error array extension in each calibrated input image (flt.fits or flc.fits). This error array encapsulates all the noise sources in each exposure such as read noise, dark current, and sky background, as well as Poisson noise from the sources which includes a dependence upon exposure time as the Poisson noise increases with increasing counts. This option should not be used for WFPC2 because the ERR array is not produced during calibration.
IVM: for this option, the user can either supply his or her own inverse-variance weighting map, or let AstroDrizzle automatically generate one during the final drizzle step. This may be necessary for specific purposes, for example, to create a drizzled weight file for software such as SExtractor that expects a weight image containing all background noise sources (sky level, read noise, dark current, etc.) but not the Poisson noise from the objects themselves.
User-generated inverse variance images are specified at astrodrizzle’s input parameter using an ASCII file containing a list of input calibrated images (one per line), with a second column containing the name of the inverse variant map (IVM) file corresponding to each calibrated exposure. Each IVM file must have the same file format as the input file. If the calibrated images are multi-extension FITS files, then the IVM extension must be defined in the EXTNAME keyword as IVM with a separate IVM extension for each SCI extension in the science image.
If no IVM files are specified on input, AstroDrizzle will rely on the flat-field reference file and computed dark value from the image header to automatically generate an IVM file specific to each exposure. This requires that the PFLTFILE (flat-field reference file) be accessible during processing.
square: original classic drizzling kernel
point: this kernel is a point so each input pixel can only contribute to the single pixel which is closest to the output position. It is equivalent to the limit pixfrac --> 0 and is very fast.
gaussian: this kernel is a circular gaussian with FWHM equal to the value of pixfrac, measured in input pixels.
turbo: this is similar to the square kernel but the box is always the same shape and size on the output grid and always aligned with the X and Y axes. This results in a significant speed increase in some cases.
tophat: the kernel is a circular "top hat" shape of width pixfrac. In effect, only output pixels within pixfrac/2 of the output position are affected.
lanczos3: a Lanczos-style kernel extending three pixels from the center. The Lanczos kernel is a damped, bounded form of the sinc interpolator and is very effective for resampling single images when scale and pixfrac are set to 1. It leads to less resolution loss than the other kernels, and also less correlated noise in outputs. It is, however, much slower. It should never be used for pixfrac != 1 and is not recommended for scale != 1.
For the default value, exptime, the scaling value is set equal to the exposure time found in the image header. It Is also possible to set this value to expsq for weighting by the square of exposure time which is optimal for read noise-dominated images.
Fraction by which the input pixels are “shrunk” before being drizzled onto the output image grid, given as a real number between 0 and 1. This specifies the size of the footprint, or drop size of a pixel in units of the input pixel size. If the pixfrac is set to less than 0.001, the final_kernel parameter is reset to point for more efficient processing. If more than a few images are being combined, values smaller than 1 (e.g. 0.7 or 0.8) can be specified, which result in a slightly sharper output image.
The final_pixfrac value has to be small enough to avoid degrading the final drizzle-combined image, but large enough that when all images are "dropped" onto the final frame, coverage of the output frame is fairly uniform. In general, final_pixfrac should be slightly larger than the final output scale to allow some "spillover" to adjacent pixels. This will help avoid "holes" in the final product when a given pixel has been flagged as "bad" in several frames. As a rule of thumb, statistics performed on the drizzled weight image in the region of interest should yield an RMS value (standard deviation) that is less than 20% of the median (midpoint) value. This threshold is a balance between the benefits of improving the image resolution at the expense of increasing noise in the background.
Value assigned to output pixels that have zero weight or did not receive flux from any input pixels during drizzling. If the default value None is used and if the weight in both the input and output images for a given pixel are zero, the output pixel will be set to the value it would have had if the input had a non-zero weight. Otherwise, if a numerical value is provided (e.g. 999), then these pixels will be set to that value.
Integer sum of all the DQ bit values from the input image’s DQ array that should be considered “good” when building the final weighting image. (If the parameter resetbits was not set, the bit flag for cosmic rays detected in a previous AstroDrizzle run, 4096 for ACS and WFPC2 data, can be set here.)
This parameter determines the units of the final drizzle-combined image, and can either be counts or cps (count rate). The designated units are passed through to drizzle in the final drizzle step.
Table 4.11: Parameters for astrodrizzle: “Custom WCS For Final Output”
Position Angle of drizzled image’s Y-axis w.r.t. North (degrees)
The default of 0.0 (None) would orient the final output image so north is at the top of the image. A value of INDEF would specify that the images will not be rotated, but will instead be drizzled in the default orientation for the camera, with the x and y axes of the drizzled image corresponding approximately to the detector axes.
Linear size of the output pixels in arcseconds/pixel for the final combined product. The default value of None specifies that the undistorted pixel scale for the first input image will be used as the pixel scale for the final output image.
Size of the X axis of the final drizzled image (in pixels). The default, None, will use the smallest size that can accommodate the full dithered field.
Size of the Y axis of the final drizzled image (in pixels). The default, None, will use the smallest size that can accommodate the full dithered field.
4.2.9
It is possible to override information in the image headers by setting these parameters directly so AstroDrizzle can work with data generated or modified by the user rather than working with data that came directly from the HST Archive.
Parameter Details
Table 4.12: Parameters for astrodrizzle: “Instrument Parameters”
4.2.10
A general overview of drizzlepac is available in Section 4.4. The examples below (following the “-->” PyRAF prompt) illustrate how to call astrodrizzle from PyRAF and Python.
Before astrodrizzle can be run, the drizzlepac package must be loaded. This only needs to be done once per session. The command is executed either in PyRAF or Python.
If the package needs to be reloaded,
To run astrodrizzle using the TEAL GUI in PyRAF,
To run astrodrizzle as a command-line in PyRAF or Python (the parameter settings are for illustrative purposes):
The command above can also be run in PyRAF or Python with the parameter values written to a configuration file (suffix “.cfg”) that is read by astrodrizzle,
The help file can be accessed either from the TEAL GUI or at the command-line as such:
To write the help contents to an ASCII file,
4.2.11
Listed below, as a refresher for experienced MultiDrizzle users, are the parameters for astrodrizzle. The values assigned to the parameters are task defaults that have been chosen to cover a wide range, but not all, data types.
While the parameters below are familiar, the format of that file is something new. It's called a configuration file, an ASCII file containing a list of parameters and their values that can be loaded into astrodrizzle. Any drizzlepac tasks run from the TEAL GUI can accept configuration files to set the value of task parameters, and parameter settings can be saved to uniquely-named configuration files.
 
4.2.12
AstroDrizzle combines data using weights, a practice that may be new to some users who routinely add images together. Summing images works if the sky is stable, or if the objects’ Poisson noise (not read noise) is the primary source of noise in the image; this is essentially equivalent to setting final_wht_type to EXP (exposure time weighting) in astrodrizzle.
However, for much of the work done with HST, sources of interest are faint compared to the sky. Images are not dominated by Poisson noise, but rather by read noise and sky noise. In this case, the inverse variance map (IVM) is a good weighting option because it weights each pixel by the sky, dark noise, and read noise, adjusting appropriately for the value of the flat field.
But then, why not do a full calculation of the noise in each pixel in each image instead? This can be done by setting final_wht_type to ERR in astrodrizzle. This weight is what statisticians call the “minimum variance estimator.” It has the smallest statistical error of all choices of weights. However, it is not an “unbiased minimum variance estimator.” If a pixel in an image has, by chance, a few lesser counts than one would expect on average in a particular pixel, then calculating the noise for that pixel based on the number of counts will underestimate the noise and thus overestimate the significance of that pixel. The inverse problem occurs if the pixel happens to be a bit brighter than average. As a result, using this weight produces a small bias (usually no more than one to two percent in HST images). Sources in the resulting final image will be slightly fainter than they really are.
In general, photometric software available to most users does not take advantage of the final weight map. Some users may wish to write their own code to use the information in the weights. In this case, there are several choices:
If exposure time weighting (EXP) was used, the final image could be multiplied by the weight image to get the number of source counts in each pixel to estimate photon noise.
For IVM weighting, and when there’s no concern for very bright sources in the field, the final IVM output weight map could be used.
If the ERR array was used, this already provides a very good estimate of the noise (but not the bias).
For users who want an accurate weight map for use in photometry, a good approach may be to first run astrodrizzle using final_wht_type set to either EXP (when bright sources are most important) or IVM (if the faint sources are the primary objects of interest). This creates the final science image but not the final weight map. To create a final weight map, astrodrizzle needs to be run again, using the same weighting scheme as in the first drizzle; however, the original weight maps (drz_wht.fits images) should be drizzled rather than the images. This will give an output “image” that fully estimates the error at each pixel. At present, there’s no easy way for the user to do this. Perhaps this could be done by swapping in the flt.fits ERR array for the science (SCI) array, then running astrodrizzle on the modified images. If there is demand for this approach, it may be implemented as a feature in a future version of AstroDrizzle.
4.2.13
The AstroDrizzle software will estimate the memory requirements for processing a particular set of data during the “Initialization Step” and print a summary to the screen.
The reported requirements include the size of the final output image in pixels, the number of cores to be used, and an estimate of the amount of memory required for processing. AstroDrizzle will estimate the maximum amount of memory required during processing based on the size of the input files, the number of cores to be used, and the size of the final output products. This information can be used by the user to determine whether or not their processing run will require more memory or disk space than installed on their system, allowing them to interrupt the processing as soon as possible using Ctrl-C so that input parameters can be reset as needed.
AstroDrizzle requires approximately the same processing time as MultiDrizzle. However, to improve speed a new astrodrizzle parameter called num_cores will enable parallel processing using multiple cores, greatly reducing processing time. This has been enabled for the driz_separate and driz_cr steps. Memory usage will be a prime concern for those who rely on this parallel processing feature as each core will require a separate copy of the output array to be stored in memory along with having each input image in memory. For example, processing four WFC3/UVIS images to generate a 5000 x 5000 mosaic on a quad-core system will require over 1.3Gb of memory during the single drizzle step. Users with little RAM are, therefore, strongly advised to run with num_cores=1.
An example of the processing time is shown in Figure 4.1 for three WFC3/UVIS images that were combined using astrodrizzle with default parameters. The total processing time using 6 cores was only 3.6 minutes. When num_cores was set to 1, the actual memory usage was lower, but the total processing time increased to 6.3 minutes, compared to the run time for MultiDrizzle (5.5 minutes) for the same dataset using one core.
Figure 4.1: Processing Time for Three WFC3/UVIS Images using One and Six Cores

1
AstroDrizzle input images can be from more than one instrument, such as cases where ACS/WFC and WFC3/UVIS images are being combined.

2
Two output files are created: a single-drizzled science image and a single-drizzled weight image, both in a simple FITS format.


Table of Contents Previous Next Index Print