bswitch: Beam-switch strings of spectra to make obj-sky pairs

Package: irs

Usage

bswitch input records

Parameters

input: The root name for the input spectra to be beam-switched.

records: The range of spectra to be included in the beam-switch operation. Each range item will be appended to the root name to form an image name. For example, if "input" is "nite1" and records is "1011-1018", then spectra nite1.1011, nite.1012 ... nite1.1018 will be included.

output: New spectra are created by the beam-switch operation. This parameter specifies the root name to be used for the created spectra.

start_rec = 1: Each new spectrum created has "output" as its root name and a trailing number appended. The number begins with start_rec and is incremented for each new spectrum. For example, if "output" is given as "nite1b" and start_rec is given as 1001, then new spectra will be created as nite1b.1001, nite1b.1002 ...

stats = "stats": A file by this name will have statistical data appended to it, or created if necessary. If a null file name is given (""), no statistical output is given. For each aperture, a listing of countrates for each observation is given relative to the observation with the highest rate.

ids_mode = yes: If the data are taken under the usual IIDS "beam-switch" mode, this parameter should be set to yes so that accumulations will be performed in pairs. But if the data are taken where there is no sky observation or different numbers of sky observations, ids_mode should be set to no. If weighting is in effect, ids_mode=yes implies weighting of the object-sky sum; if ids_mode=no, then weighting is applied to the object and sky independently because then there is no guarantee that an object and sky observation are related.

extinct = yes: If set to yes, a correction for atmospheric extinction is applied. The image header must have either a valid entry for AIRMASS or for hour angle (or right ascension and sidereal time) and declination.

weighting = no: If set to yes, the entire spectrum or a specified region will be used to obtain a countrate indicative of the statistical weight to be applied to the spectrum during the accumulations.

subset = 32767: A subset value larger than the number of independent spectra to be added indicates that the operation is to produce a single spectrum for each aperture regardless of how many input spectra are entered. If subset is a smaller number, say 4, then the accumulations are written out after every 4 spectra and then re-initialized to zero for the next 4.

wave1 = 0.0: If weighting=yes, this parameter indicates the starting point in the spectrum for the countrate to be assessed. For emission-line objects, this is particularly useful because the regime of information is then confined to a narrow spectral region rather than the entire spectrum. Defaults to the beginning of the spectrum.

wave2 = 0.0: This provides the ending wavelength for the countrate determination. Defaults to the endpoint of the spectrum.

observatory = "observatory": Observatory at which the spectra were obtained if not specified in the image header by the keyword OBSERVAT. The observatory may be one of the observatories in the observatory database, "observatory" to select the observatory defined by the environment variable "observatory" or the task observatory, or "obspars" to select the current parameters set in the observatory task. See help for observatory for additional information.

extinction = ")_.extinction": The the name of the file containing extinction values. Required if extinct=yes.

Description

Data from multiaperture spectrographs are summed according to aperture number and sky subtracted if sky observations are available. Data for up to 50 apertures may be simultaneously accumulated. The accumulated spectra are written to new images.

The exposure times for each observation may be different. All internal computations are performed in terms of count rates, and converted back to counts (for statistical analysis) prior to writing the new image. Therefore, the time on the sky and object may be different as well. When these extensions to the normal mode are required, the flag ids_mode must be set to no. Then object and sky accumulations are performed totally independently and a difference is derived at the conclusion of the operation.

If ids_mode is set to yes, then the usual IIDS/IRS "beam-switch" observing mode is assumed. This implies that an equal number of sky and object spectra are obtained through each aperture after 2N spectra have been accumulated, where N is the number of instrument apertures (2 for the IIDS/IRS). It is also assumed that the object and sky exposure times are equal for each aperture. Note that the "nebular" mode (where all instrument apertures point at an extended object simultaneously, and then all apertures point at sky simultaneously) is an acceptable form for beam-switched data in ids_mode.

The accumulations are optionally weighted by the countrate over a region of the spectrum to improve the statistics during variable conditions. The user may specify the region of spectrum by wavelength. In ids_mode, the statistics are obtained from object-sky differences; otherwise, the statistics are performed on object+sky and sky spectra separately.

The spectra may be extinction corrected if this has not already been performed. In order to perform either the extinction correction or the weighting process, the spectra must have been placed on a linear wavelength scale (or linear in the base 10 logarithm).

Strings of spectra are accumulated to produce a single summed spectrum for each observing aperture. But in some cases it is desirable to produce summed spectra from subsets of the entire string to evaluate the presence of variations either due to observing conditions or due to the physical nature of the object. A subset parameter may be set to the frequency at which spectra are to be summed.

In order that the processing occur with minimal user interaction, elements from the extended image header are used to direct the flow of operation and to obtain key observing parameters. The required parameters are: object/sky flag (OFLAG=1/0), exposure time in seconds (ITM), beam (that is, aperture) number (BEAM-NUM), airmass (AIRMASS) or alternatively hour angle (HA) and declination (DEC), or right ascension (RA), sidereal time (ST), declination (DEC), and the observatory (OBSERVAT), starting wavelength (W0), and wavelength increment per channel (WPC), where the names in parenthesis are the expected keywords in the header. If the observatory is not specified in the image the observatory parameter is used. See observatory for further details on the observatory database.

The following header flags are used as well: DC_FLAG for dispersion corrected data (must=0), BS_FLAG for beam-switching (must not be 1 which indicates the operation was already done), EX_FLAG for extinction correction (if = 0 extinction is assumed already done).

The headers may be listed with the IMHEADER task, setting the parameter "long" = yes. The values for the parameters follow the rules used for IIDS and IRS data.

After the beam-switch operation, the newly created spectra will have header elements taken from the last object spectrum. A few parameters will be updated to reflect the operation (e.g. integration time, processing flags).

Examples

The following example will accumulate a series of 16 spectra obtained in the normal beam-switched mode and create two new extinction corrected spectra having names nite1bs.1 and nite1bs.2:

cl> bswitch nite1 1011-1026 nite1bs 1

The following example performs the same functions but accumulates the data to produce 8 new spectra representing the individual object-sky pairs:

cl> bswitch nite1 1011-1026 nite1bs 1 subset=4

The following example produces an extinction corrected spectrum for every input spectrum. Note that ids_mode is set to off to generate separate object and sky sums, and subset is set to 2 so that every pair of spectra (one object and one sky) are written out as two new spectra:

cl> bswitch nite1 1011-1026 nite1bs 1 subset=2 ids_mode-

The next example produces a pair of spectra for each of 3 independent objects observed, provided that each was observed for the same number of observations (16 in this case).

cl> bswitch nite1 1011-1026,1051-1066,1081-1096 nite1bs 1 \
>>> subset=16

The next example shows how to use the weighting parameters where the indicative flux is derived from the region around the emission-line of 5007A.

cl> bswitch nite1 1011-1026 nite1bs 1 weighting- \
>>> wave1=4990, wave2=5020

Time requirements

The principle time expenditure goes toward extinction correcting the data. For IIDS type spectra (length=1024 pixels), approximately 30 cpu seconds are required to beam-switch a series of 16 spectra.

Bugs

The number of apertures is restricted to 50 and must be labeled between 0 and 49 in the image header (the IIDS uses 0 and 1).

Until an image header editor is available, BSWITCH can be applied only to data with properly prepared headers such as IIDS/IRS data read by RIDSMTN, RIDSFILE and some data via RFITS.

When used to perform the function of extinction correction only (the third example above), the statistics file fails to note the output image name for the sky spectrum.

The data must be on a linear wavelength scale. The starting wavelength, W0, and a wavelength per channel, WPC, are required header information, and the DC_FLAG must be set to 0.