skymatch

The skymatch function performs the actual sky matching operations on the input image data models.

A module that provides functions for matching sky in overlapping images.

romancal.skymatch.skymatch.match(images, skymethod='global+match', match_down=True, subtract=False)

A function to compute and/or “equalize” sky background in input images.

Note

Sky matching (“equalization”) is possible only for overlapping images.

Parameters:

• images (list of SkyImage or SkyGroup) – A list of SkyImage or SkyGroup objects.

• skymethod ({'local', 'global+match', 'global', 'match'}, optional) –

  Select the algorithm for sky computation:

  • ’local’ : compute sky background values of each input image or group of images (members of the same “exposure”). A single sky value is computed for each group of images.

    Note

    This setting is recommended when regions of overlap between images are dominated by “pure” sky (as opposed to extended, diffuse sources).

  • ’global’ : compute a common sky value for all input images and groups of images. With this setting local will compute sky values for each input image/group, find the minimum sky value, and then it will set (and/or subtract) the sky value of each input image to this minimum value. This method may be useful when the input images have been already matched.

  • ’match’ : compute differences in sky values between images and/or groups in (pair-wise) common sky regions. In this case the computed sky values will be relative (delta) to the sky computed in one of the input images whose sky value will be set to (reported to be) 0. This setting will “equalize” sky values between the images in large mosaics. However, this method is not recommended when used in conjunction with astrodrizzle because it computes relative sky values while astrodrizzle needs “absolute” sky values for median image generation and CR rejection.

  • ’global+match’ : first use the ‘match’ method to equalize sky values between images and then find a minimum “global” sky value amongst all input images.

    Note

    This is the recommended setting for images containing diffuse sources (e.g., galaxies, nebulae) covering significant parts of the image.

• match_down (bool, optional) –

  Specifies whether the sky differences should be subtracted from images with higher sky values (match_down = True) to match the image with the lowest sky or sky differences should be added to the images with lower sky values to match the sky of the image with the highest sky value (match_down = False).

  Note

  This setting applies only when the skymethod parameter is either 'match' or 'global+match'.

• subtract (bool (Default = False)) – Subtract computed sky value from image data.

Raises:

TypeError – The images argument must be a Python list of SkyImage and/or SkyGroup objects.

Notes

match() provides new algorithms for sky value computations and enhances previously available algorithms used by, e.g., astrodrizzle.

Two new methods of sky subtraction have been introduced (compared to the standard 'local'): 'global' and 'match', as well as a combination of the two – 'global+match'.

• The 'global' method computes the minimum sky value across all input images and/or groups. That sky value is then considered to be the background in all input images.

• The 'match' algorithm is somewhat similar to the traditional sky subtraction method (skymethod = 'local') in the sense that it measures the sky independently in input images (or groups). The major differences are that, unlike the traditional method,

  1. 'match' algorithm computes relative (delta) sky values with regard to the sky in a reference image chosen from the input list of images; and

  2. Sky statistics are computed only in the part of the image that intersects other images.

  This makes the 'match' sky computation algorithm particularly useful for “equalizing” sky values in large mosaics in which one may have only (at least) pair-wise intersection of images without having a common intersection region (on the sky) in all images.

  The 'match' method works in the following way: for each pair of intersecting images, an equation is written that requires that average surface brightness in the overlapping part of the sky be equal in both images. The final system of equations is then solved for unknown background levels.

  Warning

  The current algorithm is not capable of detecting cases where some subsets of intersecting images (from the input list of images) do not intersect at all with other subsets of intersecting images (except for the simple case when single images do not intersect any other images). In these cases the algorithm will find equalizing sky values for each intersecting subset of images and/or groups of images. However since these subsets of images do not intersect each other, sky will be matched only within each subset and the “inter-subset” sky mismatch could be significant.

  Users are responsible for detecting such cases and adjusting processing accordingly.

• The 'global+match' algorithm combines the 'match' and 'global' methods in order to overcome the limitation of the 'match' method described in the note above: it uses the 'global' algorithm to find a baseline sky value common to all input images and the 'match' algorithm to “equalize” sky values in the mosaic. Thus, the sky value of the “reference” image will be equal to the baseline sky value (instead of 0 in 'match' algorithm alone).

Remarks:

• match() works directly on geometrically distorted flat-fielded images thus avoiding the need to perform distortion correction on the input images.

  Initially, the footprint of a chip in an image is approximated by a 2D planar rectangle representing the borders of chip’s distorted image. After applying distortion model to this rectangle and projecting it onto the celestial sphere, it is approximated by spherical polygons. Footprints of exposures and mosaics are computed as unions of such spherical polygons while overlaps of image pairs are found by intersecting these spherical polygons.

Limitations and Discussions:

Primary reason for introducing “sky match” algorithm was to try to equalize the sky in large mosaics in which computation of the “absolute” sky is difficult due to the presence of large diffuse sources in the image. As discussed above, match() accomplishes this by comparing “sky values” in a pair of images in the overlap region (that is common to both images). Quite obviously the quality of sky “matching” will depend on how well these “sky values” can be estimated. We use quotation marks around sky values because for some image “true” background may not be present at all and the measured sky may be the surface brightness of large galaxy, nebula, etc.

In the discussion below we will refer to parameter names in SkyStats and these parameter names may differ from the parameters of the actual skystat object passed to initializer of the SkyImage.

Here is a brief list of possible limitations/factors that can affect the outcome of the matching (sky subtraction in general) algorithm:

• Since sky subtraction is performed on flat-fielded but not distortion corrected images, it is important to keep in mind that flat-fielding is performed to obtain uniform surface brightness and not flux. This distinction is important for images that have not been distortion corrected. As a consequence, it is advisable that point-like sources be masked through the user-supplied mask files. Values different from zero in user-supplied masks indicate “good” data pixels. Alternatively, one can use upper parameter to limit the use of bright objects in sky computations.

• Normally, distorted flat-fielded images contain cosmic rays. This algorithm does not perform CR cleaning. A possible way of minimizing the effect of the cosmic rays on sky computations is to use clipping (nclip > 0) and/or set upper parameter to a value larger than most of the sky background (or extended source) but lower than the values of most CR pixels.

• In general, clipping is a good way of eliminating “bad” pixels: pixels affected by CR, hot/dead pixels, etc. However, for images with complicated backgrounds (extended galaxies, nebulae, etc.), affected by CR and noise, clipping process may mask different pixels in different images. If variations in the background are too strong, clipping may converge to different sky values in different images even when factoring in the “true” difference in the sky background between the two images.

• In general images can have different “true” background values (we could measure it if images were not affected by large diffuse sources). However, arguments such as lower and upper will apply to all images regardless of the intrinsic differences in sky levels.