.help dopcor Jun94 noao.onedspec
.ih
NAME
dopcor -- Apply doppler correction
.ih
USAGE
dopcor input output redshift
.ih
PARAMETERS
.ls input
List of input spectra to be doppler corrected.
.le
.ls 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.
.le
.ls 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 \fIisvelocity\fR parameter.
.le
.ls isvelocity = no
Is the value specified by the \fIredshift\fR 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).
.le
.ls add = no
Add doppler correction to existing correction in "multispec" spectra?
.le
.ls dispersion = yes
Apply a correction to the dispersion function?
.le
.ls flux = no
Apply a flux correction?
.le
.ls factor = 3
Flux correction factor as a power of 1+z when applying a flux correction.
.le
.ls 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 \fBranges\fR
for further information.  For N-dimensional spatial spectra such as
long slit and Fabry-Perot spectra this parameter is ignored.
.le
.ls verbose = no
Print corrections performed?  The information includes the output image
name, the apertures, the redshift, and the flux correction factor.
.le
.ih
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
\fBrvcorrect\fR.  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 \fBrvcorrect\fR for example.

The choice between a redshift and a space velocity for the \fIredshift\fR
parameter is made using the \fIisvelocity\fR 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, \fIredshift\fR 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 \fIadd\fR 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 \fIadd\fR 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 \fIdispersion\fR parameter.  This correction is a term to be
applied to the dispersion coordinates defined for the image.  \fIThe spectrum
is not resampled, only the dispersion coordinate function is affected\fR.
A correction to the flux, pixel values, is selected with the \fIflux\fR
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 \fIfactor\fR 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.
.ih
EXAMPLES
1.  To dispersion and flux correct a quasar spectrum with redshift of
3.2 to a rest frame:

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

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

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

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

.nf
	cl> = 1/(1+3.2)-1
	-0.76190476190476
	cl> dopcor artspec "" -0.762 flux+
.fi
.ih
REVISIONS
.ls 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 \fIadd\fR parameter was added.
.le
.ls DOPCOR V2.10.3
A keyword is added to log the correction applied.
.le
.ls 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.
.le
.ls DOPCOR V2.10
This task is new.
.le
.ih
SEE ALSO
ranges, rvcorrect
.endhelp
