.help spbasic .sh One Dimensional Package - Basic Operators .sh INTRODUCTION The IRAF One Dimensional Package is intended to provide the basic tools required to reduce, analyze, and display data having a single dimension. This primarily refers to spectra, but may have applicability to time series photometry, or any other source of data which can be considered a simple vector. All such data will be referred to as spectra in the following discussion. Furthermore, the spectrum vector is assumed to be equally spaced along the independent variable (wavelength, channel, frequency, wavenumber,...). For the purposes of discussion, the independent variable will be referred to as wavelength but may be any of the possible physical transformations. Spectra are to be stored as 2 dimensional IRAF floating point images having a single line and are therefore limited to lengths smaller than or equal to the largest representable positive integer. For 32 bit machines, this is about 2 billion points, so that disk space will likely be the operational limit. The precision and dynamic range for each pixel will be determined by the local machine. The second dimension of the spectrum is spatial, and therefore represents a special case of the long slit spectroscopic mode. Each spectrum will, by default, be stored as a separate image file. Alternatively, an association can be declared for a related set of spectra through a "data group" mechanism. A data group can be defined to contain any number of related spectra so that an operation can be specified for the group. For example, one can group a single night of IIDS spectra into a group labeled JAN28, and then wavelength linearize JAN28. This helps minimize the user interaction which would otherwise be repetitive, and also reduces the user bookkeeping required. Data input to the package is provided through the DATAIO package. Tape readers will be provided for FITS, IIDS and IRS mountain formats, Text ("card-image"), REDUCER and PDS. The descriptor fields included in these formats will be mapped into standard IRAF image header fields when possible. Special fields will be added to the image header to represent instrument related parameters. Data output to tape (for visitor take home) will be either in FITS or text format. A variety of graphics display options will be provided for both interactive use and for hardcopy generation. Scale expansion and contraction, labeling, multiple spectra plots, and axis limit specification are to be included in the options. Specific reduction scripts will be provided to efficiently process raw data from the Kitt Peak instruments IIDS and IRS. .sh SCOPE OF SPECIFICATIONS This paper specifies the command format, parameters, and operations for the Basic contents of the One Dimensional Spectral Package. The Basic functions are those comprising the minimum set to reduce a large variety of spectra. More complicated operators and analysis functions are described in a companion paper on Intermediate Functions. Major projects in spectral analysis will be considered at a later date in the Advanced function set. The primary functions within the Basic operator set are: .ls 4 Transport Primarily magtape readers for the common tape formats. Included are FITS, IIDS/IRS, REDUCER, PDS, and Card-image formats. Tape writers will be initially limited to FITS and Card-image. .le .ls 4 Mathematical Add, subtract, multiply, divide spectra by spectra or constants. Apply functional operators such as log, exp, sqrt, sin, cos. Weighted sums and averages of spectra. .le .ls 4 Reduction operators Line identification, dispersion solution, flux calibration, coincidence correction, atmospheric extinction correction, flat fielding. .le .ls 4 Plotting Terminal package to expand, overplot, annotate plots. Hard copy package for printer/plotters. .le .ls 4 Utilities Header examination and modification. List, copy, delete spectra. Define, add, delete entries in a data group. .le .ls 4 Artificial spectra Generate ramps, Gaussian and Voigt lines, noise. .le These functions will be considered in detail in the following discussion. .ks A summary of the commands is given below: .nf rfits -- Convert FITS data files to IRAF data files riids -- Convert IIDS mountain tape format to IRAF data files rreducer -- Convert Reducer format tape to IRAF data files rpds -- Convert a PDS format tape to IRAF data files rtext -- Convert a card-image text file to an IRAF image file wfits -- Convert IRAF data files to FITS data format wtext -- Convert an IRAF image file to a card-image text file .sp 1 coin_cor -- Correct specified spectra for photon coincidence line_list -- Create a new line list, or modify an existing one mlinid -- Manually identify line features in a spectrum alinid -- Automatically locate spectral features in a spectrum disp_sol -- Determine the dispersion relation for a set of spectra disp_cor -- Linearize spectra having dispersion relation coefficients cr_flat -- Create a flat field spectrum flt_field -- Correct spectra for pixel-to-pixel variations std_star -- Define the standard stars to be used for solving the extinction and system sensitivity functions crext_func -- Create an extinction function from a set of observations crsens_func -- Create system sensitivity function ext_cor -- Extinction correct specified spectra sens_cor -- Correct the specified spectra for system sensitivity .fi .ju .ke .bp .sh TRANSPORT - INPUT Although the primary data input source for the near future will be magtape, direct links from other computers will be a likely source of input. The IRAF DATAIO package treats magtape as simple bit streams so that alternate input devices (e.g. disk, ethernet, phone lines) can also be accommodated with no programming modifications. This section describes the different formats to be made available in the initial release of the Spectroscopic package. Additional formats may be added if needed. In general, the following information will be copied to the standard image header: length of spectrum, title, abscissa units, brightness units, reference pixel abscissa value and increment, right ascension and declination of telescope. Non-standard header parameters include but are not limited to: integration time, UT and LST of the observation, airmass (or zenith distance), processing history, and comments. .sh FITS .ih NAME rfits -- Convert FITS data files to IRAF data files .ih USAGE rfits [source, filename, files] .ih DESCRIPTION FITS data is read from the specified source. The FITS header may optionally be printed on the standard output as either a full listing or a short description. Image data may optionally be converted to an IRAF image of specified data type. Eventually all data from the mountain will be in FITS format, with the exception of time-critical data transfer projects and special applications. The IRAF FITS reader will copy the data to disk for most applications. .ih PARAMETERS .ls 4 fits_source The FITS data source. If the data source is a disk file or an explicit tape file specification of the form mt*[n] where n is a file number then only that file is converted. If the general tape device name is given, i.e. mta, mtb800, etc, then the files specified by the files parameter will be read from the tape. .le .ls filename The IRAF file which will receive the FITS data if the make_image parameter switch set. For tape files specified by the files parameter the filename will be used as a prefix and the file number will be appended. Otherwise, the file will be named as specified. Thus, reading files 1 and 3 from a FITS tape with a filename of data will produce the files data1 and data3. It is legal to use a null filename. However, converting a source without a file number and with a null filename will cause a default file fits to be created. .le .ls files The files to be read from a tape are specified by the files string. The string can consist of any sequence of file numbers separated by at least one of whitespace, comma, or dash. A dash specifies a range of files. For example the string 1 2, 3 - 5,8-6 will convert the files 1 through 8. .le .ls print_header If this switch is set header information is printed on the standard output output. (default = yes) .le .ls short_header This switch controls the format of the header information printed when the print_header switch is set. When the short_header switch is set only the output filename, the FITS OBJECT string, and the image dimensions are printed. Otherwise, the output filename is followed by the full FITS header. (default = yes) .le .ls bytes_per_record The FITS standard record size is 2880 bytes which is the default for this parameter. However, non-standard FITS tapes with different record sizes can be read by setting the appropriate size. .le .ls make_image This switch determines whether FITS image data is converted to an IRAF image file. This switch is set to no to obtain just header information with the print_header switch. (default = yes) .le .ls data_type The IRAF image file may be of a different data type than the FITS image data. The data type may be specified as s for short, l for long, and r for real. The user must beware of truncation problems if an inappropriate data type is specified. If the FITS keywords BSCALE and BZERO are found then the image data is scaled appropriately. In this case the real data type may be most appropriate. .le .sh For spectroscopic applications, the parameter data_type would be specified as r for real, and the filename would probably be assigned as the "group" name as well. (see section on data groups.) .sh IIDS/IRS .ih NAME riids -- Convert IIDS mountain tape format to IRAF data files .ih USAGE riids [source, filename, form, records] .ih DESCRIPTION IIDS/IRS mountain format data is read from the specified source. The header may be printed on the standard output either in short form, label only, or a long form containing telescope and time information, processing flags, and wavelength solution values. Either raw or "mountain reduced" tapes can be specified with the parameter form. The IIDS format is destined for extinction. A FITS format will replace the current tape format, but an interim period will exist for which this tape reader must exist. .ih PARAMETERS .ls 4 iids_source The data source, either magtape or a data stream (e.g. disk file). The current IIDS tape format produces tapes having only a single file. If the source is a magtape, the general tape specification mt*[n], should either have n specified as 1, or [n] should not be present. .le .ls 4 filename The IRAF file which will contain the data if the make_image parameter is set. The filename will be used as a prefix and the record number will be used as the suffix. Thus reading records 1 through 100 from an IIDS tape with a file name of 'blue' will produce 100 files having names blue1, blue2, ..., blue100. A null filename will default to 'iids'. .le .ls 4 form This string parameter defines the tape to be either 'new' or 'red'. The 'new' designation refers to tapes made after January 1977, and 'red' refers to mountain reduced tapes. (default = 'red') .le .ls 4 records The records specified by this string parameter will be copied to disk. The syntax is identical to that for the files parameter of the FITS reader. .le .ls 4 print_header If this switch is set, header information is printed on the standard output. (default = yes) .le .ls 4 short_header If this switch is set, only the filename and label information will be printed if the print_header switch is also set. If set to 'no', the long form will be printed. (default = yes) .le .ls 4 make_image See definition of this parameter under FITS. .le .sh REDUCER REDUCER tapes require several considerations beyond the previous simple formats. The spectra actually consist of many spectra having lengths of 4096 but slightly different spectral sampling. Thus, the reader can create many small independent spectra, or interpolate the data onto a common spectral scale to create a single large spectrum. The latter alternative seems to be more generally useful, unless the interpolation process introduces significant errors. Probably the initial reader will provide both options. A second consideration is the 60 bit word length conversion. The IRAF images are limited to 32 bit reals on most 32 bit machines. Some loss of precision and dynamic range will result while reading REDUCER format data. Also, there may be a considerable number (~100) of non-standard header elements. These can be handled in a normal fashion, and tools will be provided to extract or modify these elements as needed. New elements may be added as well. .ih NAME rreducer -- Convert Reducer format tape to IRAF data files .ih USAGE rreducer [source, filename, files] .ih DESCRIPTION REDUCER format data is read from the specified source. The header may be printed on the standard output either in short form consisting of the 80 character ID field, or a long form containing some selection (to be agreed upon) of the many header elements. Either a single long spectrum requiring interpolation to match the spectral characteristics of the first data block, or multiple short spectra having individual spectral parameters can be specified with the hidden parameter, interp. Interpolation is performed via a fifth order polynomial. Subsets of the spectrum can be selected with the blocks string parameter. This specifies which blocks in the file are to be extracted. .ih PARAMETERS .ls 4 reducer_source The data source, either magnetic tape or a data stream (e.g. disk file). See the definition of fits_source above for a description of how this parameter interacts with the files parameter. .le .ls 4 filename The filename which will contain the data. See the definition of this parameter under FITS. If no name is given, the default of 'reducer' will be used. .le .ls 4 files The files to be read from tape are given by the files string. See the description of this parameter under FITS. .le .ls 4 print_header If this switch is set header information will be printed on the standard output. (default = yes) .le .ls 4 short_header If this switch is set only the filename and the first 60 characters of the 80 character ID field will be printed if the print_header switch is also set. If set to no, the long form of the header will be printed, containing selected elements of the 100 word header record. (default = yes) .le .ls 4 make_image See the definition of this parameter under FITS. .le .ls 4 interp If this switch is set, a single long spectrum is produced. If set to no, multiple spectra will be generated, one for each header-data block. The resulting filenames will have suffixes of '.1' , '.2' ... '.n'. For example, if the given filename is fts and the tape file is 2, the resulting spectrum will be fts2 if interp is set to yes, but will be fts2.1, fts2.2, and fts2.3 if there are 3 header-data block sets and interp is set to no. (default = yes). .le .ls 4 blocks This string parameter allows selected extraction of the specified header-block sets, rather than the entire spectrum. Thus subsets of the spectrum may be extracted. The parameter specifies the starting block and ending block within a tape file. If an end-of-file is found prior to exhaustion of the specification, reading is terminated. For example, the string '12 19' specifies that the eight sets starting with the twelfth block are to be extracted to form the spectrum. (default = '1 32767', or all) .le .sh PDS Tapes from the new PDS 11/23 system will be either FITS or old format PDS 9 track tapes. This reader will accept the old format tapes which are based on the PDP 8 character set and either 10 or 12 bit format. .ih NAME rpds -- Convert a PDS format tape to IRAF data files .ih USAGE rpds [source, filename, files] .ih DESCRIPTION PDS format data is read from the specified source. The header may be printed on the standard output either in short form consisting of the 40 character ID field, filename, and size, or in long form including raster parameters and origin. Because PDS data is limited to no more than 12 bit data, the output image will be short integers if the number of lines ("scans") implies two dimensional data. If one dimensional data is implied, the output image will be converted to reals. .ih PARAMETERS .ls 4 pds_source The data source, either magtape or a data stream. See the definition of fits_source above for a description of how this parameter interacts with the files parameter. .le .ls 4 filename If no filename is given, the default of 'pds' will be used. .le .ls 4 files See the definition of this parameter under FITS. .le .ls 4 print_header If this switch is set, header information will be printed on the standard output. (default = yes). .le .ls 4 short_header If this switch is set, only the filename, size, and the 40 character ID field will be printed if the print_header switch is also set. If set to no, the long form of the header will be printed containing the full information block (delta X, delta Y, scan type, speed, origin, corner, travel). (default = yes) .le .ls 4 make_image See the definition of this parameter under FITS. (default = yes) .le .ls 4 data_type Specifies the IRAF image file output data type. Normally one dimensional PDS data (NSCANS=1) will be stored as real and two dimensional PDS data (NSCANS>1) will be stored as short. The data type may be specified as s (short), l (long), or r (real). .le .sh TEXT (Read Card-Image) Card-image tapes are probably the most portable form of data transport. Unlike FITS, there is no standard for internally documenting the contents of the text file. Header information is essentially lost. This makes card-image data transfer a relatively unattractive format. .ih NAME rtext -- Convert a card-image text file to an IRAF image file. .ih USAGE rtext [source, filename, files, ncols, nlines, label] .ih DESCRIPTION The card-image text file specified by the source parameter is converted to an IRAF image file. The file is read in a free form mode (values separated by spaces) converting data along lines (1-ncols) first. No header information is stored except for the image size and the label. If additional header information is to be stored, the standard image header utility must be used. Pixel values exactly equal to some constant will be assumed to be blanks if the blank switch is set to yes. The flag value for blanks can be set with the blank_value parameter. .ih PARAMETERS .ls 4 text_source The input data source. See the definition of this parameter under FITS. .le .ls 4 filename The IRAF file which will contain the image data if the make_image switch is set. If no filename is given, the default of 'text' will be used. .le .ls 4 files See the definition of this parameter under FITS. .le .ls 4 ncols The number of columns of data which describe the image extent. .le .ls 4 nlines The number of lines (or 'rows') of data which describe the image extent. For one dimensional spectra, this parameter will be 1. .le .ls 4 label This string parameter becomes the image identification label. Up to 80 characters may be stored. .le .ls 4 print_header If this switch is set, header information consisting of the filename, image label, and image size will be printed on the standard output. (default = yes) .le .ls 4 make_image If this switch is set, an IRAF image will be created. (default = yes) .le .ls 4 data_type The IRAF image may be either s (short), l (long), or r (real). (default = r) .le .ls 4 card_length The number of columns on the "card" in the card-image file. (default = 80) .le .ls 4 blank_value The value used to flag blank pixels if the blank switch is set to yes. (default = -32767) .le .ls 4 blank If this switch is set to yes, any pixel having exactly the value specified by the parameter blank_value will be flagged as a blank pixel. If set to no, all pixel values are assumed to be valid. .le .bp .sh TRANSPORT - OUTPUT The primary format for take away tapes will eventually be FITS. Because many facilities currently cannot read FITS format, the card-image format will also be provided. .sh FITS .ih NAME wfits -- Convert IRAF data files to FITS data format .ih USAGE wfits [destination, filename, files] .ih DESCRIPTION Data is read from the specified filename(s) and written to the destination, usually a magnetic tape specification. A short header consisting of the filename, size, and label may optionally be printed on the standard output. The data will be automatically scaled to either 16 or 32 bit integer format (BITPIX = 16 or 32) depending on the number of bits per pixel in the image data, unless the bitpix parameter is specified otherwise. The scaling parameters may be forced to exactly represent the original data (BSCALE = 1.0, BZERO = 0.0) by setting the scale switch to no. If only the header information is to be copied to the destination, the write_image parameter can be set to no. If this is the case, then the NAXIS FITS keyword will be assigned the value of 0; otherwise the value for NAXIS will be taken from the IRAF image header. Each non-standard header element will be written into the FITS file in a form to be determined. These elements may be entered as FITS COMMENT records, or perhaps added to the file as FITS "special records". Other keywords will be written following standard FITS specifications. A few special cases will be set as follows: .ls 4 NAXISn The NAXIS1, NAXIS2, ... NAXISn values will be taken from the image header .le .ls 4 OBJECT The first 60 characters of the image label will be used. .le .ls 4 BLANK Blank pixels will be written to tape having the IRAF value for indefinite appropriate to 8, 16, or 32 bit integers. .le .ls 4 ORIGIN = 'KPNO IRAF' .le .ih PARAMETERS .ls 4 fits_destination The data destination, usually a magnetic tape, but may be a disk file or STDOUT. If magtape, the tape should be specified with a file number of either 1 or "eot". The file number refers to the file which will be written. Thus a file number of 2 would overwrite file 2. If the tape already has data written on it, the safest specification would be "eot". This forces the tape to be positioned between the double end-of-tape marks prior to writing. .le .ls 4 filename The IRAF filename providing the root for the source name. The files string, if given, will be used as the suffix for the file names to be written to tape. For example, if the filename is given as "image", and the files string is "1 -5", then files image1, image2, image3, image4, and image5 will be written to the destination in FITS format. If the files string is empty, only the specified filename will be converted. .le .ls 4 files See the definition of this parameter under the FITS reader. .le .ls 4 print_header If this switch is set, a short header will be printed on the standard output for each image converted. (default = yes) .le .ls 4 write_image If this switch is set to no, only header information will be written to the destination, but no image data. By using this parameter, one can generate a FITS tape containing header information only and may be used as a means for examining the IRAF image header or for generating a table of contents on a tape prior to writing the data. (default = yes) .le .ls 4 bitpix This parameter must be either 8, 16, or 32 to specify the allowable FITS pixel sizes. .le .ls 4 scale If this switch parameter is set to no, the FITS scaling parameters BSCALE and BZERO will be set to 1.0 and 0.0 respectively. The data will be copied as it appears in the original data, with possible loss of dynamic range. Values exceeding the maximum value implied by the bitpix parameter will be set to the maximum representable value. (default = yes) .le .sh TEXT (Write Card-Image) Although this format is easily readable by the destination machine, there is no real standard for encoding information, neither the image data itself nor the descriptive parameters. .ih NAME wtext -- Convert an IRAF image file to a card-image text file .ih USAGE wtext [destination, filename, files] .ih DESCRIPTION Data is read from the specified filename(s) and written to the destination, usually a magnetic tape. The data will be blank padded, ASCII in a format consistent with the data type of the image pixels, (integer or floating point). A short header description, consisting of the filename being converted and the image label, may optionally be printed on the standard output. The column length of the "card" may be changed from the default of 80 using the card_length parameter, and the field width to be allocated for each data element may be changed from the default of 10 columns by setting the field_width parameter. If the data are integers, the equivalent of the FORTRAN format I will be used; if the data are reals, the equivalent of the FORTRAN format 1PE.3 will be used, where n is the number of elements which can be output into one card length. For the default values of card_length = 80, and field_width = 10, n will be 8. (1P8E10.3). Several cards may be written as a single "block" for improving the efficiency on magtape. Reasonable efficiency (80 percent) is attained with a blocking factor of 50, but this value may be modified by changing the parameter blocking_factor. If the last block is unfilled, it will be truncated to the minimum number of card images required to flush the data. A legitimate value must be defined to represent blank pixels. The parameter blank_value is used to define this value and defaults to -32767. .ih PARAMETERS .ls 4 text_destination See the definition for fits_destination for a description of this parameter. .le .ls 4 filename See the definition of this parameter under RFITS. .le .ls 4 files See the definition of this parameter under RFITS. .le .ls 4 print_header If this switch is set, a short header is printed for each file converted. (default = yes) .le .ls 4 card_length The number of columns on the "card" to be generated. (default = 80) .le .ls 4 field_width The number of columns on the "card" to be allocated for each pixel value. (default = 10) .le .ls 4 blocking_factor The number of card images to be written as a single blocked record. (default = 50) .le .ls 4 blank_value The value to be assigned to blank pixels for the purpose of representing them on the card image. (default = -32767) .le .bp .sh MATHEMATICAL OPERATORS Because spectra are stored as IRAF images, the standard image calculator utility provides the basic arithmetic services. For example, to create a spectrum (called spavg) which is the average of two other spectra (sp1 and sp2), one can enter the command: .ls 8 cl>imcalc "spavg = (sp1 + sp2) / 2" .le Other arithmetic operations are performed in a similar fashion. The general form of the command string is output_image = expression where "expression" may consist of: .ls 8 1. Spectra or segments of spectra A segment of a spectrum is specified by the notation spectrum[x1:x2] where x1 and x2 are pixel indices along the spectrum. For example, to create a spectrum which is the difference of the first 100 pixels of two other spectra, the following command would be used: .ls 16 cl> imcalc "spdiff = sp1[1:100] - sp2[1:100]" .le An option to specify wavelength delineated segments may be added if this appears generally feasible. .le .ls 8 2. Numeric constants .le .ls 8 3. Data group names If an operation is performed on a data group, the output will be a new data group containing spectra which have been individually treated by the specified calculation. For example, if JAN28 is a group containing 100 congruent spectra and response is the instrumental response as a function of wavelength as determined from a set of standards, then the after the following command is entered: .ls 16 cl> imcalc "JAN28X = JAN28 * response" .le a new data group will be generated containing 100 spectra which have been calibrated for the instrument response. The new spectra will be given names JAN28X1 through JAN28X100. .le .ls 8 4. Intrinsic functions .ks The following intrinsic functions are to be provided: .nf abs atan2 cos int min sin acos ceil cosh log mod sinh aimag char double log10 nint sqrt asin complex exp long real tan atan conjug floor max short tanh .fi .ke .le Expression elements are to be separated by arithmetic and boolean operators (+,-,*,/,**,<,>,<=,=>,==,!,!=). The boolean operators provide a means to generate masks. Rules governing operations on non-congruent spectra are not yet fully defined. .bp .sh REDUCTION OPERATORS Most of the reduction operators discussed in this section are intended for spectra of the IIDS/IRS class, although they are sufficiently general to accommodate data obtained with the CryoCam (either multi-aperture or long-slit mode), Echelle, Coude Feed, and photographic (PDS) instruments. Some application to FTS data is also feasible. It is intended that many of these operators will never be directly executed by users, but that they will be driven by CL command scripts tuned for individual instruments. In some cases the scripts will be fairly elaborate and extensive to lead new users through the reduction phase along a reliable path. It will no doubt be necessary to either modify some of these operators, or create more specific operators for certain other instruments. These operators should be considered a sample of what will eventually be available in this package. The basic path which most spectroscopic data follows is: .ls 4 1. Coincidence Correction. .ls Many detectors can respond to incoming photevents at a limited rate. Once an event occurs, the detector cannot respond for some instrument dependent period, or dead-time. If events occur during this period, they will not be counted. If the event rate does not greatly exceed the detector limits, the uncounted events can be corrected for statistically. For many detectors, the coincidence correction is a well determined function and can be applied to the raw data to produce a reasonably corrected spectrum. .le .le .ls 4 2. Wavelength linearization. .ls Few instruments produce spectra having pixel to pixel wavelength differences which are constant across the entire spectrum. For subsequent reduction and analysis purposes, it is desirable to rectify the spectra. This is done by mapping the spectrum from the non-linear wavelength coordinate to a linear one. It is also desirable to provide a means of forcing the mapping to a grid which is common to many observations, and in some cases, to observations acquired with other instruments as well. The processes required for the mapping are outlined below. .le .ls 4 a. Manually identify a small number of spectral features having known wavelengths thereby creating a table of wavelength as a function of pixel number. .le .ls 4 b. Compute estimated relationship between wavelength and pixel number .le .ls 4 c. Automatically locate many features found in a user definable line list. Optionally locate additional features from other spectra using an alternate line list. (This allows spectra from several different sources to be used for the wavelength calibration, such as arc lamps, night/day sky.) .le .ls 4 d. Compute improved relationship between wavelength and pixel number. .le .ls 4 e. Perform 2.c. and 2.d. for all other spectral entries in the wavelength calibration data group. .le .ls 4 f. Compute relationship for wavelength as a function of pixel number and time (or zenith distance, or some other flexure parameter) as deduced from 2.e. .le .ls 4 g. Apply inverse of wavelength function to a data group. This requires interpolation of the data at pixels having fixed steps in wavelength. The start wavelength and the step size must be user definable. The interpolation may be via a polynomial of a user specified order (typically 1 to 5), or a more sophisticated interpolator. The linearization in wavelength may also be a simple rebinning of the data to exactly preserve photon statistics. .le .le .ls 4 3. Field flattening. .ls Pixel to pixel sensitivity variations and other small scale fluctuations are removed by dividing the object spectra by the spectrum of a continuum source. The latter spectrum should have a very high signal-to-noise ratio so as not to introduce additional uncertainties into the data. If the spectrum of the continuum source has much low frequency modulation, it may be necessary to filter these variations before the division is performed. Otherwise fluctuations not characteristic of the instrument response may be introduced, and may be difficult to remove during the subsequent flux calibration process. .le .le .ls 4 4. Sky Subtraction .ls Except for extremely bright sources, all spectra require that the spectrum of the night sky be removed. In some cases, sky will be the dominant contributor to the raw spectrum. Sky subtraction is a simple subtraction operation and can be accomplished with the image calculator tools. .le .le .ls 4 5. Extinction Correction .ls The effects of the Earth's atmosphere produce a wavelength dependent reduction of flux across the spectrum. The extinction function is approximately known from extensive photometric measurements obtained at the observatory over a period of many years. But on any given night this function may deviate from the average, sometimes significantly. If the spectroscopic observer has acquired the necessary data, it is possible to solve for the extinction function directly. Therefore, it should be possible for the user to either derive the extinction function, input a user-defined function, or use the standard average function and subsequently correct spectra for the effects of the atmosphere as described by that function and the effective observing airmass. (Note that because exposures may be quite long, the effective airmass must be calculated as a function of position on the sky.) .le .le .ls 4 6. Flux Calibration (Correction for Instrument Response) .ls By observing objects having known wavelength dependent flux distributions, it is possible to determine the sensitivity variations of the instrument as a function of wavelength. Usually several standards are observed for each group of data and these must be averaged together after corrections for "grey shift" variations (wavelength independent flux reductions such as those introduced by thin clouds). Although the actual flux of the standards is generally known only for a limited selection of wavelengths, the instrument response usually varies smoothly between those wavelengths and a smooth interpolator generally provides satisfactory calibration values at intermediate wavelengths. In some cases, the system sensitivity response may be known from other observations, and the user will be allowed to directly enter the sensitivity function. .le .le The above reduction path is primarily tuned to IIDS/IRS style data. Other instruments may require additional or alternate steps. It may be necessary for multiaperture Cryocam spectra, for example, to undergo an additional hole to hole sensitivity correction based on the total sky flux through each hole. The tasks performing the procedures outlined above will be described in more detail in the following discussion. .sh COINCIDENCE CORRECTION .ih NAME coin_cor -- Correct specified spectra for photon coincidence .ih USAGE coin_cor [filename, files, destination, dead_time] .ih DESCRIPTION The spectra specified by the root filename and the files parameter are corrected for photon counting losses due to detector dead-time. The corrected spectra are written to filenames having the root specified by the destination. The correction, if typical of photomultiplier discriminators, is usually of the form: .br Co(i) = C(i) exp[C(i) dt], .br dt = t/T, .br where Co(i) is the corrected count at pixel i, C(i) is the raw count, t is the detector/discriminator dead-time, and T is the exposure time at pixel i. Clearly, the correction factor can become extremely large when the count rate, C(i)/T, is large compared with the dead-time, t. The above formula cannot be expected to exactly remove the effects of undetected photo-events when large corrections are required. The exposure time will be read from the image header. If no value exists, or if the value is less than or equal to zero, a request from standard input will be issued for this parameter. Because each detector may have unique coincidence properties, this routine may be package dependent. .ih PARAMETERS .ls 4 filename See the definition of this parameter under RFITS. .le .ls 4 files See the definition of this parameter under RFITS. .le .ls 4 destination The IRAF filename providing the root for the name of the result spectra. The files parameter, if specified, will be used for the suffix. If the filename parameter is actually a data group name, the destination name will be used to create a new data group containing spectra having IRAF filenames with the destination group name as a root and a suffix starting with 1 and incremented for each converted spectrum. .le .ls 4 dead_time The value of this parameter, in seconds, represents the detector dead-time. .le .ls 4 print_header If this switch is set, a short header will be printed on the standard output for each spectrum corrected. (default = yes) .le .ls 4 exposure This parameter should be entered into the image header. If not present or not realistic, a request is made from standard input. .le .sh WAVELENGTH LINEARIZATION A package of routines is required to perform the operations leading to linearized data. These include: .ls 4 1. Spectral line list definition and editing facility .le .ls 4 2. Manual line identifier using graphics cursor. .le .ls 4 3. Automatic line identifier using preliminary identifications from manual identifier and locating lines from the predefined list. .le .ls 4 4. Computation of dispersion relationship as a function of pixel coordinate and a flexure parameter, probably zenith distance. .le .ls 4 5. Linearization of spectra according to dispersion relation. Correction can be to either a linear or logarithmic dispersion in the pixel coordinate. .le Perhaps the most critical aspect of determining the dispersion relation is the algorithm for locating spectral line centers. A variety of techniques are available, and some testing will be required before adopting a standard scheme. Probably several algorithms will be available and switch selectable at the command level. .sh LINE LIST PREPARATION .ih NAME line_list -- Create a new line list, or modify an existing one .ih USAGE line_list [filename, option] .ih DESCRIPTION The line list specified by the IRAF filename parameter will be either created, listed, or modified according to the option given. The IRAF database facility will be used to manage the line list file. Each entry within the list will contain an identification tag (e.g. HeII) a reference value (e.g. wavelength, frequency, wavenumber), and a weighting value such as 1.0 or 2.0 to be used later in the least-squares fitting. An optional descriptive header may be associated with the line list. (e.g. "HeII arc from 3500 to 11,000A") Either the header, entry identifier or value may be changed if the modify option is specified. Deletion or addition of entries is also possible with the appropriate option flags specifications. .ih PARAMETERS .ls 4 filename The IRAF filename to be assigned to the line list. The list will referenced by this name thereafter. .le .ls 4 option This string parameter determines the action of the line list task. If no option is specified, the default action is to list the specified line list on the standard output if the line list exists; if it does not exist, a new line list will be created with the given name. .ls 4 = create The identifications and values for the line list are read from the standard input on a record by record basis. Each input record contains data for one line according to the format: .br .ls 4 identification value .le .le .ls 4 = header A descriptive header is read from the standard input. .le .ls 4 = list (default) The line list is listed on the standard output. .le .ls 4 = add Additional entries to the list are read from the standard input. .le .ls 4 = delete The entries defined by the values read from the standard input are deleted from the line list. The entries deleted will be those having values nearest the entered value, unless the absolute difference from the listed value is too large. For example, one can enter 5015 to delete the helium line at 5015.675, but entering 5014 would result in an error message that no match could be found. .le .ls 4 = id The entries defined by values entered as for delete will be modified. Input is expected in the format: .br approxvalue newidentifier .le .ls 4 = value As for option = id except that the input format contains the newvalue instead of the newidentifier. .le .ls 4 = weight As for option = id except that the nput format contains the newweight instead of the newidentifier. .le .le .sh MANUAL LINE IDENTIFICATION This routine provides the option of manually identifying the locations of spectral features by either setting a graphics cursor interactively, or by entering a list of feature positions. The primary uses for this routine are to identify features of known wavelength in preparation for a dispersion solution, and also to identify features in linearized spectra for velocity measurements. .ih NAME mlinid -- Manually identify line features in a spectrum .ih USAGE mlinid [filename, files] .ih DESCRIPTION A list file is created for each of the spectra specified by the IRAF filename parameter and files string containing the locations of spectral features and their associated reference value (e.g. wavelength, frequency, wavenumber). If invoked as an interactive task from a graphics terminal, the spectra will be displayed and cursor input requested to ascertain the approximate position of the feature. An improved position will be obtained via one of the line centering algorithms, and a request will be made for the reference value of the feature. The requests continue until EOF is detected. The name of the created list file is added to the spectral image header. Positions of features are given in the coordinate system defined by the standard image header entries CRPIX and CDELT defining the reference pixel and the pixel to pixel distance. For raw spectra these values simply define the pixel position of the feature. For dispersion corrected spectra these values define the position of the feature in wavelength units. If invoked as a background task, or from a non-graphics terminal, additional requests for the cursor x-coordinate and intensity will be made from the standard input. The procedure is repeated for all specified spectra. Because the dispersion solution may be a function of an additional instrument dependent parameter (e.g. zenith distance), the driving package script can indicate the header entry to be used as the second parameter. Values for this parameter, if present, will be written to the output list file. .ih PARAMETERS .ls 4 filename See the definition of this parameter under RFITS. .le .ls 4 files See the definition of this parameter under RFITS. .le .ls 4 cur (x,y) This is a list structured parameter of type "graphics cursor". The list contains the approximate values of the pixel coordinate for the spectral features to be identified and the intensity value of the continuum at the feature. If the task is invoked from a graphics terminal in an interactive mode, values for this parameter will be read from the terminal's graphics cursor. .le .ls 4 value This is a list structured parameter containing the reference values for the spectral features to be identified. If the task is invoked in an interactive mode, the user will be prompted for these values. .le .ls 4 center_option This string parameter controls which algorithm is to be used during the improved centering phase of the process. (default = cg) .ls 4 = cg This specifies a center of gravity algorithm defined as the first moment of the intensity above the continuum level across the spectral feature. The integrals are evaluated using the trapezoidal rule and the intensity will be weighted by the square root of the intensity if the switch parameter cgweight is set to yes. The integral is evaluated from the approximate position defined by x cursor position plus and minus the number of pixels specified by the parameter cgextent. .ls 4 cgweight This switch defines whether a weighted moment is used in the center of gravity centering algorithm. (default = yes) .le .ls 4 cgextent This integer parameter defines the limits of the integrals in the center of gravity centering algorithm. The integral extends from the approximate position minus the extent to the approximate position plus the extent in units of pixels. (default = 5). .le .le .ls 4 = parabola This specifies that the centering algorithm is to be a parabolic fit to the central 3 pixels. The improved center is taken as the center of the parabola. The central 3 pixels are defined as the most extreme local pixel plus and minus one pixel. The most extreme local pixel is that pixel nearest the approximate center having the greatest deviation from the local average value of the spectrum. The extent of "local" is taken as plus and minus the parameter parextent. .ls 4 parextent This integer parameter defines the extent in units of pixels of the search for a local extreme pixel. (default = 3) .le .le .ls 4 = gauss (This algorithm will not be implemented in the initial system release.) This specifies that the centering algorithm is to be a Gaussian fit to the region near the approximate center. The fit is made to a region specified by the parameter gextent. Because this is a three parameter non-linear least-squares fit (center, width, peak intensity), it is likely to be slow. It may also produce poor results with noisy data although centering on high signal to noise data should be excellent. .ls 4 gextent This integer parameter specifies the extent in pixels of the Gaussian fit. It may be necessary to include a significant region of continuum. (default = 9) .le .le .ls 4 = none If this option is chosen, no improvement to the approximate center will be made. This may be useful for asymmetric and weak features where the other techniques can be systematically incorrect. .le .ls 4 second_order This string parameter defines the name of the image header entry to be used as the second order correction parameter in the dispersion solution. Values for this parameter, if present, are read from the image header and written to the output list file. Examples of values are zenith_distance, sidereal_time, instr_temp. (default = none) .le .sh AUTOMATIC LINE IDENTIFICATION This task allows a user to locate a set of spectral features defined in a previously prepared list. .ih NAME alinid -- Automatically locate spectral features in a spectrum .ih USAGE alinid [filename, files, mfilename, mfiles, list] .ih DESCRIPTION A list file is created for each of the spectra specified by the IRAF filename and files parameters. The file will contain the positions of the features defined in the line list file specified by the list parameter. The name of the list file will be added to the spectral image header. A preliminary estimate of the relationship of feature position as a function of feature wavelength is obtained from the list file(s) created by the task MLINID and defined by the parameters mfilename and mfiles. A single preliminary estimate may be applied to a number of spectra by specifying a null mfiles string. Otherwise, a one-to-one correspondence is assumed between preliminary list files and spectra. If the entry for mfilename is also null, the linear dispersion relation for the pixel coordinate contained in the image header will be used. This provides the option of locating features in linearized spectra. The initial position estimate is improved using one of the centering algorithms defined by the center_option parameter and then written to a list file. Also written to the list file will be the feature's reference value (e.g. wavelength), weight, identification string, and the acceptability of the line. Acceptibility is noted as either accepted, set, deleted, or not found (see below). If the task is invoked from a graphics terminal as an interactive task, the interact switches may be set to yes. Then each spectrum will be displayed in segments expanded about each feature with the automatically defined center marked. The user can then accept the given position, mark a new center, or declare the line unacceptable. If the display switch is set, the spectrum is displayed and the features marked. If the task is invoked as a background task, or if the user terminal is non-graphics, then the display and interact switches cannot assume values of yes. .ih PARAMETERS .ls 4 filename See the definition of this parameter under RFITS .le .ls 4 files See the definition of this parameter under RFITS .le .ls 4 mfilename The root for the spectra names used to define the preliminary relationship between spectral feature coordinate and reference value. The mfiles string parameter is used to define the suffix of the spectral name. If this parameter is null, the preliminary relationship is assumed to be linear and defined by the standard image header entries CRPIX and CDELT. .le .ls 4 mfiles This string parameter serves the same purpose for mfilename as the files parameter serves for filename. Note that if this parameter is null, the single spectrum defined by mfilename is used to define the preliminary relationship for all spectra defined by filename and files. .le .ls 4 list This parameter specifies the IRAF file name containing the spectral line list to be scanned for features. (See the task LINE_LIST) .le .ls 4 interact If this switch is set to yes and the task is invoked interactively from a graphics terminal, the spectrum will be displayed on the terminal. Each feature will be marked with its computed center and the user can type one of the following single keystrokes: .ls 4 a to accept the displayed position .le .ls 4 s to set the cursor to the desired position .le .ls 4 d to delete the displayed feature from the line list during this invocation of the task .le .ls 4 b to reset the operational mode to a "batch" environment where no display or interaction is desired .le .ls 4 p to reset the operational mode to a "passive" environment where the spectra are displayed and marked, but no interaction is desired .le .le .ls 4 display If this switch is set to yes, and the task is invoked from a graphics terminal, the spectrum will be displayed and the identified lines marked for the user's inspection. No interaction is allowed unless the interact switch is also set to yes. (default = yes) .le .ls 4 center_option See the description of this parameter under MLINID. .le .ls 4 second_order See the description of this parameter under MLINID. .le .sh DISPERSION SOLUTION After several spectral features have been identified, either manually with MLINID or automatically with ALINID, the relationship between feature reference value and pixel coordinate can be calculated. The dispersion relation may require a second order correction to account for variations as a function of some additional parameter, such as zenith distance or time of day. .ih NAME disp_sol -- Determine the dispersion relation for a set of spectra. .ih USAGE disp_sol [filename, files, order, global] .ih DESCRIPTION The list files containing the postions and reference values for features in the specified spectra are combined to solve for the dispersion relation by a polynomial least-squares fit to the lists. The solution can include a second order correction parameter which is also contained in the list file. The solution takes the form of a polynomial in the pixel coordinate having the specified order. The second order is also fit by a polynomial. (The choice of a polynomial applies to the initial release. Additional forms, selectable by parameter, of the solution may be available later.) The polynomial coefficients are stored in the spectral image header if the store_coeffs switch is set to yes and the spectrum does not already contain a solution. If a solution already exists, the user is asked for confirmation to overwrite the solution, unless the overwrite switch is set to yes. If filename is the name of a data group, all line list files for spectra in that data group are combined into the solution. If invoked as an interactive task from a graphics terminal, a representation of the solution will be displayed and the user will be allowed to alter the weights of the line entries. If invoked from a non-graphics terminal, the representation will be in a tabular format (also available at a graphics terminal) for inspection and alteration. If invoked as a background task, an attempt will be made to reject discrepant points. The solution is made using all available line lists combined into a single data set if the global switch is set to yes. If global is set to no, each spectrum is treated as an independent data set. .ih PARAMETERS .ls 4 filename See the definition of this parameter under RFITS. .le .ls 4 files See the definition of this parameter under RFITS. .le .ls 4 order The order of the polynomial for a least-squares fit to the dispersion solution. If the specified order exceeds the number of free parameters, the order will be reset to the maximum allowable. (default = 1 --> linear). .le .ls 4 global This switch determines if the data from all the specified spectra are to be treated as a single large data set. This is appropriate if the data represent a single congruent "setup". But if the data represent several different configurations, such as for multiaperture data, the global switch should be set to no. Note that if global is no, then no second order parameter solution is possible. .le .ls second_order This parameter specifies the order for the fit to the second order parameter. The limit described for the order parameter applies. (default = 0 --> no second parameter solution). .le .ls 4 interact If this switch is set to yes and the task is invoked interactively from a graphics terminal, the residuals of the solution will be displayed on the terminal. The user can type one of the following keystrokes: .ls 4 a to accept the current solution. The parameters of the fit are written into the headers of the spectra contributing to the fit. .le .ls 4 e to exit without saving the solution .le .ls 4 w to reset the weight of the point near the cursor positioned by the user. The user is then prompted for the new weight which may be set to zero to delete the point from the solution. .le .ls 4 t to display the solution parameters in tabular form .le .ls 4 o to specify a new order for the solution .le .ls 4 s to specify a new order for the second order parameter solution .le .ls 4 b to revert to batch mode to process the remainder of the solutions. This is only meaningful if the global switch is set to no. .le .ls 4 p to revert to passive mode as for ALINID. This is only meaningful if the global switch is set to no .le .le .ls 4 store_coeffs If this switch is set to yes, the dispersion solution polynomial coefficients will be written into the image header as special header elements. Otherwise, the solution is discarded. (default = yes) .le .ls 4 overwrite If this switch is set to yes, any existing dispersion solution contained in the image header will be overwritten without any request for confirmation from the user. If set to no, the user is asked if overwriting of the solution is acceptable. If no prior solution exists, this switch has no meaning. (default = no) .le .sh DISPERSION CORRECTION After the dispersion relation has been determined, the spectra are usually re-binned to create spectra having a linear relationship with wavelength. Although this is not always done, nor is it always desirable, subsequent processing is often simplified greatly by having to deal with only linearized data. .ih NAME disp_cor -- Linearize spectra having dispersion relation coefficients .ih USAGE disp_cor [filename, files, destination, option] .ih DESCRIPTION The spectra specified by the root filename and the files parameter are corrected for deviations from a linear wavelength relationship. The corrected spectra are written to filenames having the root specified by the destination parameter. The correction is performed by solving for the inverse relationship of pixel number as a function of equal increments in the wavelength. The new starting wavelength and increment are optionally specified by the parameters start and increment. If not specified, the current wavelength of the first pixel will be taken as the starting wavelength and the increment will be chosen to exactly fill the length of the current spectrum. The spectrum will be padded with INDEF on either end if the specified parameters request a larger spectral window than actually exists. The actual re-binning can be performed using one of several algorithms. The most efficient minimally smoothing algorithm to be available in the initial release is the fifth order polynomial interpolation. The most efficient count preserving algorithm is the simple partial-pixel summer. The interpolation can be either linear in wavelength or in the logarithm of wavelength. The latter is useful for subsequent radial velocity analyses. The choice is specified by the logarithm switch. .ih PARAMETERS .ls 4 filename See the definition of this parameter under RFITS. .le .ls 4 files See the definition of this parameter under RFITS .le .ls 4 destination See the definition of this parameter under COIN_COR. .le .ls 4 option This parameter specifies the algorithm to be used for the re-binning operation. The initial release will contain the following options: .ls 4 = linear to use a linear interpolation .le .ls 4 = poly to use a fifth order polynomial .le .ls 4 = sinc to use a sinc function interpolator .le .ls 4 = sum to use partial pixel summation .le .le .ls 4 start This parameter specifies the wavelength at which the corrected spectrum is to begin. The wavelength of the first pixel will be assigned this value. This parameter, combined with the increment parameter, allows data taken on different nights or with different instruments to be forced to be congruent. (default = value at first pixel) .le .ls 4 increment This parameter specifies the pixel to pixel wavelength (or logarithm of wavelength) increment that is to be used during the linearization process. (default = [wavelength at last pixel minus wavelength at first pixel] divided by [number of points in spectrum - 1]) .le .ls 4 logarithm If this switch is set to yes, the linearization occurs with equal increments in the logarithm of wavelength. Otherwise, equal increments of wavelength are used. (default = no) .le .ls 4 print_header See the definition of this parameter for COIN_COR. .le .sh FIELD FLATTENING Most detectors exhibit variations in sensitivity across the field of interest. These are removed by dividing all observations by the spectrum of a smooth continuous source, such as an incandescant lamp. In order that these lamps, which usually have a low color temperature, produce sufficient energy in the blue and ultraviolet, they are often enclosed in a quartz rather than a glass bulb. Thus, the field flattening operation is often referred to as "quartz division". The operation is of marginal value unless the continuum source is observed properly. First, a very high signal-to-noise ratio per pixel is required. For certain detectors and applications this may not be possible in a reasonable amount of time. Second, the continuum source should not have any significant variations across small regions of the spectrum (high frequency "bumps"). Otherwise the division will add these variations into the spectrum. There are basically two aspects to flat fielding spectra. The first is the removal of pixel-to-pixel sensitivity variations. The second is a more global pattern due to non-uniform iillumination and spatial and wavelength sensitivity variations across the detector. The very high frequency pixel-to-pixel variations are easily handled by a straightforward division of the observations by the continuum spectrum. The second problem is usually postponed in one-dimensional data reductions and included in the solution for the system sensitivity by observing standard stars. This aspect of the problem is adequately handled in this fashion and no special operators are provided in this package. If the continuum source exhibits large low frequency variations across the spectrum, it may be desirable to filter these. This is most easily done by fitting a moderately high order polynomial through the spectrum, and then dividing the polynomial representation into the original continuum spectrum. The result is a flat spectrum having an average value of unity and containing only the pixel-to-pixel sensitivity variations. Finally, it should be noted that the field flattening operation is most properly performed prior to the wavelength linearization of the spectra because the linearization process can smooth pixel-to-pixel variations. Flat fielding consists of two logical operations. The first is the solution for a continuum spectrum with the low frequency variations removed (CR_FLAT). It is assumed that multiple observations of the continuum source have been already averaged (using the image calculator program, for example). The second operation is the actual field flattening of the object spectra (FLT_FIELD). .ih NAME cr_flat -- Create a flat field spectrum .ih USAGE cr_flat [filename, destination] .ih DESCRIPTION The continuum spectrum specified by filename is corrected for low frequency spectral variations. Several algorithms may be available. The initial release will contain only a polynomial fitting technique. A fourier filtering algorithm may be added at a later date. The spectrum is fit by a polynomial in the pixel coordinate and the polynomial is divided into the original spectrum. Discrepant pixels may be rejected and the solution re-iterated. If invoked as an interactive task from a graphics terminal, the resultant spectrum is displayed and the user may alter the solution parameters if the interact switch is set to yes. If invoked from a non-graphics terminal, sufficient information concerning the fit is written to the terminal to allow the user to judge the quality of the fit and then alter the solution parameters. If invoked as a background task, or if the interact switch is set to no, default parameters will be assumed. The parameters of the fit are added to the image header for the corrected spectra. .ih PARAMETERS .ls 4 filename The IRAF filename containing the spectrum of the continuum source. If this is a data group name, then all spectra in the group will be corrected. .le .ls 4 destination The IRAF filename into which the resultant corrected spectrum is written. If the source filename is a data group, then the destination will be a new data group containing the names of the corrected spectra. The names will be assigned using the destination as a root name, and the ordinal of the spectrum in the list as a suffix. .le .ls 4 option This string parameter specifies the algorithm to be used in the correction process. Currently only option = poly is recognized. .le .ls 4 order This integer parameter specifies the initial order of the polynomial fit. (default = 8) .le .ls 4 reject This parameter specifies the number of standard deviations beyond which pixels are to be rejected. If the task is interactive, pixel rejection is performed only on command. If invoked as a background task, rejection is iterated until no further pixels are rejected, or until the iteration count has been attained (see parameter niter). (default = 2.2) .le .ls 4 niter This integer parameter specifies the number of iterations to be performed in background mode. It may be set to 0 to specify no pixel rejection. (default = 2). .le .ls 4 interact If this switch is set to yes and the task is invoked as an interactive task, the user can alter the fit parameters order, reject, and niter. If at a graphics terminal, the resultant spectrum is displayed and the user can command the operation with the following single keystrokes: .ls 4 a to accept the solution .le .ls 4 o to change the order of the fit .le .ls 4 r to reset the reject parameter .le .ls 4 n to reset the niter parameter .le .ls 4 b to reset the operational mode to a batch environment .le .ls 4 p to reset the operational mode to a passive environment .le .le If at a non-graphics terminal, the fit parameters are written to the terminal so that the user may assess the quality of the fit. A request for one of the interactive commands is then issued and the user may proceed as if on a graphics terminal. .le .ih NAME flt_field -- Correct spectra for pixel-to-pixel variations .ih USAGE flt_field [filename, files, flatname, destination] .ih DESCRIPTION The spectra specified by the IRAF filename parameter and the files string are divided by the flat field spectra specified by the parameter flatname. If filename and flatname are data group names, the division is performed on a one-for-one basis. This operation is little more than a simple division. An image header entry is added indicating that flattening by the appropriate spectrum has been performed. .ih PARAMETERS .ls 4 filename See the definition of this parameter under RFITS. .le .ls 4 files See the definition of this parameter under RFITS. .le .ls 4 flatname This string parameter sepcifies the name of the flat field spectrum, or spectra if a data group name. It is not necessary that the flat field spectra be corrected for low frequency spectral variations. It is required that the spectra be congruent with the spectra to be flattened; that is, all spectra must have the same length, reference pixel, and pixel-to-pixel increment. .le .ls 4 destination See the definition of this parameter under COIN_COR. .le .ls 4 print_header See the definition of this parameter under COIN_COR. .le .sh EXTINCTION CORRECTION/FLUX CALIBRATION At each wavelength (lambda) along the spectrum, the observed flux (fobs) must be corrected for extinction (k) due to the Earth's atmosphere and the system sensitivity (S) to obtain a true flux (f) above the atmosphere. .sp 1 fobs(lambda) = f(lambda) * exp{-z[k(lambda)+C]} * S(lambda) .sp 1 where z is the path through the Earth's atmosphere during the observation and C is an optional "grey" opacity term. For most observations, the standard extinction function is adequate, but occasionally the additive term is beneficial. In rare cases, the observer has acquired sufficient high quality data to determine the extinction function across the spectral region of interest. And in other cases, the user may have a priori knowledge of the extinction function. Observations of standard stars are used to determine either the additive constant or a new extinction function, and the system sensitivity. The two operations, determining the extinction parameters and the system sensitivity curve, are therefore intimately related. The process breaks down into four basic operations: .ls 4 1. Define the standard stars and their observations. (STD_STAR) .le .ls 4 2. Define the extinction solution option and solve for the extinction additive term or complete function if necessary. (CREXT_FUNC) .le .ls 4 3. Determine the system sensitivity function. (CRSENS_FUNC) .le .ls 4 4. Remove the effects of the extinction and the system sensitivity from the observations. (EXT_COR, SENS_COR) .le These will be described below in more detail. .ih NAME std_star -- Define the standard stars to be used for solving the extinction and system sensitivity functions. .ih USAGE std_star [fnamelist, filelist, namelist, std_file] .ih DESCRIPTION The spectra defined by the list of filenames and associated files contained in the string list parameters fnamelist and filelist are compared with the standard flux measurements for the stars listed in the string list parameter namelist. The resultant table of ratios as a function of wavelength are saved in the IRAF file specified by the std_file parameter. All spectra must be wavelength linearized. The star names given in namelist must be in a form similar to that in the IIDS Reduction manual. If a star name cannot be matched to the standards contained in a calibration file, the user is prompted for additional information. The calibration file containing the list of reference flux values is specified by the calib_file parameter. .ih PARAMETERS .ls 4 fnamelist This is a list structured parameter containing the IRAF filenames associated with the spectra for each of the standard stars contained in the list of starnames defined by the list structured parameter namelist. Both these parameters must have the same number of elements. The filename specifications are defined as in RFITS. .le .ls 4 fileslist This is also a list structured parameter having the same number of elements as fnamelist although some may be null. The entries are defined as in RFITS. .le .ls 4 namelist This is also a list structured parameter having the same number of elements as fnamelist. All elements must exist and have a form to be decided on, but probably similar to that given in the IIDS Reduction manual, page 36. For example, a typical star name might be BD+8 2015, or HILTNER 102. Case will not be significant. .le .ls 4 std_file This string parameter defines the IRAF filename in which the results from the standard star observations are stored. This file will be used to contain further calibration information such as the extinction and sensitivity function for the current set of observations. .le .ls 4 calib_file This string parameter defines which of several calibration data files are to be accessed for the comparison of the observational data to the standard fluxes. Separate tools to examine, modify, and create these files are available in the utilities package. (default = onedspec$iids.cal) .le .ls 4 print_header If this parameter is set to yes, an informative header is listed on the standard output as the standard stars are processed (default = yes). .le .ih NAME crext_func -- Create an extinction function from a set of observations .ih USAGE crext_func [std_file, option] .ih DESCRIPTION The user may specify via the option parameter which of the four extinction solutions is to be used. These are: .sp 1 .ls 4 1. Adopt standard extinction function (option = standard). .le .ls 4 2. Solve for an additive constant (option = additive). .le .ls 4 3. Solve for extinction function (option = new_function). .le .ls 4 4. Input a tabular extinction function consisting of extinction values at specified wavelengths (option = input). .le .sp 1 If the first or last options are chosen, the std_file may be empty. If the second option is chosen, several observations at differing air masses must be included in the file specified by std_file. If the third option is chosen, at least two standard stars must be included in the list of observations. The derived extinction function is added to the IRAF file specified by the std_file parameter by creating a new spectrum containing the function and adding the spectrum name to the std_file. The new spectrum will adopt a name having a root from the name std_file and a suffix of ".ext". The spectrum is created by a spline interpolation through the extinction values. If invoked as an interactive task from a graphics terminal, the derived extinction function is displayed. The user may interactively alter the derived extinction values using the graphics cursor. If invoked from a non-graphics terminal, the user may alter the values by specifying the wavelength and new extinction value from the standard input. Interaction may be suppressed by setting the interact switch to no. .ih PARAMETERS .ls 4 std_file See the definition of this parameter under STD_STAR. .le .ls 4 option This parameter specifies which aspects of the extinction solution are to be computed. See description section for CREXT_FUNC. .le .ls 4 interact If this switch is set the user may alter the derived extinction values. If invoked from a graphics terminal and interact is set to yes, the following single keystroke commands may be typed: .ls 4 a to accept the current solution .le .ls 4 m to modify the extinction value at the cursor wavelength position (cursor-x) to the cursor extinction value position (cursor-y). .le .ls 4 i to insert a new wavelength-extinction value pair at the current crosshair position. .le .ls 4 d to delete the wavelength-extinction value pair at the current cursor wavelength position. .le .le .ih NAME crsens_func -- Create system sensitivity function. .ih USAGE crsens_func [std_file, option] .ih DESCRIPTION The standard star data and extinction function contained in the IRAF file specified by the std_file parameter are used to compute the system sensitivity as a function of wavelength. The derived function is written to the file specified by std_file. There must be at least one standard star observation contained in the std_file, unless the parameter option = input. This allows the user to enter any function in the form of wavelength-sensitivity pairs. If option = shift, a "grey" shift is applied to all observations necessary to bring relatively faint values up to the brightest to account for possible cloud variations. If invoked as an interactive task from a graphics terminal, and the interact switch is set to yes, the sensitivity values from each standard are plotted with any "grey" shift correction added. The user may delete or add new points as desired using the cursor. If invoked from a non-graphics terminal, a tabular list of the solution is presented and additions or deletions may be entered through the standard input. The final function written to the std_file is simply the name of a new spectrum derived from a spline fit to the sensitivity if the spline switch is set to yes. If spline = no, a linear interpolation between sensitivity points will be used. The sensitivity spectrum name will be taken from the file name given to std_file and with the suffix ".sen". .ih PARAMETERS .ls 4 std_file See the definition of this parameter under STD_STAR. .le .ls 4 option This parameter can assume the following string values: .ls 4 = input to indicate that the sensitivity function is to be entered as wavelength-sensitivity pairs. .le .ls 4 = shift to force a "grey" shift between all standard star spectra to account for clouds. This is actually a multiplicative factor across each of the affected spectra. .le .le .ls 4 spline This switch parameter determines if a spline fit is to be made between the sensitivity points (spline = yes), or a linear fit (spline = no). (default = yes). .le .ls 4 interact If invoked as an interactive task, the user may alter the sensitivity function values. If at a graphics terminal, the sensitivity curve is displayed first for each star in the solution. The user may add or delete values for any or all stars at a given wavelength. Subsequently, the derived average curve is displayed and the user may further modify the solution. The following keystrokes are available from the graphics terminal: .ls 4 a to accept the current displayed data (solution). .le .ls 4 d to delete the value at the cross-hairs. If several values are very close together, an expanded display is presented. .le .ls 4 i to insert the sensitivity value of the y-cursor at the wavelength position. .le .ls 4 c to "create" new sensitivity values at the wavelength position of the x-cursor. Normally sensitivity values are computed only at pre-defined wavelengths specified in the calib_file. Additional values may be computed by interpolation of the standard star fluxes from the calib_file. The name of the calib_file and the spectra in the current solution are taken from the std_file. .le .le .ih NAME ext_cor -- Extinction correct specified spectra .ih USAGE ext_cor [filename, files, std_file, destination] .ih DESCRIPTION The spectra specified by the filename and files parameters are corrected for atmospheric extinction according to the extinction correction function pointed to by the function name in std_file. The resulting new spectra are created with the root of the destination parameter and having suffixes of 1 through n corresponding to the n spectra corrected. If filename is a data group name, a new data group will be created having the name given by the destination parameter. The correction has the form: .sp 1 f(lambda) = fobs(lambda) / 10**{-z[a(lambda) + C]} .sp 1 where: .ls 4 f(lambda) = the flux at wavelength lambda above the Earth's atmosphere. .le .ls 4 fobs(lambda) = the flux observed through the atmosphere .le .ls 4 z = the path length through the atmosphere is units of air masses (= 1 at the zenith) .le .ls 4 a(lambda) = the extinction function at wavelength lambda in magnitudes per airmass. .le .ls 4 C = the additive constant, if any, in magnitudes per airmass. .le .sp 1 For each spectrum, the zenith distance must be present in the image header. This is assumed to be correct for the beginning of the observation. For short exposures, this is adequate for the correction, but for long exposures, an effective air mass must be calculated over the integration. To do so requires knowledge of the altitude and azimuth of the telescope (or equivalantly RA, Dec, and sidereal time). If these are not present, the approximate air mass calculation will be used based solely on the available zenith distance. If the zenith distance is not present, user input is requested. The air mass is calculated according to the following equation for a given telescope position (based on Allen p.125,133): .sp 1 z = sqrt{[q sin (alt)]**2 + 2q + 1} - q sin(alt) .sp 1 where: .ls 4 q = atmospheric scale height (approx = 750). .le .ls 4 alt = telescope altitude .le .sp 1 If the telescope traverses a significant distance in elevation during the integration, an effective correction can be computed as: .sp 1 f(lambda)a = f(lambda)obs*T / integral{10**[-z(t)(a(lambda) + c)]}dt .sp 1 where the integral is over the integration time, T. This expression can then be evaluated numerically at each wavelength. Because this is a time-consuming operation, the switch effective_cor can be set to no and then a simplified correction scheme will be used. This will be to compute a midpoint airmass if sufficient information is available, or simply to use the header airmass otherwise. .ih PARAMETERS .ls 4 filename See the definition of this parameter under RFITS. .le .ls 4 files See the definition of this parameter under RFITS. .le .ls 4 std_file See the definition of this parameter under STD_STAR. .le .ls 4 destination See the definition of this parameter under COIN_COR. .le .ls 4 effective_cor If this switch is set to yes, the procedure to compute an effective corrective term averaged over the integration time will be used. Although a slow process, this method is more accurate than simply using the correction at any given time of the integration such as the midpoint. If set to no, a midpoint zenith distance will be computed and used if sufficient header information exists. (default = no). .le .ls 4 print_header See the definition of this parameter for COIN_COR. .le .ih NAME sens_cor -- Correct the specified spectra for system sensitivity variations across the spectrum. .ih USAGE sens_cor [filename, files, std_file, destination] .ih DESCRIPTION The spectra specified by the filename and files parameters are corrected for instrumental sensitivity by the function pointed to by the spectrum name contained in std_file. The resulting spectra are stored according to the destination parameter. Filename may be a data group name. If so, then destination will be a new data group containing the names of the corrected spectra. This correction is a simple vector multiplcation. .ih PARAMETERS .ls 4 filename See the definition of this parameter under RFITS. .le .ls 4 files See the definition of this parameter under RFITS. .le .ls 4 std_file See the definition of this parameter under STD_STAR. .le .ls 4 destination See the definition of this parameter under COIN_COR. .le .ls 4 print_header See the definition of this parameter under COIN_COR. .le .endhelp