path: root/noao/onedspec/doc/sarith.hlp

.help sarith Mar93 noao.onedspec
.ih
NAME
sarith -- Spectrum arithmetic
.ih
USAGE	
sarith input1 op input2 output
.ih
PARAMETERS
.ls input1
List of input images to be used as operands.
.le
.ls op    
Operator to be applied to the first operand or to both operands.  The
unary or single operand operators are:

.nf
	abs  - absolute value
	copy - copy (see also \fBscopy\fR)
	dex  - decimal exponentiation (antilog of base 10 logarithm)
	exp  - base e exponentiation (antilog of natural logarithm)
	flam - convert F-nu to F-lambda
	fnu  - convert F-lambda to F-nu
	inv  - inverse
	ln   - natural logarithm
	log  - base 10 logarithm
	lum  - convert magnitude to luminosity
	mag  - convert luminosity to magnitude
	sqrt - square root
.fi

The binary or two operand operators are:

.nf
	replace - replace first operand values by second operand values
	+       - addition
	-       - subtraction
	*       - multiplication
	/       - division
	^       - exponentiation
.fi
.le
.ls input2
Lists of input spectra or constants to be used as second operands for
binary operations.  If a single value is specified it applies
to all the first operand input images otherwise the list must match
the first operand list in number.
.le
.ls output
List of resultant output images 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 resultant spectra.  If a single output name is specified then all
resultant 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 used to
select 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 reverse = no
Reverse the order of the operands in a binary operation?  Because the first
operand is used as the image header template, dispersion coordinate
template, and output image in the case of a null output list it  must be an
image and not a constant.  To allow certain operations, for
example subtracting a spectra from a constant or using the subtractand as
the dispersion coordinate template, the reverse option is used to reverse
the order of the operands in a binary operation.
.le
.ls ignoreaps = no
Ignore aperture numbers in the second operand?  Normally, spectra in
binary operations must have matching aperture numbers, otherwise an
error is printed.  If this parameter is yes then the spectra are matched
by line number with the last line being used if the second operand spectrum
has fewer lines than the first operand spectrum.  This is generally
used to allow using a single spectrum with multiple aperture spectra.
.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 this 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 errval = 0.
Value for resultant pixel if an arithmetic error occurs such as dividing
by zero or the square root of a negative number.
.le
.ls verbose = no
Print a record of each operation?
.le
.ih
DESCRIPTION
\fBSarith\fR performs arithmetic operations on spectra.  It is
distinguished from \fBimarith\fR in that it includes unary operators, like
\fBimfunction\fR but with some specific to astronomical spectra, and binary
operations between two spectra are performed in dispersion coordinate space
(typically wavelength) rather than logical pixel space.  In the latter case
the spectra are checked for matching dispersion functions (which are not
necessarily linear) and, if they don't match, the second operand is
interpolated without flux conservation.  (If flux conservation is desired
then the task \fBdispcor\fR should be used first.) Thus, the spectra may
have different dispersion functions but the arithmetic is done at matching
wavelengths.  The default interpolation function is a 5th order
polynomial.  The choice of interpolation type is made with the package
parameter "interp".  It may be set to "nearest", "linear", "spline3",
"poly5", or "sinc".  Remember that this applies to all tasks which might
need to interpolate spectra in the \fBonedspec\fR and associated packages.
For a discussion of interpolation types see \fBonedspec\fR.

The unary operators operate on the spectra in the first operand list to
produce the specified output spectra, which may be the same as the
input spectra.  The operators include:

.nf
	abs  - absolute value
	copy - copy (see also \fBscopy\fR)
	dex  - decimal exponentiation (antilog of base 10 logarithm)
	exp  - base e exponentiation (antilog of natural logarithm)
	flam - convert F-nu to F-lambda
	fnu  - convert F-lambda to F-nu
	inv  - inverse
	ln   - natural logarithm
	log  - base 10 logarithm
	lum  - convert magnitude to luminosity
	mag  - convert luminosity to magnitude
	sqrt - square root
.fi

The luminosity to magnitude and magnitude to luminosity operators are
based on the standard relation:

.nf
	mag = -2.5 * log (lum)
.fi

where the log is base 10.  The F-nu to F-lambda and F-lambda to F-nu
operators are based on the relation:

.nf
	F-nu = F-lambda * lambda / nu
.fi

where lambda is wavelength and nu is frequency (currently the wavelength
is assumed to be Angstroms and so F-lambda is in units of per Angstrom
and F-nu is in units of per Hertz).  In all the operators it is the
responsibility of user as to the appropriateness of the operator to
the input.

The binary operators operate on the spectra in the first operand list
and the spectra or numerical constants in the second operand.  Numeric
constants are equivalent to spectra having the specified value at all
pixels.  The binary operators are the standard arithmetic ones plus
exponentiation and replacement:

.nf
	replace - replace first operand values by second operand values
	+       - addition
	-       - subtraction
	*       - multiplication
	/       - division
	^       - exponentiation
.fi

If the second operand is a spectrum, as mentioned previously, it is
interpolated, without flux conservation, to the dispersion
function of the first operand spectrum if necessary.

There is a distinctions between the first operand and the second operand.
The first operand must always be a spectrum.  It supplies the dispersion
function to be matched by the second operand spectrum.  It also supplies
a copy of it's image header when a new output spectrum is created.
In cases where it is desired to have the second operand be the
dispersion/header reference and/or the first operand be a constant
the \fIreverse\fR parameter is used.  For example to subtract a
spectrum from the constant 1:

.nf
	cl> sarith 1 - spec invspec reverse+
.fi

or to subtract two spectra using the subtractand as the dispersion
reference:

.nf
	cl> sarith spec1 - spec2 diff reverse+
.fi

When a binary operation on a pair of spectra is performed the aperture
numbers may be required to be the same if \fIignoreaps\fR is no.  For
images containing multiple spectra the apertures need not be in the
same order but only that matching apertures exist.  If this parameter
is set to yes then aperture numbers are ignored when the operation is
performed.  For multiple spectra images the second operand spectra
are matched by image line number rather than by aperture.  If the
second operand image has fewer lines, often just one line, then the
last line is used repeatedly.  This feature allows multiple spectra
in the primary operand list to be operated upon by a single spectrum;
for example to subtract one spectrum from all spectra in the
in a multiple spectrum image.

If it is an error to perform an operation on certain data values, for
example division by zero or the square root of a negative number,
then the output value is given the value specified by the parameter
\fIerrval\fR.

A log of the operations performed may be printed to the standard
output, which may then be redirected if desired, if the \fIverbose\fR
parameter is set.  In the output the last bracketed number is the
aperture number of the spectrum.

INPUT/OUTPUT

The arithmetic part of \fBsarith\fR is fairly straightforward and
intuitive.  The selection of input spectra from input images and
the placing of output spectra in output images can be more confusing
because there are many possibilities.  This section concentrates
on the topics of the input and output.  Since the concepts apply to all
of the operators it simplifies things to think in terms of copying
input spectra to output spectra; the "copy" operator.  Note that the
task \fBscopy\fR is actually just this case of \fBsarith\fR with
parameters set for copying.  While the discussion here is similar
to that in the help for \fBscopy\fR, the examples for that task
are more focused for illustrating this topic than the \fBsarith\fR
examples which concentrate more on the arithmetic aspects of 
the task.

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
used 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 used
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 used.  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 \fBsarith\fR with long slit and 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.
.ih
EXAMPLES
In addition to the examples in this section there are many examples
in the help for \fBscopy\fR which illustrate aspects of selecting
input spectra and producing various types of output.  Those examples
are equivalent to using the "copy" operator.  The same examples will
also apply with other operators where the input spectra are modified
arithmetically before being copied to the output images.

I.  SIMPLE EXAMPLES

The simple examples use only a single input image and create a new
output image.

1.  Examples of unary operations:

.nf
	cl> sarith example1 mag "" magexample
	cl> sarith magexample lum "" example2
	cl> sarith example1 log "" logexample
.fi

Note that a place holder for the second operand is required on the command
line which will be ignored.

2.  Examples of binary operations using constants:

.nf
	cl> sarith example1 + 1000 example2
	cl> sarith example1 - 1000 example2 reverse+
	cl> sarith example1 / 1000 example2
	cl> sarith example1 ** 2 example2
.fi

3.  Examples of binary operations between spectra with matching apertures:

.nf
	cl> sarith example1 + example2 example3
	cl> sarith example1 - example2 example3
.fi

4.  Example of binary operations between spectra with the second image
consisting of a single spectrum:

.nf
	cl> sarith example1 / flatspec flatexample1 ignore+ errval=1
.fi

II.  MORE COMPLEX EXAMPLES

5.  Unary and constant operations on a list of images:

.nf
	cl> sarith example* fnu "" %example%fnu%
	cl> sarith example* + 1000 %example%fnu%
.fi

6.  Binary operations on a list of images using a single second operand
with matching apertures:

.nf
	cl> sarith example* - skyspec %example%skysub%*
.fi

7.  Selecting apertures to operate upon:

.nf
	cl> sarith example* - skyspec %example%skysub%* aper=1,5,9
.fi

8.  Extract the sum of each 10 columns in a long slit spectrum and normalize
by the central spectrum:

.nf
	cl> nsum = "10"
	cl> sarith longslit copy "" longslit.ms aper=5-500x10
	longslit[5]  -->  longslit.ms[5]
	longslit[15]  -->  longslit.ms[15]
	longslit[25]  -->  longslit.ms[25]
	...
	cl> sarith longslit.ms / longslit.ms[*,25] norm ignore+
	longslit.ms[5]  /  longslit.ms[*,25][245]  -->  norm[5]
	longslit.ms[15]  /  longslit.ms[*,25][245]  -->  norm[15]
	longslit.ms[25]  /  longslit.ms[*,25][245]  -->  norm[25]
	...
.fi

9.  In place operations:

.nf
	cl> sarith example* + 1000 example* clobber+
	example1[1]  +  1000.  -->  example1[1]
	example1[2]  +  1000.  -->  example1[2]
	...
	example2[1]  +  1000.  -->  example2[1]
	example2[2]  +  1000.  -->  example2[2]
	...
	cl> sarith example* flam "" example* clobber+
	example1[1]  -- flam -->  example1[1]
	example1[2]  -- flam -->  example1[2]
	...
	example2[1]  -- flam -->  example2[1]
	example2[2]  -- flam -->  example2[2]
	...
	cl> sarith example* - skyspec "" clobber+ ignore+
	example1[1]  +  skyspec[1]  -->  example1[1]
	example1[2]  +  skyspec[1]  -->  example1[2]
	...
	example2[1]  +  skyspec[1]  -->  example2[1]
	example2[2]  +  skyspec[1]  -->  example2[2]
	...
.fi

10.  Merging existing spectra with the results of operations:

.nf
	cl> sarith example* / flat "" clobber+ merge+ renum+ ignor+
.fi
.ih
REVISIONS
.ls SARITH V2.11
Previously both w1 and w2 had to be specified to select a range to
be used.  Now if only one is specified the second endpoint defaults
to the first or last pixel.

The noise band in multispec data is only copied from the primary
spectrum and not modified.  This is a kludge until the noise is
handled properly.
.le
.ls SARITH 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 SARITH V2.10
This task is new.
.le
.ih
SEE ALSO
scopy, splot, imarith, imfunction
.endhelp