NAME

mkmultispec -- Create a MULTISPEC WCS based on wavelength tables.

USAGE

mkmultispec input wave output

DESCRIPTION

This task takes input spectra and wavelength tables, uses the IRAF curfit routines to fit the wavelength table, creates a MULTISPEC world coordinate system (WCS) description of the fit and creates a new copy of the input spectrum with the new WCS.

This task is intended to be used with the Hubble Space Telescope (HST) spectrographic data from Faint Object Spectrograph (FOS) and Goddard High Resolution Spectrograph (GHRS) to merge the wavelengths that result from the calibration into the data itself so that other IRAF tasks, such as splot, may be used. However, this task is general; any wavelength image or table may be applied to any one dimensional spectrum. The task does not create the appropriate MULTISPEC WCS for multiple one-dimensional spectra stacked into a two dimensional data format.

There are four functions that can be fit to the wavelength data: legendre, chebyshev, spline1, and spline3. Also, there is a table function which copies the input wavelengths into the header of the output spectral file.

mkmultispec operates in two modes: interactive or non-interactive. By default, non-interactive mode is used. In non-interactive mode, fitting information is taken from the parameters and the same fit is applied to all input. In interactive mode, mkmultispec uses the IRAF icfit task which allows users to modify fit parameters and review results---such as residuals.

Data files to be modified are specified by the input parameter. Output files will be written using the names specified by the output parameter. input and output must contain the same number of values (file names). If output is not specified, the files will be modified in-place and existing values overwritten.

The wave parameter specifies the list of files that contain tables of wavelengths. These can either be one-dimensional images or tables. You can specify just one wavelength file or as many wavelength files as there are output files. If only one wavelength file is specified, one wavelength solution will be applied to all input files. There must be as many wavelengths in the wavelength image or table as there are pixels in the corresponding input image.

The weight parameter specifies a list of files containing relative weight information to apply to the wavelength information while fitting. There can be one weight file specified, or the same number of weight files as wavelength files. If only one weight file is specified, the same weight is used for all input wavelength files. Each weight file is either a one-dimensional image or a table. There must be as many weight values in the image or table as there are wavelengths in the corresponding wavelength file. The values in the weight files should be real values between 0. (no weight) and 1. (full weight).

mkmultispec handles multi-group data automatically. The solution for each group of the current wavelength file will be applied to the corresponding group in the current input file. If the input file has more groups than the wavelength file, the fit for the last group of the wavelength file will be applied to the remaining groups of the input file. For example, if the input file has four groups of spectra and the wavelength file has four groups of wavelengths, a fit will be determined for the first wavelength group and applied to the first input group, a fit will be determined for the second wavelength group and applied to the second input group, etc. However, if the input file has four groups of data and the wavelength file only has one group, the fit to the one group of wavelength data will be applied to all four groups of the input file.

The concept of groups has been extended to tables as well. If a table is specified for the wavelengths or weights and no column is specified, mkmultispec assumes that all columns of the wavelength table contain wavelength information. For example, for a four-group input file and a wavelength table containing four columns of wavelengths, a fit will be made to the first column and applied to the first input group, a fit will be made to the second column and applied to the second input group, etc. This behavior can be changed as described above, or by specifying a specific column or list of columns with the wavelength table name. (See the description of the wave parameter for examples of the syntax to be used).

In interactive mode, mkmultispec displays the results of the fit with the current fit parameters and the current wavelength or weight information. While the image is displayed, you can examine statistics about the current fit. For example, pressing the "j" key will display the residuals of the fit, The "h" key will redisplay the fit. If some parameter of the fit needs to be changed, you can use the "colon" commands. For example, to see what the current function is, type the sequence ":function". To change the function, for example from spline3 to legendre, type the sequence ":function legendre". Pressing "q" exits interactive mode for the current fit and applies the fit to the input spectrum. If a list of wavelengths was given, the process repeats.

Once you are satisifed with the fitting parameters, you can apply them to all remaining input files instead of going through each fit. To do this, press "e". The "e" key applies the current fit to all remaining input. This will let you try a couple fits, then tell mkmultispec to apply the fit to all remaining input without further interaction. (Type "help icfit" for a list of the interactive keystroke commands.)

For more information about the MULTISPEC world coordinate system, type "help onedspec.package". For more information about the interactive curve fitting routine, type "help icfit".

PARAMETERS

input [file name template]

Input files that are to have the new MULTISPEC WCS applied.

These should be one-dimensional spectra and can be either regular IRAF images or Space Telescope multigroup data.

wave [file name template]

List of wavelength images or tables to use in determining the function pixel-to-wavelength transformation.

If only one wavelength table is specified, the resulting MULTISPEC WCS will be applied to all input spectra. If more than one input wavelength is specified, there must be the same number of wavelength specifications as input spectra. The files may either be a tables or images. If a file is a table, the columns to use are specified as follows: tablename[columnname1,columnname2,...]. If no columns are specified, mkmultispec assumes all columns contain wavelength information.

output [file name template]

The names of the output spectra.

If this parameter is blank, the spectra will be modified in-place. If file names are specified, there must be the same number of output spectra as input spectra.

(function = "legendre") [string, Allowed values: legendre | chebyshev |

spline3 | spline1 | table]

The type of function to fit to the wavelength tables. If "table" is specified, the wavelength data are written directly into the input file headers. If the input is multigroup and "table" is specified, only one table will be applied to all the groups of the input. If interactive mode was choosen, the parameter will be set to the last function specified by the ":function" command.

(nterms = 4) [integer]

The number of terms or spline pieces to fit. For legendre and chebyshev, this is the number of coefficients the fit will have. For spline3, the number of coefficients will be nterms + 3. For spline1, the number of coefficients will be nterms + 1. If interactive mode was choosen, the parameter will be set to the last value specified by the ":order" command.

(weight = "") [file name template]

Weight tables to be used during the fitting process.

If this is blank, uniform weights will be given to all points. The weights can either be in a table or one dimensional image. If only one weight file is specified, it is applied to every input spectrum. If more than one is given, there must be the same number of input spectra as weight files. If the file is a table, the column to use for the weight data can be specified as follows: filename[columnname1, columnname2,...]. If no columns are specified, mkmultispec assumes all columns contain weight information.

(label = "Wavelength") [string]

The label to use for the wavelength axis in plots generated using the MULTISPEC information, such as those produced by the task splot.

(units = "Angstroms") [string]

The units the wavelength solution is in. This will be displayed by tasks which use the MULTISPEC information, such as splot.

(low_reject = 2., high_reject = 4.) [real, min = 0.]

Rejection limits below and above the fit in units of the residual sigma. Unequal limits are used to reject spectral lines on one side of the continuum during continuum fitting. If interactive mode was choosen, the parameters will be set to the last values specified by the ":low_reject" and ":high_reject" commands.

(niterate = 0) [integer]

Number of rejection iterations. If set to 0, then no rejection is done while fitting. If interactive mode was choosen, the parameter will be set to the last value specified by the ":niterate" command.

(grow = 1.) [real]

When a pixel is rejected, pixels within this distance of the rejected pixel are also rejected. If interactive mode was choosen, the parameter will be set to the last value specified by the ":grow" command.

(format = "%g") [string]

The format to use to write the coefficients to the image header. The main use is when the table function has been specified and the user wants to conserve header space by specifying a more restrictive format.

(interactive = no) [boolean]

Use the icfit task to interactively fit the wavelengths?

The following parameters apply only for interactive fitting.

(device = "stdgraph") [string]

The graphics device to use for the interactive curve fitting.

(markrej = yes) [boolean]

Mark rejected points?

If you are rejecting many points, you might not want to mark rejected points. If interactive mode was choosen, this parameter will be set to the last value specified by the ":markrej" command.

(cursor = "") [*gcur]

Graphics cursor input. When null the standard cursor is used otherwise the specified file is used.

(verbose = yes) [boolean]

Display names of input and output files while operating on files?

EXAMPLES

1. Take all the calibrated data from HRS observations and define the MULTISPEC header information. Put the results into new files where the rootnames end in "_wcs".

        hr> mkmultispec z*.c1h z*.c0h z*%%_wcs%.c1h

2. Fit the wavelengths stored in the table wave.tab under column "wavelength" to all FOS observations in the current directory. Modify the data in-place.

        hr> mkmultispec y*.c1h wave.tab[wavelength] ""

3. Fit the wavelength information stored in the fourth group of the image wave.hhh and apply it to the first group of the image spectrum.hhh. Write the result to the file out.hhh. out.hhh will contain only the one group of data.

        hr> mkmultispec spectrum.hhh[1] wave.hhh[4] out.hhh

4. Apply the wavelength solutions found in wave.hhh to the spectra in spectra.hhh and write the results to out.hhh. Both input files contain four groups and the fitting will be done interactively.

        hr> mkmultispec spectra.hhh wave.hhh out.hhh interactive=yes

                ...The fit for the first group of 'wave.hhh' is displayed.
                ...To see what function is being fit, type:

        :function

                ...And it displays:

        --> spline3
        
                ...Change the function to "legendre":

        :function legendre
        :function
        --> legendre

                ...To refit with the new function, press the "f" key.

        f
                ...To use this fit, press "q"

        q
                ...The fit for the next group appears.  To use this
                ...fit for this and all remaining groups, press "e".

        e
                ...At this point, the fitting is completed.

SEE ALSO

curfit, icfit, splot, onedspec