| waveoff | stsdas.hst_calib.hrs | waveoff |
waveoff -- Determine offset between calculated wavelengths and calibration lamp observations
waveoff input wave offsets
This task calculates the general zero-point offset between a calculated wavelength solution, and a spectral observation of a calibration lamp with a corresponding line list. The offset is useful in determining the "correctness" of the wavelength solution. The offset can also be used as input to tasks that automatically calculate dispersion solutions but need the offset to properly find line positions. This task was developed for use with the Goddard High Resolution Spectrograph (GHRS), but there is nothing instrument-specific about the task.
The artificial spectrum is created using the input wavelength solution and the calibration source's known line list. The spectrum is set to 0 counts everywhere except those pixels where a spectral line should exist, according to the input wavelength solution. The value of the pixel depends on the input. If the known line list table has a column for intensity, the pixel is set to that value. If not, the value of the pixel will be the median value of the input observation spectrum.
Once the artificial spectrum is created, it is cross-correlated with the calibration observation. The cross-correlation function used is the normalized mean and variance correlation given by the following equation:
TOTAL{(x[i] - xmean) * (y[i - k] - ymean)}
corr[k] = ------------------------------------------------
SQRT(TOTAL{(x[i] - xmean)**2}) *
SQRT(TOTAL{(y[i - k] - ymean)**2})
where:
corr[k] - measure of correlation at offset k
x[i] - values in the first spectrum
xmean - mean value of X in the region
being correlated
y[i] - values in the second spectrum
ymean - mean value of Y in the region being
correlated
TOTAL{ } - sum over i
The absolute value of the maximum offset is specified by the max_offset parameter. The size of the correlation function is therefore two times the max_offset size plus one to accommodate shifts from "-max_offset" to "max_offset".
The maximum value of the correlation is found and the offset is computed to sub-pixel precision using quadratic refinement (i.e., the offset is the position of the maximum of the quadratic through the peak value and its two neighbors).
The offset is calculated in the following sense:
offset = artificial - observed
where:
artificial = The artificial spectrum position created
from the specified wavelength solution.
observed = The calibration lamp observation.
The offsets are reported to the standard output and written to a table for later use.
The line list should be in a table, either a binary table or simple text table, with at least one column containing the wavelengths of known lines produced by the source used for the calibration lamp observation. The table does not have to be sorted (though for efficiency, it would be useful). Optionally, a column of relative intensity value can also be present. Though not crucial, the cross-correlation performs much better when the relative line strengths are taken into account. The columns names are specified in parameters in the linetabpar pset (see below).
This graph is meant simply as a preview of how well the correlation is working. There is limited interaction. Besides the usual graphics keys available under gcur (see help for gcur), the following keys below have special functions:
1. Find how much the calculated wavelength solution is off for the GHRS calibration lamp observation z0dj020am. Since only the rootname is specified, waveoff will look for the observation in file z0dj020am.c1h and the wavelength solution in file z0dj020am.c0h.
cl> waveoff z0dj020am output=offsets # file woffset poffset soffset correlation z0dj020am.c1h[1/1] -0.0188 -0.8046 -0.2015 0.4463
The observation z0dj020am is available in the STDATA distribution (see the REFERENCES section).
To remove this zero-point offset in the wavelength solution for the observation, use the offset value found in the "woffset" column and simply add it to the wavelength image, z0dj020am.c0h. The corrected wavelength solution will be placed in the file z0dj020am_correct.c0h.
cl> imcalc z0dj020am.c0h z0dj020am_correct.c0h \ >>>"im1 + -0.0188"
2. Find the offset between the GHRS calibration lamp observation z0dj020am, the same as above, and the now corrected wavelength solution, z0dj020am_correct.c0h. This example demonstrates specifying files on input as opposed to observation rootnames.
cl> waveoff z0dj020am.c1h wave=z0dj020am_correct.c0h # file woffset poffset soffset correlation z0dj020am.c1h[1/1] -0.0012 -0.0504 -0.0126 0.4434
3. Changing the maximum offset and previewing the correlation function. For the above, the default maximum size was used, which is one-quarter the size of the spectrum, or in the case of z0dj020am, about 500 pixels. However the offset is only a few pixels. If one had a series of similar observations, it would be appropriate to limit the maximum offset to a more reasonable value, such as plus or minus 20 pixels:
cl> waveoff z0dj020am max_offset=20
To see how the maximum offset affects the correlation function, set the "preview" parameter to yes. The correlation function will be drawn on the graphics device. Hit the q key to continue after each graph is displayed:
cl> waveoff z0dj020am max_offset=indef preview+ cl> waveoff z0dj020am max_offset=20 preview+
4. The directory "wavecal$" contains only GHRS wavelength calibration observations. Find the offsets for all the observations using default values for the parameters. The offsets will be placed in the table "offsets.tab".
cl> waveoff wavecal$*.c1h output=offsets
5. Using an "@" file to specify the observations. This examples builds a file containing the list of observation names from the directory "wavecal$" using the IRAF "files" command. The list is put into the file "file.list"
cl> files *.c1h > file.list cl> waveoff @file.list
6. Finding the offset for observations that have the wavelength solution in header keywords specifying a world coordinate system (WCS) transformation. This example again uses the observation z0dj020am. However, since this observation does not have any WCS information in its header, a copy of the image must first be created that does have such information. To do this, use the task mkmultispec:
cl> mkmultispec z0dj020am.c1h z0dj020am.c0h z0dj020am_wcs.c1h
The file z0dj020am_wcs.c1h now has the wavelength solution as WCS header keywords. To use this WCS information with waveoff, specify the word "WCS" for the wave parameter:
cl> waveoff z0dj020am_wcs.c1h wave=WCS
The offset calculated should be the same as that calculated in the first example.
Jonathan Eisenhamer, STSDAS
The file "czptnelinec.tab", is an STSDAS binary table which contains the known line list for the PtNe calibration lamps used by the GHRS. This table is distributed with STSDAS in the directory "scidata". Refer to the "STSDAS Installation Guide" and "STSDAS Manager's Guide" for instructions on setting up this directory.
The observation used in some of the examples in this help, z0dj020am, is available from two places. First, it can be retrieved from the STScI archive, as any other observation can be retrieved. For instructions on using the archive, refer to the "HST Archive Manual". If one does not have an account or is otherwise unable to use the archive, the observation is available in the example data, STDATA. Refer to the "STSDAS Manager's Guide" for information on retrieving and installing the STDATA example data. If the STSDAS distribution is used, the observation will have to first be calibrated using calhrs.
For specific information about the GHRS, its data, and the reduction of such data, there are numerous manuals available: "GHRS Instrument Handbook", "GHRS Data Products Guide", "STSDAS User's Guide", and "HST Data Handbook".
For assistance using this or any other tasks, please contact help@stsci.edu or call the help desk at 410-338-1082.
gcur, mkmultispec, ctools, onedspec, hrs, calhrs