diff options
Diffstat (limited to 'noao/onedspec/doc/sarith.hlp')
| -rw-r--r-- | noao/onedspec/doc/sarith.hlp | 571 |
1 files changed, 571 insertions, 0 deletions
diff --git a/noao/onedspec/doc/sarith.hlp b/noao/onedspec/doc/sarith.hlp new file mode 100644 index 00000000..a7e7cf87 --- /dev/null +++ b/noao/onedspec/doc/sarith.hlp @@ -0,0 +1,571 @@ +.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 |