NAME

illumination -- Determine illumination calibrations

USAGE

illumination images illuminations

PARAMETERS

images

Images to use in determining illumination calibrations. These are generally sky spectra. An image section may be used to select only a portion of the image.

illuminations

Illumination calibration images to be created. Each illumination image is paired with a calibration image. If the image exists then it will be modified otherwise it is created.

interactive = yes

Graph the average spectrum and select the dispersion bins and graph and fit the slit profile for each dispersion bin interactively?

bins = ""

Range string defining the dispersions bins within which the slit profiles are determined. If the range string is null then the dispersion bins are determined by the parameter nbins .

nbins = 5

If the dispersion bins are not specified explicitly by the parameter bins then the dispersion range is divided into this number of nearly equal bins.

sample = "*"

Sample of points to use in fitting each slit profile. The sample is selected with a range string.

naverage = 1

Number of sample points to average or median before fitting a function. If the number is positive the average of each set of naverage sample points is formed while if the number is negative then the median of each set of points (in absolute value) is formed. This subsample of points is used in fitting the slit profile.

function = "spline3"

Function to fit to each dispersion bin to form the illumination function. The options are "spline1", "spline3", "legendre", and "chebyshev".

order = 1

Order of the fitting function or the number of spline pieces.

low_reject = 0., high_reject = 0.

Rejection limits below and above the fit in units of the residual sigma.

niterate = 1

Number of rejection iterations.

grow = 0

Reject additional points within this distance of points exceeding the rejection threshold.

interpolator = "poly3"

Interpolation type. One of "nearest", "linear", "poly3", "poly5", or "spline3".

graphics = "stdgraph"

Graphics output device. May be one of the standard devices "stdgraph", "stdplot", or "stdvdm" or an explict device.

cursor = ""

Graphics input device. May be either null for the standard graphics cursor or a file containing cursor commands.

CURSOR KEYS

The interactive curve fitting package icfit is used to fit a function to the average calibration spectrum. Additional help on using this package and the cursor keys is available under the name "icfit".

When the dispersion bins are set graphically the following cursor keys are defined.

?

Clear the screen and print a menu of the cursor options.

i

Initialize the sample ranges.

q

Exit interactive dispersion bin selection.

s

Set a bin with the cursor. This may be repeated any number of times. Two keystrokes are required to mark the two ends of the bin.

The parameters are listed or set with the following commands which may be abbreviated. To list the value of a parameter type the command alone.

:bins value		Illumination bins
:show			Show the values of all the parameters

DESCRIPTION

An illumination calibration, in the form of an image, is created for each longslit calibration image, normally a sky spectrum. The illumination calibration is determined by fitting functions across the slit (the slit profiles) at a number of points along the dispersion, normalizing each fitted function to unity at the center of the slit, and interpolating the illumination between the dispersion points. The fitted data is formed by dividing the dispersion points into a set of bins and averaging the slit profiles within each bin. The interpolation type is a user parameter.

The image header keyword DISPAXIS must be present with a value of 1 for dispersion parallel to the lines (varying with the column coordinate) or 2 for dispersion parallel to the columns (varying with line coordinate). This parameter may be added using hedit . Note that if the image has been transposed (imtranspose ) the dispersion axis should still refer to the original dispersion axis unless the physical world coordinate system is first reset (see wcsreset ). This is done in order to allow images which have DISPAXIS defined prior to transposing to still work correctly without requiring this keyword to be changed.

If the output image does not exist it is first created with unit illumination everywhere. Subsequently the illumination is only modified in those regions occupied by the input image. Thus, an image section in the input image may be used to select the data to be used and for which an illumination calibration will be determined. This ability is particularly userful when dealing with multiple slits or to exclude regions outside the slit.

The dispersion bins may be selected by a range string (bins ) or, if no range string is given, by the number of bins into which the dispersion range is to be divided (nbins ). When the interactive parameter is set (interactive ) then the average spectrum is graphed and the bins may be set using the cursor or with a colon command. Once the bins have been selected exit with (q)uit to continue to the slit profile fitting.

Fitting of the slit profiles is done using the interactive curve fitting package (icfit ). The parameters determining the fit are the sample points, the averaging bin size, the fitting function, the order of the function, the rejection sigmas, the number of rejection iterations, and the rejection width. The sample points for the average slit profile are selected by a range string. Points in the slit profile not in the sample are not used in determining the fitted function. The selected sample points may be binned into a set of averages or medians which are used in the function fit instead of the sample points with the averaging bin size parameter naverage . This parameter selects the number of sample points to be averaged if its value is positive or the number of points to be medianed if its value is negative (naturally, the absolute value is used for the number of points). A value of one uses all sample points without binning. The fitted function may be used to reject points from the fit using the parameters low_reject, high_reject, niterate and grow . If one or both of the rejection limits are greater than zero then the sigma of the residuals is computed and points with residuals less than -low_reject times the sigma and greater than high_reject times the sigma are removed and the function fitted again. In addition points within a distance given by the parameter grow of the a rejected point are also rejected. A value of zero for this parameter rejects only the points exceeding the rejection threshold. Finally, the rejection procedure may be iterated the number of times given by the parameter niterate .

The fitted functions may be examined and modified interactively when the parameter interactive is set. The user is asked before each dispersion bin whether to perform the fit interactively. The possible response are "no", "yes", "NO", and "YES". The lower case responses only affect the specified dispersion bin while the upper case responses affect all following dispersion bins for the current image. Thus, if the response is "NO" then no further prompts or interactive curve fitting need be performed while if the response is "YES" there are no further prompts but the slit profile for each dispersion bin must be graphed and exited with (q)uit. Changes to the fitting parameters remain in effect until they are next changed. This allows the fitting parameters to be selected from only the first dispersion bin without requiring each dispersion bin to be graphed and confirmed.

When a dispersion bin is to be fitted interactively the average slit profile and the fitted function or the residuals of the fit are graphed. Deleted points are marked with an x and rejected points by a diamond. The sample regions are indicated along the bottom of the graph. The cursor keys and colon commands are used to change the values of the fitting parameters, delete points, and window and expand the graph. When the fitted function is satisfactory exit with with a carriage return or q. The prompt for the next dispersion bin will then be given until the last dispersion bin has been fit. The illumination calibration image is then created.

EXAMPLES

1. To create an illumination image non-interactively:

	cl> illumination sky illum nbins=8 order=20 interactive=no

2. To determine independent illuminations for a multislit image determine the image sections defining each slit. Then the illumination functions are computed as follows:

	cl> illlumination sky[10:20,*],sky[35:45,*] illum,illum

3. Generally the slit image sections are prepared in a file which is then used to define the lists of input images and illuminations.

	cl> illumination @slits @illums

3. If the DISPAXIS keyword is missing and the dispersion is running vertically (varying with the image lines):

	cl> hedit *.imh dispaxis 2 add+

SEE ALSO

icfit, response