Step 6: Blotting the Median Image

In this step the median image now gets blotted back to create median-cleaned images which can be compared directly with each input image to identify cosmic-rays.

Authors:Warren Hack
License:http://www.stsci.edu/resources/software_hardware/pyraf/LICENSE
drizzlepac.ablot.blot(data, outdata, configObj=None, wcsmap=wcs_functions.WCSMap, editpars=False, **input_dict)

The median image is the combination of the WCS aligned input images that 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 for 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 image artifacts (i.e. bad-pixels, hot pixels, and cosmic-rays) whose locations will be saved to the output badpixel masks.

Aside from the input parameters, this step only requires opening the single median image created from all the input images. A distorted version of the median image corresponding to each input ‘chip’ (extension) is written as output from this step as separate simple FITS images.

For more information on the science applications of the blot task, see the DrizzlePac Handbook

Parameters:

data : str

Input distortion-corrected (median or drizzled) image to be used as the source for creating blotted images.

reference : str

Filename of image to read to define the blotted WCS; image with distortion to be matched by output blotted image.

outdata : str

Filename for output blotted image.

coeffs : bool (Default Value = True)

This parameters specifies whether or not to use the header-based distortion coefficients when creating the blotted, distorted image. If False, no distortion will be applied at all, effectively working as a cut-out operation.

interp : str{‘nearest’, ‘linear’, ‘poly3’, ‘poly5’, ‘sinc’} (Default = ‘poly5’)

This parameter defines the method of interpolation to be used when blotting drizzled images back to their original WCS solution. Valid options include:

  • nearest: Nearest neighbor
  • linear: Bilinear interpolation in x and y
  • poly3: Third order interior polynomial in x and y
  • poly5: Fifth order interior polynomial in x and y
  • sinc: Sinc interpolation (accurate but slow)

The ‘poly5’ interpolation method has been chosen as the default because it is relatively fast and accurate.

If ‘sinc’ interpolation is selected, then the value of the parameter for blot_sinscl will be used to specify the size of the sinc interpolation kernel.

sinscl : float (Default Value = 1.0)

Size of the sinc interpolation kernel in pixels.

stepsize : int (Default Value = 10)

Number of pixels for WCS interpolation. The distortion model will be sampled exactly and completely every stepsize pixel with bi-linear interpolation being used to compute the distortion for intermediate pixels. This optimization speeds up the computation significantly when stepsize >> 1 at the expense of interpolation errors for intermediate pixels.

addsky : bool (Default Value = Yes)

Add back a sky value using the MDRIZSKY value from the header. If ‘Yes’ (True), the blot_skyval parameter is ignored.

skyval : float (Default Value = 0.0)

This is a user-specified custom sky value to be added to the blot image. This is only used if blot_addsky is ‘No’ (False).

in_units : str{‘cps’, ‘counts’} (Default Value= ‘cps’)

Units of input (drizzled) image. Valid options are ‘cps’ and ‘counts’.

out_units : str{‘cps’, ‘counts’} (Default Value = ‘counts’)

Units of the ouput (blotted) image. Valid options are ‘cps’ and ‘counts’.

expkey : str (Default Value = ‘exptime)

Name of keyword to use to extract exposure time value, which will be used to scale the blotted image to the final output flux values when out_units is set to counts.

expout : str or float (Default Value = ‘input’)

Value of exposure time to use in scaling the output blotted image when out_units is set to counts. If set to ‘input’, the value will be read in from the input image header keyword specified by expkey.

Note

The following parameters, when set, will override any value determined from refimage if a reference image was specified.

outscale : float,optional

Absolute size of output pixels in arcsec/pixel

orient : float

Orientation of output (PA of Y axis, N through E)

raref : float

RA of reference point on output image(CRVAL1,degrees)

decref : float

Dec of reference point on output image (CRVAL2, degrees)

xrefpix : float

Reference pixel X position on output (CRPIX1)

yrefpix : float

Reference pixel Y position on output (CRPIX2)

outnx : float

Size of output image’s X-axis (pixels)

outny : float

Size of output image’s Y-axis (pixels)

Notes

These tasks are designed to work together seemlessly when run in the full AstroDrizzle interface. More advanced users may wish to create specialized scripts for their own datasets, making use of only a subset of the predefined AstroDrizzle tasks, or add additional processing, which may be usefull for their particular data. In these cases, individual access to the tasks is important.

Something to keep in mind is that the full AstroDrizzle interface will make backup copies of your original files and place them in the OrIg/ directory of your current working directory. If you are working with the stand alone interfaces, it is assumed that the user has already taken care of backing up their original datafiles as the input file with be directly altered.

Examples

1. Basic example of how to call blot yourself from a python command line, using the default parameter settings:

>>> from drizzlepac import ablot
>>> ablot.blot()

2. Creation of a blotted image from the products generated by running the astrodrizzle task can be done for the median image “adriz_aligned_wcs_f814w_med.fits” to re-create the (SCI,1) chip from “j8c0d1bwq_flc.fits” using:

>>> from drizzlepac import ablot
>>> from stsci.tools import teal
>>> blotobj = teal.load('ablot') # get default values
>>> ablot.blot('adriz_aligned_wcs_f814w_med.fits','j8c0d1bwq_flc.fits[sci,1]',
'aligned_f814w_sci1_blot.fits',configObj=blotobj)

or

>>> a = teal.teal('ablot')
# set data = adriz_aligned_wcs_f814w_med.fits
# set reference = j8c0d1bwq_flc.fits[sci,1]
# set outdata = aligned_f814w_sci1_blot.fits
drizzlepac.ablot.buildBlotParamDict(configObj)
drizzlepac.ablot.do_blot(source, source_wcs, blot_wcs, exptime, coeffs=True, interp='poly5', sinscl=1.0, stepsize=10, wcsmap=None)

Core functionality of performing the ‘blot’ operation to create a single blotted image from a single source image. All distortion information is assumed to be included in the WCS specification of the ‘output’ blotted image given in ‘blot_wcs’.

This is the simplest interface that can be called for stand-alone use of the blotting function.

Parameters:

source

Input numpy array of undistorted source image in units of ‘cps’.

source_wcs

HSTWCS object representing source image distortion-corrected WCS.

blot_wcs

(py)wcs.WCS object representing the blotted image WCS.

exptime

exptime to use for scaling output blot image. A value of 1 will result in output blot image in units of ‘cps’.

coeffs

Flag to specify whether or not to use distortion coefficients associated with blot_wcs. If False, do not apply any distortion model.

interp

Form of interpolation to use when blotting pixels. Valid options:

"nearest","linear","poly3", "poly5"(default), "spline3", "sinc"

sinscl

Scale for sinc interpolation kernel (in output, blotted pixels)

stepsize

Number of pixels for WCS interpolation

wcsmap

Custom mapping class to use to provide transformation from drizzled to blotted WCS. Default will be to use drizzlepac.wcs_functions.WCSMap.

drizzlepac.ablot.getHelpAsString(docstring=False, show_ver=True)

return useful help from a file in the script directory called __taskname__.help

drizzlepac.ablot.help(file=None)

Print out syntax help for running astrodrizzle

Parameters:

file : str (Default = None)

If given, write out help to the filename specified by this parameter Any previously existing file with this name will be deleted before writing out the help.

drizzlepac.ablot.run(configObj, wcsmap=None)

Run the blot task based on parameters provided interactively by the user.

drizzlepac.ablot.runBlot(imageObjectList, output_wcs, configObj={}, wcsmap=wcs_functions.WCSMap, procSteps=None)
drizzlepac.ablot.run_blot(imageObjectList, output_wcs, paramDict, wcsmap=wcs_functions.WCSMap)

Perform the blot operation on the list of images.