IRAF help page for package noao.imred.kpnocoude, program do3fiber

Aperture Definitions

The first operation is to define the extraction apertures, which include the aperture width and position dependence with wavelength, for the object and arc fibers. This is done on a reference spectrum which is usually a flat field taken through both fibers. Other spectra will inherit the reference apertures and may apply a correction for any shift of the orders across the dispersion. The reference apertures are defined only once unless the redo option is set.

The selected number of fibers are found automatically by selecting the highest peaks in a cut across the dispersion. Apertures are assigned with a limits set by the lower and upper parameter and numbered sequentially. A query is then given allowing the apertures to be reviewed interactively. If answered affirmatively a cut across the orders is shown with the apertures marked and an interactive aperture editing mode is entered (see apedit). The main thing to be concerned about is that the aperture numbers agree with the objaps and arcaps definitions. The aperture numbers may be changed with the 'i' or 'o' keys. The apertures may also be resized from the default limits. To exit the background and aperture editing steps type 'q'.

Next the positions of the fiber profiles at various points along the dispersion are measured and a "trace function" is fit. The user is asked whether to fit the trace function interactively. This is selected to adjust the fitting parameters such as function type and order. When interactively fitting a query is given for each aperture. After the first aperture one may skip reviewing the other traces by responding with "NO". Queries made by do3fiber generally may be answered with either lower case "yes" or "no" or with upper case "YES" or "NO". The upper case responses apply to all further queries and so are used to eliminate further queries of that kind.

The above steps are all performed using tasks from the apextract package and parameters from the params parameters. As a quick summary, the dispersion direction of the spectra are determined from the package dispaxis parameter if not defined in the image header. The default line or column for finding the orders and the number of image lines or columns to sum are set by the line and nsum parameters. A line of INDEF (the default) selects the middle of the image. The automatic finding algorithm is described for the task apfind and basically finds the strongest peaks. The tracing is done as described in aptrace and consists of stepping along the image using the specified t_step parameter. The function fitting uses the icfit commands with the other parameters from the tracing section.

Extraction

The actual extraction of the spectra is done by summing across the fixed width apertures at each point along the dispersion. The default is to simply sum the pixels using partial pixels at the ends. There is an option to weight the sum based on a Poisson noise model using the readnoise and gain detector parameters. Note that if the clean option is selected the variance weighted extraction is used regardless of the weights parameter. The sigma thresholds for cleaning are also set in the params parameters.

The cleaning and variance weighting options require knowing the effective (i.e. accounting for any image combining) read out noise and gain. These numbers need to be adjusted if the image has been processed such that the intensity scale has a different origin (such as a background light subtraction) or scaling (such as caused by unnormalized flat fielding). For optimal extraction and cleaning to work it is recommended that a datamax value be determined for the data and the fitflat option be used. For further discussion of cleaning and variance weighted extraction see apvariance and approfiles as well as apsum.

Scattered Light Subtraction

Scattered light may be subtracted from the input two dimensional image as the first step. This is done using the algorithm described in apscatter. This can be important if there is significant scattered light since the flat field/throughput correction will otherwise be incorrect. The algorithm consists of fitting a function to the data outside the defined apertures by a specified buffer at each line or column across the dispersion. The function fitting parameters are the same at each line. Because the fitted functions are independent at each line or column a second set of one dimensional functions are fit parallel to the dispersion using the evaluated fit values from the cross-dispersion step. This produces a smooth scattered light surface which is finally subtracted from the input image. Again the function fitting parameters are the same at each line or column though they may be different than the parameters used to fit across the dispersion.

The first time the task is run with a particular flat field (or aperture reference image if no flat field is used) the scattered light fitting parameters are set interactively using that image. The interactive step selects a particular line or column upon which the fitting is done interactively with the icfit commands. A query is first issued which allows skipping this interactive stage. Note that the interactive fitting is only for defining the fitting functions and orders. When the graphical icfit fitting is exited (with 'q') there is a second prompt allowing you to change the buffer distance (in the first cross-dispersion stage) from the apertures, change the line/column, or finally quit.

The initial fitting parameters and the final set parameters are recorded in the apscat1 and apscat2 hidden parameter sets. These parameters are then used automatically for every subsequent image which is scattered light corrected.

The scattered light subtraction modifies the input 2D images. To preserve the original data a copy of the original image is made with the same root name and the word "noscat" appended. The scattered light subtracted images will have the header keyword "APSCATTE" which is how the task avoids repeating the scattered light subtraction during any reprocessing. However if the redo option is selected the scattered light subtraction will also be redone by first restoring the "noscat" images to the original input names.

Flat Field Correction

Flat field corrections may be made during the basic CCD processing; i.e. direct division by the two dimensional flat field observation. In that case do not specify a flat field spectrum; use the null string "". The do3fiber task provides an alternative flat field response correction based on division of the extracted object spectra by the extracted flat field spectra. A discussion of the theory and merits of flat fielding directly verses using the extracted spectra will not be made here. The do3fiber flat fielding algorithm is the recommended method for flat fielding since it works well and is not subject to the many problems involved in two dimensional flat fielding.

The first step is extraction of the flat field spectrum, if specified, using the reference apertures. Only one flat field is allowed so if multiple flat fields are required the data must be reduced in groups. If the fitflat option is selected (the default) the extracted flat field spectra are averaged together and a smooth function is fit. The default fitting function and order are given by the parameters f_function and f_order. If the parameter f_interactive is "yes" then the fitting is done interactively using the fit1d task which uses the icfit interactive fitting commands.

The fitted function is divided into the individual flat field spectra to remove the basic shape of the spectrum while maintaining the relative individual pixel responses and any fiber to fiber differences. This step avoids introducing the flat field spectrum shape into the object spectra and closely preserves the object counts.

The final step is to normalize the flat field spectra by the mean counts over all the fibers. This normalization step is simply to preserve the average counts of the extracted object and arc spectra after division by the response spectra.

Dispersion Correction

If dispersion correction is not selected, dispcor=no, then the object spectra are simply extracted. If it is selected the arc spectra are used to dispersion calibrate the object spectra. There are four steps involved; determining the dispersion functions relating pixel position to wavelength, assigning the appropriate dispersion functions to a particular observation, determining a zero point wavelength shift from the arc fibers to be applied to the object fiber dispersion functions, and either storing the nonlinear dispersion function in the image headers or resampling the spectra to evenly spaced pixels in wavelength.

The first arc spectrum in the arc list is used to define the reference dispersion solution. It is extracted using the reference aperture definitions. The interactive task identify is used to define the dispersion function in one fiber. The idea is to mark some lines whose wavelengths are known (with the line list used to supply additional lines after the first few identifications define the approximate wavelengths) and to fit a function giving the wavelength from the pixel position. The dispersion functions for the other fibers are then determined automatically by reference to the first fiber using the task reidentify. Except in batch mode a query is given allowing the reidentified arc spectra to be examined interactively with identify. This would normally be done only if the information about the reidentification printed on the terminal indicates a problem such as a large increase in the RMS. This query may be eliminated in the usual way.

The set of arc dispersion function parameters are from identify and reidentify. The parameters define a line list for use in automatically assigning wavelengths to arc lines, a parameter controlling the width of the centering window (which should match the base line widths), the dispersion function type and order, parameters to exclude bad lines from function fits, and parameters defining whether to refit the dispersion function, as opposed to simply determining a zero point shift, and the addition of new lines from the line list when reidentifying additional arc spectra. The defaults should generally be adequate and the dispersion function fitting parameters may be altered interactively. One should consult the help for the two tasks for additional details of these parameters and the operation of identify.

If resampling of the spectra is selected by the parameter linearize all the arc dispersion functions are combined to provide a default starting and ending wavelength and dispersion with the same number of pixels is determined and the user is queried for any changes. This linear dispersion system will be applied to all spectra so that all the final processed object spectra will have the same dispersion sampling.

Once the reference dispersion functions are defined other arc spectra are extracted as they are assign to the object spectra. The assignment of arcs is done either explicitly with an arc assignment table (parameter arctable) or based on a header parameter such as a time. The assignments are made by the task refspectra. When two arcs are assigned to an object spectrum an interpolation is done between the two dispersion functions. This makes an approximate correction for steady drifts in the dispersion. Because the arc fibers monitor any zero point shifts in the dispersion functions, due to translation and rotation of the detector, it is probably only necessary to have one or two arc spectra, one at the beginning and/or one at the end of the night.

The tasks setjd and setairmass are automatically run on all spectra. This computes and adds the header parameters for the Julian date (JD), the local Julian day number (LJD), the universal time (UTMIDDLE), and the air mass at the middle of the exposure. The default arc assignment is to use the Julian date grouped by the local Julian day number. The grouping allows multiple nights of data to be correctly assigned at the same time.

When the object spectra are extracted so are the simultaneous arc spectra. A zero point shift of the arc spectra relative to the dispersion solutions of an assigned full arc observation is computed using reidentify. The zero point shifts from the arc fibers are then interpolated across the detector based on the positions of the arc apertures to the positions of the object apertures. A linear interpolation is used which accounts for a rotation of the detector as well as a translation along the dispersion. The interpolated zero point wavelength shifts are then added to the dispersion functions from the full arc observation for the object fibers. Note that this does not assume that the object and arc fiber dispersion functions are the same or have the same wavelength origin, but only that the interpolated shifts in wavelength zero point apply to all fibers. When there are two assigned full arc spectra the above steps are done independently and the final pair of zero point corrected dispersion functions for each object fiber are combined using the assigned weights. Once the dispersion function correction is determined from the extracted arc fiber spectra they are deleted leaving only the object spectra.

The last step of dispersion correction is setting the dispersion of the object spectra. There are two choices here. If the linearize parameter is not set the nonlinear dispersion functions are stored in the image header. Other IRAF tasks interpret this information when dispersion coordinates are needed for plotting or analysis. This has the advantage of not requiring the spectra to be interpolated and the disadvantage that the dispersion information is only understood by IRAF tasks and cannot be readily exported to other analysis software.

If the linearize parameter is set then the spectra are resampled to a linear dispersion relation either in wavelength or the log of the wavelength. The linear dispersion parameters are those defined previously for the arc reference image.

The linearization algorithm parameters allow selecting the interpolation function type, whether to conserve flux per pixel by integrating across the extent of the final pixel, and whether to linearize to equal linear or logarithmic intervals. The latter may be appropriate for radial velocity studies. The default is to use a fifth order polynomial for interpolation, to conserve flux, and to not use logarithmic wavelength bins. These parameters are described fully in the help for the task dispcor which performs the correction.

1. The following example uses artificial data and may be executed at the terminal (with IRAF V2.10). This is also the sequence performed by the test procedure "demos do3fiber".

kp> demos mkdo3fiber
Creating image demoobj ...
Creating image demoflat ...
Creating image demoarc ...
kp> do3fiber demoobj apref=demoflat flat=demoflat arcs=demoarc 
>>> width=4 edit=yes
Set reference apertures for demoflat
Resize apertures for demoflat?  (yes):
Edit apertures for demoflat?  (yes):

Fit traced positions for demoflat interactively?  (yes):
Fit curve to aperture 1 of demoflat interactively  (yes):

Fit curve to aperture 2 of demoflat interactively  (yes): N
Create response function demoflatnorm.ms
Extract flat field demoflat
Fit and ratio flat field demoflat
Create the normalized response demoflatnorm.ms
demoflatnorm.ms -> demoflatnorm.ms  using bzero: 0.  and bscale: 1.
    mean: 1.  median: 1.034214  mode: 0.8378798
    upper: INDEF  lower: INDEF
Average aperture response:
1.  0.8394014
2.  1.034403
3.  1.126194
Extract arc reference image demoarc
Determine dispersion solution for demoarc






REIDENTIFY: NOAO/IRAF V2.10BETA valdes@puppis Fri 11:04:32 06-Mar-92
  Reference image = demoarc.ms, New image = demoarc.ms, Refit = yes
     Image Data Found    Fit Pix Shift  User Shift  Z Shift     RMS
d...ms - Ap 1   30/30  29/30  -0.00675       -0.04  -6.9E-6   0.252
Fit dispersion function interactively? (no|yes|NO|YES) (yes): n
d...ms - Ap 3   30/30  29/30   -0.0154     -0.0928  -1.4E-5   0.303
Fit dispersion function interactively? (no|yes|NO|YES) (no): y

d...ms - Ap 3   30/30  29/30   -0.0154     -0.0928  -1.4E-5   0.303
Dispersion correct demoarc
d...ms: w1 = 5785.86, w2 = 7351.59, dw = 6.14, nw = 256
  Change wavelength coordinate assignments? (yes|no|NO): N
Extract object spectrum demoobj
Edit apertures for demoobj?  (yes): n
Assign arc spectra for demoobj
[demoobj] refspec1='demoarc'
Reidentify arc fibers in demoobj with respect to demoarc
REIDENTIFY: NOAO/IRAF V2.10BETA valdes@puppis Fri 11:04:52 06-Mar-92
  Reference image = demoarc.ms, New image = demoobjarc.ms, Refit = no
  Image Data   Found    Fit Pix Shift  User Shift  Z Shift     RMS
d...ms - Ap 1  27/30  27/27   0.00502      0.0263  3.99E-6   0.175
d...ms - Ap 3  27/30  27/27   8.62E-4       0.006  5.07E-7   0.248
Dispersion correct demoobj
demoobj.ms.imh: REFSHFT1 = 'demoobjarc.ms interp', shift = -0.0050,
rms = 0.00282813 intercept = -0.0118401, slope = 2.70764E-4
d...ms: ap = 2, w1 = 5785.86, w2 = 7351.59, dw = 6.14, nw = 256
demoobj.ms.imh:
Splot spectrum? (no|yes|NO|YES) (yes):