EXAMPLES · REVISIONS · SEE_ALSO

## NAME

disptrans -- Transform dispersion units and apply air correction

## USAGE

`disptrans input output units`

## PARAMETERS

- input
- List of dispersion calibrated input spectra to be dispersion transformed.

- 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.

- units
- Output dispersion units. A wide range of dispersion units may be specified and they are described in the UNITS section.

- 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.

- 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.

- verbose = yes
- Print a log of each spectrum transformed to the standard output?

- 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.

- t = 15, p = 760, f = 4
- Temperture t in degrees C, pressure p in mmHg, and water vapour pressure f in mmHg for the air index of refraction.

OTHER PARAMETERS

- interp = "poly5" (nearest|linear|poly3|poly5|spline3|sinc)
- Spectrum interpolation type used when spectra are resampled. The choices are:
nearest - nearest neighbor linear - linear poly3 - 3rd order polynomial poly5 - 5th order polynomial spline3 - cubic spline sinc - sinc function

## 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 *linearize*
parameter should be
set to no and the task **dispcor**
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.

## 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.

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)

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:

km/s 1 micron

## 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.

## EXAMPLES

1. Convert a spectrum dispersion calibrated in Angstroms to electron volts and resample to a linear sampling.

cl> disptrans spec1 evspec1 ev linear+ evspec1: Dispersion transformed to ev.

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.

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.

## REVISIONS

- DISPTRANS V2.10.4
- New task with this release.

## SEE ALSO

dispcor, identify, scopy, dopcor