STScI Logo

disptrans noao.onedspec



disptrans -- Transform dispersion units and apply air correction


disptrans input output units


List of dispersion calibrated input spectra to be dispersion transformed.
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.
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.


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


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.


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


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.


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 angs air=air2vac Dispersion transformed to angstroms in vacuum with
      t = 15. C, p = 760. mmHg, f = 4. mmHg.


New task with this release.


dispcor, identify, scopy, dopcor

Search Form · STSDAS