The MultiDrizzle Handbook

6.2 ACS

---

6.2.1 Introduction

The MultiDrizzle software resides in the stsdas.analysis.dither package and can only be run from within PyRAF. It contains an extensive set of parameters for user modification, but the default values should allow the processing of nearly any set of images for an initial review. From within the `epar' window, the MultiDrizzle parameters are separated according to which drizzle task they control, making them easier to interpret. In default mode, MultiDrizzle performs each of its 7 steps in order:

1.) static mask

2.) sky subtraction

3.) drizzle separate

4.) median

5.) blot

6.) cosmic ray rejection

7.) final drizzle

MultiDrizzle may be executed from the command line, as part of a script, or run using the `epar' facility which allows the user to view all parameters and turn particular steps on and off. We recommend that beginners use the `epar' facility to become familiar with each step and to fine-tune the parameters in each step before running MultiDrizzle from the command line. For more details, a help document describing each task and its parameters may be accessed by typing `help MultiDrizzle' from within PyRAF. In the examples below, several of the commands are too long to fit on a single line with the current document formatting. When a command is meant to continue on the same line, it will be followed by a backslash.

To understand the processing which took place in the pipeline, it can be helpful to inspect the MultiDrizzle parameter table which is given by the image header keyword MDRIZTAB. To query this information, the IRAF tasks `hselect' and `tread' may be used as illustrated below. It is important to note that default MultiDrizzle parameters (within the `epar' facility) are not necessarily the same as the parameters specified in the MDRIZTAB during pipeline processing.

  hselect *flt.fits[1] $I,mdriztab yes
 tread table_mdz.fits

Drizzled products which were obtained from the archive have been processed using the parameters specified in the MDRIZTAB. These parameters work best for observations which were obtained as part of a pre-defined observing pattern and thus are `associated' in the pipeline via an association table (*_asn.fits). For example, images which were obtained using a sub-pixel dither box pattern are usually aligned to better than 0.1 pixels and have accurate cosmic ray flags. When a sub-pixel dither pattern has been obtained, the final drizzle sampling can often be improved via manual reprocessing. The steps required to improve the drizzle sampling are described in Example 1. When images are obtained in separate visits, the image alignment and cosmic ray flagging can usually be fine-tuned, and these are described in Examples 2 and 3, respectively.

The calibrated products from CALACS (either the association table `_asn.fits' or the calibrated files with the extension `_flt.fits' or `_crj.fits') should be used as input for drizzling. The calibrated files have been corrected for bias, dark current and flat fielding. They are not corrected for distortion and may contain numerous cosmic rays, hot pixels, and other artifacts. These images appear square in detector space, but the pixels actually do not cover equal area on the sky. Once ACS images have been corrected for geometric distortion via drizzling, they will appear `rhombus'-shaped, as shown in the examples below.

When manual reprocessing is desired, the calibrated data products and the distortion reference files should be placed on the user's local disk. The user is advised to retain a copy of the original archival data and place it in a separate directory. This is because MultiDrizzle will modify the input files, for example, when fine tuning the sky subtraction or cosmic ray rejection. The drizzle reference files include the geometric distortion table (IDCTAB= *_idc.fits), the distortion correction image (DGEOFILE= *_dxy.fits), and an optional MultiDrizzle parameter table (MDRIZTAB= *_mdz.fits). When combining images which were taken on different dates (and therefore at different orientations), the software will automatically correct for time-dependent distortion and will print a message to the screen "Computing ACS Time Dependent Distortion Coefficients" during processing.

The drizzle reference files are assumed to be in a directory called `jref'. This path must be defined before starting PyRAF and should be set to point to the user's local directory where the data resides. For example:

  'setenv jref /mydata/jref/'

It is usually a good idea to make sure that you request that all the calibration files which were used to calibrate your data be delivered from the archive when you make the request for your science datasets.

The following three ACS examples are intended to be read consecutively, since each builds on information presented in the previous example. Testing was performed using the following software versions, which were current at the time of writing this document:

  MultiDrizzle 3.2.1
 NUMPY Version 1.0.4
 PyFITS Version 1.4
 PyDrizzle Version 6.3.0 (3-Sep-2008)
 Python Version 2.5.1 (Mar 19 2008)

Users may obtain the latest public release of the STSDAS software (which includes the drizzling code) from STScI. Release notes for the latest version may be found on the STScI software Web page.

6.2.2 Example 1: Optimizing the Image Sampling for Single Visit

The following example describes the combination of four ACS/HRC images of the globular cluster M15 (Program 10401, PI Chandar) which were obtained with the F435W filter. These images were acquired in a single visit and are all at the same orientation. This program uses the default HRC dither pattern ACS-HRC-DITHER-BOX which has relative pixel coordinates (0, 0), (5.0, 1.5), (2.5, 4.5), (-2.5, 3.0). It is a parallelogram pattern designed for half-pixel sampling in both x and y, with overall dimensions large enough to help reject the larger detector artifacts.

Figure 6.1: A 4-point Dither Pattern for ACS-HRC


 
The ACS-HRC-DITHER-BOX is 4-point dither pattern designed for half-pixel sampling in both x and y.
 

The data described in this example are available from the HST archive for those who would like to repeat this example. The search parameters are `Dataset' = `j95z02010'. Under the archive `Retrieval Options', the box for `Science Files Requested' should be set to `Calibrated' and the box for `Reference Files' should be set to `Best Reference Files'.

The archive will deliver the reference files required for running MultiDrizzle, including the geometric distortion table `IDCTAB' = `_idc.fits', the distortion correction image `DGEOFILE' = `_dxy.fits', and the MultiDrizzle parameter table `MDRIZTAB' = `_mdz.fits'. Also delivered are the calibrated data products produced by CALACS which will be used as input to MultiDrizzle. These can be one of the following: 1.) the association table `_asn.fits', 2.) the flat-fielded images `_flt.fits', or 3.) the cosmic ray rejected, flat-fielded images `_crj.fits' (when available). Finally, the archive will deliver one or more drizzled data products `_drz.fits' which were created by running MultiDrizzle in the pipeline with a default set of parameters. The `_drz.fits' files may be saved in a separate directory for comparison with the drizzled products from this example.

The table below replicates the contents of the association table, where the rootnames of the four dithered images are given under the column `MEMNAME'.

  tprint j95z02010_asn.fits

Table 6.1: Contents of the Association Table for the Dithered Images in this Example

MEMNAME	MEMTYPE	MEMPRSNT
J95Z02AQQ	EXP-DTH	yes
J95Z02ARQ	EXP-DTH	yes
J95Z02ASQ	EXP-DTH	yes
J95Z02ATQ	EXP-DTH	yes
J95Z02010	PROD-TARG	yes

Since these data were obtained as part of a sub-pixel dither box pattern, the default MultiDrizzle parameters applied during pipeline processing are adequate for aligning images (to better than 0.1 pixels) and for providing cosmic ray masks (where the 4096 flag is written to the DQ array of the calibrated image). To examine the quality of the pipeline cosmic ray masking, the user may blink the science and DQ extensions of the calibrated files, where the display range is chosen so that only flags with a value greater than 4000 are shown. The SCI and DQ extensions are shown in the figures below for the first image in the association.

  display j95z02aqq_flt.fits[1] 1 zs- zr- z1=0 z2=1000 fill+
 display j95z02aqq_flt.fits[3] 2 zs- zr- z1=4000 z2=6000 fill+

Figure 6.2: Science Portion of the Calibrated ACS Image


 
The science portion of the calibrated image: `j95z02aqq_flt.fits[1].
 
Figure 6.3: Data Quality Portion of the Calibrated ACS Image


 
The data quality portion of calibrated image `j95z02aqq_flt.fits[3].
 

In default mode, MultiDrizzle performs each of its 7 steps in order. In this example, however, steps 1-6 can be turned off since the pipeline processing was adequate for aligning images and creating cosmic ray masks. To optimize the parameters for the final `driz_combine' step, the user is encouraged to experiment with different combinations of the parameters: 1.) `final_scale' (the size of the output pixels) and 2.) `final_pixfrac' (the linear size of the `drop' in input pixels). One must choose a `pixfrac' value that is small enough to avoid degrading the final image, but large enough that when all images are dropped onto the final frame, the flux coverage of the output frame is fairly uniform. As suggested in the HST Dither Handbook, statistics performed on the drizzled weight image should yield an rms value (standard deviation) which is less than 20% of the median (midpoint) value. This threshold is a balance between the benefit of improving the image resolution at the expense of increasing the noise in the background from resampling the pixels. In general, the `pixfrac' should be slightly larger than the scale to allow some spill over to adjacent pixels.

Before running MultiDrizzle, the package stsdas.analysis.dither must be loaded. The commands below show how to run a `test grid' of varying `final_scale' and `final_pixfrac' values, where the default HRC scale is 0.025"/pixel. When specifying parameters from the command line within PyRAF, as illustrated below, the parameter must be preceded by the word `iraf'. Since the output file `hrc_drz.fits' will be overwritten with each successive run, the example renames the drizzled product with a unique name between each separate trial.

  unlearn multidrizzle
 iraf.multidrizz.static=no
 iraf.multidrizz.skysub=no
 iraf.multidrizz.driz_separate=no
 iraf.multidrizz.median=no
 iraf.multidrizz.blot=no
 iraf.multidrizz.driz_cr=no
 iraf.multidrizz.driz_combine=yes
 iraf.multidrizz.final_rot=INDEF
  multidrizzle *flt.fits output='hrc' final_scale=0.0250 final_pixfrac=1
 imrename hrc_drz.fits hrc_drz_test1.fits
  multidrizzle *flt.fits output='hrc' final_scale=0.0200 final_pixfrac=0.9
 imrename hrc_drz.fits hrc_drz_test2.fits
  multidrizzle *flt.fits output='hrc' final_scale=0.0175 final_pixfrac=0.8
 imrename hrc_drz.fits hrc_drz_test3.fits
  multidrizzle *flt.fits output='hrc' final_scale=0.0150 final_pixfrac=0.7
 imrename hrc_drz.fits hrc_drz_test4.fits
  multidrizzle *flt.fits output='hrc' final_scale=0.0125 final_pixfrac=0.6
 imrename hrc_drz.fits hrc_drz_test5.fits

When the initial setup parameters are set: `build=yes' (default) and `context=yes' (non-default), the final MultiDrizzle output image will be a single multi-extension FITS file named `hrc_drz.fits'. This file contains the science image in extension 1, the weight image in extension 2, and the context image in extension 3. When `build=no', these files will be written to separate output files. When the default value `context=no' is used, no context image is created.

The MultiDrizzle parameter `final_rot' is the position angle of final drizzled 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.

The first extension of the drizzled product `hrc_drz.fits[1]' contains the science (SCI) image which has been corrected for distortion which represents the combination of all eight dithered images. All pixels cover an equal area on the sky and have an equal photometric normalization across the field of view, giving an image which is both photometrically and astrometrically accurate for both point and extended sources. The dimensions of the output image are computed on-the-fly by MultiDrizzle and the default output plate scale is read from the `scale' column in the IDCTAB. These parameters, however, may be chosen by the user to best suit the actual data. The SCI portion of the final drizzled product is presented in the figure below and is in units of electrons/sec. Changing the `final_units' parameter from the default value `cps' (counts per second) to `counts' will produce a drizzled image in units of electrons.

The second extension of the output image contains the weight (WHT) image. When the `final_wht_type' is set to `EXP', the weight image can be considered an effective exposure time map. The weight image from our example is shown in the figure below, where darker areas have higher weight.

Figure 6.4: Science Extension of the Final ACS Drizzled Product


 
The science extension of the final drizzled product.
 
Figure 6.5: Weight Extension of the Final ACS Drizzled Product


 
The weight extension of the final drizzled product for trial number 4 (scale=0.6, pixfrac=0.7).
 

In the table below, the statistics in the weight image (rms/median) are reported for each trial (1-5) using the task `imexam' for a 500x500 pixel box in the center and in the lower right corner of each weight image. The PSF FWHM was measured using an isolated star at coordinate (878,966) in the first trial image, where scale=0.025" and pixfrac=1.0. Note that the table gives the value of `scale' in two different ways, for illustration: as a fraction of the default plate scale and as an absolute size in arcseconds/pixel. MultiDrizzle uses the latter for defining the parameter `final_scale'.

Table 6.2: Weight Image Statistics and PSF FWHM for Various Final Drizzle Scale/Pixfrac Combinations

Trial Number	Pixfrac (fraction)	Scale (fraction)	Scale (arcsec)	RMS/Median (center)	RMS/Median (corner)	PSF FWHM (pixels)	PSF FWHM (arcsec)
1	1.0	1.0	0.0250"	0.078	0.162	2.06	0.0515"
2	0.9	0.8	0.0200"	0.100	0.154	2.58	0.0516"
3	0.8	0.7	0.0175"	0.125	0.133	2.83	0.0495"
4	0.7	0.6	0.0150"	0.129	0.164	3.23	0.0485"
5	0.6	0.5	0.0125"	0.143	0.251	3.69	0.0461"

The statistics of the weight image for the central portion of the chip meet the general requirement `rms/median < 20%' for all five trials. In the lower right corner, however, trial #5 has a ratio greater than 20%. This is an indication that the `scale' and `pixfrac' parameters have been `shrunk' too far (i.e. increasing numbers of output pixels which have no contribution from any of the four input pixels will result in `holes' in the final image, and this is reflected by the increased rms of the weight image.) Looking at the weight image in the above figure, it is clear how the rms varies over the field of view. The majority of this variation is due to the change in geometric distortion over the chip, where the input pixels cover significantly different areas on the sky. (For more information, refer to the discussion on Pixel Area Maps.

Determining which is the best solution will depend on the position of the target on the detector. For a compact source in the center of the chip, trial #5 would be the best choice because the PSF FWHM is the narrowest, while the weight image ratio `rms/median' is still less than 20%. For this example, however, stars are evenly distributed over the entire chip and trial #4 provides the best result, where `rms/median' does not exceed 20% on any portion of the detector. The drizzled product for trial #4 is presented in the above figure, where the final `scale' is equal to 0.6 times the default pixel scale and the final `pixfrac' equal to 0.7. The resulting image has a plate scale of 0.0150"/pixel and the FWHM of the PSF in the optimized version of the image (in arcseconds) is 0.0485" compared to 0.0515" in the version created by the pipeline. Because the HRC detector is already well sampled at blue wavelengths, this is a relatively minor improvement. For the WFC, however, the detector pixels are significantly undersampled, and optimizing the final `scale' and `pixfrac' parameters will produce a much more dramatic improvement. For example, for the ACS-WFC-DITHER BOX, the PSF FWHM can usually be improved from ~0.10" to approximately ~0.06".

6.2.3 Example 2: Optimizing the Image Alignment for Multiple Visits

The following example describes the combination of three single ACS/WFC images of the globular cluster NGC104 (Program 10737, PI Mack) which were obtained with the F606W filter. These images were acquired in separate visits and are all at unique orientations. Note that the second image was taken as part of a cosmic ray split association, so the ASN product rootname `j9irw4041' should be selected from the archive query, and the two cosmic ray split `*_flt.fits' images will be delivered as part of the dataset.

The IRAF task `hselect' may be used to query the image headers and compare the observing parameters.

 hselect*flt.fits[1]'rootname,proposid,date-obs,filter*,
aperture,orientat,exptime,ccdgain' yes

Table 6.3: Header Keywords for the Exposures of NGC104 Taken in Subsequent Visits

Rootname	Proposal ID	Observation Date	Filter Name	Aperture	Orientation	Exposure Time	Gain
j9irw3fwq	10737	2006-05-30	F606W	WFCENTER	-125.2	339.0	2
j9irw4b1q	10737	2006-07-08	F606W	WFCENTER	-88.6	339.0	2
j9irw5kaq	10737	2006-08-31	F606W	WFCENTER	-31.4	339.0	2

MultiDrizzle uses the information stored in the World Coordinate System (WCS) of the image header to align images. When the parameter `driz_separate=yes', the input images will be corrected for geometric distortion and drizzled onto separate output frames which have a common WCS. Any required shifts, rotations, or scale changes are computed from the image headers. The output image dimensions are calculated on-the-fly and the pixel scale is taken from the column `scale' from the IDCTAB reference file, where the default values are 0.05 arcsec/pix for the WFC and 0.025 arcsec/pix for the HRC and SBC. If drizzling is not done, the effects of distortion must be removed from the photometry by applying the Pixel Area Maps.

The distortion reference file is read from the image header via the IDCTAB and DGEOFILE keywords which specify the name and location of the appropriate reference files (*_idc.fits and *_dxy.fits). The distortion coefficients for each chip are written to temporary ascii files named `*_coeffs?.dat'. These files are useful for running several tasks in the drizzle package. If the user wishes to retain these files, the parameter `clean' should be set to `no'. In future versions of the software, the distortion information will be maintained in the image header via SIP coefficients, rather than external reference files.

By default, MultiDrizzle will look for all files in the working directory with the `_flt.fits' extension. Alternately, a file `suffix' may be used to define the input image list, or a subset of images in a given directory may be specified via the `filelist' parameter. The first image in the list will be defined as the reference image, and all the others will be registered with respect to this WCS. The size of the output images will be chosen such that all the input images are contained within the array.

A reference image may be specified, and the input images will be drizzled to match the WCS of this image. Alternately, the central RA and Dec (ra, dec) of the reference pixel and the dimensions of the output frame (outnx, outny) may be specified, though reasonable values will be automatically determined from the images' WCS if these parameters are left blank. The central RA and Dec are specified in the initial setup parameters, and the output image dimensions are specified in both the `driz_separate' and `driz_combine' parameters in MultiDrizzle steps 3 and 7, respectively.

Within a single visit, small dithers are usually accurately reflected by the WCS. This is not always the case for multiple visits which often require guide star re-acquisitions and may utilize different guide stars. Even for back-to-back exposures that are part of an association, residual offsets on the order of a few tenths of a pixel can be significant enough to degrade final combinations. It is therefore essential to verify the presence of image-to-image shifts, rotations, and/or scale variations before combining data with MultiDrizzle. These residual offsets may be determined by separately drizzling onto a common output frame and then matching source lists to derive a single correction for each image.

The input files are:

1. the calibrated images `*_flt.fits'
2. the reference files `*_idc.fits' & `*_dxy.fits' (obtained from the archive)

The output products are:

1. the single science and weight images: `*_single_sci.fits' & `*_single_wht.fits'
2. the coefficient files `*_coeffs?.dat' (one for each chip)
3. the mask files `*_single_mask?.fits' & `*_final_mask?.fits' (one for each chip)

MultiDrizzle uses the asnUtil package to create an association table whose name is defined by the MultiDrizzle parameter `output'. This association will be used to define the data set, and the header WCS from the entire set is used to define a common output frame. If user defined shifts are available, these may be specified via the `shiftfile' parameter, and the association table will be updated. A shift file is not usually available until after separately drizzling the images onto a common WCS and source lists have been matched.

By default, the `driz_separate' step uses the drizzle kernel `turbo', the linear drop size `pixfrac=1', and an output pixel scale equal to the input scale. For more information on setting these parameters, refer to the HST Dither Handbook. These parameters can be changed when the images are obtained as part of a sub-pixel dither pattern; for example, masks can be substantially improved by specifying a smaller value of scale, with the primary trade-off being increased computation time and much larger images (the size increases as the inverse square of the value of `scale').

In this example, we have left the `driz_separate' parameters to their default values. While the final drizzled image would contain 3 extensions in a single file (the science, weight, and context images), the `driz_separate' products are separate science and weight images named `*_single_sci.fits' and `*_single_wht.fits'. By default, ACS drizzled images are corrected for exposure time and are output in units of electrons per second.

The separately drizzled science images may be used to improve the image registration prior to final drizzle combination. While the WCS information for images taken within a single visit are usually adequate to align them, there can be significant residual offsets between visits. Shifts which are determined from separately drizzling images onto a common WCS are by definition `delta' shifts, and will be applied in addition to any offsets from the WCS when a shift file is provided.

The images have been renamed as shown below for the purposes of illustration within this example. Next, the images are separately drizzled onto a common output frame which is free from distortion.

  imrename j9irw3fwq_flt.fits f606w_01_flt.fits
 imrename j9irw4b1q_flt.fits f606w_02_flt.fits
 imrename j9irw5kaq_flt.fits f606w_03_flt.fits
  unlearn multidrizzle
 iraf.multidrizz.clean = no
 iraf.multidrizz.build = no
 iraf.multidrizz.static = no
 iraf.multidrizz.skysub = no
 iraf.multidrizz.driz_separate = yes
 iraf.multidrizz.median = no
 iraf.multidrizz.blot = no
 iraf.multidrizz.driz_cr = no
 iraf.multidrizz.driz_combine = no
  multidrizzle *_flt.fits output=f606w

Next, the user should measure the positions of stars in the separately drizzled images, and compute a shift file which defines the residual offsets between images which were not accounted for using the header WCS. To find stars using the task `daofind', it is necessary to first measure the standard deviation of the sky background using the task `imexamine'. In this example, setting the object detection threshold to 50 sigma above the local background results in ~16K sources detected over the field of view which can be used to perform catalog matching. When specifying IRAF task parameters from the command line within PyRAF, the parameter must be preceded by the word `iraf.' as shown below. When specifying these parameters from the command line within IRAF, the prefix `iraf.' is not necessary.

  apphot
 iraf.findpar.thresh=50
 iraf.datapar.sigma=0.02
 daofind f606w_01_single_sci output=f606w_01.cdt inter- verif-
 daofind f606w_02_single_sci output=f606w_02.cdt inter- verif-
 daofind f606w_03_single_sci output=f606w_03.cdt inter- verif-

To match star lists using `xyxymatch', an initial guess of the residual image offsets may be determined by displaying each single drizzled image and measuring the xy-shift of a single star with respect to the first (reference) image.

  displ f606w_01_single_sci 1 zs- zr- z1=-0.1 z2=1
 displ f606w_02_single_sci 2 zs- zr- z1=-0.1 z2=1
 displ f606w_03_single_sci 3 zs- zr- z1=-0.1 z2=1

In this case, we find that the stars in the second visit are offset from the first visit by approximately (-29,-40) pixels. The tolerance for matching has been set to 2 pixels in this example; however, if sufficient numbers of stars are not matched, the tolerance can increased slightly.

  iraf.xyxymatch.matching='tolerance'
  xyxymatch inp="f606w_02.cdt" refer="f606w_01.cdt"\ 
out="f606w_match2.cdt" xin=-29 yin=-40 xrot=0 yrot=0 toler=2
  xyxymatch inp="f606w_03.cdt" refer="f606w_01.cdt"\ 
out="f606w_match3.cdt" xin=-8  yin=-30 xrot=0 yrot=0 toler=2

The resulting matched coordinate lists now contain ~6K stars, since cosmic rays and saturated star spikes have now been removed by matching coordinate lists. Using the task `tvmark', the user may overplot the original coordinate list in blue, the stars matched with image two in red, and the stars matched with image three in green.

  tvmark 1  f606w_01.cdt mark=point nx=0 ny=0 points=3 color=203 inter-
 tvmark 1  f606w_match2.cdt mark=point nx=0 ny=0 points=3 color=204 inter-
 tvmark 1  f606w_match3.cdt mark=point nx=0 ny=0 points=3 color=205 inter-

To compute a more accurate estimate of the residual offsets, it is necessary to compute the geometric transformation between images. This can be done using the matched star lists which contain 4 columns each: xref, yref, xin, yin. The task `geomap' allows the user to specify the fitting geometry to be used. In this case, we use `fitgeom=rscale' which tells `geomap' to solve for an x and y shift, a single rotation, and a single scale correction. (See the help file for `geomap' for more details on the fitting geometry.)

It is important to note that `geomap' computes the transformation about the pixel (0,0), while MultiDrizzle applies the shifts with respect to the center of the drizzled image. Therefore, it is necessary for the user to subtract the image center from the star coordinates in order to compute the correct offsets. The reference center of the drizzled output images can be determined with the task `hselect' as follows:

  hselect *sci.fits $I,D001OUXC,D001OUYC yes

The reference center in this example is at the position (2732.5, 2958.5), and these x and y values must be subtracted from the matched star lists before computing the transformation.

  tcalc *match*.cdt  c7  "c1-2732.5"
 tcalc *match*.cdt  c8  "c2-2958.5"
 tcalc *match*.cdt  c9  "c3-2732.5"
 tcalc *match*.cdt c10  "c4-2958.5"

Finally, the corrected columns for each image can be extracted and piped to a new output file which will be used by `geomap' to compute the transformation.

  fields f606w_match2.cdt 7,8,9,10 > f606w_match2_sub.cdt
 fields f606w_match3.cdt 7,8,9,10 > f606w_match3_sub.cdt
  geomap f606w_match2_sub.cdt datab=cdt.db fitgeom=rscale inter=no\
     reject=3 maxiter=5 xmin=INDEF xmax=INDEF ymin=INDEF ymax=INDEF
 geomap f606w_match3_sub.cdt datab=cdt.db fitgeom=rscale inter=no\
     reject=3 maxiter=5 xmin=INDEF xmax=INDEF ymin=INDEF ymax=INDEF

The resulting offsets were recorded to the nearest 0.01 pixel and are listed below in the form of a shift file. The ascii file below is called `shift.dat' and contains the residual offsets which were derived by the user using the results from `geomap'. The columns are as follows: image, x_resid, y_resid, rotation, scale. For observations which are taken in different visits (and therefore at different orientations), residual rotations and scales are usually required.

  # units: pixels
 # form: delta
 # frame: output
 # refimage: refimage.fits
 f555w_01_flt.fits   0.00   0.00 0.0000 1.00000
 f555w_02_flt.fits -29.25 -40.58 0.0046 1.00008
 f555w_03_flt.fits  -7.61 -29.87 0.0008 0.99996
 

Before moving on to further processing steps, the single drizzled image should be copied to a file called `refimage.fits'. The residual offsets given in the shift file are defined with respect to this reference image. MultiDrizzle may now be called again, this time specifying the name of the file with the residual offsets, and the single drizzled images will now be accurately aligned.

  imcopy f606w_01_single_sci.fits refimage.fits
  multidrizzle *_flt.fits output=f606w shiftfile='shift.dat'

6.2.4 Example 3: Optimizing the Cosmic Ray Rejection
for an ACS Mosaic with Sub-pixel Dithers

The following example describes the combination of eight ACS/WFC images of the galaxy NGC 4449 (Program 10585, PI Aloisi) which were obtained with the F555W filter. These images were acquired in two separate visits and are all at the same orientation. A combination of two ACS-WFC-DITHER-LINE patterns were used for this program. The primary pattern has two points shifted roughly 5x60 pixels apart to span the WFC interchip gap, so that combined data will not have missing data there. The secondary pattern is a 2-point sub-pixel dither pattern which, when used in conjunction with the gap dither, allows the user to sub-sample the PSF. The two image associations j9cd01020 and j9cd02020 correspond to the left and right halves of the galaxy, and this is reflected in the target RA and Dec information. These data are available from the HST archive for those who wish to repeat this example. Approximately 5 GB of free disk space is required when intermediate products are not removed.

An outline of the drizzling process for the NGC4449 dataset is described below. While MultiDrizzle may be run from start to finish in a single pass, we have chosen to break up this example into several sections so that intermediate products can be examined and fine-tuned before moving on to later processing steps.

Table 6.4: Calibrated datasets used in the accompanying MultiDrizzle example. The two sets of images have a significant shift to image the left and right halves of the galaxy. Within a given visit, small sub-pixel dithers have been specified in accordance with the WFC-DITHER-BOX pattern.

Association	Dataset	Observation Date	RA/Dec (degrees)	POS-TARG1 (arcsec)	POS-TARG2 (arcsec)	Exposure Time (seconds)
j9cd01020	j9cd01kqq_flt	2005-11-10	187.0656 +44.1148	0.000	0.000	608
	j9cd01l5q_flt	2005-11-10	187.0656 +44.1148	0.123	0.084	615
	j9cd01ldq_flt	2005-11-10	187.0656 +44.1148	0.247	2.984	616
	j9cd01mfq_flt	2005-11-10	187.0656 +44.1148	0.370	3.068	621
j9cd02020	j9cd02phq_flt	2005-11-11	187.0128 +44.0854	0.000	0.000	608
	j9cd02ppq_flt	2005-11-11	187.0128 +44.0854	0.123	0.084	615
	j9cd02pxq_flt	2005-11-11	187.0128 +44.0854	0.247	2.984	616
	j9cd02q5q_flt	2005-11-11	187.0128 +44.0854	0.370	3.068	621

When large volumes of data are being processed, it can be helpful to rename the input files in the working directory in a meaningful way. The IRAF task `hselect' may be used to query the image headers to assist in defining a naming convention. For example:

  hselect images="*flt.fits[1]" expr=yes \
   fields='rootname,date-obs,targname,ra_targ,dec_targ,postarg*,\
exptime,filter*' 

The output from `hselect' tells us that the first four images are centered on the left half of the galaxy `POSA' and the second four images are centered on the right half of the galaxy: `POSB'. In this example, the images have been renamed `f555w_pos?_0?_flt.fits', where the first index refers to the target position, and the second index refers to the sub-pixel dithers 1-4 in the box pattern. For illustration, only two images have been renamed in the box below, but in practice, the user should rename all eight images.

  imrename j9cd01kqq_flt.fits f555w_posa_01_flt.fits
 imrename j9cd02phq_flt.fits f555w_posb_01_flt.fits

6.2.4.1 Improving the Alignment

The images should first be singly drizzled by running MultiDrizzle step 3 (driz_separate), as described in Example 2. The separately drizzled science images may be used to improve the image registration prior to final drizzle combination. In this example, the images form two groups of three. While the WCS information for images within a single group (visit) are adequate to align them, there is a small residual offset between visits. Shifts which are determined from separately drizzling images onto a common WCS are by definition `delta' shifts, and will be applied in addition to any offsets from the WCS when a shift file is provided.

One of the singly drizzled FLT images, `f555w_posa_01_flt_single_sci.fits', is shown in Figure 6.6. This image still contains numerous cosmic ray events, hot pixels, and other artifacts. The `rhombus' shape is a result of correcting the geometric distortion. The corresponding weight image, `f555w_posa_01_flt_single_wht.fits', is shown in Figure 6.7, where white indicates pixels with zero weight. Due to the effects of distortion and varying pixel area in the `_flt.fits' images, the weight image changes gradually by ~10% across the detector. Because the association table was used to define a common WCS for all images, the drizzled image is `padded' with zeros outside the boundary of the original array. The weight image is set to zero in these regions, allowing these pixels to be rejected during median combination.

Figure 6.6: Single ACS Science Image


 
The single science image.
 
Figure 6.7: Single ACS Weight Image


 
The weight image for the single science image.
 

Next, the user should measure the positions of stars in the separately drizzled images, and compute a shift file which defines the residual offsets between images which were not accounted for using the header WCS. This process is described in detail in Example 2 and will not be addressed in this example. After separately drizzling, the `_single_sci.fits' images at POSB are offset from the first image at POSA by approximately (-20,+19) pixels. The tolerance for matching has been set to 2 pixels in this example; however, if the images were obtained at different orientations, small residual rotations on the order of 0.005 degrees may also exist. In this case, the tolerance should be set slightly higher, for example 10 pixels, to ensure that stars are matched.

The resulting matched coordinate lists contain ~6K stars for POSA and ~2K stars for POSB. The fewer stars matched for POSB are due to the fact that there is only a small overlap between the two pointings.

The residual offsets were recorded to the nearest 0.01 pixel and are listed below in the form of a shift file. The transformation results for this example using `fitgeom=rscale' show no significant rotation or scale terms (i.e. the largest residual rotation is less than 0.001 degrees and the largest scale correction, 1.000009, times the detector size, 4096 pixels, is less than 0.1 pixels). Thus, the `geomap' steps described above may be rerun, but with `fitgeom=shift' to obtain slightly more accurate results. (Note that the fit rms given in the geomap output is approximately the same (0.1 pixels) whether `shift' or `rscale' was used. If indeed a residual rotation or scale was required, the fit rms would be significantly smaller when `fitgeom' was set to `rscale' compared to when it was set to `shift'.)

The ascii file below is called `shift.dat' and contains the residual offsets which were derived by the user using `geomap'. The columns are as follows: image, x_resid, y_resid, rotation, scale. In this case, no significant rotation or scale terms were found, so these columns have been left blank. For observations which are taken in different visits (and therefore at different orientations), residual rotations and scales are usually required.

  # units: pixels
 # form: delta
 # frame: output
 # refimage: refimage.fits
 f555w_posa_01_flt.fits   0.00   0.00
 f555w_posa_02_flt.fits  -0.05  -0.05
 f555w_posa_03_flt.fits   0.10   0.08
 f555w_posa_04_flt.fits   0.02   0.06
 f555w_posb_01_flt.fits -19.99  18.63
 f555w_posb_02_flt.fits -19.97  18.65
 f555w_posb_03_flt.fits -20.00  18.69
 f555w_posb_04_flt.fits -19.98  18.70

Before moving on to further processing steps, the single drizzled image should be copied to a file called `refimage.fits'. The residual offsets given in the shift file are defined with respect to this reference image.

  imcopy f555w_posa_01_single_sci.fits refimage.fits

6.2.4.2 A Quick-way to Produce a Combined Image

All the necessary information for successfully combining the data should be in hand at this point. The `shiftfile' provides the corrections to the alignment of the images to allow the rest of the MultiDrizzle processing to correctly identify and remove cosmic rays. The final combined image can be generated using one more call to MultiDrizzle, this time turning on all the steps:

  unlearn multidrizzle
 multidrizzle *_flt.fits output=f555w shiftfile='shift.dat'

The resulting product will be the final combined image named, in this case, `f555w_drz.fits' which can now be used for science. Because the default MultiDrizzle parameters may not provide optimal data products, and the user is strongly advised to inspect the quality of the sky subtraction and cosmic ray rejection and to experiment with the output `scale' and `pixfrac' parameters for the final drizzle step. The following sections will walk the user through each of the remaining processing steps.

6.2.4.3 Creating the Median

Once the appropriate offsets have been determined, MultiDrizzle should be rerun from the beginning with only steps 1-4 (static mask, sky subtraction, single drizzle, and median) turned on and with the `shiftfile' parameter pointing to the ascii file containing the residual offsets. MultiDrizzle will use the header WCS information in combination with the shift file to appropriately align images.

When `static=yes', MultiDrizzle goes through each of the input images, calculates the rms value for each chip, and identifies pixels that are below the median value by more than `static_sig' times the rms. This step is used for identifying pixels that may have high values in the dark frame, which is subtracted during calibration, but may not necessarily have high values in the images, and thus subtraction gives them large negative values. Such pixels are not always flagged in the DQ file, and this step allows them to be identified. Sometimes such pixels fall on bright objects so instead of being negative, they would be positive but lower than surrounding pixels. If the images are dithered, then they should land on blank sky at least some of the time, in which case they will appear negative and will be flagged.

When `skysub=yes', MultiDrizzle will subtract the sky from each drizzled exposure. Since the input images have different exposure times, it is important to remove the sky prior to creation of the median image. Otherwise, deviant pixels will not be optimally rejected from the median, and this will impact the accuracy of the cosmic ray rejection which is performed in step 5 and which compares each input pixel with the blotted median image. Sky subtraction is recommended for effective cosmic ray flagging and removal, but only if sufficient blank sky is available to perform an accurate determination. Great care must be taken when choosing to implement sky subtraction, because if blank sky is not available, sky subtraction will produce erroneous results. Two important parameters to consider are the upper and lower values for data that will be used to estimate the sky value. These should be set to include most pixels in the sky (so substantially more than the FWHM of the sky distribution) but not so large as to include a substantial amount of power from objects or cosmic rays. For more information, refer to Section 4.6 of the ACS Data Handbook.

During pipeline processing, the header keyword MDRIZSKY is estimated using the default MultiDrizzle parameters and is then written to the image header in the science extensions [1] and [4] of the `*_flt.fits' image. The sky is not subtracted from the science array pixel values. If the user wishes instead to compute the sky using an alternate method, the parameter `skyuser' can be set to point to a keyword in the image header which gives the user's sky value. MultiDrizzle will assume that this sky value has already been removed from the `*_flt.fits' images prior to processing. The value set by the parameter `skyuser' is then copied to MDRIZSKY for computing statistics, but it is not actually subtracted from the drizzled image since it assumes this has already been done.

The sky background is calculated independently for each of the two chips, and the lowest value is taken to represent the true sky value for both chips. Since the main body of NGC4449 is centered on the lower chip, the sky value from the upper chip has been selected by MultiDrizzle for populating the header keyword MDRIZSKY in the `*_flt.fits' image header. MultiDrizzle will subtract the sky from the single drizzled prior to the creating the median. Note that the pixel values in the `*_flt.fits' images themselves are not modified when MultiDrizzle completes.

When `median=yes', MultiDrizzle creates a median image from the separate drizzled input images, allowing a variety of combination and rejection schemes. If `combine_type' is set to `median' or `average', then the routine carries out a similar calculation to the standard IRAF task `imcombine', with equivalent behavior for the parameters `combine_nlow' and `combine_nhigh' (the number of low and high pixels to reject), and `combine_grow' (the amount by which flagged pixels can grow). All imcombine parameters other than those specified above are reset to their default values.

If `combine_type=minmed', a more sophisticated algorithm is used to combine images. The basic concept is that each pixel in the output combined image will be either the median or the minimum of the input pixel values, depending on whether the median is above the minimum by more than n times sigma. An estimate of the "true" counts is obtained from the median image (after rejecting the highest-valued pixel), while the minimum is actually the minimum unmasked ("good") pixel. This algorithm is designed to perform optimally in the case of combining only a few images (3 or 4), where triple-incidence cosmic rays often pose a serious problem for more simplified median combination strategies. The `minmed' algorithm performs the following steps:

a.) Create median image, rejecting the highest pixel and applying masks.

b.) Use this median to estimate the true counts, and thus derive an rms.

c.) If the median is above the lowest pixel value by less than the first value in `combine_nsigma', then use the median value, otherwise use the lowest value.

d.) If `combine_grow' > 0, repeat the above 3 steps for all pixels around those that have already been chosen as the minimum, this time using a lower significance threshold specified as the second value in `combine_nsigma'.

The last step is very successful at flagging the lower signal-to-noise "halos" around bright cosmic rays which were flagged in the first pass.

If `median_newmasks=yes', then the singly drizzled weight maps (`*_single_wht.fits') are used to create pixel masks for each image, based on the pixel flag information originally present in the DQ arrays. These masks will then be used when combining images, in order to prevent bad pixels from adversely affecting the median. If `median_newmasks=no', MultiDrizzle will use masks which have been created offline by the user and which are specified via the `BPM' header keyword in each image.

The median image has been generated by running MultiDrizzle steps 1-4 in succession on the `*_flt.fits' images. The eight separately drizzled images are combined using the bad pixel masks and the rejection parameters specified below to create a single clean median image named `f555w_med.fits'. Note that by rerunning step 3, new versions of the single drizzled images have been created, and these will now be correctly aligned. These separate images will be combined to create the median image.

   multidrizzle *_flt.fits output=f555w shiftfile='shift.dat' \
       static+  skysub+  driz_separate+ driz_sep_fillval=99999 \
       driz_sep_bits=4192 median+ combine_type=minmed \
       combine_nhigh=0 combine_hthresh=99990

Selecting the best parameters for the median step can be an iterative process and should always involve examination of the clean, combined product to verify that the majority of cosmic rays and other artifacts are successfully removed. The rejection algorithm which is ultimately chosen depends largely on the number of datasets being combined and the amount of overlap between dithered images. In this example, the parameter 'driz_sep_fillval' has been set to a very large number (99999) and the median parameter 'combine_hthresh' has been chosen so that pixels with no valid input are rejected prior to median combination. The parameters 'combine_type=minmed' and 'combine_nhigh=0' were selected because the left and right halves of the mosaic have only 4 input images contributing, and because the area containing the WFC chip gap has only 2 input images. When a large number of input images are available, the parameter 'combine_type' may be set to 'median', and this will save the user excess computation time.

When examining the median image, the width and shape of the PSF should be inspected over the entire field of view to confirm the quality of the image registration. A PSF which is 'round' and 'narrow' is a sign that the alignment was successful. To confirm that no residual offsets or rotations remain, the position of stars and the geometric transformations should again be examined for the new separately drizzled images (using the steps outlined in Example 2). The median combination may require some 'tweaking' of the rejection parameters to produce a clean result. To avoid overwriting the median image when 'fine-tuning' the parameters, the user should copy the image to a unique filename before rerunning MultiDrizzle. The median image created from each test run should be carefully inspected and compared to verify which parameters work best at removing cosmic rays, hot pixels, and other artifacts.

  imcopy f555w_med.fits f555w_med_test1.fits

6.2.4.4 Computing the Cosmic Ray Masks

Turning on steps 5 and 6 (blot and driz_cr), MultiDrizzle will transform the median image back to the distorted reference frame, and it will compare the original and the blotted median images in order to identify cosmic rays. For optimal flagging, sky subtraction should be performed when the background is more than a few electrons. Images obtained from the archive have already been run through MultiDrizzle using a default set of parameters, and these pixels will be flagged with a value of 4096 in the data quality (DQ) array of the '*_flt.fits' images. Because the default values may not be optimal for every dataset, the user is encouraged to fine-tune the cosmic ray rejection parameters 'driz_cr_snr' and 'driz_cr_scale', especially if the images were not obtained using a pre-defined dither pattern.

When 'blot=yes', the median image is transformed back ('reverse drizzled') to the reference frame of each original input image. This is done by backing out the shifts/rotations which were applied in step 3 and by applying an inverse distortion correction. The median image is resampled to the pixel scale of the original images and is trimmed to match the dimensions of each input image. The blotted frames are created for each chip and are named '*_sci?_blt.fits'. If desired, the user may wish to display the input images and blink them with their 'blotted' counterparts. The 'blotted' images should align perfectly with their respective input images and should be similar in appearance, except for being cleaned of cosmic rays and other defects.

When 'driz_cr=yes', MultiDrizzle uses the original input images, the blotted median image, and the derivative of the blotted image (created with the 'deriv' task) to create a cosmic ray mask for each input image. The 'deriv' task 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 saved to a temporary image, '*_sci?_bl_deriv.fits', which represents an effective gradient or spatial derivative. These derivative images are used by 'driz_cr' 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*deriv_image + SNR*noise 

where 'scale' is defined as the multiplicative factor applied to the derivative which 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.

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. The following command illustrates how to reproduce the cosmic ray rejection performed in the pipeline.

 multidrizzle *_flt.fits output=f555w shiftfile='shift.dat'\ 
   static+ skysub+ driz_separate+ driz_sep_fillval=99999\
   driz_sep_bits=4192 median+ combine_type=minmed \
   combine_nhigh=0 combine_hthresh=99990 blot+ driz_cr+ \
   driz_cr_corr+ driz_cr_snr='3.5 3.0' driz_cr_scale='1.2 0.7' \
   crbit=0

When 'driz_cr_corr'=yes, the task will create both a cosmic ray mask image ('*_sci?_crmask.fits') and a clean version of the original input images ('*_sci?_cor.fits') where flagged pixels are replaced with pixels from the blotted median. The cosmic ray masks are multiplied by the bad pixel masks from step 1 (which are a combination of the image DQ array and the static masks) to create a final mask for each image. The optional parameter 'crbit' tells MultiDrizzle which flag value to assign to cosmic rays, and this flag will be written to the DQ array of each input image. If this parameter is left blank during reprocessing, the default value of 4096 is used. While experimenting with the 'driz_cr' parameters, the user can tell MultiDrizzle not to update the DQ arrays by setting this parameter equal to zero. Then, once the user is happy with the cosmic ray masks, the 'crbit' may be assigned a unique value, for example, 8192.

The quality of the cosmic ray masks should be verified by blinking the original input image with the cosmic ray mask. For comparison, the user may also blink the cosmic rays flagged by the pipeline. This may be done by displaying only pixels in the DQ array with a value greater than 4096. When testing various parameter values, the user may find that the centers of stars are being unnecessarily masked, and this indicates that the 'driz_cr_scale' parameter should be increased. If not enough cosmic rays are being detected, this parameter should be decreased.

 displ f555w_posa_01_flt.fits[1] 1 \
      zs- zr- z1=0 z2=1000 ztran=log
 displ f555w_posa_01_sci1_crmask.fits 2 \
      zs- zr- z1=0 z2=1
 displ f555w_posa_01_flt.fits[3] 3\
      zs- zr- z1=4000 z2=5000

In the figures below, chip 2 of the original input image j8cw54orq_flt.fits[sci,1] (Figure 6.8) is presented with its corresponding cosmic ray mask(Figure 6.9). Note that a mask value of 1 (shown in black) corresponds to good pixels, while a mask value of 0 (white) corresponds to pixels flagged as cosmic rays.

Figure 6.8: Single Chip from ACS FLT Image


 
The FLT image.
 
Figure 6.9: Cosmic Ray Mask from Single ACS FLT Image


 
The cosmic ray mask.
 

For these observations, the default 'driz_cr_snr' values "3.5 3.0" are too stringent and cause numerous single pixels to be flagged where the background noise is high. True cosmic ray impacts are usually more spatially extended, so the 'driz_cr_snr' parameter has been increased to "5.0 4.0" to create more conservative masks. This approach was chosen because only 4 images go into making each half of the final mosaic. Thus if too many input pixels are flagged, the final image may be degraded. Large rms deviations in the background noise will be 'beat down' when the images are combined in the final drizzle step.

Once the optimal cosmic ray rejection parameters have been determined, the user should rerun the MultiDrizzle with the 'crbit' set to a unique value, 8192, for example. In this way, the DQ arrays will be updated with the user-defined masks. Then, during the final drizzle step, the 'driz_final_bits' parameter can be set so that MultiDrizzle will ignore the erroneous 4096 DQ values flagged during pipeline processing.

  multidrizzle input="*_flt.fits" output=f555w \
    shiftfile='shift.dat' static+ skysub+ driz_sep+ \
    driz_sep_fillval=99999 driz_sep_bits=4192 \
    combine_type=minmed median+ driz_comb+ blot+ driz_cr+ 
    driz_cr_corr+ driz_cr_snr='5.0 4.0' combine_nhigh=0\
    combine_hthresh=99999 driz_cr_scale='1.2 0.7' crbit=8192

6.2.4.5 Final Drizzle

Once the residual shifts and improved cosmic ray masks have been computed, the final drizzled combined mosaic may be created by running step 7 only and turning off all intermediate processing steps. The sky background is NOT removed in this example, following the recommendation from the DAOPHOT Reference Guide by Lindsey Davis: "The sky background should NOT be subtracted from imaging prior to photometry. DAOPHOT fitting routines use an optimal weighting scheme which depends on the readnoise, gain, and true counts in each pixel. If the mean sky has been subtracted, the computed weights will be incorrect". Depending on the user's science needs, the sky background can be left in or removed by setting the 'skysub' parameter appropriately.

  multidrizzle output='f555w'  final_bits=4192 \
    shiftfile='shift.dat'  static- skysub- driz_sep- \
    median- blot-  driz_cr- driz_comb+ final_rot=INDEF

When 'driz_combine=yes', this step takes the original input images, together with the final masks, and drizzles them onto a single output image. The standard drizzle parameters 'final_kernel', 'final_scale', 'final_pixfrac', and 'final_rot' can be specified by the user, if desired. By default the scale of the output WFC image is 0.05"/pixel, but the user is encouraged to experiment with other options (e.g. shrinking the 'final_scale' and 'final_pixfrac' to yield a sharper output PSF.)

The 'bits' parameter is defined as the integer sum of all bit values from the input image DQ array that should be considered 'good' when building the weight mask. Because MultiDrizzle was designed for use with multiple instruments, the default value for the 'bits' parameter and is set to zero both in step 3 ('driz_sep_bits') and in step 7 ('final_bits'). For ACS data, the pipeline uses the value 96 which is specified in the MDRIZTAB reference file and which tells MultiDrizzle to ignore data quality flags 32 and 64. These flags were set by CALACS and correspond to CTE tails of hot pixels in superdark DQ arrays and warm pixels in superdark DQ arrays. For more information on selecting the appropriate bits for your data, refer to Section 5.5.7. Information from the DQ array for each chip is used in combination with the 'bits' parameter to create temporary mask files for each chip, where pixels which were flagged in the DQ array and which were not specified as good are assigned a value of zero in the mask. The 'final_bits' value in this example is 4192, the sum of 4096, 32, and 64. This tells MultiDrizzle to ignore pixels which were flagged with a value of 4096 during pipeline processing and to treat them as 'good' pixels.

The first extension of the drizzled mosaic 'f555w_drz.fits[1]' contains the science (SCI) image which has been corrected for distortion which represents the combination of all eight dithered images. All pixels cover an equal area on the sky and have an equal photometric normalization across the field of view, giving an image which is photometrically and astrometrically accurate for both point and extended sources. The dimensions of the output image are computed on-the-fly by MultiDrizzle and the default output plate scale is read from the 'scale' column in the IDCTAB. These parameters, however, may be chosen by the user to best suit the actual data. In this example, the size of the output image is ~7700x4340 pixels. The SCI image is presented in Figure 6.10 and is in units of 'electrons/sec'. Changing the 'final_units' parameter from the default value 'cps' (counts per second) to 'counts' will produce a drizzled image in units of electrons.

Figure 6.10: The Final ACS Science Image


 
The final science image.
 

The second extension of the output image contains the weight (WHT) image. When the `final_wht_type' is set to `EXP', the weight image can be considered an effective exposure time map. The weight image from our example is shown in Figure 6.11, where darker areas have higher weight. The chip gaps are clearly visible, as are column defects and cosmic ray features. The center of the image is "black" and corresponds to the overlap of all eight images. The weight in this region is ~4700 which is approximately equal to the sum of the exposure times of all eight images. The majority of the weight image is "dark gray" and corresponds to the overlap of the four input images at each position (A and B). In this region the weight is ~2400. Note that there is a smooth variation of approximately 10% across both the left and right halves mosaic which is due to the variation of the pixel area on the sky caused by the distortion. This variation cannot be seen in the figure, but is clearly present when performing statistics on different regions of the weight image. Finally, the "light grey" regions correspond to a weight of ~1200 where only two images contribute to the final product, for example in the chip gap Figure 6.11.

Figure 6.11: The Final ACS Weight Image


 
The final weight image.
 

The output weight image can also be specified to be in units of inverse variance by setting `final_wht_type = ERR'. In this case, the weight is calculated using the error arrays in the second and fifth extensions of the `*_flt.fits' files. The error arrays include all sources of error, including read-noise, dark current, as well as the sky background and all the source.

Finally, if `final_wht_type = IVM', MultiDrizzle will look for inverse variance files provided by the user (for example, to include all sources of noise except those related to photons from objects in the field). These would be specified by giving all the input `*_flt.fits' files to MultiDrizzle in an ASCII file list, with each line containing just two filenames, namely the name of the `*_flt.fits' file and its corresponding IVM file. The IVM file should have a similar structure as the `*_flt.fits' file, except that the inverse variance values are stored in an extension that is called [IVM].

6.2.4.6 Optimizing Scale and Pixfrac for Subsampled Data

To determine the optimal drizzle parameters for the final mosaic, the user is advised to experiment with different combinations of the parameters 'final_scale' (the size of the output pixels) and 'final_pixfrac' (the linear size of the 'drop' in input pixels). One must choose a pixfrac value that is small enough to avoid degrading the final image, but large enough that when all images are dropped onto the final frame, the flux coverage of the output frame is fairly uniform. As suggested in the HST Dither Handbook, statistics performed in different regions of the drizzled weight image should yield an rms value which is less than 20% of the median value. In general, the 'pixfrac' should be slightly larger than the scale to allow some spill over to adjacent pixels.

For bookkeeping purposes, it can be helpful to rename the final drizzled product to reflect the final drizzle parameters. Then, different versions of the drizzled science and weight images may be compared directly for the purpose of selecting the best parameters. Following the guidelines described above, a final scale equal to 0.7 times the default pixel scale (0.05"/pixel) and a final pixfrac of 0.8 provides the best sampling for these dithered data. (For more discussion, refer to ACS Example 1.) The plate scale of the resulting mosaic is 0.035"/pixel and the FWHM of the PSF (in arcseconds) is narrower than in the drizzled pipeline product.

 multidrizzle output='f555w'  final_bits=4192 \
   shiftfile='shift.dat' static- skysub- driz_sep- median+ \
   blot- driz_cr- driz_comb+ final_scale=0.035 \
   final_pixfrac=0.8 final_rot=INDEF
 imrename f555w_drz.fits f555_drz_sc07_px08.fits