STScI Logo

scopy noao.onedspec


NAME · USAGE · PARAMETERS · DESCRIPTION · EXAMPLES · REVISIONS
SEE_ALSO

NAME

scopy -- Select and copy spectra

USAGE

scopy input output

PARAMETERS

input
List of input images containing spectra to be copied.
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 clobber , merge , renumber and offset parameters to achieve the desired output. If more than one output image is specified then it must match the input image list in number.
w= INDEF, w2 = INDEF
Starting and ending wavelengths to be copied. If w1 is not specified then the wavelength of the starting edge of the first pixel is used (wavelength at pixel coordinate 0.5) and if w2 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 rebin 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.
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 xtools.ranges 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.
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.
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.
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.
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 offset parameter may be used to change the starting number.
offset = 0
Offset to be added to the input or renumbered aperture number to form the final output aperture number.
clobber = no
Modify an existing output image either by overwriting or merging?
merge = no
Merge apertures into existing spectra? This requires that the clobber 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.
rebin = yes
Rebin the spectrum to the exact wavelength range specified by the w1 and w2 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 w1 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.
verbose = no
Print a record of each aperture copied?

DESCRIPTION

Scopy 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.

   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

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 dispaxis package parameter. The aperture and band parameters specify a spatial position. A number of adjacent lines, columns, and bands, specified by the nsum 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

	name*
	name.????.imh

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 names . To generate this syntax for output images the format parameter is set to "onedspec" (this will be discussed further later).

From the input images one may select a range of wavelengths with the w1 and w2 parameters and a subset of spectra based on aperture and beam numbers using the aperture and beam 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 rebin 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 scopy with long slit or Fabry-Perot images provides a quick and simple type of extraction as opposed to using the apextract 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 nsum 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 apextract , 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 apmodulus 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 renumber 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 offset 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 clobber 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 merge 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 renumber or offset options.

To print a record as each input spectrum is copied the verbose 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.

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):

	cl> scopy example1 ap3 aperture=3
	example1[3]  -->  ap3[3]

2. Select a wavelength region from a single spectrum:

	cl> scopy example1 ap3 aperture=3 w1=5500 w2=6500
	example1[3]  -->  ap3[3]

3. Select a subset of spectra (apertures 1, 2, 4, 6, and 9):

	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]

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:

	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]
	...

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:

	cl> scopy example* ap2 aperture=2 renumber+
	example1[2]  -->  ap2[1]
	example2[2]  -->  ap2[2]
	example3[2]  -->  ap2[3]
	...

6. To renumber the apertures sequentially starting with 11:

	cl> scopy example1 renum renumber+
	example1[1]  -->  renum[11]
	example1[5]  -->  renum[12]
	example1[9]  -->  renum[13]
	...

7. To replace apertures (2) in one image with that from another:

	cl> scopy example1 example2 aperture=2 clobber+ merge+
	example1[2]  --> example2[2]

8. To merge two sets of spectra with different aperture numbers into one image:

	cl> scopy example![12]* merge
	example1[1]  ->  merge[1]
	example1[3]  ->  merge[3]
	...
	example2[2]  ->  merge[2]
	example2[4]  ->  merge[4]
	...

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:

	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]

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:

	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]
	...

Note that this could also be done with imcopy . The last example is done in place; i.e. replacing the input image by the output image with the other bands elimintated; i.e. the output image is two dimensional.

II. ONEDSPEC IMAGES

1. Expand a multi-spectrum image to individual single spectrum images:

	cl> scopy example1 record format=onedspec
	example1[1]  -->  record.0001
	example1[5]  -->  record.0005
	example1[9]  -->  record.0009
	...

2. Pack a set of individual 1D spectra into a single image:

	cl> scopy record.????.imh record.ms
	record.0001[1]  -->  record.ms[1]
	record.0005[5]  -->  record.ms[5]
	record.0009[9]  -->  record.ms[9]
	...

3. Copy a set of record syntax spectra to a different rootname and renumber:

	cl> scopy record.????.imh newroot format=onedspec
	record.0001[1]  -->  newroot.0001
	record.0005[5]  -->  newroot.0002
	record.0009[9]  -->  newroot.0003
	...

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 dispaxis parameter must be set. In these examples the output is the default multispec format.

1. To extract column 250 into a spectrum:

	cl> scopy longslit1 c250 aperture=250
	longslit1[250]  -->  c250[250]

2. To sum and extract every set of 10 columns:

	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]
	...

3. To extract the sum of 10 columns centered on column 250 from a set of 2D images:

	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]
	...

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:

	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]
	...

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 dispaxis 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:

	cl> scopy fp1 a250 aperture=250 band=250
	longslit1[250]  -->  a250[250]

2. To sum and extract every set of 10 lines and bands (dispaxis=1):

	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]
	...

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:

	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]
	...

REVISIONS

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.
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.
SCOPY V2.10
This task is new.

SEE ALSO

ranges, sarith, imcopy, dispcor, specshift


Source Code · Search Form · STSDAS