crnebula: Detect and replace cosmic rays in nebular data

Package: crutil

Usage

crnebula input output

Parameters

input

Input image in which cosmic rays are to be detected.

output

Output image in which cosmic rays are to be replaced by the median. If no output image is given (specified as "") then no output image is created.

crmask = ""

Output cosmic ray mask identifying the cosmic rays found. The mask will have values of one for cosmic rays and zero for non-cosmic rays. If no output cosmic ray mask is given (specified as "") then no mask is created.

residual = ""

Output residual image. This is the input image minus the median filtered image divided by the estimated sigma at each pixel. Thresholds in this image determine the cosmic rays detected. If no image name is given then no output will be created.

rmedresid = ""

Output image for the difference between the box median filter image and the ring median filtered image divided by the estimated sigma at each pixel. If no image name is given then no output will be created.

var0 = 0., var1 = 0., var2 = 0.

Variance coefficients for the variance model. The variance model is

variance = var0 + var1 * data + var2 * data^2

where data is the maximum of zero and median pixel value and the variance is in data numbers. All the coefficients must be positive or zero. If they are all zero then empirical data sigmas are estimated by a percentile method in boxes of size given by ncsig and nlsig.

sigmed = 3.

Sigma clipping factor for the residual image.

sigdiff = 3.

Sigma clipping factor for the residuals between the box median and ring median filtered images.

mbox = 5

Box size, in pixels, for the box median filtering.

rin = 1.5, rout = 6.

Inner and outer radii, in pixels, for the ring median filtering.

verbose = no

Print some progress information?

Description

This task uses a combination of box median filtering to detect cosmic rays and the difference between box and ring median filtering to identify regions of fine nebular structure which should not be treated as cosmic rays. The output consists of some set of the input image with cosmic rays replaced by the median, a cosmic ray mask, the residual image used to detect the cosmic rays, and the residual image used to exclude cosmic rays in regions of nebular fine structure. The cosmic ray mask may be used later with crgrow and crfix to grow and remove the cosmic rays from the data by interpolation rather than the median.

The algorithm is as follows. The input image is median filtered using a box of size given by mbox. The residual image between the unfiltered and filter data is computed. The residuals are divided by the estimated sigma of the pixel. Cosmic rays are those which are more than sigmed above zero in the residual image. This residual image may be output if an output name is specified. This part of the algorithm is identical to that of the task crmedian and, in fact, that task is used.

The median image not only enhances cosmic rays it also enhances narrow fine structure in the input image. To avoid identifying this structure as cosmic rays a second filtered residual image is created which preferentially identifies this structure over the cosmic rays. The input image is filtered using a ring median of specified inner and outer radius. The inner radius is slightly larger than the scale of the cosmic rays and the outer radius is comparable to the box size of the box median filter. A ring filter replaces the center of the ring by the median of the ring. The difference between the input and ring median filtered image divided by the estimated sigma will then be very similar to the box median residual image both where there are cosmic rays and where there is diffuse structure but will be different where there are linear fine structure patterns. The difference between the median residual image and this ring median residual image highlights the regions of fine structure. If a image name is specified for the difference of the residual images it will be output.

The difference of the median residual images is used to exclude any cosmic ray candidate pixels determined from sigma clipping the box median residual image which lie where the difference of the median residual images is greater than sigdiff different from zero (both positive or negative).

To understand this algorithm it is recommended that the user save the residual and residual difference images and display them and blink against the original data.

Examples

This example, the same as in crmedian, illustrates using the crnebual task to give a cosmic ray removed image and examining the results with an image display. The image is a CCD image with a readout noise of 5 electrons and a gain of 3 electrons per data number. This implies variance model coefficients of

var0 = (5/3)^2 = 2.78
var1 = 1/3 = 0.34

cl> display obj001 1                  # Display in first frame
cl> # Determine output image, cosmic ray mask, and residual images
cl> crnebula obj001 crobj001 crmask=mask001 resid=res001\
>>> rmedresid=rmed001 var0=2.78 var1=0.34
cl> display crobj001 2                # Display final image
cl> display res001 3 zs- zr- z1=-5 z2=5  # Display residuals
cl> display rmed001 4 zs- zr- z1=-5 z2=5

By looking at the residual image the sigma clippig threshold can be adjusted and the noise parameters can be tweaked to minimize clipping of real extended structure.

See also

cosmicrays, crmedian, median, rmedian, crfix, crgrow