IRAF help page for package noao.onedspec, program scopy

• input
• output
• w1 = INDEF, w2 = INDEF
• apertures = , beams =
• bands =
• apmodulus = 0
• format = multispec (multispec|onedspec)
• renumber = no
• offset = 0
• clobber = no
• merge = no
• rebin = yes
• verbose = no

• SCOPY V2.10.3
• SCOPY V2.10

scopy input output

input

output

w1 = INDEF, w2 = INDEF

apertures = , beams =

bands =

apmodulus = 0

format = multispec (multispec|onedspec)

renumber = no

offset = 0

clobber = no

merge = no

rebin = yes

verbose = no

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.

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

SCOPY V2.10

ranges, sarith, imcopy, dispcor, specshift,