diff options
Diffstat (limited to 'noao/onedspec/doc/disptrans.hlp')
| -rw-r--r-- | noao/onedspec/doc/disptrans.hlp | 193 |
1 files changed, 193 insertions, 0 deletions
diff --git a/noao/onedspec/doc/disptrans.hlp b/noao/onedspec/doc/disptrans.hlp new file mode 100644 index 00000000..d73a4cb4 --- /dev/null +++ b/noao/onedspec/doc/disptrans.hlp @@ -0,0 +1,193 @@ +.help disptrans Aug94 noao.onedspec +.ih +NAME +disptrans -- Transform dispersion units and apply air correction +.ih +USAGE +disptrans input output units +.ih +PARAMETERS +.ls input +List of dispersion calibrated input spectra to be dispersion transformed. +.le +.ls output +List of output dispersion transformed spectra. If given the input names +(or a null list), each input spectrum will be replaced by the transformed +output spectrum. +.le +.ls units +Output dispersion units. A wide range of dispersion units may be +specified and they are described in the UNITS section. +.le +.ls error = 0.01 +Maximum error allowed in the output dispersion transformation expressed +as a pixel error; that is, the equivalent pixel shift in the output +dispersion function corresponding to the maximum difference between +the exact transformation and the dispersion function approximation. +The smaller the allowed error the higher the order of dispersion +function used. +.le +.ls linearize = no +Resample the spectrum data to linear increments in the output dispersion +system? If no then the output dispersion function is stored in the +spectrum header and if yes the spectrum is resampled into the same +number of pixels over the same dispersion range but in even steps +of the output dispersion units. +.le +.ls verbose = yes +Print a log of each spectrum transformed to the standard output? +.le + +.ls air = "none" (none|air2vac|vac2air) +Apply an air to vacuum or vacuum to air conversion? It is the +responsibility of the user to know whether the input dispersion +is in air or vacuum units and to select the appropriate conversion. +The conversion types are "none" for no conversion, "air2vac" to +convert from air to vacuum, and "vac2air" to convert from vacuum +to air. +.le +.ls t = 15, p = 760, f = 4 +Temperature t in degrees C, pressure p in mmHg, and water vapour pressure f +in mmHg for the air index of refraction. +.le + +OTHER PARAMETERS + +.ls interp = "poly5" (nearest|linear|poly3|poly5|spline3|sinc) +Spectrum interpolation type used when spectra are resampled. The choices are: + +.nf + nearest - nearest neighbor + linear - linear + poly3 - 3rd order polynomial + poly5 - 5th order polynomial + spline3 - cubic spline + sinc - sinc function +.fi +.le +.ih +DESCRIPTION +The dispersion function in the input spectra, y = f(x) where x is the +pixel coordinate and y is the input dispersion coordinate, is +transformed to y' = g(x) where y' is in the new dispersion units. This is done +by evaluating the input dispersion coordinate y at each pixel, applying an +air to vacuum or vacuum to air conversion if desired, and applying the +specified unit transformation y' = h(y). Since the transformations are +nonlinear functions and the output dispersion function must be expressed in +polynomial form, the function g(x) is determined by fitting a cubic spline +to the set of x and y' values. The lowest number of spline pieces is used +which satisfies the specified error. Note that this error is not a random +error but difference between the smooth fitted function and the smooth +dispersion function in the header. As a special case, the first +fit tried is a linear function. If this satisfies the error condition +then a simpler dispersion description is possible. Also this is +appropriate for dispersion units which are simply related by a +scale change such as Angstroms to nanometers or Hertz to Mev. + +The error condition is that the maximum difference between the exact or +analytic (the air/vacuum conversion is never exact) transformation and the +fitted function value at any pixel be less than the equivalent shift in +pixel coordinate evaluated at that point. The reason for using an error +condition in terms of pixels is that it is independent of the dispersion of +the spectra and the resolution of spectra is ultimately limited by the +pixel sampling. + +After the new dispersion function is determined the function is either +stored in the coordinate system description for the spectrum or used to +resample the pixels to linear increments in the output dispersion units. +The resampling is not done if the new dispersion function is already linear +as noted above. The sampling uses the mean value over the input spectrum +covered by an output spectrum pixel (it is flux per unit dispersion element +preserving as opposed to flux/counts preserving). The linear sampling +parameters are limited to producing the same number of output pixels as +input pixels over the same range of dispersion. If one wants to have more +control over the resampling then the \fIlinearize\fR parameter should be +set to no and the task \fBdispcor\fR used on the output spectrum. + +Note that an alternative to using this task is to do the original +dispersion calibration (based on calibration spectra) with IDENTIFY +and DISPCOR in the desired units. However, currently the standard +lines lists are in Angstroms. There are, however, linelists for +He-Ne-Ar, Th-Ar, and Th in vacuum wavelengths. +.ih +UNITS +The dispersion units are specified by strings having a unit type from the +list below along with the possible preceding modifiers, "inverse", to +select the inverse of the unit and "log" to select logarithmic units. For +example "log angstroms" to select the logarithm of wavelength in Angstroms +and "inv microns" to select inverse microns. The various identifiers may +be abbreviated as words but the syntax is not sophisticated enough to +recognized standard scientific abbreviations except for those given +explicitly below. + +.nf + angstroms - Wavelength in Angstroms + nanometers - Wavelength in nanometers + millimicrons - Wavelength in millimicrons + microns - Wavelength in microns + millimeters - Wavelength in millimeters + centimeter - Wavelength in centimeters + meters - Wavelength in meters + hertz - Frequency in hertz (cycles per second) + kilohertz - Frequency in kilohertz + megahertz - Frequency in megahertz + gigahertz - Frequency in gigahertz + m/s - Velocity in meters per second + km/s - Velocity in kilometers per second + ev - Energy in electron volts + kev - Energy in kilo electron volts + mev - Energy in mega electron volts + + nm - Wavelength in nanometers + mm - Wavelength in millimeters + cm - Wavelength in centimeters + m - Wavelength in meters + Hz - Frequency in hertz (cycles per second) + KHz - Frequency in kilohertz + MHz - Frequency in megahertz + GHz - Frequency in gigahertz + wn - Wave number (inverse centimeters) +.fi + +The velocity units require a trailing value and unit defining the +velocity zero point. For example to transform to velocity relative to +a wavelength of 1 micron the unit string would be: + +.nf + km/s 1 micron +.fi +.ih +AIR/VACUUM CONVERSION +The air to vacuum and vacuum to air conversions are obtained by multiplying +or dividing by the air index of refraction as computed from the +formulas in Allen's Astrophysical Quantities (p. 124 in 1973 edition). +These formulas include temperature, pressure, and water vapour terms +with the default values being the standard ones. +.ih +EXAMPLES +1. Convert a spectrum dispersion calibrated in Angstroms to electron +volts and resample to a linear sampling. + +.nf + cl> disptrans spec1 evspec1 ev linear+ + evspec1: Dispersion transformed to ev. +.fi + +2. Apply an air to vacuum correction to an echelle spectrum using the +default standard temperature and pressure. Don't resample but rather use +a nonlinear dispersion function. + +.nf + cl> disptrans highres.ec vac.ec angs air=air2vac + vac.ec: Dispersion transformed to angstroms in vacuum with + t = 15. C, p = 760. mmHg, f = 4. mmHg. +.fi +.ih +REVISIONS +.ls DISPTRANS V2.10.4 +New task with this release. +.le +.ih +SEE ALSO +dispcor, identify, scopy, dopcor +.endhelp |