.help telluric Mar97 noao.onedspec
.ih
NAME
telluric -- remove telluric features from 1D spectra
.ih
SUMMARY
Telluric calibration spectra are shifted and scaled to best divide out
telluric features from data spectra.  This may be done non-interactively to
minimize the RMS in some region or regions of the data spectra and
interactively with a graphically search.
.ih
USAGE
telluric input output cal
.ih
PARAMETERS
.ls input
List of input data images containing one dimensional spectra to be
corrected.  All spectra in each image are corrected. The spectra need not
be wavelength calibrated.
.le
.ls output
List of output corrected images.  The list must either match the input list
or be an empty list.  If an empty list is specified the input spectra will
be replaced by the corrected spectra.  The input spectra will also be
replaced if the input and output image names are the same.  Any other image
name must be for a new image otherwise a warning message will be given and
the task will proceed to the next input image.
.le
.ls cal  
List of telluric calibration images.  If a single image is specified it
will apply to all the input images.  Otherwise the list of calibration
images must match the list of input images.
.le
.ls ignoreaps = no
Ignore aperture numbers between the input spectra and the calibration
spectra?  If "no" then the calibration image must contain a spectrum
with the same aperture number as each spectrum in the input image.
Otherwise the first spectrum in the calibration image will be used
for all spectra in the input image.
.le
.ls xcorr = yes
Cross-correlate each input spectrum with the calibration spectrum to
determine an shift for the calibration spectrum?  Only regions specified by
the sample regions parameter will be used in the cross-correlation.
.le
.ls tweakrms = yes
Search for the minimum RMS in the corrected spectrum by adjusting the
shifts and scales between the input spectrum and the calibration spectrum?
The RMS is minimized in the specified sample regions.
.le
.ls interactive = yes
Enter an interactive graphical mode to search for the best shift
and scale between the input spectra and calibration spectra?  This
is done after the optional automatic cross-correlation and RMS minimization
step.  A query is made for each input spectrum so that the interactive
step may be skipped during the execution of the task.
.le
.ls sample = "*"
Sample regions to use for cross-correlation, automatic RMS minimization,
and RMS values.  The sample regions are specified by a list of comma
separated ranges.  The ranges are colon separate coordinate values.
For dispersion calibrated spectra the coordinate values are in the
dispersion units otherwise they are in pixel coordinates.  The string "*"
selects the entire spectrum.  The sample regions may be changed
interactively either with the cursor or with a colon command.
.le
.ls threshold = 0.
Since the calibration consists of division by the scaled calibration data
it is possible for totally saturated lines to have zero or negative values.
The task will quit if detects negative or zero calibration values.  The
\fIthreshold\fR allows applying a minimum threshold to the calibration
values so the task may continue.
.le
.ls lag = 10
The cross-correlation lag to use when \fIxcorr\fR = yes.  The lag
is given in pixels.   This is the distance to either side of the
initial shift over which the cross-correlation profile is computed.
If a value of zero is given then the cross-correlation step is not done.
.le
.ls shift = 0., dshift = 1.
The initial shift and shift step in pixels.  This initializes the shift
search parameters for the first spectrum.  If \fIdshift\fR is zero then
there will be no search for a new shift and the 'x' interactive function is
disabled.  These parameters may be changed interactively.  After the
first spectrum subsequent spectra begin with the values from the last
spectrum.
.le
.ls scale = 1., dscale = 0.2
The initial scale and scale step.  This initializes the scale
search parameters for the first spectrum.  If \fIdscale\fR is zero then
there will be no search for a new scale and the 'y' interactive function is
disabled.  These parameters may be changed interactively.  After the
first spectrum subsequent spectra begin with the values from the last
spectrum.
.le
.ls offset = 1.
The interactive search displays three candidate corrected spectra which
have been normalized to a mean of one.  The offset is added and subtracted
to separate the three candidates.  The value may be changed interactively.
.le
.ls smooth = 1
The displayed candidate corrected spectra are smoothed by a moving
boxcar average with a box size specified by this parameter.  The smoothing
only applies to the displayed spectra and does not affect the measured
RMS or the output corrected spectra.  The value may be changed interactively.
.le
.ls cursor = ""
Input cursor for the interactive graphics.  A null value selects the
graphics cursor otherwise a file of cursor values may be specified.
.le
.ls airmass
Query parameter for the airmass.  If the airmass is not in the image
header under the keyword AIRMASS the user is queried for the airmass.
This parameter should not be specified on the command line.
.le
.ls answer
Query parameter for responding to the interactive question.  This parameter
should not be specified on the command line.
.le
.ls interp = poly5
The \fBpackage\fR parameter specifying the interpolation function for shifting
the calibration spectra to match the input spectra.
.le
.ih
DESCRIPTION
Input one dimensional spectra are corrected to remove telluric features by
dividing by shifted and scaled calibration spectra.  The calibration
spectra are generally of hot, nearly featureless stars; hence this procedure
is sometimes referred to as a B-star correction.  The shifting
allows for possible small shifts or errors in the dispersion zeropoints.
The intensity scaling allows for differences in the airmass and variations
in the abundance of the telluric species.  The intensity scaling
uses Beer's law which is the approximation that the change in absorption
with abundance is an exponential relation.  

The following describes the correction.  Let J(x_i) be the calibration
spectrum at a set of pixels x_i.  An interpolation function is fit to this
spectrum to give J(x).  The shifted and scaled calibration function
is then

.nf
    (1)  J'(x) = max (threshold, J(x+dx)) ** (A / A_cal * scale)
.fi

where dx is the pixel shift parameter, A is the airmass of the input
spectrum, A_cal is the airmass of the calibration spectrum, and
scale is the scale parameter.  The operator "**" is exponentiation.
The max operation limits the calibration spectrum to be greater
than or equal to the specified threshold value.  If the calibration
value is ever less than or equal to zero then the task will quit
with a warning error.

The output corrected spectrum is then computed as

.nf
    (2)  I'(x_i) = I(x_i) / (J'(x_i) / <J'>)
.fi

where I' is the corrected spectrum, I is the input spectrum, and <J'> is
the mean of the shifted and scaled calibration spectrum to keep the output
intensities comparable to the input spectrum.  The value of <J'> is
printed in the output as the "normalization".  If the spectra are
dispersion calibrated, possibly with different dispersion parameters, then
the x values in (2) from the input spectrum are converted to matching
pixels in the calibration spectrum using the dispersion functions of the
two spectra.

The purpose of this task is to determine the best values of the
shift and scale parameters dx and scale.  There
are automatic and interactive methods provided.  The automatic
methods are cross-correlation of the calibration and input spectra
to find a shift and an iterative search for the in both
shift and scale that minimizes the RMS of I' in some region.
The automatic methods are performed first, if selected, followed
by the interactive, graphical step.  The following describes
the steps in the order in which they occur.

The initial values of the shift and scale are set by the parameters
\fIshift\fR and \fIscale\fR for the first spectrum.  After that the values
determined for the previous spectrum, those actually applied to correcting
that spectrum, are used as the initial values for the next spectrum.  The
search steps and sample regions are also initialized by task parameters but
may be modified during the interactive step and the modified values apply
to subsequent spectra.

If the \fIxcorr\fR parameter is yes and the \fIlag\fR parameter is
not zero the calibration spectrum is cross-correlated against the input
spectrum.  Each spectrum is prepared as follows.  A large scale continuum
is fit by a quadratic chebyshev using 5 iterations of sigma clipping with a
clipping factor of 3 sigma below the fit and 1 sigma above the fit and
rejecting the deviant points along with one pixel on either side.  This
attempts to eliminate the effects of absorption lines.  The continuum fit
is subtracted from the spectrum and the spectrum is extended and tapered by
a cosine function of length given by the \fIlag\fR parameter.

The prepared spectra are then cross-correlated by shifting the calibration
spectrum plus and minus the specified \fIlag\fR amount about the current
shift value.  Only the regions in the input spectrum specified by the
sample regions parameter are used in the correlation.  This produces a
correlation profile whose peak defines the relative shift between the two
spectra.  The current shift value is updated.  This method assumes the
common telluric features dominate within the specified sample regions.  The
lag size should be roughly the profile widths of the telluric features.

If the \fItweakrms\fR parameter is yes and \fIdshift\fR is greater than
zero trial corrections at the current shift value and plus and minus one
shift step with the scale value fixed at its current value are made and the
RMS in the sample regions computed.  If the RMS is smallest at the current
shift value the shift step is divided in half otherwise the current shift
value is set to the shift with the lowest RMS.  The process is then
repeated with the new shift and shift step values.  This continues until
either the shift step is less than 0.01 pixels or the shift is more than
two pixels from the initial shift.  In the latter case the final shift is
reset to the original shift.

The scale factor is then varied if \fIdscale\fR is greater than zero by the
scale step at a fixed shift in the same way as above to search for a
smaller RMS in the sample regions.  This search terminates when the scale
step is less than 0.01 or if the scale value has departed by 100% of the
initial value.  In the latter case the scale value is left unchanged.

The search over the shifts and scales is repeated a second time after which
the tweak algorithm terminates.

After the optional cross-correlation and tweak steps the interactive search
mode may be entered.  This occurs if \fIinteractive\fR = yes.  A query is
asking whether to search interactively.  The answers may be "no", "yes",
"NO", or "YES".  The lower case answers apply to the current spectrum and
the upper case answers apply to all subsequent spectra.  This means that if
an answer of "NO" or "YES" is given then there will be no further queries
for the remaining input spectra.

If the interactive step is selected a graph of three candidate corrections
for the input spectrum is displayed.  There also may be a graph of the
calibration or input spectrum shown for reference.  Initially the
calibration spectrum is displayed.  The additional graph may be toggled off
and on and between the input and calibration spectra with the 'c' and 'd'
keys.  The three candidate corrected spectra will be with the current shift
and scale in the middle and plus or minus one step in either the shift or
scale.  Initially the spectra will be at different scale values.
Information about the current shift and scale and the step used is given in
the graph title.

One may toggle between shift steps and scale steps with the 'x' (for shift)
or 'y' (for scale) keys.  The RMS in the title is the RMS within the
currently defined sample regions.  If one of the step values is zero then a
display of different values of that parameter will not be selected.  The
step size will need to be set with a colon command to search in that
parameter.

If 'x' is typed when the three spectra are at different shifts then the
nearest spectrum to the y cursor at the x cursor position will be
selected.  If the central spectrum is selected the step size is divided in
half otherwise the current shift is changed and the  selected spectrum
becomes the middle spectrum.  Three new spectra are then shown.  The same
applies if 'y' is typed when the three spectra are at different scales.
This allows an interactive search similar to the iterative tweakrms method
described previously except the user can use whatever criteria is desired
to search for the best scale and shift.

There are additional keystrokes and colon commands to set or change sample
regions, reset the current shift, scale, and step sizes, expand the step
size in the current mode, adjust the offsets between the spectra, and
get help.  The 'w' key and GTOOLS colon commands are available to window
the graphs.  Any changes in the x limits apply to both graphs while y limit
adjustments apply to the graph pointed to by the cursor.

Two other commands require a short explanation.  The 'a' key may
be used to run the tweakrms algorithm starting from the current
shift, scale, and steps and the current sample regions.  This allows
one to graphically set or reset the sample regions before doing
the RMS minimization.  The ":smooth" command and associated
\fIsmooth\fR task parameter allow the corrected spectra to be
displayed with a boxcar smoothing to better see faint features in
noise.  It is important to realize that the smoothing is only
done on the displayed spectra.  The telluric correction and computed RMS
are done in the unsmoothed data.

After the interactive step is quit with 'q' or if the interactive
step is not done then the final output spectrum is computed and
written to the output image.  A brief log output is printed for
each spectrum.
.ih
CURSOR KEYS AND COLON COMMANDS
.nf
? - print help
a - automatic RMS minimization within sample regions
c - toggle calibration spectrum display
d - toggle data spectrum display
e - expand (double) the step for the current selection
q - quit
r - redraw the graphs
s - add or reset sample regions
w - window commands (see :/help for additional information)
x - graph and select from corrected shifted candidates
y - graph and select from corrected scaled candidates

:help           - print help
:shift  [value] - print or reset the current shift
:scale  [value] - print or reset the current scale
:dshift [value] - print or reset the current shift step
:dscale [value] - print or reset the current scale step
:offset [value] - print or reset the current offset between spectra
:sample [value] - print or reset the sample regions
:smooth [value] - print or reset the smoothing box size
.fi
.ih
EXAMPLES
1.  To interactively search for a best correction with the default
cross-correlation and tweak steps:

.nf
    cl> telluric spec001.ms telspec001.ms spec005.ms
.fi

2.  To search only for a scale factor:

.nf
    cl> telluric spec001.ms telspec001.ms spec005.ms xcorr- dshift=0.
.fi

3.  To processes a set of spectra non-interactively with the same calibration
spectrum and to replace the input spectra with the corrected spectra and
log the processing:

.nf
    cl> telluric spec* "" calspec inter- > log
.fi

4.  To apply the simplest scaling by the ratio of the airmasses alone:

.nf
    cl> telluric spec* tel//spec* calspec inter- xcorr- tweak- inter- \
    >>> scale=1. shift=0.
.fi
.ih
REVISIONS
.ls TELLURIC V2.12.3
The normalization is printed.
.le
.ls TELLURIC V2.11.2
Threshold parameter added.
.le
.ls TELLURIC V2.11
This task is new in this version.
.le
.ih
SEE ALSO
skytweak
.endhelp
