STScI

The MultiDrizzle Handbook

TOC PREV NEXT INDEX PDF

5.4 MultiDrizzle


5.4.1 Introduction

Cosmic ray rejection using the separate tasks in IRAF's dither package required the interactive use of many separate tasks; a complicated and often error-prone procedure. In addition, the geometric distortion must be removed from each input exposure in order to calculate precise shifts for alignment of the images well enough to recognize the presence of cosmic rays in each exposure. MultiDrizzle automates this entire process into a single operation based on the basic drizzle algorithm for removing the distortion and aligning the images. It then provides control over the individual steps through a separate set of parameters for each step in the process while taking into account many of the unique characteristics of the different HST cameras. As a result, a single set of dithered exposures can be combined into a single mosaic while removing the distortion and cosmic rays simply by running this one task.

5.4.2 Software Requirements

MultiDrizzle has been designed as a Python package with its own interface and can be run from the Python environment in conjunction with STSDAS 3.2 or later. However, it can also be loaded into STSDAS under PyRAF to enable use of the graphical EPAR interface that comes with the PyRAF command interface. These packages have been designed to work together in an almost seamless manner without requiring any manual setting of the environment by the user. MultiDrizzle requires at least Python 2.4, Numpy v1.0, and F2PY to be installed for operation with the Python interfaces. In addition, STSDAS 3.8 and PyRAF 1.1 are required for use of the GUI EPAR interface.

5.4.3 Data and Header Specifics

This is a detailed example for ACS data, but will be generally applicable for any instrument. For a specific, more detailed example of the instrument you are working with please see Real-World Examples Chapter 6.

All ACS data calibrated using the standard HST calibration pipeline has been processed by MultiDrizzle to remove geometric distortion and cosmic rays when associated images are combined. Data taken using a standard dither pattern, using CR-SPLIT on a long exposure or using REPEAT-OBS, as specified in the observing proposal will produce associated datasets that will be automatically combined into a dither product by MultiDrizzle. There will be times, though, when the results are not sufficient for scientific analysis and the images require reprocessing off-line using MultiDrizzle. This example illustrates how to take observations associated by the HST calibration pipeline and reprocess them with MultiDrizzle.


Table 5.6: Association table for dithered observations. This example will be based on observations taken using a 2-point Dither-Line pattern with CR-SPLIT=2 at each pointing using the WFC detector of the ACS.
MEMNAME
MEMTYPE
MEMPRSNT
J8CW03A1Q
EXP-CR1
yes
J8CW03A2Q
EXP-CR1
yes
J8CW03FFQ
EXP-CR2
yes
J8CW03FJQ
EXP-CR2
yes
J8CW030X0
PROD-DTH
no
J8CW03021
PROD-CR1
yes
J8CW03031
PROD-CR2
yes

It is assumed that this association has already been processed using calacs. The products created by calacs include both cosmic ray cleaned, calibrated products with `crj.fits' suffixes and fully calibrated input images with `flt.fits' suffixes. This will result in having at least the following files available in the current directory:


Table 5.7: Files That Need to be Available to run MultiDrizzle
J8cw030x0_asn.fits
J8CW03A1Q_flt.fits
J8CW03A2Q_flt.fits
J8CW03FFQ_flt.fits
J8CW03FJQ_flt.fits

5.4.3.1 Reference Files

The default files which were used to process data retrieved from the HST archive are referenced in the header using an environment variable which points to the directory where they are stored. For ACS this variable is called "jref". If you retrieved the best reference files along with your data, make sure that this points to the directory in which they were saved. If you have used specialized reference files make sure that the full path to their location is also referenced correctly in the data headers. A quick way to check the current value of the variable (in IRAF or PyRAF) is to use the "show" command:

  >show jref

If the variable is incorrect, it can be set using the standard IRAF command "set", where the directory shown in this example would be replaced by the correct one for your local system. It might, for example, be located at:

  >set jref = /grp/hst/cdbs/jref

You should also set jref in your appropriate operating system environment setup file (such as .setenv on Mac X11, Unix and Linux)

  >setenv jref /grp/hst/cdbs/jref

Two important file are the distortion coefficients reference file, IDCTAB (Section 4.2.4), and MultiDrizzle parameter table, mdriztab (Section 5.4.7), which are referenced in the primary headers of each dataset. The MultiDrizzle parameter table provides all the default settings used by the pipeline to run MultiDrizzle on any given single image or association. For these images, using the IRAF syntax, we find that idctab and mdriztab are:

  >hedit j8cw03a1q_flt.fits[0] idctab,mdriztab .
 >j8cw03a1q_flt.fits[0],IDCTAB = jref$wfc_smov_idc.fits
 >j8cw03a1q_flt.fits[0],MDRIZTAB = jref$wfc_smov_mdz.fits

5.4.4 Running Under PyRAF

MultiDrizzle has been incorporated into STSDAS not only as a Python task in its own right, but also as an IRAF task with the usual parameter driven interface. The Python syntax can also be used from PyRAF, since PyRAF provides full Python functionality as well as access to IRAF tasks.

PyRAF can usually be started by simply running the command:

  >your_computer> pyraf

Once PyRAF has started up, load the STSDAS, then dither packages:

  >stsdas
 >dither

At this point, the PyDrizzle code has been loaded into PyRAF and is available for use. The IRAF EPAR interface can be used to review and set the available parameters which guide MultiDrizzle's processing routines.

5.4.5 Running under Python

MultiDrizzle can also be used directly from Python without loading IRAF, STSDAS or PyRAF. MultiDrizzle has been written as a Python package and can be treated just like any other Python package. Therefore, to use MultiDrizzle directly from Python, go to the directory with the data and start up Python:

  your_computer> python

In order to use MultiDrizzle with the Python interface the code must be installed in a directory accessible by Python. If that directory is not already included in the PYTHONPATH or default Python system path, you can point to it inside Python using:

  >>> sys.path.insert(1,'/directory/with/Multidrizzle/code')

MultiDrizzle can then be loaded using the usual import mechanism in Python:

  >>> import multidrizzle

At this point, MultiDrizzle can be run on the calibrated images in the local directory. Interactive help can be obtained for MultiDrizzle using the built-in help mechanism. This will provide basic information on the methods available for use and their syntax as well as the most basic set of commands outlined in this example for running MultiDrizzle.

  >>> multidrizzle.help()

5.4.6 Running MultiDrizzle

The Python syntax for running MultiDrizzle does not vary that much from the PyRAF syntax. Unlike the PyRAF syntax, it provides the user with the ability to examine the inputs and computed parameters before spending the majority of time actually doing the image combination. MultiDrizzle creates an instance of a MultiDrizzle object which contains all the methods necessary for editing the input parameters, computing the image combination parameters, then performing the actual cosmic ray detection and image combination. All of these functions get wrapped into one call through the PyRAF interface, making for simpler operation at the cost of the ability to inspect the object and its contents.

The processing starts with the creation of a MultiDrizzle object, which for the sake of this example will simply be called `md':

  >>>md = multidrizzle.Multidrizzle(input='j8cw030x0_asn.fits', 
mdriztab=yes, editpars=False,
**input_dict)

The parameter `input_dict' serves as the means for the user to specify any of the remaining parameters from the parameter table which should have non-default values. Setting `editpars' to True here will cause the Python GUI parameter editor to start automatically. You may also choose to use the separate `editpars()' method.

The specification of the mdriztab parameter in the initialization demonstrates how any of the input parameters whose values need to be changed from the default value can be provided at the start. If many parameters need to be edited, the Python GUI interface can be started, simply closing this GUI saves the values in the MultiDrizzle object for use.

  >>>md.editpars()

This editor allows the user to examine all the inputs for MultiDrizzle and set them as necessary to work best with the input data. See the parameter table (Section 5.4.7) for the full available set of MultiDrizzle parameters. At this point the MultiDrizzle object contains all the input parameter values necessary for the processing. However, the computation of the parameters necessary for doing the image combination and cosmic ray detection still need to be performed using the build method:

  >>>md.build()

The MultiDrizzle object (md) now contains everything necessary for the processing. It can still be inspected using simple python commands, but no further method operations are necessary to complete the setup process. Alternatively, a help method can provide a reminder of the available methods for any MultiDrizzle object already created using:

  >>>md.help()

The full MultiDrizzle process can now be started:

  >>>md.run(static=None, skysub=None, driz_separate=None, 
         median=None, blot=None, driz_cr=None, 
         driz_combine=None)

This method allows the user one last chance to specify what processing steps should be performed. If no parameters are specified, all processing steps turned on during the instantiation of the MultiDrizzle object will be performed. Generally, though, the user simply wants to run this method without any specified parameters, such as:

  >>>md.run()

This represents the last step in processing images with MultiDrizzle, with the final product being a registered, cosmic ray cleaned, distortion-free, photometrically uniform image.

5.4.6.1 Session Summary

Very few commands are actually needed in order to process images or sets of images using MultiDrizzle. The total session described here simply boils down to:

  >your_computer> cd /directory/with/data/
 >your_computer> pyraf
 >stsdas
 >dither
 >multidrizzle j8cw030x0_asn.fits mdriztab=yes mode=h

The Python syntax does not require many more commands:

  >import multidrizzle 
 >md = multidrizzle.Multidrizzle('j8cw030x0_asn.fits',mdriztab=yes)
 >md.editpars()
 >md.build()
 >md.run()

Both ways of running MultiDrizzle will produce the exact same output products if the same input files are supplied.

5.4.6.2 Intermediate Products

There are many intermediate steps during the full course of "drizzling" your input images into a mosaic. Each of these steps has particular output which informs the next stage of the proceedure. The intermediate products are all those files which get created during the process but are not necessarily considered final science products. These may include files with the extensions:

MultiDrizzle allows an option (clean) to turn on and off the saving of files which are created during intermediate steps. While it is good to keep intermediate files so that you can assess the full performance of the tasks, you must keep in mind the size of your input images and the disk capacity of the machine on which you're running, and set this parameter accordingly.

5.4.6.3 Final Products

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. 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 astrometricaly 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 and the users needs.

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 as a cube with additional 32-bit deep planes as required to handle all the input images.

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

The WFC3/IR pipeline is based on the NICMOS pipeline, and produces a calibrated _flt.fits file using the same up-the-ramp fitting procedure which rejects cosmic rays. The units of the WFC3/IR _flt.fits file are electrons per second, rather than data numbers per second, to be more consistent with the calibrated WFC3/UVIS _flt.fits files, which are in units of electrons.

ACS and WFC3 users should note that the calibrated FLT files contain additional bits in the DQ mask that identify pixels flagged as cosmic rays by MultiDrizzle. The default value for these bits is 4096, and if MultiDrizzle is re-run on the FLT files offline it will be able to use these flags and proceed directly to the final drizzle step without the need to re-do cosmic ray masking, unless that is required. Alternatively, if the cosmic ray rejection needs to be improved, then the pipeline CRs can be ignored/reset by adding 4096 to the "bits" parameter value when running MultiDrizzle.

5.4.7 MultiDrizzle Parameters

MultiDrizzle processing starts with a list of input images, then applies a number of operations on them to produce the final cosmic ray cleaned image; specifically:

  1. Initialization (Section 5.4.8)
  2. Bad pixel (Section 5.4.9) (static) mask creation
  3. Sky Subtraction (Section 5.5.4)
  4. Drizzle onto separate (Section 5.4.10), registered output images
  5. Combine the separate drizzled images (Section 5.4.11) into a median
  6. "blot" (Section 5.4.12), or transform back the median to each input image
  7. Compare the median with original images to make cosmic ray masks (Section 5.4.13)
  8. Drizzle all the images onto a final image (Section 5.4.14), using the cosmic ray masks

MultiDrizzle relies on a large number of parameters for specifying what steps get performed and for controlling the algorithm used by each step. The complete list of parameters and their default values are given in the parameter table (Section 5.4.7). It is generally recommended to try running the script first with the default parameters, which should allow the task to process nearly any set of images for an initial review. The script can then be re-run, or restarted at a particular step, with modified parameters if this is necessary. MultiDrizzle is not designed to be restarted in the middle of processing, so when computing improved cosmic ray masks, the user must turn on all steps prior to 'driz_cr'. If this is not done, the header keyword mdrizsky will be set to zero, and the software will flag any reasonably bright objects in the image. The result is a cosmic ray mask that looks like a map of the image, where all pixels containing sources have been flagged. When MultiDrizzle is run by the archive instrument pipelines it references the mdriztab file in the header of the dataset. mdriztab is a fits table file which contains carefully chosen input parameters for MultiDrizzle which are optimized for the widest range of science cases. These are the default parameters which are used in the instrument pipelines for data retrieved from the HST archive, and may be different for each instrument. Users are encouraged to examine whether these parameters are appropriate for their particular datasets and recombine their science data as necessary.


Table 5.8: Parameters for MultiDrizzle
Parameter
Default Value
Description
Format
Initialization
input
*flt.fits
Input files: filename, wildcard suffix, or @list
string
[*flt.fits]
output
Rootname for output
drizzled products
string
mdriztab
no
Use table with
MultiDrizzle parameters?
boolean [True,False]
refimage
Name of image which specifies the output WCS
string
runfile
File for logging the final drizzle commands
string
workinplace
no
Work on input files in place? (NOT RECOMMENDED)
boolean
[False,True]
updatewcs
yes
Update the WCS
keywords?
boolean
[False,True]
coeffs
header
Use header-based
distortion coefficients?
string [header,cubic,trauger,none]
context
no
Create context image
during final drizzle?
boolean
[False, True]
clean
no
Remove temporary files?
boolean
[True,False]
group
Specification of extension
or group to process
string
ra
right ascension of
output frame center
float
dec
declination of output
frame center
float
build
yes
Create multi-extension output file?
boolean [True,False]
shiftfile
Name of file
containing shifts
string
staticfile
Name of the optional
input static bad-pixel mask
string
Static Mask Creation
static
yes
Create static bad-pixel
mask from the data?
boolean
[True,False]
static_sig
4.0
Sigma*rms below mode
to clip for static mask
float
Sky Subtraction
skysub
yes
Perform sky subtraction?
boolean
[True,False]
skywidth
0.1
Bin width for sampling
sky statistics (in sigma)
float
skystat
median
Sky correction
statistics parameter
string [median,mode,mean]
skylower
INDEF
Lower limit of usable data
for sky (always in electrons)
float
skyupper
INDEF
Upper limit of usable data
for sky (always in electrons)
float
skyclip
5
Number of clipping iterations
integer
skylsigma
4
Lower side clipping
factor (in sigma)
float
skyusigma
4
Upper side clipping
factor (in sigma)
float
skyuser
KEYWORD indicating a
sky subtraction value if
done by user.
string
Create Separate Drizzled Images (Section 5.4.10)
driz_separate
yes
Drizzle onto separate output images?
boolean
[False,True]
driz_sep_outnx
Size of separate output frame's X-axis (pixels)
float
driz_sep_outny
Size of separate output frame's Y-axis (pixels)
float
driz_sep_kernel
turbo
Shape of kernel function
string [turbo,square,point,gaussiantophat
,lanczos3]
driz_sep_wt_scl
exptime
Weighting factor
for input data image
float
driz_sep_scale
INDEF
Absolute size of
output pixels in arcsec/pixel
float
driz_sep_pixfrac
1.0
Linear size of drop
in input pixels
float
driz_sep_rot
INDEF
Orientation of final
image's Y-axis w.r.t.
North (in degrees)
float
driz_sep_fillval
INDEF
Value to be assigned to undefined output points
float
driz_sep_bits
0
Integer mask bit values considered good
integer
Create Median Image
median
yes
Create a median image?
boolean [True,False]
median_newmasks
yes
Create new masks when doing the median?
boolean [True,False]
combine_maskpt
0.7
Percentage of weight image value below which it is flagged
float
combine_type
median
Type of combine operation
string [minmed,minimum,median,sum]
combine_nsigma
4 3
Significance for accepting minimum instead of median
string
combine_nlow
0
minmax: Number of low pixels to reject
integer
combine_nhigh
1
minmax: Number of high pixels to reject
integer
combine_lthresh
INDEF
Lower threshold for clipping input pixel values
float
combine_hthresh
INDEF
Upper threshold for
clipping input pixel values
float
combine_grow
1
Radius (pixels) for
neighbor rejection
float
Blot Median Image
blot
yes
Blot the median back
to the input frame?
boolean [True,False]
blot_interp
poly5
Interpolation function to use
string [nearest,linea,rpoly3,poly5,
sinc]
blot_sinscl
1
Scale for sinc interpolation kernel
float
Remove Cosmic Rays (Section 5.4.13)
driz_cr
yes
Perform CR rejection with deriv and driz_cr?
boolean [True,False]
driz_cr_corr
no
Create CR cleaned _cor file and a _crmask file?
boolean [True,False]
driz_cr_snr
3.5 3.0
SNR parameter for cosmic rays
string
driz_cr_grow
1
pixel grow parameter for cosmic rays
integer
driz_cr_cte_grow
0
driz_cr: length of CTE tail to mask in final product
integer
driz_cr_scale
1.2 0.7
driz_cr: scale parameter
string
Create Final Cleaned, Combined Product
driz_combine
yes
Perform final drizzle image combination?
boolean [True,False]
final_wht_type
EXP
type of weighting for final drizzle
string [EXP,IVM,ERR]
final_outnx
Size of FINAL output frame X-axis (pixels)
float
final_outny
Size of FINAL output frame Y-axis (pixels)
float
final_kernel
square
Shape of kernel function
string [square,top,gaussian,turbo,tophat,lanczos3]
final_wt_scl
exptime
weighting factor for input data image
float
final_scale
INDEF
Absolute size of output pixels in arcsec/pixel
float
final_pixfrac
1.0
Linear size of drop in input pixels
float
final_rot
0.0
Orientation of final image's Y-axis w.r.t. North (in degrees)
float
final_fillval
INDEF
Value to be assigned to undefined output points
float
final_bits
0
Integer mask bit values considered good, bit values greater than 0 will include 0
integer
final_units
cps
Units for final drizzled image [counts,cps]
string
Override Instrument Specific Parameters
gain
Detector gain in electrons per count
float
gnkeyword
Detector gain keyword in header
string
rdnoise
Detector read noise in electrons
float
rnkeyword
Detector read noise keyword in header
string
exptime
Exposure time
float
expkeyword
Exposure time keyword in header
string
crbit
Bit value for CR identification in DQ array
integer

5.4.8 Initialization

5.4.8.1 General Explanation

MultiDrizzle starts by determining what files are being specified as inputs. These files then get converted as necessary to a usable input format with appropriate units. This conversion includes making copies of each input file, if `workinplace' is set to `False', so that the original input SCI arrays are not altered and can be used for successive runs. A set of drizzle parameter values needed to combine the images into a final output image then get computed using PyDrizzle.

5.4.8.2 Parameter Details

Input: This controls all inputs for the entire MultiDrizzle task. In addition, it requires access to:

Output: The rootname for the output drizzled products. This step can result in the creation of several files, including:

mdriztab: Specifies whether or not to use an mdriztab reference table to specify the remaining MultiDrizzle parameter settings. If `True', the values in the table will override the settings for the remainder of the parameters.

refimage: Optional "reference image" that can be provided, in which case MultiDrizzle will create a final product with the same WCS. This reference image should be a simple FITS file (single-group, no multiple extensions), and should have been already drizzled so that all of its distortion has been removed, and its WCS is completely rectified.

runfile: This log file will contain the IRAF CL commands necessary for performing the final combination manually using the drizzle task directly.

workinplace: This parameter specifies whether to perform all processing on the original, including sky subtraction and update of the DQ array. If set to `True', then no copy of the input will be created for processing, and the original input will be modified directly by MultiDrizzle.

updatewcs: This parameter specifies whether the WCS keywords are to be updated by running makewcs on the input data, or left alone. The update performed by makewcs not only recomputes the WCS based on the currently used idctab, but also populates the header with the SIP coefficients. Also, for ACS/WFC images, the time-dependence correction will also be applied to the WCS and SIP keywords. This parameter should usually be set to `yes', unless the WCS keywords have been carefully set by some other method, and need to be passed through to drizzle `as is'.

coeffs: The source of the distortion coefficients gets specified using:

Alternatively, an arbitrary distortion coefficients file can be specified (including optionally the full pathname). This distortion file is used in computing the WCS of the header. NOTE: When the `header' option has been selected, if the idctab file is not found on disk, then the task will exit for all instruments except for WFPC2 data, which will default to the older "Trauger" model.

context: This parameter specifies whether or not to create a context image during the final drizzle combination. The context image contains the information on what image(s) contributed to each pixel encoded as a bit-mask. More information on context images can be obtained from the ACS Data Handbook.

clean: The temporary files created by MultiDrizzle can be automatically removed by setting this parameter to `True'. The affected files would include the coefficients files and static mask files created by PyDrizzle, along with other intermediate files created by MultiDrizzle. It is often useful to retain the intermediate files and examine them when first learning how to run MultiDrizzle. But when running it routinely, or on a small disk drive, these files can be removed to save space.

group: A single FITS extension or group can be drizzled by setting this parameter. If an extension is provided, then only that chip will be drizzled onto the output frame. Either a FITS extension number or GEIS group number (such as `1'), or a FITS extension name (such as `sci,1') may be specified.

ra: Right ascension (in decimal degrees) of the center of the output image. If this is not specified, the code will calculate the center automatically based on the distribution of image dither positions.

dec: Declination (in decimal degrees) of the center of the output image. If this is not specified, the code will calculate the center automatically based on the distribution of image dither positions.

build: MultiDrizzle will combine the separate `drizzle' output files into a single multi-extension format FITS file when this parameter gets set to `True'. This combined output file will contain a SCI (science), a WHT (weight), and a CTX (context) extension. If set to `False', each extension would remain as a separate simple FITS file on its own.

shiftfile: Name of optional input file containing the shifts to be applied to the input images to improve their registration.These shifts will be added to those calculated automatically from the image headers. The file should be organized as follows:

  # units: pixels 
 # frame: input
 # form: delta
 rootname xshift yshift rotation   
 staticfile: Name of the optical input static bad-pixel mask. The input data are multiplied 
by the contents of this static mask file.

gain: Value used to override instrument specific default gain values. The value is assumed to be in units of electrons/count. This parameter should not be populated if the gain keyword parameter is in use.

gainkeyword: Keyword used to specify a value to be used to override instrument specific default gain values. The value is assumed to be in units of electrons/count. This parameter should not be populated if the gain parameter is in use.

rdnoise: Value used to override instrument specific default readnoise values. The value is assumed to be in units of electrons. This parameter should not be populated if the rnkeyword parameter is in use.

rnkeyword: Keyword used to specify a value to be used to override instrument specific default readnoise values. The value is assumed to be in units of electrons. This parameter should not be populated if the rdnoise parameter is in use.

exptime: Value used to override default exposure time image header values. The value is assumed to be in units of seconds. This parameter should not be populated if the expkeyword parameter is in use.

expkeyword: Keyword used to specify a value to be used to override default exposure time image header values. The value is assumed to be in units of seconds. This parameter should not be populated if the exptime parameter is in use.

crbit: Integer used to override instrument specific cosmic ray bit values. This value is used by MultiDrizzle to update data quality arrays when cosmic rays or other image defects are identified as "bad" in the DRIZ_CR step. To prevent the image's data quality array from being updated set the crbit value to 0.

5.4.8.3 Basic Example

An example of an input image that you would like to drizzle is in Figure 5.2.

Figure 5.2: Single Extension from an ACS FLT File


 
A single extension from a calibrated ACS FLT file, j8cw54orq_flt.fits, which still contains numerous cosmic rays, hot pixels, and other artifacts.
 

5.4.9 Static Mask Creation

5.4.9.1 General Explanation

If the static flag is set to "yes", a static mask will be created for all input images. The mask contains pixels which fall more than `static_sig' *RMS below the mode for a given chip or extension. Those severely negative or low pixels might result from over subtraction of bad pixels in the dark image, or high sky levels, during calibration. For example, each ACS WFC image contains a separate image for each of 2 CCDs and separate mask will be generated for each chip.

The final static mask for each chip contains all the bad pixels that meet this criteria from all the input images along with any bad pixels which satisfied the final_bits value specified by the user and found in the images DQ mask. This static mask could also be combined with a user supplied static mask specified in the `staticfile' parameter.

Users should consider the details of their science image and decide whether creating this mask is appropriate for the resulting science. For example, if your field is very crowded, contains mostly nebulous or extended objects, the statistics could be heavily skewed and the mask could end up containing sources.

Input: Aside from the input parameters, this step requires opening each input image to access the science (SCI) extensions for generating the static masks.

Output: The generated static masks exist strictly in memory as numarray objects that get applied during the single drizzle step. They also get used to update the input mask files for the final image combination.

5.4.9.2 Parameter Details

static: This parameter specifies whether to create a static bad-pixel mask from the data or not. This mask flags all pixels that deviate by more than `static_sig' sigma below the image median.

static_sig: Number of sigma below the RMS to use as the clipping limit for creating the static mask, defaulted to 4.0

5.4.9.3 Basic Examples

An example of what a bad pixel mask might look like. (Figure 5.3) is a badpixel mask from a NICMOS camera 3 image where the differing gray levels signify different bits which have been set in the Data Quality (DQ) extension of the science image with which it is associated.

Figure 5.3: An Example Bad Pixel Mask Taken from a NICMOS Image


 
Bad pixel mask from NICMOS camera 3. There are multiple shades of grey because the DQ image contains the logical AND of all pixel processing flags generated during calnica.
 

5.4.10 Create Separate Drizzled Images

5.4.10.1 General Explanation

Each input image gets drizzled onto a separate copy of the output frame. When stacked, these copies would correspond to the final combined product. As separate images, they allow for treatment of each input image separately in the undistorted, final WCS system. These images provide the information necessary for refining the image registration for each of the input images. They also provide the images which will later be combined into a median image used for the later blot and cosmic ray detection steps.

Input: Aside from the input parameters, this step requires:

Output: This step produces:

These images all have the same WCS based on the original input parameters and those provided for this step; specifically, output shape, pixel size, and orientation, if any have been specified at all.

5.4.10.2 Parameter Details

driz_separate: This parameter specifies whether or not to drizzle each input image onto separate output images. The separate output images will all have the same WCS as the final combined output frame. These images are used to create the median image, needed for the cosmic ray rejection step further on.

driz_sep_outnx: Size of the X axis of the output images, in pixels, on which each input will be drizzled onto. If no value is specified, it will use the smallest size that can accommodate the full dithered field.

driz_sep_outny: Size of the Y axis of the output images, in pixels, on which each input will be drizzled onto. If no value is specified, it will use the smallest size that can accommodate the full dithered field.

driz_sep_kernel: For the initial separate drizzling operation only, this specifies the form of the kernel function used to distribute flux onto the separate output images. The options are currently:

The default for this step is "turbo" since it is much faster than "square", and it is quite satisfactory for the purposes of generating the median image. More information about the different kernels can be found in the help for the task `drizzle'.

driz_sep_wt_scl: Weighting factor for input image. If driz_sep_wt_scl=exptime then 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 wt_scl=expsq for weighting by the square of exposure time, which is optimal for read-noise dominated images.

driz_sep_scale: Linear size of the output pixels in arcseconds/pixel for each separate drizzled image (to be used in creating the median for cosmic ray rejection). The default value of INDEF specifies that the undistorted pixel scale for the first input image, as computed by PyDrizzle, will be used as the pixel scale for all the output images.

driz_sep_pixfrac: Fraction by which 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, "dropsize", 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 step of drizzling each input image onto a separate output image, the default value of 1 is best in order to ensure that each output drizzled image is fully populated with pixels from the input image. For more information, see the help file for the drizzle task.

driz_sep_rot: Position Angle of output image's Y-axis relative to North. A value of 0.0 would orient the final output image with North up. The default of INDEF specifies 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. This conserves disk space, since these single drizzled images are only used in the intermediate step of creating a median image.

driz_sep_fillval: Value to be assigned to output pixels that have zero weight or did not receive flux from any input pixels during drizzling. This parameter corresponds to the `fillval' parameter of the drizzle. If the default of `INDEF' is used and if the weight in both the input and output images for a given pixel are zero, then 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. 0), then these pixels will be set to that value.

driz_sep_bits: Integer sum of all the DQ bit values from the input image's DQ array that should be considered `good' when building the weighting mask. This can also be used to reset pixels to good if they had been flagged as cosmic rays during a previous run of MultiDrizzle, by adding the value 4096 for ACS and WFPC2 data. Please see the section on Selecting the `Bits' Parameter (Section 5.5.7) for a more detailed discussion.

5.4.10.3 Basic Example

Figure 5.4 and Figure 5.5 contain two basic examples.

Figure 5.4: A Singly Drizzled ACS Image


 
The singly drizzled FLT image `j8cw54ovq_flt_single_sci.fits'. The two chips have been combined and the geometric distortion has been removed.
 
Figure 5.5: Weight Map Corresponding to the Singly Drizzled ACS Image


 
The weight image `j8cw54ovq_flt_single_wht.fits' corresponding to the singly drizzled image in Figure 5.5 where white indicates zero weight.
 

5.4.11 Create Median Image

5.4.11.1 General Explanation

The singly drizzled science images are combined to create a single median image. This median combination gets performed section-by-section from the input single drizzle images. Each section corresponds to a contiguous set of lines from each image taking up no more than 1Mb in memory, so that combining 10 input images would only require 10Mb for these sections. The goal of this step is to created an estimate of what the fully cleaned image should look like in order to enable better bad pixel detection as well as a chance to improve the alignment of the image stack. Creating a median image from the aligned and undistorted input images allows for a statistical rejection of bad pixels.

Input: Aside from the input parameters, this step requires access to the single drizzled images on disk.

Output: The final median image serves as the only output from this step.

5.4.11.2 Parameter Details

median: The user can specify whether or not to create a median image with this parameter. This median image will be used as the comparison `truth' image: in the cosmic ray rejection step.

median_newmasks: The user can specify whether or not to create new mask files when creating the median image. These masks are generated from the weight files produced previously by the "driz_separate" step, and would contain all the bad pixel information. These pixels will be excluded when calculating the median. Generally this step should be set to "yes", unless it is desired to include bad pixels in generating the median.

combine_type: This parameter allows the user to choose which method is used to create the median image. Valid options are:

combine_nsigma: Sigmas used for accepting minimum values instead of median values when using the `minmed' combination method. If two values are specified, then the first value will be used in the initial choice between median and minimum, while the second value will be used in the "growing" step to reject additional pixels around those identified in the first step. If only one value is specified, then it is used in both steps.

combine_nlow: When using a `minmed' rejection method, this parameter sets the number of low value pixels to reject.

combine_nhigh: When using a `minmed' rejection method, this parameter sets the number of high value pixels to reject.

combine_lthresh: Sets the lower threshold for clipping input pixel values during image combination. This value gets passed directly to `imcombine' for use in creating the median image. If None, no thresholds are used at all.

combine_hthresh: Sets the upper threshold for clipping input pixel values during image combination. This value gets passed directly to `imcombine' for use in creating the median image. If None, no thresholds are used at all.

combine_grow: Width in pixels for additional pixels to be rejected in an image with a rejected pixel from one of the rejection algorithms. This parameter is used to set the `grow' parameter in imcombine for use in creating the median image.

5.4.11.3 Basic Example

This is a cleaned median image created using six separately drizzled images and their associated bad pixel masks.

Figure 5.6: ACS Example of a Cleaned Median Image


 
The cleaned median image created using the 6 separately drizzled Tadpole images and their bad pixel masks.
 

5.4.12 Blot Median Image

5.4.12.1 General Explanation

The median image is the combination of the WCS aligned input images which have already had the distortion model applied. Taking the median of the aligned images allows for a statistical rejection of bad pixels from the image stack. The resulting median image can then be input to the blot task with the goal of creating `cleaned' versions of the input images at each of their respective dither locations. These "blotted" images can then be directly compared to the original distorted input images for detection of bad-pixels, hot pixels, and cosmic rays whose locations will be saved to the output badpixel masks.

Input: Aside from the input parameters, this step only requires opening the single median image created from all the input images.

Output: A distorted version of the median image corresponding to each input `chip' (extension) gets written out as output from this step as separate simple FITS images.

5.4.12.2 Parameter Details

blot: Perform the blot operation on the median image. The output will be median smoothed images which match each input chips location, these are used in the cosmic ray rejection step.

blot_interp: Type of interpolation to use when blotting drizzled images back to their original WCS. Valid options are:

The poly5 interpolation method has been chosen as the default because it is relatively fast and accurate. 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.

blot_sinscl: Size of the sinc interpolation kernel in pixels.

5.4.12.3 Basic Example

Figure 5.7: Original ACS FLT Image Fed into the Drizzle Step


 
The original FLT image that was fed into the single drizzle step.
 
Figure 5.8: The Returned Corresponding Blotted Imager


 
The blotted image, this is a cutout of the median image at the location of the original image. Note the absence of cosmic rays because they were statistically rejected.
 

5.4.13 Remove Cosmic Rays

5.4.13.1 General Information

The blotted median images which are now transformed back into the original reference frame, get compared to the original input images to detect any spurious pixels (which may include pixels impacted by cosmic rays) in each input. Those spurious pixels then get flagged as `bad' in the output mask files, which get used as input for the final combination, so that they do not show up in the final product.

Input: Aside from the input parameters, this step requires:

Output: The identified bad pixels get flagged by updating the input mask files. Optionally, copies of the original images with the bad pixels removed can be created through the use of the `driz_cr_corr' parameter.

5.4.13.2 Parameter Details

driz_cr: Perform cosmic ray detection? If set to "yes", it will detect cosmic rays and create cosmic ray masks using the algorithms from deriv and driz_cr.

driz_cr_corr: Create a cosmic ray cleaned input image? The cosmic ray cleaned _cor image will be generated directly from the input image, and a corresponding _crmask file will be written to document the pixels detected as affected by cosmic rays.

driz_cr_snr: These values specify the signal-to-noise ratios for the driz_cr task to use in detecting cosmic rays. This parameter value gets passed directly to driz_cr;

driz_cr_scale: Scaling factor applied to the derivative in driz_cr when detecting cosmic rays. This parameter gets passed directly to driz_cr.

driz_cr_grow: Radius (in pixels) around each detected cosmic ray to use more stringent detection criteria for additional cosmic rays.

driz_cr_cte_grow: Length (in pixels) of CTE tail to mask in drizzled output.

5.4.13.3 Basic Example

Figure 5.9: Single chip ACS Cosmic Ray Mask


 
A single cosmic ray mask `j8cw54orq_flt_sci2_crderiv.fits'. This mask should be blinked with the original image `j8cw54orq_flt' input file to assure that optimal parameters were chosen in the driz_cr task.
 

5.4.14 Create Final Cleaned, Combined Product

5.4.14.1 General Explanation

This step performs the final image combination of the original input images (or their copies) using the updated mask files to remove any cosmic rays. The output frame, just like the single drizzle step, can be redefined here using some parameters for this step, otherwise it will use the defaults to (ideally) include all the input pixels from all the input images after registering them according to their header's WCS information.

Input: Aside from the input parameters, this step requires:

Output: The final product of MultiDrizzle is a registered, cosmic ray cleaned, distortion-free, photometrically flat science image with associated weight and context images. By default, these will be written out as a single multi-extension FITS file, but the user could simply have them written out as separate simple FITS images.

5.4.14.2 Parameter Details

driz_combine: This parameter specifies whether or not to perform the final drizzle image combination. This applies the bad pixel masks to the input images and creates a final, cleaned, distortion-corrected product.

final_wht_type: Specify the type of weighting image to combine with the bad pixel mask for the final drizzle step. The options are:

final_outnx: Size of the X axis of the final drizzled image (in pixels). If no value is specified, it will use the smallest size that can accommodate the full dithered field.

final_outny: Size of the Y axis of the final drizzled image (in pixels). If no value is specified, it will use the smallest size that can accommodate the full dithered field.

final_kernel: Shape of the kernel used by `drizzle' in the final image combination. The supported choices are:

final_wt_scl: Weighting factor for input image. If final_wt_scl = exptime then 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 wt_scl=expsq for weighting by the square of exposure time which is optimal for read-noise dominated images.

final_scale: Linear size of the output pixels in arcseconds/pixel for the final combined product. The default value of INDEF specifies that the undistorted pixel scale for the first input image, as computed by PyDrizzle, will be used as the pixel scale for the final output image.

final_pixfrac: Fraction by which 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, "dropsize", of a pixel in units of the input pixel size. If pixfrac is set to less than 0.001, the kernel 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. For more information, read the help for the task `drizzle'.

final_rot: Position Angle of output image's Y-axis relative to North. The default of 0.0 would orient the final output image with North up. 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.

final_fillval: Value to be assigned to output pixels that have zero weight or did not receive flux from any input pixels during drizzling. This parameter corresponds to the `fillval' parameter of the drizzle task. If the default of INDEF is used and if the weight in both the input and output images for a given pixel are zero, then 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. 0), then these pixels will be set to that value.

final_bits: Integer sum of all the DQ bit values from the input image's DQ array that should be considered `good' when building the weighting mask. This can also be used to reset pixels to good if they had been flagged as cosmic rays during a previous run of MultiDrizzle, by adding the value 4096 for ACS and WFPC2 data. The section on selecting the bits parameter (Section 5.5.7) provides more details on which bits should be included.

5.4.14.3 Basic Example

Figure 5.10 shows the SCI extension, Figure 5.11 shows the WHT extension, and Figure 5.12 shows the CTX extension of the drizzled product.

Figure 5.10: Science Extension of an ACS Drizzled Output Product


 
The science (SCI) extension of the drizzled product. This image has been corrected for distortion and drizzled onto a single mosaic using the six images in the dither pattern.
 
Figure 5.11: Corresponding Weight Extension of the ACS Drizzled Output


 
The corresponding weight (WHT) extension of the drizzled product.
 
Figure 5.12: Corresponding Context Extension of the ACS Drizzled Output


 
The corresponding context (CTX) extension of the drizzled product.
 

5.4.15 Override Instrument Specific Parameters

5.4.15.1 General Information

The user may choose to override the information contained in the headers of the images by setting these parameters directly.

5.4.15.2 Parameter Details

gain: Detector gain

gnkeyword: Detector gain keyword in header

rdnoise: Detector read noise

rnkeyword: Detector read noise keyword in header

exptime: Exposure time

expkeyword: Exposure time keyword in header

crbit: Bit value for CR identification in DQ array


Space Telescope Science Institute
http://www.stsci.edu
Voice: (410) 338-1082
help@stsci.edu
TOC PREV NEXT INDEX PDF