autowisp.image_calibration package — AutoWISP documentation

# autowisp.image_calibration package

## Class Inheritance Diagram

Module implementing the low-level image calibration.

class autowisp.image_calibration.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

class autowisp.image_calibration.MasterFlatMaker(*, stamp_statistics_config=None, stamp_select_config=None, large_scale_smoother=None, cloud_check_smoother=None, master_stack_config=None)

  Bases: `MasterMaker`

  Specialize MasterMaker for making master flat frames.

  stamp_statistics_config

    Dictionary configuring how stamps statistics for stamp-based selection are extracted from the frames.

  stamp_select_config

    Dictionary configuring how stamp-based selection is performed. See keyword only arguments of `configure_stamp_selection()` for details.

  large_scale_smoother

    A `autowisp.image_smoothing.ImageSmoother` instance applied to the ratio of a frame to the reference large scale structure before applying it to the frame.

  cloud_check_smoother

    `autowisp.image_smoothing.ImageSmoother` instance used for cloud detection performed on the full flat frames after smoothing to the master large scale structure.

  master_stack_config

    Dictionary configuring how to stack the individual frames into a master.

  _master_large_scale

    The large scale structure imposed on all master flats. Dictionary with keys `values`, `stdev`, `mask` and `header`. If empty dictionary, nothing is imposed.

  Examples

      >>> import scipy.ndimage.filters
      >>> from autowisp.image_smoothing import\
      >>>     PolynomialImageSmoother,\
      >>>     SplineImageSmoother,\
      >>>     ChainSmoother,\
      >>>     WrapFilterAsSmoother
      >>>
      >>> #Stamp statistics configuration:
      >>> #  * stamps span half the frame along each dimension
      >>> #  * stamps are detrended by a bi-quadratic polynomial with at most
      >>> #    one rejection iteration, discarding more than 3-sigma outliers.
      >>> #  * for each stamp a iterative rejection mean and variance are
      >>> #    calculated with up to 3 iterations rejecting three or more
      >>> #    sigma outliers.
      >>> stamp_statistics_config = dict(
      >>>     fraction=0.5,
      >>>     smoother=PolynomialImageSmoother(num_x_terms=3,
      >>>                                      num_y_terms=3,
      >>>                                      outlier_threshold=3.0,
      >>>                                      max_iterations=3),
      >>>     average='mean',
      >>>     outlier_threshold=3.0,
      >>>     max_iter=3
      >>> )
      >>>
      >>> #Stamp statistics based selection configuration:
      >>> #  * Stamps with more than 0.1% of their pixels saturated are
      >>> #    discarded
      >>> #  * if variance vs mean quadratic fit has residual of more than 5k
      >>> #    ADU^2, the entire night is considered cloudy.
      >>> #  * individual frames with stamp mean and variance deviating more
      >>> #    than 2*(fit_residual) are discarded as cloudy.
      >>> #  * high master flat will be generated from frames with stamp mean
      >>> #    > 25 kADU, and low master flat from frames with stamp mean < 15
      >>> #    kADU (intermediate frames are discarded).
      >>> stamp_select_config = dict(max_saturated_fraction=1e-4,
      >>>                            var_mean_fit_threshold=2.0,
      >>>                            var_mean_fit_iterations=2,
      >>>                            cloudy_night_threshold=5e3,
      >>>                            cloudy_frame_threshold=2.0,
      >>>                            min_high_mean=2.5e4,
      >>>                            max_low_mean=1.5e4)
      >>>
      >>> #Large scale structure smoothing configuration. For each frame, the
      >>> #large scale struture is corrected by taking the ratio of the frame
      >>> #to the reference (median of all input frames), smoothing this ratio
      >>> #and then dividing by it. The following defines how the smoothing is
      >>> #performed:
      >>> #  * shrink by a factor of 4 in each direction (16 pixels gets
      >>> #    averaged to one).
      >>> #  * Performa a box-filtering with a half-size of 6-pixels using
      >>> #    median averaging
      >>> #  * Perform a bi-cubic spline interpolation smoothing of the
      >>> #    box-filtered image.
      >>> #  * Discard more than 5-sigma outliers if any and re-smooth (no
      >>> #    further iterations allowed)
      >>> #  * Re-interpolate the image back to its original size, using
      >>> #    bicubic interpolation (see zoom_image()).
      >>> #  * The resulting image is scaled to have a mean of 1 (no
      >>> #    configuration for that).
      >>> large_scale_smoother = ChainSmoother(
      >>>     WrapFilterAsSmoother(scipy.ndimage.filters.median_filter,
      >>>                          size=12),
      >>>     SplineImageSmoother(num_x_nodes=3,
      >>>                         num_y_nodes=3,
      >>>                         outlier_threshold=5.0,
      >>>                         max_iter=1),
      >>>     bin_factor=4,
      >>>     zoom_interp_order=3
      >>> )
      >>>
      >>> #Configuration for smoothnig when checking for clouds.
      >>> #After smoothing to the master large scale structure:
      >>> #  * extract a central stamp is extracted from each flat covering
      >>> #    3/4 of the frame along each dimension
      >>> #  * shrink the fractional deviation of that stamp from the master
      >>> #    by a factor of 4 in each dimension
      >>> #  * smooth by median box-filtering with half size of 4 shrunk
      >>> #    pixels
      >>> #  * zoom the frame back out by a factor of 4 in each dimension
      >>> #    (same factor as shrinking, no separater config), using
      >>> #    bi-quadratic interpolation.
      >>> cloud_check_smoother = WrapFilterAsSmoother(
      >>>     scipy.ndimage.filters.median_filter,
      >>>     size=8,
      >>>     bin_factor=4,
      >>>     zoom_interp_order=3
      >>> )
      >>>
      >>> #When stacking masters require:
      >>> #  * At least 10 input frames for a high intensity master and at
      >>> #    least 5 for a low intensity one.
      >>> #  * When creating the stack used to match large-scale structure,
      >>> #    use median averaging with outlier rejection of more than
      >>> #    4-sigma outliers with at most one reject/re-fit iteration.
      >>> #  * When creating the final master use median averaging with
      >>> #    outlier rejection of more than 2-sigma outliers in the positive
      >>> #    and more than 3-sigma in the negative direction with at most 2
      >>> #    reject/re-fit iterations. Create the master compressed and
      >>> #    raise an exception if a file with that name already exists.
      >>> master_stack_config = dict(
      >>>     min_pointing_separation=150.0,
      >>>     large_scale_deviation_threshold=0.05,
      >>>     min_high_combine=10,
      >>>     min_low_combine=5,
      >>>     large_scale_stack_options=dict(
      >>>         outlier_threshold=4,
      >>>         average_func=numpy.nanmedian,
      >>>         min_valid_values=3,
      >>>         max_iter=1,
      >>>         exclude_mask=MasterMaker.default_exclude_mask
      >>>     ),
      >>>     master_stack_options=dict(
      >>>         outlier_threshold=(2, -3),
      >>>         average_func=numpy.nanmedian,
      >>>         min_valid_values=3,
      >>>         max_iter=2,
      >>>         exclude_mask=MasterMaker.default_exclude_mask,
      >>>         compress=True,
      >>>         allow_overwrite=False
      >>>     )
      >>> )
      >>>
      >>> #Create an object for stacking calibrated flat frames to master
      >>> #flats. In addition to the stamp-based rejections:
      >>> #  * reject flats that point within 40 arcsec of each other on the
      >>> #    sky.
      >>> #  * Require at least 10 frames to be combined into a high master
      >>> #    and at least 5 for a low master.
      >>> #  * if the smoothed cloud-check image contains pixels with absolute
      >>> #    value > 5% the frame is discarded as cloudy.
      >>> make_master_flat = MasterFlatMaker(
      >>>     stamp_statistics_config=stamp_statistics_config,
      >>>     stamp_select_config=stamp_select_config,
      >>>     large_scale_smoother=large_scale_smoother,
      >>>     cloud_check_smoother=cloud_check_smoother,
      >>>     master_stack_config=master_stack_config
      >>> )
      >>>
      >>> #Create master flat(s) from the given raw flat frames. Note that
      >>> #zero, one or two master flat frames can be created, depending on
      >>> #the input images. Assume that the raw flat frames have names like
      >>> #10-<fnum>_2.fits.fz, with fnum ranging from 1 to 30 inclusive.
      >>> make_master_flat(
      >>>     ['10-%d_2.fits.fz' % fnum for fnum in range(1, 31)],
      >>>     high_master_fname='high_master_flat.fits.fz',
      >>>     low_master_fname='low_master_flat.fits.fz'
      >>> )

  __call__(frame_list, high_master_fname, low_master_fname, *, compress=True, allow_overwrite=False, stamp_statistics_config=None, stamp_select_config=None, master_stack_config=None, custom_header=None)

    Attempt to create high & low master flat from the given frames.

    Parameters:

      - frame_list – A list of the frames to create the masters from (FITS filenames).

      - high_master_fname – The filename to save the generated high intensity master flat if one is successfully created.

      - low_master_fname – The filename to save the generated low intensity master flat if one is successfully created.

      - compress – Should the final result be compressed?

      - allow_overwrite – See same name argument to `autowisp.image_calibration.fits_util.create_result()` .

      - stamp_statistics_config (dict) – Overwrite the configuration for extracting stamp statistics for this set of frames only.

      - stamp_select_config (dict) – Overwrite the stamp selection configuration for this set of frames only.

      - master_stack_config (dict) – Overwrite the configuration for how to stack frames to a master for this set of frames only.

      - custom_header – See same name argument to `autowisp.image_calibration.master_maker.MasterMaker.__call__()` .

    Returns:

      A dictionary splitting the input list of frames into

      > high:

      >   All entries from `frame_list` which were deemed suitable for inclusion in a master high flat.

      > low:

      >   All entries from `frame_list` which were deemed suitable for inclusion in a master low flat.

      > medium:

      >   All entries from `frame_list` which were of intermediate intensity and thus not included in any master, but for which no issues were detected.

      > colocated:

      >   All entries from `frame_list` which were excluded because they were not sufficiently isolated from their closest neighbor to guarantee that stars do not overlap.

      > cloudy:

      >   All entries from `frame_list` which were flagged as cloudy either based on their stamps or on the final full-frame cloud check.

    Return type:

      dict

  __init__(*, stamp_statistics_config=None, stamp_select_config=None, large_scale_smoother=None, cloud_check_smoother=None, master_stack_config=None)

    Create object for creating master flats out of calibrated flat frames.

    Parameters:

      - stamp_statistics_config – A dictionary mith arguments to pass to `configure_stamp_statistics()`.

      - stamp_select_cofig – A dictionary with arguments to pass to `configure_stamp_selection()`.

      - large_scale_smoother – An ImageSmoother instance used when matching large scale structure of individual flats to master.

      - cloud_check_smoother – An ImageSmoother instance used when checkng the full frames for clouds (after stamps are checked).

      - master_stack_config – Configuration of how to stack frames to a master after matching their large scale structure. See example in class doc-string for details.

    Returns:

      None

  _classify_from_stamps(frame_list, stamp_statistics_config, stamp_select_config)

    Classify frames by intensity: (high/low/ntermediate), or flag as cloudy.

    Parameters:

      frame_list – The list of frames to create masters from.

    Returns:

      filename list:

        The list of high intensity non-cloudy frames.

      filename list:

        The list of low intensity non-cloudy frames.

      filename list:

        The list of medium intensity non-cloudy frames.

      filename list:

        The list of frames suspected of containing clouds in their central stamps.

    Return type:

      (tuple)

  _find_colocated(frame_list)

    Split the list of frames into well isolated ones and co-located ones.

    Parameters:

      frame_list – A list of the frames to create the masters from (FITS filenames).

    Returns:

      filename list:

        The ist of frames sufficiently far in pointing from all other frames.

      filename list:

        The list of frames which have at least one other frame too close in pointing to them.

    Return type:

      (tuple)

  _get_stamp_statistics(frame_list, **stamp_statistics_config)

    Get relevant information from the stamp of a single input flat frame.

    Parameters:

      frame_list – The list of frames for which to extract stamp statistics.

    Returns:

      An array with fields called `mean`, `variance` and `num_averaged` with the obvious meanings.

    Return type:

      numpy field array

  configure_stamp_selection(*, max_saturated_fraction=None, var_mean_fit_threshold=None, var_mean_fit_iterations=None, cloudy_night_threshold=None, cloudy_frame_threshold=None, min_high_mean=None, max_low_mean=None)

    Configure stamp-based frame selection and high/low split.

    Parameters:

      - max_saturated_fraction – The maximum fraction of stamp pixels allowed to be saturated before discarding the frame.

      - cloudy_night_threshold – The maximum residual of the variance vs mean quadratic fit before a night is declared cloudy. If None, this check is disabled.

      - cloudy_frame_threshold – The maximum deviation in units of the RMS residual of the fit an individual frame’s variance vs mean from the var(mean) quadratic fit before the frame is declared cloudy.

      - min_high_mean – The minimum mean of the stamp pixels in order to consider the frame high intensity.

      - max_low_mean – The maximum mean of the stamp pixels in order to consider the frame low intensity. Must not overlap with min_high_mean.

    Returns:

      None

  configure_stamp_statistics(*, fraction=None, smoother=None, outlier_threshold=None, max_iter=None, average=None)

    Configure extraction of stamp satistics for rejection & high/low split.

    Any arguments left as None are not updated.

    Parameters:

      - fraction – The fraction of the frame size that is included in the stamp along each dimension (i.e. fraction=0.5 means 1/4 of all frame pixels will be incruded in the stamp).

      - smoother – An ImageSmoother instance used used for de-trending the stamps before extracting statistics

      - outlier_threshold – The threshold in units of RMS deviation from the average above which pixels are considered outliers from the de-trending function and discarded from its fit.

      - max_iter – The maximum number of fit/reject iterations to perform before declaring the de-trending function final.

      - average – How to compute the average. Should be either `'mean'` or `'median'`.

    Returns:

      None

  prepare_for_stacking(image)

    Match image large scale to self._master_large_scale if not empty.

    Parameters:

      image – The image to transform large scale structure of.

    Returns:

      If `_master_large_scale` is an empty dictionary, this is just `image`. Otherwise, `image` is transformed to have the same large scale structure as `_master_large_scale`, while the small scale structure is preserved. `image` is also checked for clouds, and discarded if cloudy.

    Return type:

      2-D array

class autowisp.image_calibration.MasterMaker(*, outlier_threshold=5.0, average_func=<function nanmedian>, min_valid_frames=10, min_valid_values=5, max_iter=inf, exclude_mask=('BAD', ), compress=16, add_averaged_keywords=())

  Bases: `Processor`

  Implement the simplest & fully generalizable procedure for making a master.

  stacking_options

    A dictionary with the default configuration of how to perform the stacking. The expected keys exactly match the keyword only arguments of the `stack()` method.

  Examples

      >>> #Create an object for stacking frames to masters, overwriting the
      >>> #default outlier threshold and requiring at least 10 frames be
      >>> #stacked
      >>> make_master = MasterMaker(outlier_threshold=10.0,
      >>>                           min_valid_frames=10)
      >>>
      >>> #Stack a set of frames to a master, allowing no more than 3
      >>> #averaging/outlier rejection iterations and allowing a minimum of 3
      >>> #valid source pixels to make a master, for this master only.
      >>> make_master(
      >>>     ['f1.fits.fz', 'f2.fits.fz', 'f3.fits.fz', 'f4.fits.fz'],
      >>>     'master.fits.fz',
      >>>     max_iter=3,
      >>>     min_valid_values=3
      >>> )

  __call__(frame_list, output_fname, *, allow_overwrite=False, custom_header=None, compress=None, **stacking_options)

    Create a master by stacking the given frames.

    The header of the craeted frame contains all keywords that are common and with consistent value from the input frames. In addition the following keywords are added:

    Parameters:

      - frame_list – A list of the frames to stack (FITS filenames).

      - output_fname – The name of the output file to create. Can involve substitutions of any header keywords of the generated file.

      - compress – See `__init__()`

      - allow_overwrite – See same name argument to autowisp.image_calibration.fits_util.create_result.

      - custom_header (dict) – A collection of keywords to use in addition to/instead of what is in the input frames header.

      - stacking_options – Keyword only arguments allowing overriding the stacking configuration specified at construction for this stack only.

    Returns:

      Whether creating the master succeeded.

      [<FITS filenames>]:

        Frames which were discarded during stacking.

    Return type:

      bool

  __init__(*, outlier_threshold=5.0, average_func=<function nanmedian>, min_valid_frames=10, min_valid_values=5, max_iter=inf, exclude_mask=('BAD', ), compress=16, add_averaged_keywords=())

    Create a master maker with the given default stacking configuration.

    Keyword Arguments:

      - compress – If None or False, the final result is not compressed. Otherwise, this is the quantization level used for compressing the image (see astropy.io.fits documentation).

      - oothers (all) – See the keyword only arguments to the `stack()` method.

    Returns:

      None

  default_exclude_mask = ('BAD',)

    The default bit-mask indicating all flags which should result in a pixel being excluded from the averaging.

  prepare_for_stacking(image)

    Override with any useful pre-processing of images before stacking.

    Parameters:

      image – One of the images to include in the stack.

    Returns:

      The image to actually include in the stack. Return None if the image should be excluded.

    Return type:

      same type as image

  stack(frame_list, *, min_valid_frames, outlier_threshold, average_func, min_valid_values, max_iter, exclude_mask, add_averaged_keywords, custom_header=None)

    Create a master by stacking a list of frames.

    Parameters:

      - frame_list – The frames to stack. Should be a list of FITS filenames.

      - min_valid_frames – The smallest number of frames from which to create a master. This could be broken if either the input list is not long enough or if too many frames are discarded by `prepare_for_stacking()`.

      - outlier_threshold – See same name argument to `autowisp.iterative_rejection_util.iterative_rejection_average()` .

      - average_func – See same name argument to `autowisp.iterative_rejection_util.iterative_rejection_average()` .

      - min_valid_values – The minimum number of valid values to average for each pixel. If outlier rejection or masks results in fewer than this, the corresponding pixel gets a bad pixel mask.

      - max_iter – See same name argument to `autowisp.iterative_rejection_util.iterative_rejection_average()` .

      - exclude_mask – A bitwise or of mask flags, any of which result in the corresponding pixels being excluded from the averaging. Other mask flags in the input frames are ignored, treated as clean.

      - add_averaged_keywords – Any keywords listed will be added to the master header with a value calculated using the same averaging procedure as the image pixels.

      - custom_header – See same name argument to __call__().

    Returns:

      2-D array:

        The best estimate for the values of the maseter at each pixel. None if stacking failed.

      2-D array:

        The best estimate of the standard deviation of the master pixels. None if stacking failed.

      2-D array:

        The pixel quality mask for the master. None if stacking failed.

      fits.Header:

        The header to use for the newly created master frame. None if stacking failed.

      [<FITS filenames>]:

        List of the frames that were excluded by self.prepare_for_stacking().

    Return type:

      (tuple)

## Submodules

- autowisp.image_calibration.calibrator module
  - Class Inheritance Diagram
  - `Calibrator`
    - `Calibrator.configuration`
    - `Calibrator.master_bias`
    - `Calibrator.master_dark`
    - `Calibrator.master_flat`
    - `Calibrator.masks`
    - `Calibrator.extra_header`
    - `Calibrator.__call__()`
    - `Calibrator.__init__()`
    - `Calibrator._calib_mask_from_master()`
    - `Calibrator._document_in_header()`
    - `Calibrator._get_calibration_params()`
    - `Calibrator.check_calib_params()`
    - `Calibrator.default_configuration`
    - `Calibrator.module_git_ids`
    - `Calibrator.set_masters()`
- autowisp.image_calibration.fits_util module
  - Class Inheritance Diagram
  - `TimeISOTNoSep`
    - `TimeISOTNoSep.fast_parser_pars`
    - `TimeISOTNoSep.name`
    - `TimeISOTNoSep.subfmts`
  - `add_channel_keywords()`
  - `add_required_keywords()`
  - `assemble_channels()`
  - `create_result()`
  - `get_raw_header()`
- autowisp.image_calibration.mask_utilities module
  - Class Inheritance Diagram
    - `mask_flags`
  - `combine_masks()`
  - `get_saturation_mask()`
- autowisp.image_calibration.master_flat_maker module
  - Class Inheritance Diagram
  - `MasterFlatMaker`
    - `MasterFlatMaker.stamp_statistics_config`
    - `MasterFlatMaker.stamp_select_config`
    - `MasterFlatMaker.large_scale_smoother`
    - `MasterFlatMaker.cloud_check_smoother`
    - `MasterFlatMaker.master_stack_config`
    - `MasterFlatMaker._master_large_scale`
    - `MasterFlatMaker.__call__()`
    - `MasterFlatMaker.__init__()`
    - `MasterFlatMaker._classify_from_stamps()`
    - `MasterFlatMaker._find_colocated()`
    - `MasterFlatMaker._get_stamp_statistics()`
    - `MasterFlatMaker.configure_stamp_selection()`
    - `MasterFlatMaker.configure_stamp_statistics()`
    - `MasterFlatMaker.prepare_for_stacking()`
- autowisp.image_calibration.master_maker module
  - Class Inheritance Diagram
  - `MasterMaker`
    - `MasterMaker.stacking_options`
    - `MasterMaker.__call__()`
    - `MasterMaker.__init__()`
    - `MasterMaker.default_exclude_mask`
    - `MasterMaker.prepare_for_stacking()`
    - `MasterMaker.stack()`
- autowisp.image_calibration.overscan_methods module
  - Class Inheritance Diagram
  - `Base`
    - `Base.__call__()`
    - `Base.document_in_fits_header()`
  - `Median`
    - `Median.__call__()`
    - `Median.__init__()`
    - `Median.document_in_fits_header()`