autowisp.image_calibration.calibrator module — AutoWISP documentation

# autowisp.image_calibration.calibrator module

## Class Inheritance Diagram

Define a class (Calibrator) for low-level image calibration.

class autowisp.image_calibration.calibrator.Calibrator(*, saturation_threshold, **configuration)

  Bases: `Processor`

  Provide basic calibration operations (bias/dark/flat) fully tracking noise.

  Public attributes, set through `__init__()`, provide defaults for calibration parameters that can be overwritten on a one-time basis for each frame being calibrated by passing arguments to `__call__()`.

  configuration

    Defines the following calibration parameters:

    raw_hdu: Which hdu of the raw frame contains the image to

      calibrate. If a single number, the channels are assumed staggeder in that image. Otherwise, should be be a dictionary indexed by channel name specifying the header of each color channel. Note that the header is always taken from the first non-trivial hdu. For compressed frames, this should never be zero.

    split_channels: If this is a color image (i.e. staggering 4 color

      channels), this argument should be a dictionary with keys the names to use for the color channels and values specifying slices in the image that isolate the pixels of each channel. If single color images it should be `{None: slice(None)}`.

    saturation_threshold: The value (in ADU) above which the pixel is

      considered saturated.

    overscan: A dictionary containing:

    > - areas: The areas in the raw image to use for overscan corrections. The format is:

    >       [
    >           dict(xmin = <int>,
    >                xmax = <int>,
    >                ymin = <int>,
    >                ymax = <int>),
    >           ...
    >       ]

    > - method: See `overscan_methods.Base`

    image_area: The area in the raw image which actually contains the

      useful image of the night sky. The dimensions must match the dimensions of the masters to apply an of the overscan correction retured by overscan_method. The format is:

          dict(xmin = <int>, xmax = <int>, ymin = <int>, ymax = <int>)

    gain: The gain to assume for the input image (electrons/ADU).

      Only useful when estimating errors and could be used by the overscan_method.

    calibrated_fname: The filename under which to save the craeted

      image. Treated as a format string that may involve replacement fields from the resulting header, including {CLRCHNL}, which gets replaced by the color channel if channel splitting is performed, as well as {RAWFNAME}, which gets replaced by the file name of the input FITS file with all directories and .fits or .fits.fz extension stripped and {FNUM} which gets replaced by the frame number (see above).

  master_bias

    A dictionary indexed by channel with each entry being further dictionary containing:

    - filenames: Dictionary indexed by color channel of the filename of the master bias frame to use in subsequent calibrations (if not overwritten).

    - correction: The correction to apply (if not overwritten) constructed by combining the master biases for each channel.

    - variance: An estimate of the variance of the `correction` entry.

    - mask: The bitmask the pixel indicating the combination of flags raised for each pixel. The individual flages are defined by `mask_utilities.mask_flags`.

  master_dark

    Analogous to `master_bias` but contaning the information about the default master dark.

  master_flat

    Analogous to `master_bias` but contaning the information about the default master flat.

  masks

    A dictionary containing:

    - filenames: Dictionary indexed by channel containing a list of the files from which this mask was constructed.

    - image: The combined mask image (bitwise OR) of all masks in `filenames`.

  extra_header

    Additional keywords to add to the header.

  Examples

      >>> from autowisp.image_calibration import Calibrator,\
      >>>     overscan_methods
      >>>
      >>> #Create a calibrator callable instance
      >>> calibrate = Calibrator(
      >>>     #The first 20 lines of the image are overscan area and overscan
      >>>     #is applied by subtracting the median of all pixels in the
      >>>     #overscan area from the remaining image.
      >>>     overscans=dict(areas=[dict(xmin=0, xmax=4096, ymin=0, ymax=20)],
      >>>                    method=overscan_methods.Median())
      >>>
      >>>     #The master bias frame to use.
      >>>     master_bias='masters/master_bias1.fits',
      >>>
      >>>     #The gain (electrons/ADU) to assume for the input images.
      >>>     gain=16.0,
      >>>
      >>>     #The area within the raw frame containing the image:
      >>>     image_area=dict(xmin=0, xmax=4096, ymin=20, ymax=4116)
      >>> )
      >>>
      >>> #Specify a master dark after construction.
      >>> calibrate.set_masters(dark='masters/master_dark3.fits')
      >>>
      >>> #Calibrate an image called 'raw1.fits', producing (or overwriting a
      >>> #calibrated file called 'calib1.fits' using the previously specified
      >>> #calibration parameters. Note that no flat correction is going to be
      >>> #applied, since a master flat was never specified.
      >>> calibrate(raw='raw1.fits', calibrated='calib1.fits')
      >>>
      >>> #Calibrate an image, changing the gain assumed for this image only
      >>> #and disabling overscan correction for this image only.
      >>> calibrate(raw='raw2.fits',
      >>>           calibrated='calib2.fits',
      >>>           gain=8.0,
      >>>           overscans=None)

  __call__(raw, **calibration_params)

    Calibrate the raw frame, save result to calibrated.

    Parameters:

      - raw – The filename of the raw frame to calibrate.

      - calibration_params – Keyword only arguments allowing one of the calibration parameters to be switched for this calibration only.

    Returns:

      None

  __init__(*, saturation_threshold, **configuration)

    Create a calibrator and define some default calibration parameters.

    Parameters:

      - default (Any configuration parameters users wish to change from their)

      - values (see class description for details)

      - masters – See set_masters.

    Returns:

      None

  static _calib_mask_from_master(mask)

    Overwrite a master mask with what should be used for a calibrated frame.

    Parameters:

      mask – The mask of the master frame. On exit, gets overwritten by the mask with which the calibrated image mask should be combined to account for imperfections in the master.

    Returns:

      None

  static _document_in_header(calibration_params, header)

    Return header(s) documenting how the calibration was done.

    The following keywords are added or overwritten:

        MBIASFNM: Filename of the master bias used

        MBIASSHA: Sha-1 checksum of the master bias frame used.

        MDARKFNM: Filename of the master dark used

        MDARKSHA: Sha-1 checksum of the master dark frame used.

        MFLATFNM: Filename of the master flat used

        MFLATSHA: Sha-1 checksum of the master flat frame used.

        OVRSCN%02d: The overscan regions get consecutive IDs and for
            each one, the id gets substituted in the keyword as given.
            The value describes the overscan region like:
            %(xmin)d < x < %(xmax)d, %(ymin)d < y < %(ymax)d with the
            sibustition dictionary given directly by the corresponding
            overscan area.

        IMAGAREA: '%(xmin)d < x < %(xmax)d, %(ymin)d < y < %(ymax)d'
            subsituted with the image are as specified during
            calibration.

        CALBGAIN: The gain assumed during calibration.

        CLIBSHA: Sha-1 chacksum of the Calibrator.py blob per Git.

    In addition, the overscan method describes itself in the header in any way it sees fit.

    Parameters:

      - calibration_params – The parameters used when calibrating (see calibration_params argument to `__call__()`.

      - header – The header to update with the calibration information. Must already have the `CLRCHNL` keyword defined.

    Returns:

      Indexed by channel name the header to use for the

        calibrated image.

    Return type:

      dict

  _get_calibration_params(overwrite_params, raw_image)

    Set all calibration parameters following overwrite rules.

  static check_calib_params(raw_image, calib_params)

    Check if calibration parameters are consistent mutually and with image.

    Raises an exception if some problem is detected.

    Parameters:

      - raw_image – The raw image to calibrate (numpy 2-D array).

      - calib_params – The current set of calibration parameters to apply.

    Returns:

      None

    Notes

    Checks for:

      - Overscan or image areas outside the image.

      - Any master resolution does not match image area for corresponding channel.

      - Image or overscan areas have inverted boundaries, e.g. xmin > xmax

      - gain is not a finite positive number

      - leak_directions is not an iterable of 2-element iterables

  default_configuration = {'allow_overwrite': False, 'bias_level_adu': 0.0, 'compress_calibrated': 16, 'gain': 1.0, 'image_area': None, 'leak_directions': [], 'overscans': {'areas': None, 'method': None}, 'split_channels': False}
  module_git_ids = {'calibrator': '$Id: 577de2417317dd1d26c623e59f8474f0efd50369 $', 'mask_utilities': '$Id: 5b6835e1bfd0bec642536c00517b8d088d1f5d28 $', 'overscan_methods': '$Id: 4aad389e1ad0897f0fa4ec0744ba76050d01fe00 $'}

    A collection of Git Id values (sha1 checksums of the git blobs) for each module used by the calibration. Those get added to the header to ensure reprobducability.

  set_masters(*, bias=None, dark=None, flat=None, masks=None)

    Define the default masterts to use for calibrations.

    The cannels and image area must be correctly set by __init__.

    Parameters:

      - bias – The filename of the master bias to use. String if single channel processing, dictionary indexed by channel if multi-channel.

      - dark – The filename of the master dark to use. See bias.

      - flat – The filename of the master flat to use. See bias.

      - masks – Either a single filename or a list of the mask files to use. See bias.

    Returns:

      None