Initial commit

1 files changed, 541 insertions, 0 deletions

diff --git a/noao/onedspec/doc/scopy.hlp b/noao/onedspec/doc/scopy.hlp
new file mode 100644
index 00000000..d0863687
--- /dev/null
+++ b/noao/onedspec/doc/scopy.hlp
@@ -0,0 +1,541 @@
+.help scopy Mar93 noao.onedspec
+.ih
+NAME
+scopy -- Select and copy spectra
+.ih
+USAGE
+scopy input output
+.ih
+PARAMETERS
+.ls input
+List of input images containing spectra to be copied.
+.le
+.ls output
+List of output image names or root names.  Image
+sections are ignored and if the output format is "onedspec" then any record
+extensions are stripped to form the root name.  If no output list is
+specified then the input list is used and the input images are replaced by
+the copied output spectra.  If a single output name is specified then all
+copied spectra are written to the same output image or image root
+name.  This allows packing or merging multiple spectra and requires
+properly setting the \fIclobber\fR, \fImerge\fR, \fIrenumber\fR and
+\fIoffset\fR parameters to achieve the desired output.  If more than one
+output image is specified then it must match the input image list in
+number.
+.le
+.ls w1 = INDEF, w2 = INDEF
+Starting and ending wavelengths to be copied.  If \fIw1\fR is not specified
+then the wavelength of the starting edge of the first pixel is used
+(wavelength at pixel coordinate 0.5) and if \fIw2\fR is not specified then
+the wavelength of the ending edge of the last pixel is used (wavelength of
+the last pixel plus 0.5).  If both are not specified, that is set to INDEF,
+then the whole spectrum is copied and the \fIrebin\fR parameter is
+ignored.  Note that by specifying both endpoints the copied region can be
+set to have increasing or decreasing wavelength per pixel.  If the spectrum
+only partially covers the specified range only that portion of the spectrum
+within the range is copied.  It is an error if the range is entirely
+outside that of a spectrum.
+.le
+.ls apertures = "", beams = ""
+List of apertures and beams to be selected from the input spectra.  The
+logical intersection of the two lists is selected.  The null list
+selects all apertures or beams.  A list consists of comma separated
+numbers and ranges of numbers.  A range is specified by a hyphen.  An
+optional step size may be given by 'x' followed by a number.
+See \fBxtools.ranges\fR for more information.  If the first character
+is "!" then the apertures/beams not in the list are selected.  Note
+that a "!" in either of the lists complements the intersection of the
+two lists.  For longslit input spectra the aperture numbers
+selects the lines or columns to be extracted.  For 3D Fabry-Perot
+spectra the aperture numbers select the first spatial axis.
+.le
+.ls bands = ""
+List of bands in 3D multispec.
+For 3D spatial spectra the band parameter applies to the second
+spatial axis.
+The null list selects all bands.  The syntax is as described above.
+.le
+.ls apmodulus = 0
+Modulus to be applied to the input aperture numbers before matching against
+the aperture list.  If zero then no modulus is used.  This is allows
+selecting apertures which are related by the same modulus, typically a
+factor of 10; for example, 10, 1010 and 2010 with a modulus of 1000 are
+related.
+.le
+.ls format = "multispec" (multispec|onedspec)
+Output image format and name syntax.  The "multispec" format consists of
+one or more spectra in the same image file.  The "onedspec" format consists
+of a single spectrum per image with names having a root name and a four
+digit aperture number extension.  Note that converting to "onedspec" format
+from three dimensional images where the third dimension contains associated
+spectra will not include data from the extra dimension.  Image sections may
+be used in that case.
+.le
+.ls renumber = no
+Renumber the output aperture numbers?  If set the output aperture
+numbers, including any preexisting spectra when merging, are renumbered
+beginning with 1.  The \fIoffset\fR parameter may be used to
+change the starting number.
+.le
+.ls offset = 0
+Offset to be added to the input or renumbered aperture number to form
+the final output aperture number.
+.le
+.ls clobber = no
+Modify an existing output image either by overwriting or merging?
+.le
+.ls merge = no
+Merge apertures into existing spectra?  This
+requires that the \fIclobber\fR parameter be set.  If not merging
+then the selected spectra entirely replace those in existing output images.
+If merging then the input spectra replace those in the output image
+with the same aperture number and new apertures are added if not present.
+.le
+.ls rebin = yes
+Rebin the spectrum to the exact wavelength range specified by the \fIw1\fR
+and \fIw2\fR parameters?  If the range is given as INDEF for both endpoints
+this parameter does not apply.  If a range is given and this parameter is
+not set then the pixels in the specified range (using the nearest pixels to
+the endpoint wavelengths) are copied without rebinning.  In this case the
+wavelength of the first pixel may not be exactly that specified by \fIw1\fR
+and the dispersion, including non-linear dispersions, is unchanged.  If
+this parameter is set the spectra are interpolated to have the first and
+last pixels at exactly the specified endpoint wavelengths while preserving
+the same number of pixels in the interval.  Linear and log-linear
+dispersion types are maintained while non-linear dispersions are
+linearized.
+.le
+.ls verbose = no
+Print a record of each aperture copied?
+.le
+.ih
+DESCRIPTION
+\fBScopy\fR selects regions of spectra from an input list of spectral
+images and copies them to output images.  This task can be used to extract
+aperture spectra from long slit and Fabry-Perot images and to select,
+reorganize, merge, renumber, pack, and unpack spectra in many ways.  Below
+is a list of some of the uses and many examples are given in the EXAMPLES
+section.
+
+.nf
+   o Pack many spectra into individual images into a single image
+   o Unpack images with multiple spectra into separate images
+   o Extract a set of lines or columns from long slit spectra
+   o Extract a set of spatial positions from Fabry-Perot spectra
+   o Extract specific wavelength regions
+   o Select a subset of spectra to create a new image
+   o Merge a subset of spectra into an existing image
+   o Combine spectra from different images into one image
+   o Renumber apertures
+.fi
+
+Input spectra are specified by an image list which may include explicit
+image names, wildcard templates and @files containing image names.
+The image names may also include image sections such as to select portions of
+the wavelength coverage.  The input images may be either one or two
+dimensional spectra.  One dimensional spectra may be stored in
+individual one dimensional images or as lines in two (or three)
+dimensional images.  The one dimensional spectra are identified by
+an aperture number, which must be unique within an image, and a beam number.
+Two dimensional long slit and three dimensional Fabry-Perot spectra are
+treated, for the purpose of this
+task, as a collection of spectra with dispersion either along any axis
+specified by the DISPAXIS image header parameter
+or the \fIdispaxis\fR package parameter.  The aperture and band
+parameters specify a spatial position.  A number of adjacent
+lines, columns, and bands, specified by the \fInsum\fR package parameter,
+will be summed to form an aperture spectrum.  If number is odd then the
+aperture/band number refers to the middle and if it is even it refers to the
+lower of the two middle lines or columns.
+
+In the case of many spectra each stored in separate one dimensional
+images, the image names may be such that they have a common root name
+and a four digit aperture number extension.  This name syntax is
+called "onedspec" format.  Including such spectra in an
+input list may be accomplished either with wildcard templates such as
+
+.nf
+	name*
+	name.????.imh
+.fi
+
+where the image type extension ".imh" must be given to complete the
+template but the actual extension could also be that for an STF type
+image, or using an @file prepared with the task \fBnames\fR.
+To generate this syntax for output images the \fIformat\fR parameter
+is set to "onedspec" (this will be discussed further later).
+
+From the input images one may select a range of wavelengths with the
+\fIw1\fR and \fIw2\fR parameters and a subset of spectra based on aperture and
+beam numbers using the \fIaperture\fR and \fIbeam\fR parameters.
+If the wavelength range is specified as INDEF the full spectra are
+copied without any resampling.  If the aperture and beam lists are not
+specified, an empty list, then all apertures and beams are selected.  The
+lists may be those spectra desired or the complement obtained by prefixing
+the list with '!'.  Only the selected wavelength range and spectra will
+be operated upon and passed on to the output images.
+
+Specifying a wavelength range is fairly obvious except for the question
+of pixel sampling.  Either the pixels in the specified range are copied
+without resampling or the pixels are resampled to correspond eactly
+to the requested range.  The choice is made with the \fIrebin\fR parameter.
+In the first case the nearest pixels to the specified wavelength
+endpoints are determined and those pixels and all those in between
+are copied.  The dispersion relation is unchanged.  In the second case
+the spectra are reinterpolated to have the specified starting and
+ending wavelengths with the same number of pixels between those points
+as in the original spectrum.  The reinterpolation is done in either
+linear or log-linear dispersion.  The non-linear dispersion functions
+are interpolated to a linear dispersion.
+
+Using \fBscopy\fR with long slit or Fabry-Perot images provides a quick and
+simple type of extraction as opposed to using the \fBapextract\fR package.
+When summing it is often desired to start each aperture after the number of
+lines summed.  To do this specify a step size in the aperture/band list.  For
+example to extract columns 3 to 23 summing every 5 columns you would use an
+aperture list of "3-23x5" and an \fInsum\fR of 5.  If you do not use the
+step in the aperture list you would extract the sum of columns 1 to 5, then
+columns 2 to 6, and so on.
+
+In the special case of subapertures extracted by \fBapextract\fR, related
+apertures are numbered using a modulus; for example apertures
+5, 1005, 2005.  To allow selecting all related apertures using a single
+aperture number the \fIapmodulus\fR parameter is used to specify the
+modulus factor; 1000 in the above example.  This is a very specialized
+feature which should be ignored by most users.
+
+The output list of images may consist of an empty list, a single image,
+or a list of images matching the input list in number.  Note that it
+is the number of image names that matters and not the number of spectra
+since there may be any number of spectra in an image.  The empty list
+converts to the same list as the input and is shorthand for replacing
+the input image with the output image upon completion; therefore it
+is equivalent to the case of a matching list.  If the input
+consists of just one image then the distinction between a single
+output and a matching list is moot.  The interesting distinction is
+when there is an input list of two or more images.  The two cases
+are then a mapping of many-to-many or many-to-one.  Note that it is
+possible to have more complex mappings by repeating the same output
+name in a matching list provided clobbering, merging, and possibly
+renumbering is enabled.
+
+In the case of a matching list, spectra from different input images
+will go to different output images.  In the case of a single output
+image all spectra will go to the same output image.  Note that in
+this discussion an output image when "onedspec" format is specified
+is actually a root name for possibly many images.  However,
+it should be thought of as a single image from the point of view
+of image lists.
+
+When mapping many spectra to a single output image, which may have existing
+spectra if merging, there may be a conflict with repeated aperture
+numbers.  One option is to consecutively renumber the aperture numbers,
+including any previous spectra in the output image when merging and then
+continuing with the input spectra in the order in which they are selected.
+This is specified with the \fIrenumber\fR parameter which renumbers
+beginning with 1.
+
+Another options which may be used independently of renumbering or in
+conjunction with it is to add an offset as specified by the \fIoffset\fR
+parameter.  This is last step in determining the output aperture
+numbers so that if used with the renumber option the final aperture
+numbers begin with one plus the offset.
+
+It has been mentioned that it is possible to write and add to
+existing images.  If an output image exists an error will be
+printed unless the \fIclobber\fR parameter is set.  If clobbering
+is allowed then the existing output image will be replaced by the
+new output.  Rather than replacing an output image sometimes one
+wants to replace certain spectra or add new spectra.  This is
+done by selecting the \fImerge\fR option.  In this case if the output
+has a spectrum with the same aperture number as the input spectrum
+it is replaced by the input spectrum.  If the input spectrum aperture
+number is not in the output then the spectrum is added to the output
+image.  To add spectra with the same aperture number and not
+replace the one in the output use the \fIrenumber\fR or
+\fIoffset\fR options.
+
+To print a record as each input spectrum is copied the \fIverbose\fR
+parameter may be set.  The syntax is the input image name followed
+by the aperture number in [].  An arrow then points to the output
+image name with the final aperture number also in [], except for
+"onedspec" format where the image name extension gives the aperture
+number.  It is important to remember that it is the aperture numbers
+which are shown and not the image lines; there is not necessarily any
+relation between image lines and aperture numbers though often they
+are the same.
+.ih
+EXAMPLES
+Because there are so many possiblities there are many examples.  To
+help find examples close to those of interest they are divided into
+three sections; examples involving standard multispec images only, examples
+with onedspec format images, and examples with long slit and Fabry-Perot
+images.  In the examples the verbose flag is set to yes and the output is
+shown.
+
+I.   MULTISPEC IMAGES
+
+The examples in this section deal with the default spectral format of
+one or more spectra in an image.  Note that the difference between
+a "onedspec" image and a "multispec" image with one spectrum is purely
+the image naming syntax.
+
+1.  Select a single spectrum (aperture 3):
+
+.nf
+	cl> scopy example1 ap3 aperture=3
+	example1[3]  -->  ap3[3]
+.fi
+
+2.  Select a wavelength region from a single spectrum:
+
+.nf
+	cl> scopy example1 ap3 aperture=3 w1=5500 w2=6500
+	example1[3]  -->  ap3[3]
+.fi
+
+3.  Select a subset of spectra (apertures 1, 2, 4, 6, and 9): 
+
+.nf
+	cl> scopy example1 subset apertures="1-2,4,6-9x3"
+	example1[1]  -->  subset[1]
+	example1[2]  -->  subset[2]
+	example1[4]  -->  subset[4]
+	example1[6]  -->  subset[6]
+	example1[9]  -->  subset[9]
+.fi
+
+This example shows various features of the aperture list syntax.
+
+4.  Select the same apertures (1 and 3) from multiple spectra and in the
+same wavelength region:
+
+.nf
+	cl> scopy example* %example%subset%* apertures=1,3 w1=5500 w2=6500
+	example1[1]  -->  subset1[1]
+	example1[3]  -->  subset1[3]
+	example2[1]  -->  subset2[1]
+	example2[3]  -->  subset2[3]
+	...
+.fi
+
+The output list uses the pattern substitution feature of image templates.
+
+5.  Select the same aperture from multiple spectra and pack them in a
+a single image:
+
+.nf
+	cl> scopy example* ap2 aperture=2 renumber+
+	example1[2]  -->  ap2[1]
+	example2[2]  -->  ap2[2]
+	example3[2]  -->  ap2[3]
+	...
+.fi
+
+6.  To renumber the apertures sequentially starting with 11:
+
+.nf
+	cl> scopy example1 renum renumber+
+	example1[1]  -->  renum[11]
+	example1[5]  -->  renum[12]
+	example1[9]  -->  renum[13]
+	...
+.fi
+
+7.  To replace apertures (2) in one image with that from another:
+
+.nf
+	cl> scopy example1 example2 aperture=2 clobber+ merge+
+	example1[2]  --> example2[2]
+.fi
+
+8.  To merge two sets of spectra with different aperture numbers into
+    one image:
+
+.nf
+	cl> scopy example![12]* merge
+	example1[1]  ->  merge[1]
+	example1[3]  ->  merge[3]
+	...
+	example2[2]  ->  merge[2]
+	example2[4]  ->  merge[4]
+	...
+.fi
+
+The input list uses the ![] character substitution syntax of image templates.
+
+9.  To merge a set of spectra with the same aperture numbers into another
+existing image:
+
+.nf
+	cl> scopy example2 example1 clobber+ merge+ renumber+
+	example1[5]  -->  example1[2]
+	example1[9]  -->  example1[3]
+	example2[1]  -->  example1[4]
+	example2[5]  -->  example1[5]
+	example2[9]  -->  example1[6]
+.fi
+
+Both images contained apertures 1, 5, and 9.  The listing does not show
+the renumbering of the aperture 1 from example1 since the aperture number
+was not changed.
+
+10.  Select parts of a 3D image where the first band is the
+variance weighted extraction, band 2 is nonweighted extraction,
+band 3 is the sky, and band 4 is the sigma:
+
+.nf
+	cl> scopy example3d.ms[*,*,1] var1.ms
+	example3d.ms[*,*,1][1]  -->  var1.ms[1]
+	example3d.ms[*,*,1][2]  -->  var1.ms[2]
+	...
+	cl> scopy example3d.ms[10:400,3,3] skyap3
+	example3d.ms[10:400,3,3][3]  -->  skyap3[3]
+	cl> scopy example3d.ms[*,*,1] "" clobber+
+	example3d.ms[*,*,1][1]  -->  example3d.ms[1]
+	example3d.ms[*,*,1][2]  -->  example3d.ms[2]
+	...
+.fi
+
+Note that this could also be done with \fBimcopy\fR.  The last example
+is done in place; i.e. replacing the input image by the output image
+with the other bands eliminatated; i.e. the output image is two dimensional.
+
+II.  ONEDSPEC IMAGES
+
+1.  Expand a multi-spectrum image to individual single spectrum images:
+
+.nf
+	cl> scopy example1 record format=onedspec
+	example1[1]  -->  record.0001
+	example1[5]  -->  record.0005
+	example1[9]  -->  record.0009
+	...
+.fi
+
+2.  Pack a set of individual 1D spectra into a single image:
+
+.nf
+	cl> scopy record.????.imh record.ms
+	record.0001[1]  -->  record.ms[1]
+	record.0005[5]  -->  record.ms[5]
+	record.0009[9]  -->  record.ms[9]
+	...
+.fi
+
+3.  Copy a set of record syntax spectra to a different rootname and renumber:
+
+.nf
+	cl> scopy record.????.imh newroot format=onedspec
+	record.0001[1]  -->  newroot.0001
+	record.0005[5]  -->  newroot.0002
+	record.0009[9]  -->  newroot.0003
+	...
+.fi
+
+III. LONG SLIT IMAGES
+
+To define the dispersion axis either the image header parameter DISPAXIS
+must be set (using HEDIT for example) or a the package \fIdispaxis\fR
+parameter must be set.  In these examples the output is the default
+multispec format.
+
+1.  To extract column 250 into a spectrum:
+
+.nf
+	cl> scopy longslit1 c250 aperture=250
+	longslit1[250]  -->  c250[250]
+.fi
+
+2.  To sum and extract every set of 10 columns:
+
+.nf
+	cl> nsum = 10  (or epar the package parameters)
+	cl> scopy longslit1 sum10 apertures=5-500x10
+	longslit1[5]  -->  sum10[5]
+	longslit1[15]  -->  sum10[15]
+	longslit1[25]  -->  sum10[25]
+	...
+.fi
+
+3.  To extract the sum of 10 columns centered on column 250 from a set
+of 2D images:
+
+.nf
+	cl> nsum = 10  (or epar the package parameters)
+	cl> scopy longslit* %longslit%c250.%* aperture=250
+	longslit1[250]  -->  c250.1[250]
+	longslit2[250]  -->  c250.2[250]
+	longslit3[250]  -->  c250.3[250]
+	...
+.fi
+
+4.  To extract the sum of 10 columns centered on column 250 from a set of
+2D images and merge them into a single, renumbered output image:
+
+.nf
+	cl> nsum = 10  (or epar the package parameters)
+	cl> scopy longslit* c250 aperture=250 renum+
+	longslit1[250]  -->  c250[1]
+	longslit2[250]  -->  c250[2]
+	longslit3[250]  -->  c250[3]
+	...
+.fi
+
+IV. FABRY-PEROT IMAGES
+
+To define the dispersion axis either the image header parameter DISPAXIS
+must be set (using HEDIT for example) or a the package \fIdispaxis\fR
+parameter must be set.  In these examples the output is the default
+multispec format.
+
+1.  To extract a spectrum from the spatial position (250,250) where
+dispaxis=3:
+
+.nf
+	cl> scopy fp1 a250 aperture=250 band=250
+	longslit1[250]  -->  a250[250]
+.fi
+
+2.  To sum and extract every set of 10 lines and bands (dispaxis=1):
+
+.nf
+	cl> nsum = "10"
+	cl> scopy fp1 sum10 apertures=5-500x10 bands=5-500x10
+	longslit1[5]  -->  sum10[5]
+	longslit1[15]  -->  sum10[15]
+	longslit1[25]  -->  sum10[25]
+	...
+.fi
+
+3.  To extract the sum of 10 columns and 20 lines centered on column 250 and
+line 100 from a set of 3D images with dispaxis=3:
+
+.nf
+	cl> nsum = "10 20"
+	cl> scopy longslit* %longslit%c250.%* aperture=250 band=100
+	longslit1[250]  -->  c250.1[250]
+	longslit2[250]  -->  c250.2[250]
+	longslit3[250]  -->  c250.3[250]
+	...
+.fi
+.ih
+REVISIONS
+.ls SCOPY V2.11
+Previously both w1 and w2 had to be specified to select a range to
+copy.  Now if only one is specified the second endpoint defaults
+to the first or last pixel.
+.le
+.ls SCOPY V2.10.3
+Additional support for 3D multispec/equispec or spatial spectra has been
+added.  The "bands" parameter allows selecting specific bands and
+the onedspec output format creates separate images for each selected
+aperture and band.
+.le
+.ls SCOPY V2.10
+This task is new.
+.le
+.ih
+SEE ALSO
+ranges, sarith, imcopy, dispcor, specshift
+.endhelp