Initial commit

1 files changed, 382 insertions, 0 deletions

diff --git a/noao/onedspec/doc/sys/revisions.v3.ms b/noao/onedspec/doc/sys/revisions.v3.ms
new file mode 100644
index 00000000..1c3da8be
--- /dev/null
+++ b/noao/onedspec/doc/sys/revisions.v3.ms
@@ -0,0 +1,382 @@
+.nr PS 9
+.nr VS 11
+.RP
+.ND
+.TL
+ONEDSPEC Package Revisions Summary: IRAF Version 2.10
+.AU
+Francisco Valdes
+.AI
+IRAF Group - Central Computer Services
+.K2
+P.O. Box 26732, Tucson, Arizona 85726
+July 1990
+.AB
+This paper summarizes the changes in Version 3 of the IRAF \fBonedspec\fR
+package which is part of IRAF Version 2.10.  The major new features and
+changes are:
+
+.IP \(bu
+\fBIdentify\fR and \fBreidentify\fR now treat multispec format spectra
+and two dimensional images as a unit.
+.IP \(bu
+\fBReidentify\fR supports both tracing (the old method) and always starting
+with the primary reference vector when reidentifying other vectors in a
+two dimensional reference image.
+.IP \(bu
+\fBReidentify\fR matches reference lines or apertures when reidentifying
+those vectors in different images rather than tracing.
+.IP \(bu
+\fBReidentify\fR has an interactive capability to review
+suspect reidentifications.
+.IP \(bu
+\fBReidentify\fR provides the capability to add new features.
+.IP \(bu
+The task \fBmsdispcor\fR provides for spatial interpolation of wavelength
+zero point shifts from simultaneous arc spectra.
+.IP \(bu
+The new task \fBscopy\fR copies subsets of apertures and does format
+conversions between the different spectrum formats.
+.IP \(bu
+The new task \fBsapertures\fR adds or modifies beam numbers and
+aperture titles for selected apertures based on an aperture
+identification file.
+.IP \(bu
+The new task \fBsfit\fR fits spectra and outputs the fits in various ways.
+Apertures in  multispec and echelle format are fit independently.
+.IP \(bu
+The task \fBcontinuum\fR now does independent fits for multispec and
+echelle format spectra.
+.IP \(bu
+\fBSplot\fR now allows deblending of any number of components and
+allows simultaneous fitting of a linear background.
+.IP \(bu
+The new task \fBfitprofs\fR fits 1D gaussian profiles in images.
+.AE
+.NH
+Introduction
+.PP
+Though  most of the ONEDSPEC package is unchanged there have been
+significant changes to a number of the commonly used tasks in IRAF
+Version 2.10.  The changes will be made available as part of an
+external package prior to the release of V2.10.  This paper summarizes
+the changes and new features.  The changes primarily apply to multispec
+or echelle format spectra.
+.PP
+Tables 1 and 2 summarize most of the major and minor changes in the package.
+
+.ce
+TABLE 1:  Summary of Major New Features and Changes
+
+.IP \(bu
+\fBIdentify\fR and \fBreidentify\fR now treat multispec format spectra
+and two dimensional images as a unit allowing easy movement between
+different image lines or columns.  The database is only updated upon
+exiting the image.
+.IP \(bu
+\fBReidentify\fR supports both tracing (the old method) and always starting
+with the primary reference vector when reidentifying other vectors in a
+two dimensional reference image.
+.IP \(bu
+\fBReidentify\fR matches reference lines or apertures when reidentifying
+those vectors in different images rather than tracing.
+.IP \(bu
+\fBReidentify\fR has an interactive capability to review
+suspect reidentifications.
+.IP \(bu
+\fBReidentify\fR provides the capability to add new features.
+.IP \(bu
+The task \fBmsdispcor\fR allows using
+auxilary reference spectra to provide a shift in the wavelength
+zero point to the primary dispersion functions.  This includes
+spatial interpolation of simultaneous arc spectra in multifiber
+spectrographs.
+.IP \(bu
+The new task \fBscopy\fR copies subsets of apertures and does format
+conversions between the different spectrum formats.
+.IP \(bu
+The new task \fBsapertures\fR adds or modifies beam numbers and
+aperture titles for selected apertures based on an aperture
+identification file.
+.IP \(bu
+The new task \fBsfit\fR fits spectra and outputs the fits in various ways.
+This includes a new feature to replace deviant points by the fit.
+Apertures in  multispec and echelle format are fit independently.
+.IP \(bu
+The task \fBcontinuum\fR now does independent fits for multispec and
+echelle format spectra.
+.IP \(bu
+\fBSplot\fR now allows deblending of any number of components and
+allows simultaneous fitting of a linear background.
+.IP \(bu
+The new task \fBfitprofs\fR fits 1D gaussian profiles to spectral lines or
+features in an image line or column.  This is done noniteractively and
+driven by an input list of feature positions.
+.bp
+.LP
+.ce
+TABLE 2:  Summary of Other New Features and Changes
+
+.IP \(bu
+The \fBidentify\fR database format uses aperture numbers rather than
+image sections for multispec format spectra.
+.IP \(bu
+The apertures in multispec format images need not be in the same order
+or even the same number of apertures as the reference image in
+\fBreidentify\fR or \fBmsdispcor\fR.
+.IP \(bu
+An automatic write parameter has been added to \fBidentify\fR.
+.IP \(bu
+The tasks \fBmsdispcor\fR and \fBspecplot\fR support the extra information
+in the third dimension of multispec format spectra which is optionally
+output by the \fBapextract\fR package.
+.IP \(bu
+\fBMsdispcor\fR and \fBspecplot\fR now include a logfile.
+.IP \(bu
+\fBSplot\fR selects spectra from multispec or echelle format by their
+aperture number.  Also a new keystroke was added to select a new
+line/aperture without having to enter the image name again.
+.IP \(bu
+The task \fBspecplot\fR may select apertures from a multispec or
+echelle format spectrum.
+.IP \(bu
+The aperture identification in multispec format is used, if present,
+for labeling in \fBsplot\fR, \fBspecplot\fR, and \fBstandard\fR.
+.NH
+IDENTIFY and REIDENTIFY
+.PP
+These tasks have been modified for greater flexibility when dealing with
+two dimensional images and multispec format spectra in particular.  These
+tasks were initially designed primarily to work on one dimensional images
+with provisions for two dimensional images through image sections and
+tracing to other parts of the image.  Now these tasks treat such images
+as a unit.
+.PP
+The task \fBidentify\fR has three added keystrokes, 'j', 'k', and 'o'.
+These provide for moving between lines and columns of a two dimensional
+image and different apertures in a multispec format spectrum.  When
+changing vectors the last set of features and fit are recalled, if they
+have been previously defined, or the last set of features and fit are
+inherited.  For efficiency and to minimize queries, the feature
+information from all the lines or apertures is not written to the
+database until you quit the image (or explicitly write it) rather than
+one at a time.  A new parameter was also added, \fIautowrite\fR, which
+may be set to automatically write the results to the database rather
+than querying as is currently done.
+.PP
+The format of the database entries have also been slightly modified in
+the case of multispec format images.  Instead of using image sections
+as part of the image name to define different vectors in the image
+(this is still the case for regular two dimensional images) the aperture
+number is recorded.  This decouples the solutions for an aperture from
+the specific image line allowing reference images to have a different
+aperture order and additional or missing apertures.
+.PP
+While the changes to \fBidentify\fR are minor as far as usage, the task
+\fBreidentify\fR is quite different and is essentially a new program.
+Much of the complexity in this task relates to two dimensional images.
+Two additions that apply to both one and two dimensional images is the
+capability to add features from a coordinate list and to interactively
+review the reidentifications using \fBidentify\fR.  The addition of new
+features may be useful in cases where the signal-to-noise varies or to
+compensate for lost features when tracing across an image.  The review
+capability first prints the statistical results and then ask the user if
+they want to examine the results interactively .  This allows
+basing the decision to interactively examine the features and fit based
+on this information.  Ideally, only a few of the worst cases need be
+examined interactively.
+.PP
+There are two phases of reidentifications which apply to two
+dimensional and multispec format images.  In the first phase, one needs
+to expand the identifications in the reference image from an initial,
+interactively defined line, column, or aperture to other parts of the
+reference image.  A very important change is that there are now two
+ways to transfer the features list; by successive steps (tracing) using
+the previous results as a starting point (the only method provided in
+the previous version) or always starting from the original reference
+list.  The first method is suitable for long slit spectra which have
+significant positional trends across the image.  If a feature is lost,
+however, the feature remains missing (barring automatic addition as
+mentioned above) for all following lines or columns.  The latter method
+is best if there are only small variations relative to the initial
+reference or in multispec format spectra where there is no inherent
+relation between apertures.
+.PP
+The second phase of reidentifications is between the reference image
+and other images.  In the previous version the primary reference vector
+was transferred to the new image and then tracing would be applied
+again.  This compounds the problem with losing features during tracing
+and prevents any possible reidentifications from multispec images in
+which the wavelength range may vary greatly.  In the new version there
+is a direct reidentification from the same line, column, or aperture in
+the reference to that of the next image.  In the case where different
+apertures may have significantly different wavelength coverage, as
+occurs with aperture masks, it will at least be possible to
+interactively identify features and coordinate functions for each
+aperture, using the scrolling capability in the new \fBidentify\fR, in
+just a single image and then correctly transfer the features to
+additional images.
+.PP
+For multispec format spectra the database information is organized by
+aperture number independent of image line number.  Thus, it is possible
+to reidentify features in multispec format spectra even if the aperture
+order is different.  If there is only a partial overlap in the aperture
+set only those apertures having an entry in the reference image will be
+done.
+.NH
+MSDISPCOR
+.PP
+The task \fBmsdispcor\fR dispersion corrects (rebins to a linear
+dispersion function) multispec format spectra.  It was introduced in
+V2.8 of IRAF in the prototype \fBimred.msred\fR package.  A number of
+changes have been made in this task as summarized here.
+.PP
+The most fundamental change is support for spatial interpolation of
+reference dispersion functions from a subset of apertures to other
+apertures originating at different positions in a two dimensional
+image.  This is primarily intended for the case of comparison arc
+spectra which are interspersed with object spectra in multifiber
+spectrographs.  It would also be useful in digitized photographic
+spectra having calibration spectra exposed next to the object
+spectrum.  While usable directly, this feature is intended for the
+processing scripts in the new \fBimred\fR fiber instrument packages.
+.PP
+The interpolation is only for a wavelength zero point shift, as determined
+by \fBreidentify\fR with \fIrefit\fR=no.  The full dispersion function
+is still provided by a calibration image covering all apertures.  Thus,
+the simultaneous arc apertures are used to monitor shifts in the
+detector relative to the full calibration which includes the relative
+differences between each aperture and the arc monitoring apertures.
+.PP
+The multispec spectra containing the apertures used for the spatial
+wavelength zero point corrections are specified in the image header
+using the keywords REFSHFT1 and REFSHFT2.  These are analogous to
+the REFSPEC keywords used to define the reference dispersion functions
+for the apertures.
+.PP
+As part of the general theme of multispec format support the
+multispec dispersion reference spectra may have additional spectra and
+need not be in the same order.  However, all aperture in the
+images being dispersion corrected must have dispersion relations
+in the database.  Multispec format spectra may include additional
+data in the 3rd image dimension produced by the new
+\fBapextract\fR package.  \fBMsdispcor\fR rebins this information
+in the same way as the spectra, thus, preserving the information
+but now in linear wavelength sampling.
+.PP
+A new parameter, \fIlogfile\fR, has been added to capture information
+about the dispersion correction process.
+.NH
+SCOPY and SAPERTURES
+.PP
+The task \fBscopy\fR is intended to bridge the gap between the various
+spectrum formats and provide a tool to flexibly manipulate multispec
+format spectra.  It replaces the more primitve tasks
+\fBmsred.msselect\fR and \fBechelle.ecselect\fR.  Basically, this task
+copies all or selected spectra from one format to a new image or images
+of the same or different format.  The typical uses are:
+
+.IP \(bu
+Extract selected spectra from a multispec format image.
+.IP \(bu
+Allow converting the voluminous onedspec format from previous reductions
+done before the multispec format was introduced into the more compact
+multispec format.
+.IP \(bu
+Splice selected apertures from different multispec images into a new
+multispec image.
+.IP \(bu
+Provide a quick way to convert lines or columns from two dimensional
+long slit images into one dimensional spectra.  This replaces
+the task \fBproto.toonedspec\fR.
+.PP
+Because \fBscopy\fR can easily change the number and order of apertures
+in the multispec image format it is important that the other tasks which
+use the multispec format have been modified to be insensitive to which
+line a spectrum is in and generally key off the aperture number.
+.PP
+The task \fBsapertures\fR is a simple way to set the aperture identifications,
+APID keyword, and beam number, second field of APNUM keyword, based on
+the aperture number and a simple text file.  The text file contains lines
+with aperture number, beam number, and (optional) title.  This file is
+used by the \fBapextract\fR package as well.  Its likely usage is
+to change image titles which might be wrong because of being inherited
+from an aperture reference image during extraction.
+.NH
+SFIT, CONTINUUM, and ECCONTINUUM
+.PP
+The original version of \fBcontinuum\fR was a simple script based on
+the task \fBfit1d\fR.  The problem is that \fBfit1d\fR is intended to
+process all the lines or columns in a two dimensional image
+noninteractively.  To do this it applies the same fitting parameters to
+every line or column.  The interactive step in this task is simply to
+adjust fitting parameters.  For spectra, particularly multispec and
+echelle format spectra, one often needs to fit each spectrum
+interactively and independently.  When this problem was encountered for
+the \fBechelle\fR package Rob Seaman wrote a nice program,
+\fBeccontinuum\fR, which allows fitting a set of orders and keeps track
+of which orders have been fit.
+.PP
+The general feature of the continuum fitting tasks is that they fit
+spectra using the \fBicfit\fR interactive function fitting interface.
+The results of the fit may be output as the fit itself, the difference
+or residuals, the ratio, or the input data with rejected points replaced
+by the fitted values.  The last feature is new an provides a useful
+spectrum cleaning option.  The general equivalent to \fBfit1d\fR is
+the new task \fBsfit\fR which provides the same independent fitting and
+image line selection capabilites as \fBeccontinuum\fR.  Note this task
+is line oriented and does not select by aperture or order number.  The
+revised version of \fBcontinuum\fR is now based on \fBsfit\fR and
+provides the independent continuum fitting capability for onedspec and
+multispec format spectra that \fBeccontinuum\fR provides for echelle
+format spectra.  Technically what has been done is that \fBsfit\fR,
+\fBcontinuum\fR, and \fBeccontinuum\fR are the same task; essentially
+the task written by Seaman for echelle data.  They differ in the
+default parameters with the continuum fitting task having default
+parameters providing continuum normalization (ratio) output and
+iterative rejection values for excluding lines.
+.NH
+SPLOT, FITPROFS, and SPECPLOT
+.PP
+\fBSplot\fR has been modified to better support multispec and echelle
+format images.  The line selection for multispec and echelle format
+spectra is now in terms of the aperture number rather than the image
+line.  The aperture title is used in place of the image title
+if present.
+.PP
+The restriction to a maximum of four lines in the gaussian fitting and
+deblending option of \fBsplot\fR has been lifted.  Any number of
+lines may be fit simultaneously, though execution time will become
+long for a large number.  In addition the fitting allows determining
+a simultaneous linear background as well as using the cursor defined
+points.  The positions of the lines to be fit may be marked with
+the cursor, typed in, or read from a file.  The last choice is a new
+feature.
+.PP
+In the past many people have used \fBsplot\fR for bulk, noninteractive
+gaussian fitting by going through the trouble of redirecting the cursor
+input, ukey input, text output, and graphics output.  The main reason
+this has been done is the lack of a one dimensional gaussian fitting
+task.  The task \fBfitprofs\fR has been added to provide simultaneous
+gaussian fitting.  This task takes a list of positions and optional
+sigmas and fits gaussians to a list of images or spectra.  The lines,
+columns, or apertures may be selected.  In addition a linear
+background may be specified or included in the fitting.  The output
+consists of any combination of text similiar to the \fBsplot\fR
+logfile, plots showing the data and fit, and image output of the fit or
+the difference.  This task is noninteractive; the interactive version
+is the deblend command of \fBsplot\fR.  The multiparameter, nonlinear
+fitting software is the same as used in \fBsplot\fR.
+.PP
+\fBFitprofs\fR complements the task \fBstsdas.fitting.ngaussfit\fR from
+the \fBstsdas\fR package (available from the Space Telescope Science
+Institute).  This task is similar in character to \fBfit1d\fR and has
+an interactive one dimensional nonlinear function fitting interface
+similar to \fBicfit\fR.
+.PP
+The task \fBspecplot\fR has a new parameter to select apertures to
+plot.  Previously there was no way to limit the apertures plotted other
+than with image sections.  All associated lines of a multispec
+spectrum (those in the third dimension) are also plotted for the
+selected apertures.  This extra information is a new option of the
+\fBapextract\fR package.