Repatch (from linux) of OSX IRAF

1 files changed, 532 insertions, 0 deletions

diff --git a/noao/twodspec/multispec/doc/multispec.ms b/noao/twodspec/multispec/doc/multispec.ms
new file mode 100644
index 00000000..cc17352e
--- /dev/null
+++ b/noao/twodspec/multispec/doc/multispec.ms
@@ -0,0 +1,532 @@
+.EQ
+delim	$$
+.EN
+.TL
+The Multi-Spectra Extraction Package (multispec)
+.AU
+Francisco Valdes
+.AI
+IRAF Group
+.K2
+October 1984
+.NH
+Introduction
+.PP
+This document provides an introduction and overview of the multi-spectra
+extraction package \fBmultispec\fR.  Detailed descriptions and usage
+information for the tasks of the package are available in the manual
+pages.  The tasks in the package are:
+
+.TS
+center;
+n.
+findpeaks \&- Find the peaks
+fitfunction \&- Fit a function to the spectra parameter values
+fitgauss5 \&- Fit spectra profiles with five parameter Gaussian model
+modellist \&- List data and model pixel values
+msextract \&- Extract spectra
+mslist \&- List entries in a MULTISPEC database
+msplot \&- Plot a line of image and model data
+msset \&- Set entries in a MULTISPEC database
+newextraction \&- Create a new MULTISPEC extraction database
+newimage \&- Create a new multi-spectra image
+.TE
+
+.PP
+The \fBmultispec\fR package is a subpackage of the \fBtwodspec\fR package.
+It provides tools to locate, model, clean, correct for blending,
+and extract integrated or strip spectra from two dimensional, multi-spectra
+images.  These tools may be used directly or combined in scripts to
+extract specific types of spectra or spectra from specific instruments.
+Examples of the latter usage are the tasks in the image reduction package
+\fBcryomap\fR.
+.PP
+The extraction of spectra consists of locating pixels along each
+image line which intersect the spectra and recording either the sum of
+the pixels, \fIintegrated spectra\fR (some times referred to as
+one-dimensional spectra), or the set of pixels,
+\fIstrip spectra\fR, for each line and for each spectrum as output.
+The size and limits of the intersection region are specified by the
+user relative to the centers of the spectra.
+The locations of the spectra in each image line are determined separately
+so that the spectra need not be aligned along the columns of the image nor
+be perfectly straight.  However, since the extraction is done by image line,
+if the spectra are not aligned with the columns then the spectral resolution
+will be decreased.  If the spectra are aligned with the image lines then
+the image should be rotated or transposed using \fBimtranspose\fR.
+.PP
+The \fBmultispec\fR extraction produces three dimensional images with
+one image band (the third dimension) for each extracted spectrum
+and one line (the second dimension) for each extracted image line.
+For integrated spectra there is only one column
+while for strip spectra, the number of columns is equal to the extraction
+strip width.  The strips are aligned to the same positions relative to the
+spectra centers by image interpolation.  If desired the output extractions can
+be reformated in a variety of ways.
+.PP
+In addition to direct extraction of the image spectra the \fBmultispec\fR
+package provides for modeling the spectrum profiles.  The model
+may be extracted instead of the image spectra as either integrated or
+strip spectra.  The model may be used to correct for blending of the spectra
+and to detect and replace bad pixels.  The cleaning replaces data pixels which
+are discrepant from the model by the model values.
+.PP
+The modeling and cleaning features of the \fBmultispec\fR package can also
+be used for creating new multi-spectra images.  In other words a new
+image is created containing cleaned or model spectra for selected
+lines.
+.PP
+Section 2 gives an overview of the \fBmultispec\fR package and the extraction
+process.  The next section briefly describes the tasks in the package.
+This is followed by a description of the extraction database.
+The final section defines the model profiles used in the \fBmultispec\fR
+package.
+.NH
+Overview of the Multispec Package and the Extraction Process
+.PP
+The \fBmultispec\fR package consists of general and flexible tools
+for creating and manipulating databases which describe multi-spectra
+images.  The contents of the databases are described in a later section.
+Each database is associated with a particular image and is referenced
+through the image name.  The first positional argument in all the
+\fBmultispec\fR tasks is an image.  In the current version of the package each
+database exists as a separate binary file with a filename formed by adding
+the extension '.db' to the image name.  Note, however, that this
+need not be the case in the future.
+.PP
+The organization of the package as a set of tools operating on a database
+allows room for the package to evolve.  Different algorithms may be
+designed for different types of multi-spectra images by using combinations
+of the existing tools and by adding new tools.  The discussion below
+points out areas where new tasks might be added as well as citing the
+applicable existing tasks.
+.PP
+The extraction of spectra from a multi-spectra image consists of two
+basic steps; determining the locations of the spectra in the image and
+extracting the spectra.  The positions of the spectra in a multi-spectra
+image are determined at a set of "sample" image lines.  These positions
+are used to fit an interpolation function defining the spectrum positions
+at all the image lines.  This function is then used in the extraction of
+the spectra.
+.PP
+The sample image lines are chosen by the user when the database is first
+created by the task \fBnewextraction\fR.  An exception to this is when
+a template image is used (discussed below).  However, in this case the
+sample image lines are still those chosen by the user when the template
+image database was created.  The sample image lines may consist of
+anywhere from one image line to all the image lines.  The purpose
+of the sample lines is to sample the image often enough to follow changes
+in the positions and shapes of the spectra but to still minimize the
+time spent in finding the spectra and the size of the database.  The choice
+of sample lines also depends on the algorithm used to determine the
+positions of the spectra; a large number of sample
+lines for a fast, approximate method and a smaller number of lines
+for a complex and accurate method.  For example, in order to deal with
+very blended spectra the task \fBfitgauss5\fR provides a sophisticated
+model fitting algorithm.  This technique is computationally slow and, so,
+the user should not choose too many sample lines.
+.PP
+After the database has been created the minimum information needed
+for extraction is the spectrum positions at the sample lines.  There
+are many ways in which the positions may be determined.  Some
+possibilities are listed below.
+
+.IP (1)
+Enter the spectrum positions from a list using \fBmsset\fR.  The
+list might be generated from a graphics/cursor task.
+This is method is very time consuming when the number of spectra and
+the number of images are large.
+.IP (2)
+Determine the spectrum positions automatically by finding the peaks in
+each sample image line.  The task \fBfindpeaks\fR performs this function.
+.IP (3)
+Determine the spectrum positions at just one sample image line
+using either (1) or (2) and trace the spectra by a fast and refined
+peak finding method.  Such a task is desirable but is not a part of the
+current package.
+.IP (4)
+Determine the spectrum positions at just one sample image line
+using either (1) or (2) and trace the spectra by fitting model
+spectrum profiles.  The task \fBfitgauss5\fR does this using
+the model gauss5 described in section 5.  Additional model fitting
+tasks can be added as needed.
+.IP (5)
+Use the positions determined for a previous image and, if necessary,
+refine the positions.  \fBFitgauss5\fR is used to
+refine the spectrum positions at each sample line independently.
+
+.PP
+Several position finding algorithms may be used in stages to achieve
+the degree of accuracy required by the user.
+Thus, the first position determinations may be relatively crude and
+then, if needed, more sophisticated methods may be applied to refine the
+positions.  The task \fBfindpeaks\fR is a crude peak finder.  The positions
+are only determined to the nearest pixel.  The task \fBfitgauss5\fR is
+a sophisticated model fitting techique which is used after \fBfindpeaks\fR
+first determines the approximate positions of the spectra.
+.PP
+The determination of the spectra locations may be performed independently
+at each sample line as in (1) and (2) above or the spectra locations may
+be traced starting from one sample line as in (3) and (4).  The second method
+is preferable.  Generally, \fBfindpeaks\fR is used at only one sample line
+to initially determine the number and approximate locations of the spectra.
+\fBFitgauss5\fR then fits model gauss5 to the spectrum profiles and
+the model solution is used at the next sample line as the starting
+point for the next model fit.  In this manner the positions of
+the spectra are determined at the other sample image lines.
+.PP
+The results of the peak finding and profile fitting are improved
+by using an average of many image lines about the sample image line rather
+than just the sample image line by itself.  Both \fBfindpeaks\fR and
+\fBfitgauss5\fR have this ablility.
+.PP
+It is often the case that several multi-spectra images have essentially
+the same format; i.e. the same image size, the same number of spectra,
+and the same positions (either approximately or identically).
+Commonly, one of the images is used for calibrations and has strong,
+high signal-to-noise spectra while the other images have weaker spectra.
+In this case it is not necessary to repeat the position determinations.
+The spectrum positions in one of the images, generally the one with
+the strong calibration spectra, are determined first.  This image is
+then used as a "template" to provide the initial position estimates for
+the other images.  If the positions are identical no further work is needed,
+otherwise, the positions can be refined to correct for small changes in the
+positions and shapes of the spectra.
+.PP
+The task \fBnewextraction\fR creates new databases.  If a template image
+is specified then a copy is made of the template image database.  This means
+that the number of spectra and the sample image lines remain the same.
+If the spectrum positions are slightly different from the template image
+then the task \fBfitgauss5\fR is used to determine the new positions.
+.PP
+The spectrum positons and possibly any model parameters are interpolated
+from the sample lines to the remaining image lines by fitting a function
+to values at the sample lines.  In addition, the function fits may
+leave out poorly determined points and also smooth the values at the
+sample lines.  The task \fBfitfunction\fR fits selected functions of
+specified order to the selected spectra and sample image lines.
+.PP
+The extraction of the spectra from multi-spectra images is performed by
+the task \fBmsextract\fR.  The task extracts either integrated or strip
+spectra, either data or model values, with or without blending corrections,
+and with or without replacing bad pixels by model values.
+The user specifies the limits of the extraction
+strip as well as the spectra and image lines to be extracted.
+.PP
+For the simplest type of data extractions (basically strip extraction)
+no modeling is required.  Other types of extractions, such as model
+extractions and/or with cleaning and blending corrections require some
+degree of modeling.  There are two models which may be used;
+"smooth" and "gauss5".  These models are described in section 5.
+The model parameters for model gauss5 must be set by \fBfitgauss5\fR
+before \fBmsextract\fR is used.  Additional models may added for
+extraction as well as for the spectrum position determinations.
+.PP
+The model based features of \fBmsextract\fR -- model extractions
+and cleaning -- are available in the related task \fBnewimage\fR.
+This task creates new images which consist of either model spectra
+or cleaned data spectra.
+.PP
+The models in the \fBmultispec\fR package assume that the profiles
+go to zero; i.e. there is no background light.  Background light
+may be removed using \fBbackground\fR.  In the future a task will
+be provided create a mask defining the locations of the spectra from
+the database which can be used with general surface fitting tasks
+to create a background surface to be subtracted from the image.
+.PP
+The final step in using the \fBmultispec\fR package is to convert the
+extraction output to the desired format.  This may include graphs,
+card image formats, and files for the \fBonedspec\fR and \fBlongslit\fR
+packages.  Currently, the available formats are images and IIDS
+card images.
+.NH
+The Tasks of the Multispec Package
+.PP
+Use of the \fBmultispec\fR package begins with \fBnewextraction\fR and
+ends, usually, with \fBmsextract\fR.  In between there are tasks which
+update, refine or change the database and tasks which provide diagnositic
+information.  The informational tasks can be combined with tasks from
+other packages to produce tabular or graphical output.  The task
+\fBmsplot\fR is an example.  In this section a brief description of
+each task is given.  Further information about the tasks, including usage,
+is available in the manual pages.
+.SH
+findpeaks
+.IP
+Selected sample image lines are examined to determine the number and
+column positions of data peaks in the line.  An average of a number of image
+lines surrounding the sample lines is formed in which the local maxima
+are located.  Various criteria are applied to cull the list of local
+maxima to the desired peaks.  These criteria include a peak threshold,
+a maximum peak-to-peak contrast, a minimum peak separation, and a
+maximum number of peaks.  This task is used to determine crude, initial
+estimates for the spectrum positions.  It could be used alone for
+simple extractions.
+.SH
+fitfunction
+.IP
+This task has two roles.  It's primary role is to define the
+interpolation/extrapolation function for the spectra
+positions between the sample lines.  The fitting function can be
+either purely interpolative or may also provide smoothing of the
+parameters from the sample lines.  The second role is to provide
+smoothing of the model parameters along the dispersion and the
+ability to replace bad values by the function fit to the remaining
+parameters.  In this second role the user may iterate between
+smoothing and model fittng.  The functions are always defined between
+the first and last image lines.
+.SH
+fitgauss5
+.IP
+The model profiles gauss5, described in section 5, are fit to the
+selected spectra and sample lines.  The parameters to be determined
+and the fitting algorithm may also be selected.
+The model parameters are recorded in the database.
+The model may be tracked from a starting line to other sample image
+lines or each sample line may be fitted independently.
+This task is used to accurately determine the spectrum positions
+and provide an extraction model for heavily blended spectra.
+.SH
+modellist
+.IP
+For the selected sample image lines and image columns data
+and model values are listed.  This task is used to check how well
+the model fitting tasks (currently just \fBfitgauss5\fR) have fit
+the sample image line.  The task \fBmsplot\fR is used to produce
+graphical output.
+.SH
+msextract
+.IP
+This task does the actual extraction of spectra.  It requires that
+the spectrum positions are defined by fitting functions in the
+database.  If model gauss5 is to be used then the database must
+also contain the model parameters for the sample image lines.  It
+extracts integrated or strip spectra, using data or model values,
+with or without blending corrections, and with or without cleaning
+of bad pixels.
+.SH
+mslist
+.IP
+Of the diagnositic or informational tasks \fBmslist\fR is the most
+general.  The user selects the type of information from the database
+which is desired and it is then printed.  The types of information
+include the database header, the database comments, the spectra
+positions and model parameter values for the sample lines, and the
+interpolation/smoothing function values for any desired set of
+image lines.
+.SH
+msplot
+.IP
+This task extracts data and models values and plots them superposed.
+This task is used as a diagnositic tool to inspect how well model fitting
+represents the image spectra.
+.SH
+msset
+.IP
+This task is a general tool for modifying or setting some of the quantities 
+in the database.  The quantity to be changed or set is
+selected by a keyword and the values are input in two ways;
+with a list structured parameter (such a file containing the list of
+values or the standard input) or as a parameter value.  This task
+is the way a user may enter comments in the database or manually
+set the number and positions of the spectra.  It is also used to
+set the initial values for the gauss5 model parameters s0, s1, and s2
+prior to using \fBfitgauss5\fR.
+.SH
+newextraction
+.IP
+This task has three important roles.  First it creates the database
+associated with the multi-spectra image.  Second, it defines the sample
+image lines to be used.  The user can specify as many or as few sample lines
+as desired.  It should be kept in mind that the more sample lines used
+the larger the database becomes and the longer the processing time when
+modeling the spectra.  Finally, \fBnewextraction\fR allows
+a database from another image (called a template image) to initialize the
+database for the new multi-spectra image.  The template image is generally
+a calibration image with strong, well-defined spectra.
+Initializing a database with a template image saves time, reduces problems
+with bad pixels, and is more accurate when an image with weak spectra is
+to be extracted.
+.SH
+newimage
+.IP
+This task is similar to \fBmsextract\fR; it uses the same algorithms
+and parameters.  It differs in the type output.
+Rather than producing extracted integrated or strip spectra this task
+produces new image lines.  It is particularly useful for extracting
+model images to be compared against the original image or to
+produce images which have been cleaned.
+.NH
+The Multispec Database
+.PP
+The tasks in the \fBmultispec\fR package create and manipulate a database.
+The database contains a description of the multi-spectra image which
+is modified, refined, examined, or otherwise used by the tasks in the package.
+In the current version the database is a separate binary file with a filename
+formed by appending ".db" to the image name described by the database.
+.PP
+The database contains four basic types of data; general information,
+comments and history, position parameters, and model parameters.
+The data in the database is examined with the task \fBmslist\fR.
+The general information section, called the database header, contains the
+the name of the image, the size of the image, and the number of spectra in
+the image.  Once the number of spectra in the image has
+been entered in the database it is an error to attempt to change this
+number.  The database must be deleted and a new database created in order
+to change the number of spectra.
+.PP
+The comment and history section of the database contains text
+strings.  Each task which modifies the contents of the database places
+a dated history line in this section.  The user may also add comments
+with \fBmsset\fR.  Currently this information is not passed on to
+the extraction output.
+.PP
+There are three types of position information in the database.  The
+first is a set of sample image lines.  The sample lines are set when
+the database is created by \fBnewextraction\fR.  The sample lines select
+which image lines from the multi-spectra image are to be examined and used
+during the extraction.  Information from these sample lines, and only
+these sample lines, is entered in the database.  The sample lines
+may be listed with \fBmslist\fR.
+.PP
+The second type of position information is the positions of the
+spectra (centers) at each sample line.  These positions are initially
+set by either \fBfindpeaks\fR or, manually, by \fBmsset\fR.  The
+position information is refined by fitting model profiles.
+.PP
+The third type of position information is a function fit to the
+positions from all the sample lines for each spectrum.
+These function fits are produced by \fBfitfunction\fR.
+The functions define the positions of the spectra at all the image
+lines.  The spectra positions at the sample lines or the function
+evaluation for any image line may be listed with \fBmslist\fR.
+.PP
+The finally type of basic data contained in the database are
+model parameter values.  A model need not be used in the extraction
+but if one is used then the parameters determining the model profiles
+are recorded in the database.  The specific parameters depend on the
+model.  Currently the only model is \fIgauss5\fR.  The model and its
+parameters are described in section 5.
+.PP
+As with the spectra positions the parameters are stored in the database
+in two forms; as values for each spectrum at each sample image line
+and as function fits to the values at the sample lines which interpolate
+them to any image line.  The sample line values are
+set by the model fitting tasks and the function fits are set by
+\fBfitfunction\fR.  The parameter values at the sample lines or the
+function evaluations for any image lines may be listed with \fBmslist\fR.
+.NH
+Multispec Spectrum Profile Models
+.PP
+The spectra profiles in the image are modeled for many reasons:
+To provide accurate, subpixel position determinations, to extract model
+spectra or model images, to detect and replace bad pixels, and
+to estimate and correct for blending between the spectra.
+There are currently two models used in the \fBmultispec\fR package, "gauss5"
+and "smooth".
+.NH 2
+Model Gauss5
+.PP
+The gauss5 model profiles are Gaussian but with a scale which varies
+smoothly between the center and the edge of the profile.  There
+are five parameters:
+
+.RS
+.IP x0
+The column position in the image line of the center of the profile.
+.IP i0
+The intensity scale of the profile.  It corresponds to the intensity
+of the center of the profile.
+.IP s0
+The zeroth order, constant, term in the Gaussian scale.
+.IP s1
+The even first order term in the Gaussian scale.
+.IP s2
+The odd first order term in the Gaussian scale.
+.RE
+
+.PP
+The mathematical form of the the model is shown in equation (1):
+.EQ (1)
+roman profile (x)~=~i0 exp~left { -s( DELTA x )~DELTA x sup 2 right }
+.EN
+where
+.EQ
+DELTA x ~=~x~-~x0~,
+.EN
+.EQ
+s( DELTA x)~=~s0~+~s1~|y| +~s2~y~,
+.EN
+and
+.EQ
+y~=~ DELTA x / ( DELTA x sup 2 + alpha ) sup half ~.
+.EN
+The profile is defined within the user specified limits \fIlower\fR and
+\fIupper\fR measured relative to the the profile center and
+$alpha~=~(upper-lower)/4$.  The quantity $y$ lies in the range
+-1 to 1 over the interval in which the profile is defined.  The odd
+and even terms, s1 and s2, allow for symmetric and antisymmetric profile
+changes relative to a simple Gaussian profile.
+.PP
+The task \fBfitgauss5\fR fits the gauss5 model to the spectrum profiles in
+the sample image lines to determine one or more of the model parameters for
+each spectrum.  The parameter values are stored in the database for the image.
+In \fBmsextract\fR the model profiles for each
+image line are obtained by interpolating the profile shapes from the sample
+lines (with the model parameters in the database determined by
+\fBfitgauss5\fR) and then fitting only the intensity scale "i0".
+There are a number of technical details associated with the model fitting
+in each of these tasks which are discussed in the manual pages.
+.PP
+The gauss5 model is used to accurately determine the positions of the
+spectrum centers at the sample image lines.  Fitting simultaneously
+for the model parameters allows the spectra to be blended.
+This is the chief advantage of this model.
+This model is also used during extraction to correct for blending of
+the spectra and to detect and replace bad pixels.
+.NH 2
+Model Smooth
+.PP
+The spectrum profiles from the lines immediately preceeding
+the image line in which the spectrum profile is to be fit are shifted
+to a common center and averaged to form the model profile.
+An intensity scale factor is then determined which best fits the model
+profile to the image profile.  This is done for each spectrum in the
+image.  The scale factors are determined by least squares with
+possible bad pixel rejection.  Rejected pixels are eliminated
+when the image line is later used in forming new average model profiles.
+.PP
+The advantages of this model are that the image spectrum profiles may
+have any shape and the least squares fitting with bad pixel rejection
+is fast and rigorous.  By passing through the image lines sequentially
+the image lines need be accessed only once and the profile averages
+can be quickly updated for the next image line.
+.PP
+The disadvantages of this model are that the spectrum profiles cannot
+be blended and the model does not measure profile positions.
+This means that the spectrum profile positions must be
+known.  This model is suitable for model extractions and cleaning of
+bad pixels in unblended multi-spectra images.  It is available in
+the task \fBmsextract\fR.
+.bp
+.SH
+Glossary
+.LP
+\fBmultispec\fR
+.IP
+Acronym for Multi-Spectra Extraction as in \fBmultispec\fR Package.
+.LP
+integrated spectra
+.IP
+The spectra are extracted by integrating the pixel values across the spectrum
+to produce a single aperture luminosity value.
+.LP
+sample image line
+.IP
+The spectra positions and model profile shapes are determined at a set
+of image lines selected when the database is created.
+.LP
+strip spectra
+.IP
+The spectra are extracted as a strip of fixed with the spectra shifted by
+image interpolation to a common center.