diff options
Diffstat (limited to 'noao/onedspec/doc/scopy.hlp')
| -rw-r--r-- | noao/onedspec/doc/scopy.hlp | 541 |
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 |