# Step 2: Generate a Static Mask

This step focuses entirely on creating a static mask for each detector used in the input images of all negative (presumably bad) pixel values.

This module provides functions and classes that manage the creation of the global static masks.

For `staticMask`, the user interface function is `createMask()`.

Authors: | Ivo Busko, Christopher Hanley, Warren Hack, Megan Sosey
License: | LICENSE

`drizzlepac.staticMask.``buildSignatureKey`(signature)

  Build static file filename suffix used by mkstemp()

`drizzlepac.staticMask.``constructFilename`(signature)

  Construct an output filename for the given signature:

      signature=[instr+detector,(nx,ny),detnum]

  The signature is in the image object.

`drizzlepac.staticMask.``createMask`(input=None, static_sig=4.0, group=None, editpars=False, configObj=None, **inputDict)

  Create a static mask for all input images. The mask contains pixels that fall more than `static_sig` RMS below the mode for a given chip or extension. Those severely negative, or low pixels, might result from oversubtraction 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 seperate masks will be generated for each chip accordingly.

  The final static mask for each chip contains all of the bad pixels that meet this criteria from all of the input images along with any bad pixels that satisfy the final_bits value specified by the user, and found in the images DQ mask.

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

  The generated static masks are saved to disk for use in later steps with the following naming convention:

  > [Instrument][Detector]_[xsize]x[ysize]_[detector number]_staticMask.fits

  so an ACS image would produce a static mask with the name:

  > ACSWFC_2048x4096_1_staticMask.fits

  and this would be the only file saved to disk, storing the logic and of all the badpixel masks created for each acs image in the set.

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

  Parameters:

  input : str, None (Default = None)

    A list of images or associations you would like to use to compute the mask.

  static : bool (Default = True)

    Create a static bad-pixel mask from the data? This mask flags all pixels that deviate by more than a value of `static_sig` sigma below the image median, since these pixels are typically the result of bad pixel oversubtraction in the dark image during calibration.

  static_sig : float (Default = 4.0)

    The number of sigma below the RMS to use as the clipping limit for creating the static mask.

  editpars : bool (Default = False)

    Set to `True` if you would like to edit the parameters using the GUI interface.

  Examples

  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.

  Basic example of how to call static yourself from a python command line, using the default parameters for the task.

      >>> from drizzlepac import staticMask
      >>> staticMask.createMask('*flt.fits')

`drizzlepac.staticMask.``createStaticMask`(imageObjectList=[], configObj=None, procSteps=None)

`drizzlepac.staticMask.``getHelpAsString`(docstring=False, show_ver=True)

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

`drizzlepac.staticMask.``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.staticMask.``run`(configObj)

class `drizzlepac.staticMask.``staticMask`(configObj=None)

  This class manages the creation of the global static mask which masks pixels that are unwanted in the SCI array. A static mask object gets created for each global mask needed, one for each chip from each instrument/detector. Each static mask array has type Int16, and resides in memory.

  Notes: | Class that manages the creation of a global static mask which is used to mask pixels that are some sigma BELOW the mode computed for the image.

  `addMember`(imagePtr=None)

    Combines the input image with the static mask that has the same signature.

    Parameters:

    imagePtr : object

      An imageObject reference

    Notes

    The signature parameter consists of the tuple:

        (instrument/detector, (nx,ny), chip_id)

    The signature is defined in the image object for each chip

  `close`()

    Deletes all static mask objects.

  `deleteMask`(signature)

    Delete just the mask that matches the signature given.

  `getFilename`(signature)

    Returns the name of the output mask file that should reside on disk for the given signature.

  `getMaskArray`(signature)

    Returns the appropriate StaticMask array for the image.

  `getMaskname`(chipid)

    Construct an output filename for the given signature:

        signature=[instr+detector,(nx,ny),detnum]

    The signature is in the image object and the name of the static mask file is saved as sci_chip.outputNames[“staticMask”].

  `saveToFile`(imageObjectList)

    Saves the static mask to a file it uses the signatures associated with each mask to contruct the filename for the output mask image.