Combiner

class ccdproc.Combiner(ccd_list, dtype=None)[source]

Bases: object

A class for combining CCDData objects.

The Combiner class is used to combine together CCDData objects including the method for combining the data, rejecting outlying data, and weighting used for combining frames.

Parameters:

ccd_list : list

A list of CCDData objects that will be combined together.

dtype : str or numpy.dtype or None, optional

Allows user to set dtype. See numpy.array dtype parameter description. If None it uses np.float64. Default is None.

Raises:

TypeError

If the ccd_list are not CCDData objects, have different units, or are different shapes.

Examples

The following is an example of combining together different CCDData objects:

>>> import numpy as np
>>> import astropy.units as u
>>> from astropy.nddata import CCDData
>>> from ccdproc import Combiner
>>> ccddata1 = CCDData(np.ones((4, 4)), unit=u.adu)
>>> ccddata2 = CCDData(np.zeros((4, 4)), unit=u.adu)
>>> ccddata3 = CCDData(np.ones((4, 4)), unit=u.adu)
>>> c = Combiner([ccddata1, ccddata2, ccddata3])
>>> ccdall = c.average_combine()
>>> ccdall  
CCDData([[ 0.66666667,  0.66666667,  0.66666667,  0.66666667],
         [ 0.66666667,  0.66666667,  0.66666667,  0.66666667],
         [ 0.66666667,  0.66666667,  0.66666667,  0.66666667],
         [ 0.66666667,  0.66666667,  0.66666667,  0.66666667]])

Attributes Summary

dtype
scaling Scaling factor used in combining images.
weights Weights used when combining the CCDData objects.

Methods Summary

average_combine([scale_func, scale_to, …]) Average combine together a set of arrays.
clip_extrema([nlow, nhigh]) Mask pixels using an IRAF-like minmax clipping algorithm.
median_combine([median_func, scale_to, …]) Median combine a set of arrays.
minmax_clipping([min_clip, max_clip]) Mask all pixels that are below min_clip or above max_clip.
sigma_clipping([low_thresh, high_thresh, …]) Pixels will be rejected if they have deviations greater than those set by the threshold values.
sum_combine([sum_func, scale_to, …]) Sum combine together a set of arrays.

Attributes Documentation

dtype
scaling

Scaling factor used in combining images.

Parameters:

scale : function or numpy.ndarray-like or None, optional

Images are multiplied by scaling prior to combining them. Scaling may be either a function, which will be applied to each image to determine the scaling factor, or a list or array whose length is the number of images in the Combiner.

weights

Weights used when combining the CCDData objects.

Parameters:

weight_values : numpy.ndarray or None

An array with the weight values. The dimensions should match the the dimensions of the data arrays being combined.

Methods Documentation

average_combine(scale_func=<function average>, scale_to=None, uncertainty_func=<numpy.ma.core._frommethod instance>)[source]

Average combine together a set of arrays.

A CCDData object is returned with the data property set to the average of the arrays. If the data was masked or any data have been rejected, those pixels will not be included in the average. A mask will be returned, and if a pixel has been rejected in all images, it will be masked. The uncertainty of the combined image is set by the standard deviation of the input images.

Parameters:

scale_func : function, optional

Function to calculate the average. Defaults to numpy.ma.average.

scale_to : float or None, optional

Scaling factor used in the average combined image. If given, it overrides scaling. Defaults to None.

uncertainty_func : function, optional

Function to calculate uncertainty. Defaults to numpy.ma.std.

Returns:

combined_image: CCDData

CCDData object based on the combined input of CCDData objects.

clip_extrema(nlow=0, nhigh=0)[source]

Mask pixels using an IRAF-like minmax clipping algorithm. The algorithm will mask the lowest nlow values and the highest nhigh values before combining the values to make up a single pixel in the resulting image. For example, the image will be a combination of Nimages-nlow-nhigh pixel values instead of the combination of Nimages.

Parameters:

nlow : int or None, optional

If not None, the number of low values to reject from the combination. Default is 0.

nhigh : int or None, optional

If not None, the number of high values to reject from the combination. Default is 0.

Notes

Note that this differs slightly from the nominal IRAF imcombine behavior when other masks are in use. For example, if nhigh>=1 and any pixel is already masked for some other reason, then this algorithm will count the masking of that pixel toward the count of nhigh masked pixels.

Here is a copy of the relevant IRAF help text [R1]:

nlow = 1, nhigh = (minmax)
The number of low and high pixels to be rejected by the “minmax” algorithm. These numbers are converted to fractions of the total number of input images so that if no rejections have taken place the specified number of pixels are rejected while if pixels have been rejected by masking, thresholding, or nonoverlap, then the fraction of the remaining pixels, truncated to an integer, is used.

References

[R1](1, 2) image.imcombine help text. http://stsdas.stsci.edu/cgi-bin/gethelp.cgi?imcombine
median_combine(median_func=<function median>, scale_to=None, uncertainty_func=<function sigma_func>)[source]

Median combine a set of arrays.

A CCDData object is returned with the data property set to the median of the arrays. If the data was masked or any data have been rejected, those pixels will not be included in the median. A mask will be returned, and if a pixel has been rejected in all images, it will be masked. The uncertainty of the combined image is set by 1.4826 times the median absolute deviation of all input images.

Parameters:

median_func : function, optional

Function that calculates median of a numpy.ma.MaskedArray. Default is numpy.ma.median.

scale_to : float or None, optional

Scaling factor used in the average combined image. If given, it overrides scaling. Defaults to None.

uncertainty_func : function, optional

Function to calculate uncertainty. Defaults is sigma_func.

Returns:

combined_image: CCDData

CCDData object based on the combined input of CCDData objects.

Warning

The uncertainty currently calculated using the median absolute deviation does not account for rejected pixels.

minmax_clipping(min_clip=None, max_clip=None)[source]

Mask all pixels that are below min_clip or above max_clip.

Parameters:

min_clip : float or None, optional

If not None, all pixels with values below min_clip will be masked. Default is None.

max_clip : float or None, optional

If not None, all pixels with values above min_clip will be masked. Default is None.

sigma_clipping(low_thresh=3, high_thresh=3, func=<numpy.ma.core._frommethod instance>, dev_func=<numpy.ma.core._frommethod instance>)[source]

Pixels will be rejected if they have deviations greater than those set by the threshold values. The algorithm will first calculated a baseline value using the function specified in func and deviation based on dev_func and the input data array. Any pixel with a deviation from the baseline value greater than that set by high_thresh or lower than that set by low_thresh will be rejected.

Parameters:

low_thresh : positive float or None, optional

Threshold for rejecting pixels that deviate below the baseline value. If negative value, then will be convert to a positive value. If None, no rejection will be done based on low_thresh. Default is 3.

high_thresh : positive float or None, optional

Threshold for rejecting pixels that deviate above the baseline value. If None, no rejection will be done based on high_thresh. Default is 3.

func : function, optional

Function for calculating the baseline values (i.e. numpy.ma.mean or numpy.ma.median). This should be a function that can handle numpy.ma.MaskedArray objects. Default is numpy.ma.mean.

dev_func : function, optional

Function for calculating the deviation from the baseline value (i.e. numpy.ma.std). This should be a function that can handle numpy.ma.MaskedArray objects. Default is numpy.ma.std.

sum_combine(sum_func=<numpy.ma.core._frommethod instance>, scale_to=None, uncertainty_func=<numpy.ma.core._frommethod instance>)[source]

Sum combine together a set of arrays.

A CCDData object is returned with the data property set to the sum of the arrays. If the data was masked or any data have been rejected, those pixels will not be included in the sum. A mask will be returned, and if a pixel has been rejected in all images, it will be masked. The uncertainty of the combined image is set by the multiplication of summation of standard deviation of the input by square root of number of images. Because sum_combine returns ‘pure sum’ with masked pixels ignored, if re-scaled sum is needed, average_combine have to be used with multiplication by number of images combined.

Parameters:

sum_func : function, optional

Function to calculate the sum. Defaults to numpy.ma.sum.

scale_to : float or None, optional

Scaling factor used in the sum combined image. If given, it overrides scaling. Defaults to None.

uncertainty_func : function, optional

Function to calculate uncertainty. Defaults to numpy.ma.std.

Returns:

combined_image: CCDData

CCDData object based on the combined input of CCDData objects.