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