## NAME

crnebula -- create a cosmic ray mask from nebular images

## 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.

- var= 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 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