| dispcor | noao.onedspec | dispcor |
dispcor -- Dispersion correct and resample spectra
dispcor input output [records]
Also if a reference table or image is given and ignoreaps =yes then the default dispersion parameters for any aperture not defined by the table or image will be that of the first defined aperture. This can still be overridden by giving explicit values for w1, w2, dw and nw .
The dispersion coordinate systems of the input spectra are set or changed in the output spectra. The output spectra may be the same as the input spectra if no output spectra are specified or the output name is the same as the input name. The input and output spectra are specified by image templates or lists. In the irs/iids packages the input and output spectra are specified as root names and the record numbers are specified by the record parameter. The records are given as a set of comma separate single numbers or ranges of hyphen separated numbers. If no records are specified then the input and output images are assumed to be full names.
The dispersion coordinate system is defined either in the image header or by dispersion functions in the specified database. To use reference spectra dispersion functions they must first be assigned to the image with identify (reidentify) , ecidentify (ecreidentify) , refspectra , or hedit . These tasks define the image header keywords REFSPEC1, REFSPEC2, REFSHFT1, and REFSHFT2. The test which determines whether to use the current dispersion coordinate system or reference spectra dispersion solutions is the presence of the REFSPEC1 keyword. Since it is an error to apply a dispersion function to data which have already been dispersion corrected the any dispersion function keywords are deleted after use and a record of them entered in sequential image header keywords beginning with DCLOG.
Dispersion functions are specified by one or both of the reference spectrum image header keywords REFSPEC1 and REFSPEC2 containing the name of calibration spectra with dispersion function solutions (either echelle dispersion functions from ecidentify or non-echelle dispersion functions from identify ) in the database. There must be a dispersion function for each aperture in the input spectrum unless the ignoreaps flag is set. If the flag is not set the task will abort if a matching aperture is not found while if it is set spectra without a matching aperture in the reference dispersion solutions will use the first dispersion solution. Note that aperture number matching is done in both cases and the ignoreaps parameter only applies to non-matching spectra. The common situation for using the ignoreaps option is when there is a single reference dispersion solution which is to be applied to a number of spectra with different aperture numbers; hence effectively ignoring the reference spectrum aperture number.
If two reference spectra are specified the names may be followed by a weighting factor (assumed to be 1 if missing). The wavelength of a pixel is then the weighted averge of the wavelengths of the two dispersion functions. The task refspectra provides a number of ways to assign reference spectra. Note, however, that these assignments may be made directly using the task hedit or with some other task or script if none of the methods are suitable. Also note that identify and reidentify add the REFSPEC1 keyword refering to the image itself when a database entry is written.
In addition to the one or two reference dispersion functions for each input aperture there may also be image header keywords REFSHFT1 and REFSHFT2 specifying reference spectra whose dispersion function zero point shifts (the "shift" parameter in the database files) are to be applied to the reference dispersion functions. The shifts from REFSHFT1 will be applied to the dispersion functions from REFSPEC1 and similarly for the second dispersion functions. The reference shifts need not be present for every aperture in a multispectrum image. By default the mean shift from all the reference apertures having a zero point shift is applied to all the reference dispersion functions. If the REFSHFT keyword has the modifier word "nearest" following the spectrum name then the shift from the nearest aperture in spatial position (from the aperture extraction limits in the original 2D spectrum as recorded in the 6th and 7th fields of the APNUM keywords) is used for a particular input aperture. If the modifier word is "interp" then the nearest two apertures are used to interpolate a zero point shift spatially.
The purpose of the reference shift keywords is to apply a wavelength zero point correction to the reference dispersion functions determined from separate arc calibration observations using a few apertures taken at the same time as object observations. For example, consider multifiber observations in which one or more fibers are assigned to arc lamps at the same time the other fibers are used to observe various objects. The basic dispersion reference, the REFSPEC keywords, will come from arc observations taken through all the fibers. The arc fibers used during an object observation are then calibrated against their corresponding fibers in the arc calibration observations to determine a zero point shift. The REFSHFT keywords will contain the name of the object spectrum itself and the shifts from the simultaneous arc fibers will be interpolated spatially to the nonarc object fibers and applied to the dispersion functions from the arc calibrations for those fibers.
The reference shift keywords are currently added with hedit and zero point shifts computed with identify/reidentify . The complexities of this have been hidden in the multifiber imred instrument reduction packages. The reference shift correction feature was added primarily for use in those reduction packages.
If the linearize parameter is no the dispersion functions, weights, and shifts are transfered from the database to the world coordinate system keywords in the image header. Except for printing processing information that is all that is done to the spectra.
If the linearize parameter is yes the spectra are interpolated to a linear wavelength scale and the dispersion coordinate system in the header is set apprpriately. A linear wavelength coordinate system is defined by a starting wavelength, an ending wavelength, a wavelength interval per pixel, and the number of pixels. These four parameters actually overspecify the coordinate system and only three of these values are needed to define it. The output coordinate system is specified by giving a set or subset of these parameters using the parameters w1 , w2 , dw , and nw .
When the log option is used these parameters are still specified and computed in non-log units but the effective interval per pixel is
dw_log = (log10(w2) - log10(w1)) / (nw - 1) dw_log = (log10(w1+dw*(nw-1)) - log10(w1)) / (nw - 1)
In other words, the logarithmic interval divides the starting and ending wavelength into the required number of pixels in log step. To avoid confusion in this case it is best to specify the starting and ending wavelengths (in non-log units) and the number of pixels.
Note that if log =yes the input spectra in either linear or log sampling will be resampled to produces an output spectrum in log sampling. Similarly, if log =no the input spectra will be resampled to linear sampling. This means that log sampled input spectra will be resampled to to linear sampling.
Default values for any parameters which are not specified, by using the value INDEF, are supplied based on the wavelengths of the first and last pixel as given by the dispersion function and the number of pixels in the input image. The defaults may either be determined separately for each spectrum (global = no ), from all spectra with the same aperture (global = yes and samedisp = no ), or from all the spectra (global = yes and samedisp = yes ). As indicated, the parameter samedisp determines whether defaults are determined independently for each aperture or set the same for all apertures.
Another way to specify the wavelengths when there are many apertures is to use a wavelength table or reference image. If an spectrum image name is specified with the table parameter then the dispersion parameters for each apertures are set to be the same as the reference spectrum. Alternatively, a text file table consisting of lines containing an aperture number, the starting wavelength, the ending wavelength, the wavelength interval per pixel, and the number of output pixels may be specified. Any of these values may be specified as INDEF (though usually the aperture number is not). One way to view the wavelength table/reference spectrum is that an entry in the wavelength table/reference spectrum overrides the values of the parameters w1 , w2 , dw , and nw , which normally apply to all apertures, for the specified aperture. The wavelength table is used to specify explicit independent values for apertures. The global mechanism can supply independent values for the INDEF parameters when the samedisp parameter is no.
If one wishes to verify and possibly change the defaults assigned, either globally or individually, the confirm flag may be set. The user is asked whether to accept these values. By responding with no the user is given the chance to change each parameter value. Then the new parameters are printed and the user is again asked to confirm the parameters. This is repeated until the desired parameters are set. When the defaults are not global the changed parameters will not be used for the next spectrum. When the global option is used any changes made are retained (either for all apertures or independently for each aperture) until changed again.
When adjusting the wavelengths the user should specify which parameter is free to change by entering INDEF. If none of the parameters are specified as INDEF then those values which were not changed, i.e. by accepting the current value, are the first to be changed.
Once the wavelength scale has been defined the input spectrum is interpolated for each output pixel. Output wavelengths outside the range of the input spectrum are set to the value given by the blank parameter value. The default interpolation function is a 5th order polynomial. The choice of interpolation type is made with the package parameter "interp". It may be set to "nearest", "linear", "spline3", "poly5", or "sinc". Remember that this applies to all tasks which might need to interpolate spectra in the onedspec and associated packages. For a discussion of interpolation types see onedspec .
When it is desired to conserve total flux, particularly when the dispersion is significantly reduced, the parameter flux is set to yes and the output pixel value is obtained by integrating the interpolation function across the wavelength limits of the output pixel. If it is set to no then the flux density is conserved by averaging across the output pixel limits.
The input spectrum name, reference spectra, and the wavelength parameters will be printed on the standard output if the verbose parameter is set and printed to a log file if one is specified with the logfile parameter. If one wishes to only check what wavelengths will be determined for the defaults without actually dispersion correcting the spectra the listonly flag may be set.
Other tasks which may be used to change the dispersion coordinate system are scopy , specshift , and sapertures .
In the examples when the task is used in the IRS and IIDS packages, shown with the "ir>" prompt the spectra have a record number extension image name format and the records parameter must be specified. In the other case shown with the "on>" prompt the records parameter is not used.
1. Dispersion correct spectra so that they have the same number of pixels and the wavelengths limits are set by the reference spectra.
ir> dispcor spec dcspec 9,10,447-448 dcspec.0009: ap = 0, w1 = 5078.84, w2 = 6550.54, dw = 1.797, nw = 820 dcspec.0010: ap = 1, w1 = 5078.71, w2 = 6552.81, dw = 1.800, nw = 820 dcspec.0447: ap = 0, w1 = 5082.57, w2 = 6551.45, dw = 1.794, nw = 820 dcspec.0448: ap = 1, w1 = 5082.03, w2 = 6553.66, dw = 1.797, nw = 820 on> dispcor allspec.ms dcallspec.ms dcallspec.ms: ap = 1, w1 = 5078.84, w2 = 6550.54, dw = 1.797, nw = 820 dcallspec.ms: ap = 2, w1 = 5078.71, w2 = 6552.81, dw = 1.800, nw = 820 dcallspec.ms: ap = 3, w1 = 5082.57, w2 = 6551.45, dw = 1.794, nw = 820 dcallspec.ms: ap = 4, w1 = 5082.03, w2 = 6553.66, dw = 1.797, nw = 820
2. Confirm and change assignments.
on> dispcor spec* %spec%new%* confirm+ new009: ap = 0, w1 = 5078.84, w2 = 6550.54, dw = 1.797, nw = 820 Change wavelength coordinate assignments? (yes): Starting wavelength (5078.8421234): 5070 Ending wavelength (6550.535123): Wavelength interval per pixel (1.79693812): Number of output pixels (820): INDEF new009: ap = 0, w1 = 5070., w2 = 6550.53, dw = 1.795, nw = 826 Change wavelength coordinate assignments? (yes): no new010: ap = 1, w1 = 5078.71, w2 = 6552.81, dw = 1.800, nw = 820 Change wavelength coordinate assignments? (no): yes Starting wavelength (5078.7071234): 5100 Ending wavelength (6550.805123): 6500 Wavelength interval per pixel (1.79987512): INDEF Number of output pixels (820): INDEF new010: ap = 1, w1 = 5100., w2 = 6500., dw = 1.797, nw = 780 Change wavelength coordinate assignments? (yes): no new447: ap = 0, w1 = 5082.57, w2 = 6551.45, dw = 1.793, nw = 820 Change wavelength coordinate assignments? (yes): no new448: ap = 1, w1 = 5082.03, w2 = 6553.66, dw = 1.797, nw = 820 Change wavelength coordinate assignments? (no):
3. Confirm global assignments and do dispersion correction in place. record format.
ir> dispcor irs "" 9,10,447,448 confirm+ global+ samedisp+ irs.0009: ap = 0, w1 = 5078.71, w2 = 6553.66, dw = 1.801, nw = 820 Change wavelength coordinate assignments? (yes): Starting wavelength (5078.7071234): 5100 Ending wavelength (6553.664123): 6500 Wavelength interval per pixel (1.80092412): Number of output pixels (820): irs.0009: ap = 0, w1 = 5100., w2 = 6500., dw = 1.799, nw = 779 Change wavelength coordinate assignments? (yes): no irs.0010: ap = 1, w1 = 5100., w2 = 6500., dw = 1.799, nw = 779 Change wavelength coordinate assignments? (no): irs.0447: ap = 0, w1 = 5100., w2 = 6500., dw = 1.799, nw = 779 Change wavelength coordinate assignments? (no): irs.0448: ap = 1, w1 = 5100., w2 = 6500., dw = 1.799, nw = 779 Change wavelength coordinate assignments? (no):
4. Make a nonlinear dispersion correction in place.
on> dispcor spec* "" linearize=no verbose- logfile=logfile
5. Apply a single dispersion solution to a set of record number format images.
ir> dispcor nite101 dcnite101 "1-10" ignore+ confirm-
DISPCOR will now allow multiple uses of IDENTIFY dispersion solutions in a simple way with but with continuing protection against accidental multiple uses of the same dispersion solutions. When a spectrum is first dispersion corrected using one or more reference spectra keywords the dispersion flag is set and the reference spectra keywords are moved to DCLOGn keywords. If DISPCOR is called again without setting new reference spectra keywords then the spectra are resampled (rebinned) using the current coordinate system. If new reference spectra are set then DISPCOR will apply these new dispersion functions. Thus the user now explicitly enables multiple dispersion functions by adding reference spectra keywords and DISPCOR eliminates accidental multiple uses of the same dispersion function by renaming the reference spectra. The renamed keywords also provide a history.
The flux conservation option now computes an average across the output pixel rather than interpolating to the middle of the output pixel when flux is no. This preserves the flux density and includes all the data; i.e. a coarse resampling will not eliminate features which don't fall at the output pixel coordinates.
Some additional log and verbose output was added to better inform the user about what is done.
Better error information is now printed if a database dispersion function is not found.
package, refspectra, scopy, specshift, sapertures
