dopcor: Doppler correct spectra

Package: specred

Usage

dopcor input output redshift

Parameters

input: List of input spectra to be doppler corrected.

output: List of doppler corrected spectra. If no output list is specified then the input spectra are modified. Also the output name may be the same as the input name to replace the input spectra by the calibrated spectra.

redshift: Redshift or radial velocity (km/s) to be removed? The spectra are corrected so that the specified redshift is removed; i.e. spectra with a positive velocity are shifted to shorter wavelengths and vice-versa. This parameter may be either a number or an image header keyword with the desired redshift or velocity value. An image header keyword may also have an initial minus sign, '-', to specify the negative of a velocity or the redshift complement (1/(1+z)-1) of a redshift. The choice between a redshift and a velocity is made with the isvelocity parameter.

isvelocity = no: Is the value specified by the redshift parameter a velocity? If no then the value is interpreted as a redshift and if it is yes then it is interpreted as a physical velocity in kilometers per second. Note that this is a relativistic velocity and not c*z! For nearby cosmological velocities users should specify a redshift (z = v_cosmological / c).

add = no: Add doppler correction to existing correction in "multispec" spectra?

dispersion = yes: Apply a correction to the dispersion function?

flux = no: Apply a flux correction?

factor = 3: Flux correction factor as a power of 1+z when applying a flux correction.

apertures = "": List of apertures to be corrected. If none are specified then all apertures are corrected. An aperture list consists of comma separated aperture number or aperture number ranges. A range is hypen separated and may include an interval step following the character 'x'. See ranges for further information. For N-dimensional spatial spectra such as long slit and Fabry-Perot spectra this parameter is ignored.

verbose = no: Print corrections performed? The information includes the output image name, the apertures, the redshift, and the flux correction factor.

Description

The input spectra (as specified by the input image list and apertures) are corrected by removing a specified doppler shift and written to the specified output images. The correction is such that if the actual shift of the observed object is specified then the corrected spectra will be the rest spectra. The opposite sign for a velocity or the redshift complement (1/(1+z)-1) may be used to add a doppler shift to a spectrum.

There are two common usages. One is to take spectra with high doppler velocities, such as cosmological sources, and correct them to rest with respect to the earth. In this case the measured redshift or velocity is specified to "remove" this component. The other usage is to correct spectra to heliocentric or local standard of rest. The heliocentric or LSR velocities can be computed and entered in the image header with the task rvcorrect. In this case it is tempting to again think you are "removing" the velocity so that you specify the velocity as given in the header. But actually what is needed is to "add" the computed standard of rest velocity to the observed spectrum taken with respect to the telescope to place the dispersion in the desired center of rest. Thus, in this case you specify the opposite of the computed heliocentric or LSR velocity; i.e. use a negative.

The redshift or space velocity in km/s is specified either as a number or as an image header keyword containing the velocity or redshift. If a number is given it applies to all the input spectra while an image header keyword may differ for each image. The latter method of specifying a velocity is useful if velocity corrections are recorded in the image header. See rvcorrect for example.

The choice between a redshift and a space velocity for the redshift parameter is made using the isvelocity parameter. If isvelocity=yes then the header dispersion solution is modified according to the relativistic Doppler correction:

lambda_new = lamda_old * sqrt((1 + v/c)/(1 - v/c))

where v is the value of "redshift". If isvelocity=no, redshift is interpreted as a cosmological redshift and the header dispersion solution is modified to give:

lambda_new = lamda_old * z

where z is the value of "redshift"

If the add parameter is used and the image uses a "multispec" format where the previous doppler factor is stored separately then the new doppler factor is:

znew = (1 + z) * (1 + zold) - 1 = z + zold + z * zold

where z is the specified doppler factor, zold is the previous one, and znew is the final doppler factor. If the add parameter is no then the previous correction is replaced by the new correction. Note that for images using a linear or equispec coordinate system the corrections are always additive since a record is not kept of the previous correction. Also any flux correction is made based on the specified doppler correction rather than znew.

There are two corrections which may be made and the user selects one or both of these. A correction to the dispersion function is selected with the dispersion parameter. This correction is a term to be applied to the dispersion coordinates defined for the image. The spectrum is not resampled, only the dispersion coordinate function is affected. A correction to the flux, pixel values, is selected with the flux parameter. This correction is only significant for cosmological redshifts. As such the correction is dependent on a cosmological model as well as whether a total flux or surface brightness is measured. To provide the range of possible corrections the flux correction factor is defined by the factor parameter as the power of 1+z (where z is the redshift) to be multiplied into the observed pixel values.

A keyword DOPCORnn is added to the image header. The index starts from 01 and increments if multiple corrections are applied. The value of the keywords gives the redshift applied, the flux factor if used, and the apertures which were corrected.

Examples

1. To dispersion and flux correct a quasar spectrum with redshift of 3.2 to a rest frame:

cl> dopcor qso001.ms qso001rest.ms 3.2 flux+

2. To correct a set of spectra (in place) to heliocentric rest the task rvcorrect is used to set the VHELIO keyword using an observed velocity of 0. Then:

cl> dopcor *.imh "" -vhelio isvel+

3. To artificially add a redshift of 3.2 to a spectrum the complementary redshift is computed:

cl> = 1/(1+3.2)-1
-0.76190476190476
cl> dopcor artspec "" -0.762 flux+

Revisions

DOPCOR V2.10.3: This task was extended to work on two and three dimensional spatial spectra such as long slit and Fabry-Perot spectra. The add parameter was added.

DOPCOR V2.10.3: A keyword is added to log the correction applied.

DOPCOR V2.10.2: A sign error in converting velocity to redshift was fixed. A validity check on the velocities and redshifts was added. The documentation was corrected and improved.

DOPCOR V2.10: This task is new.