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