From 40e5a5811c6ffce9b0974e93cdd927cbcf60c157 Mon Sep 17 00:00:00 2001 From: Joe Hunkeler Date: Tue, 11 Aug 2015 16:51:37 -0400 Subject: Repatch (from linux) of OSX IRAF --- noao/onedspec/doc/sys/1and2dspec.hlp | 66 + noao/onedspec/doc/sys/Headers.hlp | 189 +++ noao/onedspec/doc/sys/Onedspec.hlp | 2219 ++++++++++++++++++++++++++++ noao/onedspec/doc/sys/Review.hlp | 512 +++++++ noao/onedspec/doc/sys/TODO | 28 + noao/onedspec/doc/sys/coincor.ms | 46 + noao/onedspec/doc/sys/identify.ms | 347 +++++ noao/onedspec/doc/sys/onedproto.ms | 1673 +++++++++++++++++++++ noao/onedspec/doc/sys/onedv210.ms | 680 +++++++++ noao/onedspec/doc/sys/revisions.v3.ms | 382 +++++ noao/onedspec/doc/sys/revisions.v31.ms | 329 +++++ noao/onedspec/doc/sys/revisions.v31.ms.bak | 307 ++++ noao/onedspec/doc/sys/rvidentify.ms | 304 ++++ noao/onedspec/doc/sys/sensfunc.ms | 83 ++ noao/onedspec/doc/sys/specwcs.ms | 612 ++++++++ 15 files changed, 7777 insertions(+) create mode 100644 noao/onedspec/doc/sys/1and2dspec.hlp create mode 100644 noao/onedspec/doc/sys/Headers.hlp create mode 100644 noao/onedspec/doc/sys/Onedspec.hlp create mode 100644 noao/onedspec/doc/sys/Review.hlp create mode 100644 noao/onedspec/doc/sys/TODO create mode 100644 noao/onedspec/doc/sys/coincor.ms create mode 100644 noao/onedspec/doc/sys/identify.ms create mode 100644 noao/onedspec/doc/sys/onedproto.ms create mode 100644 noao/onedspec/doc/sys/onedv210.ms create mode 100644 noao/onedspec/doc/sys/revisions.v3.ms create mode 100644 noao/onedspec/doc/sys/revisions.v31.ms create mode 100644 noao/onedspec/doc/sys/revisions.v31.ms.bak create mode 100644 noao/onedspec/doc/sys/rvidentify.ms create mode 100644 noao/onedspec/doc/sys/sensfunc.ms create mode 100644 noao/onedspec/doc/sys/specwcs.ms (limited to 'noao/onedspec/doc/sys') diff --git a/noao/onedspec/doc/sys/1and2dspec.hlp b/noao/onedspec/doc/sys/1and2dspec.hlp new file mode 100644 index 00000000..01f01763 --- /dev/null +++ b/noao/onedspec/doc/sys/1and2dspec.hlp @@ -0,0 +1,66 @@ +.help onedspec (Oct84) "Spectral Reductions" +.ce +Relationship Between Onedspec and Twodspec +.ce +Discussion +.ce +October 24, 1984 +.sp 3 +Two types of interactions between one dimensional and two dimensional +spectra may be defined: + +.ls (1) +Perform a one dimensional operation on the average or sum of a set +of lines in a two dimensional image. +.le +.ls (2) +Perform a one dimensional operation successively on a set of lines +in a two dimensional image. +.le + +The two functions might be combined as: + +.ls (3) +Perform a one dimensional operation on the average or sum of a set +of lines in a two dimensional image and apply the one dimensional +result successively on a set of lines in a two dimensional image. +.le + +Examples of this are dispersion solutions and flux calibrations for +longslit spectra. + + Some choices for implementation are: + +.ls (1) +Use a 2-D to 1-D operator to create a 1-D spectrum by averaging or summing +lines. +.le +.ls (2) +Use an apply a 1-D arithmetic correction to a 2-D image operator. +Alternatively, expand a 1-D correction to a 2-D correction. +.le +.ls (3) +Convert the 2-D image to a group of 1-D images and provide the 1-D operators +with the ability to perform averaging or summation. +.le +.ls (4) +To perform a one dimensional operation successively on +a set of lines first convert the two dimensional image into a group +of one dimensional spectra. Perform the 1-D operation on the desired +elements of the group and then reconstruct the 2-D image from the group +of 1-D images. +.le +.ls (5) +Built separate operators for 2-D images using the 1-D subroutines. +.le +.ls (6) +Provide the ability in the 1-D operators to perform the desired 2-D +operations directly. +.le + + Options (1) and (2) are essentially what is done on the IPPS. Option (5) +would lessen the amount of development but increase the number of tasks +to be written. I find option (6) desirable because of its +increased generality but it would require a +further definition of the data structures allowed and the syntax. +.endhelp diff --git a/noao/onedspec/doc/sys/Headers.hlp b/noao/onedspec/doc/sys/Headers.hlp new file mode 100644 index 00000000..9bb394b7 --- /dev/null +++ b/noao/onedspec/doc/sys/Headers.hlp @@ -0,0 +1,189 @@ +.LP +.SH +Image Header Parameters +.PP +The ONEDSPEC package uses the extended image header to extract +information required to direct processing of spectra. If the +header information were to be ignored, the user would need to +enter observing parameters to the program at the risk of +typographical errors, and with the burden of supplying the +data. For more than a few spectra this is a tedious job, +and the image header information provides the means to eliminate +almost all the effort and streamline the processing. +.PP +However, this requires that the header information be present, +correct, and in a recognizable format. To meet the goal of +providing a functional package in May 1985, the first iteration +of the header format was to simply adopt the IIDS/IRS headers. +This allowed for processing of the data which would be first +used heavily on the system, but would need to be augmented at +a later date. The header elements may be present in any order, +but must be in a FITS-like format and have the following names +and formats for the value fields: +.sp 1 +.TS +l c l +l l l. +Parameter Value Type Definition + +HA SX Hour angle (+ for west, - for east) +RA SX Right Ascension +DEC SX Declination +UT SX Universal time +ST SX Sidereal time +AIRMASS R Observing airmass (effective) +W0 R Wavelength at center of pixel 1 +WPC R Pixel-to-pixel wavelength difference +NP1 I Index to first pixel containing good data (actually first-1) +NP2 I Index to last pixel containing good data (last really) +EXPOSURE I Exposure time in seconds (ITIME is an accepted alias) +BEAM-NUM I Instrument aperture used for this data (0-49) +SMODE I Number of apertures in instrument - 1 (IIDS only) +OFLAG I Object or sky flag (0=sky, 1=object) +DF-FLAG I Dispersion fit made on this spectrum (I=nr coefs in fit) +SM-FLAG I Smoothing operation performed on this spectrum (I=box size) +QF-FLAG I Flat field fit performed on this spectrum (0=yes) +DC-FLAG I Spectrum has been dispersion corrected (0=linear, 1=logarithmic) +QD-FLAG I Spectrum has been flat fielded (0=yes) +EX-FLAG I Spectrum has been extinction corrected (0=yes) +BS-FLAG I Spectrum is derived from a beam-switch operation (0=yes) +CA-FLAG I Spectrum has been calibrated to a flux scale (0=yes) +CO-FLAG I Spectrum has been coincidence corrected (0=yes) +DF1 I If DF-FLAG is set, then coefficients DF1-DFn (n <= 25) exist +.TE +.PP +The values for the parameters follow the guidelines adopted for +FITS format tapes. All keywords occupy 8 columns and contain +trailing blanks. Column 9 is an "=" followed by a space. The value field +begins in column 11. Comments to the parameter may follow a "/" after +the value field. The value type code is as follows: +.RS +.IP SX +This is a sexagesimal string of the form '12:34:56 ' where the first +quote appears in column 11 and the last in column 30. +.IP R +This is a floating point ("real") value beginning in column 11 and +extending to column 30 with leading blanks. +.IP I +This is an integer value beginning in column 11 and extending to +column 30 with leading blanks. +.RE +.sp 1 +.PP +The parameters having FLAG designations all default to -1 to indicate +that an operation has not been performed. +The ONEDSPEC subroutines "load_ids_hdr" and "store_keywords" follow +these rules when reading and writing spectral header fields. +If not present in a header, load_ids_hdr will assume a value of zero +except that all flags are set to -1, and the object flag parameter +defaults to object. +.PP +When writing an image, only the above parameters are stored by store_keywords. +Other header information is lost. This needs to be improved. +.PP +Not all programs need all the header elements. The following table +indicates who needs what. Tasks not listed generally do not require +any header information. Header elements not listed are not used. +The task SLIST requires all the elements listed above. +The task WIDTAPE requires almost all (except NP1 and NP2). +The headings are abbreviated task names as follows: +.sp 1 +.nr PS 8 +.ps 8 +.TS +center; +l l | l l | l l. +ADD addsets COE coefs FIT flatfit +BSW bswitch COM combine REB rebin +CAL calibrate DIS dispcor SPL splot +COI coincor FDV flatdiv STA standard +.TE +.sp 1 +.TS +center, tab(/); +l | l | l | l | l | l | l | l | l | l | l | l | l. +Key/ADD/BSW/CAL/COI/COE/COM/DIS/FDV/FIT/REB/SPL/STA +_ +HA// X////////// X/ +RA// X////////// X/ +DEC// X////////// X/ +ST// X////////// X/ +UT// X////////// X/ +AIRMASS// X////////// X/ +W0// X/ X/// X//// X/ X/ X/ +WPC// X/ X/// X//// X/ X/ X/ +NP1/////////// X/// +NP2/////////// X/// +EXPOSURE/ X/ X/// X/ X///// X/// +BEAM-NUM// X/ X//// X/ X/ X// X/ X// +OFLAG// X////////// X/ +DF-FLAG//// X +DC-FLAG// X//// X//// X/ X/ X/ +QD-FLAG//////// X/ +EX-FLAG// X/ +BS-FLAG// X/ +CA-FLAG/ X// X//////// X/ +CO-FLAG///// X// +DFn//// X/ +.TE +.nr PS 10 +.ps 10 +.bp +.SH +Headers From Other Instruments +.PP +The header elements listed above are currently created only when reading +IIDS and IRS data from one of the specific readers: RIDSMTN and RIDSFILE. +The time-like parameters, (RA, DEC, UT, ST, HA), are created in a +compatible fashion by RCAMERA and RFITS (when the FITS tape is written +by the KPNO CCD systems). +.PP +For any other header information, the ONEDSPEC package is at a loss +unless the necessary information is edited into the headers with +an editing task such as HEDIT. This is not an acceptable long term +mode of operation, and the following suggestion is one approach to +the header problem. +.PP +A translation table can be created as a text file which outlines +the mapping of existing header elements to those required by the +ONEDSPEC package. A mapping line is needed for each parameter +and may take the form: +.sp 1 +.RS +.DC +1D_param default hdr_param key_start value_start type conversion +.DE +.RE +where the elements of an entry have the following definitions: +.TS +center; +l l. +1D_param T{The name of the parameter expected by the ONEDSPEC package, +such as EXPOSURE, OFLAG, BEAM-NUM. T} + +default T{A value to be used if no entry is found for this parameter.T} + +hdr_param T{The string actually present in the existing image header to be +associated with the ONEDSPEC parameter. T} + +key_start T{The starting column number at which the string starts +in the header. T} + +value_start T{The starting column number at which the string describing the +value of the parameter starts in the header. T} + +type T{The format type of the parameter: integer, real, string, boolean, +sexagesimal. T} + +conversion T{If the format type is string, a further conversion may +optionally be made to one of the formats listed under type. T} +.TE +.sp 1 +.PP +A translation file can be built for each instrument and its +peculiar header formats, and the file name associated with a +package parameter. The two subroutines in ONEDSPEC dealing +directly with the headers (load_ids_hdr and store_keywords) +can be modified or replaced to access this file and +translate the header elements. +.endhelp diff --git a/noao/onedspec/doc/sys/Onedspec.hlp b/noao/onedspec/doc/sys/Onedspec.hlp new file mode 100644 index 00000000..85a3f20e --- /dev/null +++ b/noao/onedspec/doc/sys/Onedspec.hlp @@ -0,0 +1,2219 @@ +.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 diff --git a/noao/onedspec/doc/sys/Review.hlp b/noao/onedspec/doc/sys/Review.hlp new file mode 100644 index 00000000..5139f630 --- /dev/null +++ b/noao/onedspec/doc/sys/Review.hlp @@ -0,0 +1,512 @@ +.help onedspec Sep84 "Spectral Reductions" +.ce +\fBOne Dimensional Spectral Reductions\fR +.ce +Analysis and Discussion +.ce +September 4, 1984 +.sp 3 +.nh +Introduction + + The \fBonedspec\fR package is a collection of programs for the reduction +and analysis of one dimensional spectral data. The more general problem of +operations upon one dimensional images or vectors shall be dealt with elsewhere, +primarily in the \fBimages\fR and \fBplot\fR packages. The problems of getting +data in and out of the system are handled by the \fBdataio\fR package, at least +for the standard data formats such as FITS. + +The operators provided in \fBonedspec\fR shall be general purpose and, as far +as possible, independent of the instrument which produced the data. Instrument +dependent reductions tailored for specific instruments will be implemented as +subpackages of the \fBimred\fR (image reductions) package. For example, +the subpackages \fBiids\fR and \fBirs\fR will be provided in \fBimred\fR for +reducing data from the KPNO instruments of the same name. The \fBimred\fR +packages shall call upon the basic operators in \fBonedspec\fR, \fBimages\fR, +and other packages to reduce the data for a specific instrument. + + +.ks +.nf + iids(etc) + imred + imredtools + onedspec + plot + tv + dataio + images + dbms + lists + system + language + +.fi +.ce +Relationship of \fBOnedspec\fR to other IRAF Packages +.ke + + +The relationship of the \fBonedspec\fR packages to other related packages in +the IRAF system is shown above. A program (CL script) in a package at one +level in the hierarchy may only call programs in packages at lower levels. +The system will load packages as necessary if not already loaded by the +user. The user is expected to be familiar with the standard system packages. + +.nh +Basic Functions Required for One-Dimensional Spectral Reductions + + The following classes of functions have been identified (in the preliminary +specifications document for \fBonedspec\fR) as necessary to perform basic one +dimensional spectral reductions. Only a fraction of the functionality +required is specific to the reduction of spectral data and is therefore +provided by the \fBonedspec\fR package itself. + +.ls Transport +Provided by the \fBdataio\fR package, although we do not currently have a +reader for REDUCER format data tapes. Readers for all standard format +tapes are either available or planned. +.le +.ls Mathematical +Standard system functions provided by \fBimages\fR (arithmetic, forward and +inverse FFT, filtering, etc.). +.le +.ls Reduction Operators +The heart of \fBonedspec\fR. Operators are required (at a minimum) for +coincidence correction, dispersion determination and correction, flat +fielding, sky subtraction, extinction correction, and flux calibration. +Operators for flat fielding and sky subtraction are already available elsewhere +in IRAF. Basic continuum fitting and subtraction is possible with existing +software but additional algorithms designed for spectral data are desirable. +.le +.ls Plotting +Standard system functions provided by the \fBplot\fR package. +.le +.ls Utilities +Standard system functions provided by the \fBdbms\fR package. +.le +.ls Artificial Spectra +These functions belong in the \fBartdata\fR package, but it is expected that +prototype operators will be built as part of the initial \fBonedspec\fR +development. +.le + +.nh +Data Structures + + Spectra will be stored as one or two dimensional IRAF images embedded in +database format files. A free format header is associated with each image. +Spectra may be grouped together as lines of a two dimensional image provided +all can share the same header, but more commonly each image will contain a +single spectrum. The second image dimension, if used, will contain vectors +directly associated with the images, such as a signal to noise vector. +If the image is two dimensional the spectrum must be the first image line. +The database facilities will allow images to be grouped together in a single +file if desired. + +While most or all \fBonedspec\fR operators will expect a one dimensional +image as input, image sections may be used to operate on vector subsections +of higher dimensioned images if desired. The datatype of an image is +arbitrary, but all pixel data will be single precision real within +\fBonedspec\fR. While the IRAF image format does not impose any restrictions on +the size of an image or image line, not all spectral operators may be usable +on very large images. In general, pointwise and local operations may easily +be performed on images of any size with modest memory requirements, and +most of the \fBonedspec\fR operations appear to fall into this class. + +.nh 2 +The IRAF Database Faciltities + + An understanding of the IRAF database facilities is necessary to visualize +how data will be treated by operators in \fBonedspec\fR and other packages. +The database facilities will be used not just for image storage but also for +program intercommunication, program output, and the storage of large +astronomical catalogs (e.g. the SAO catalog). Access to both small and +large databases will be quite efficient; achieving this requires little +innovation since database technology is already highly developed. We begin by +defining some important terms. + +.ls +.ls DBIO +The database i/o package, used by compiled programs to access a database. +.le +.ls DBMS +The database management package, a CL level package used by the user to +inspect, analyze, and manipulate the contents of a database. +.le +.ls database +A set of one or more "relations" or tables (DBIO is a conventional relational +database). A convenient way to think of an IRAF database is as a directory. +The relations appear as distinct files in the directory. +.le +.ls relation +A relation is a set of \fBrecords\fR. Each record consists of a set of +\fBfields\fR, each characterized by a name and a datatype. All the records +in a relation have the same set of fields. Perhaps the easiest way to +visualize a relation is as a \fBtable\fR. The rows and columns of the table +correspond to the records and fields of the relation. +.le +.ls field +A field of a record is characterized by an alphanumeric name, datatype, and +size. Fields may be one dimensional arrays of variable size. Fields may be +added to a relation dynamically at run time. When a new field is added to +a relation it is added to all records in the relation, but the value of the +field in a particular record is undefined (and consumes no storage) until +explicitly written into. +.le +.ls key +.br +A function of the values of one or more fields, used to select a subset of +rows from a table. Technically, a valid key will permit selection of any +single row from a table, but we often use the term is a less strict sense. +.le +.le + + +An \fBimage\fR appears in the database as a record. The record is really +just the image header; the pixels are stored external to the database in a +separate file, storing only the name of the pixel storage file in the record +itself (for very small images we are considering storing the pixels directly +in the database file). Note that the record is a simple flat structure; +this simple structure places restrictions on the complexity of objects which +can be stored in the database. + +The records in a relation form a set, not an array. Records are referred to +by a user-defined key. A simple key might be a single field containing a +unique number (like an array index), or a unique name. More complex keys +might involve pattern matching over one or more fields, selection of records +with fields within a certain range of values, and so on. + +From the viewpoint of \fBonedspec\fR, a relation can be considered a +\fBdata group\fR, consisting of a set of \fBspectra\fR. + +.nh 2 +Image Templates + + The user specifies the set of spectra to be operated upon by means of an +image template. Image templates are much like the filename templates commonly +used in operating systems. The most simple template is the filename of +a single data group; this template matches all spectra in the group. If there +is only one spectrum in a file, then only one spectrum is operated upon. +A slightly more complex template is a list of filenames of data groups. +More complex templates will permit use of expressions referencing the values +of specific fields to select a subset of the spectra in a group. The syntax +of such expressions has not yet been defined (examples are given below +nonetheless), but the function performed by an image template will be the same +regardless of the syntax. In all cases the image template will be a single +string valued parameter at the CL level. + +.nh 2 +Standard Calling Sequence + + The standard calling sequence for a unary image operator is shown below +The calling sequence for a binary operator would be the same with a second input +parameter added as the second argument. In general, any data dependent +control parameters should be implemented as positional arguments following +the primary operands, and data independent or optional (rarely used) parameters +should be implemented as hidden parameters. + + +.ks +.nf + imop (input, output, data_dependent_control_params) + + imop image operator name + input image template specifying set of input images + output filename of output datagroup + + data_dependent_control_parameters + (hidden parameters) + +for example, + + coincor (spectra, newgroup, dead_time) +.fi +.ke + + +If a series of spectra are to be processed it seems reasonable to add the +processed spectra to a new or existing data group (possibly the same as an +input datagroup). If the operation is to be performed in place a special +notation (e.g. the null string) can be given as the output filename. +At the \fBonedspec\fR level output filenames will not be defaulted. + +.nh 2 +Examples + + Some examples of image templates might be useful to give a more concrete +idea of the functionality which will be available. Bear in mind that what we +are describing here is really the usage of one of the fundamental IRAF system +interfaces, the DBMS database management subsystem, albeit from the point of +view of \fBonedspec\fR. The same facilities will be available in any program +which operates upon images, and in some non-image applications as well (e.g. +the new \fBfinder\fR). Our philosopy, as always, is to make standard usage +simple, with considerable sophistication available for those with time to +learn more about the system. + +The simplest case occurs when there is one spectrum per data group (file). +For example, assuming that the file "a" contains a single spectrum, the +command + + cl> coincor a, b, .2 + +would perform coincidence correction for spectrum A, placing the result in +B, using a dead time parameter of .2. For a more complex example, consider +the following command: + + cl> coincor "a.type=obj&coincor=no,b", a, .2 + +This would perform coincidence correction for all spectra in group B plus all +object spectra in group A which have not already been coincidence corrected, +adding the corrected spectra to group A (notation approximate only). If the +user does not trust the database explicit record numbers may be used and +referenced via range list expressions, e.g., + + cl> coincor "a.recnum=(1,5,7:11),b", a, .2 + +would select records 1, 5, and 7 through 11 from data group A. Alternatively +the database utilities could be used to list the spectra matching the selection +criteria prior to the operation if desired. For example, + + cl> db.select "a.type=obj" + +would write a table on the standard output (the terminal) wherein each spectrum +in data group A is shown as a row of field values. If one wanted to generate +an explicit list of records to be processed with help from the database +utilities, a set of records could be selected from a data group and selected +fields from each record written into a text file: + + cl> db.select "a.type=obj", "recnum, history" > reclistfile + +The output file "reclistfile" produced by this command would contain the +fields "recnum" (record number) and "history" (description of processing +performed to generate the record). The editor could be used to delete +unwanted records, producing a list of record numbers suitable for use as +an image template: + + cl> coincor "a.recnum=@reclistfile", a, .2 + +.nh +Reduction Operators + +.nh 2 +Line List Preparation + + I suggest maintaining the line lists as text files so that the user can +edit them with the text editor, or process them with the \fBlists\fR operators. +A master line list might be maintained in a database and the DBMS \fBselect\fR +operator used to extract ASCII linelists in the wavelength region of interest, +but this would only be necessary if the linelist is quite large or if a linelist +record contains many fields. I don't think we need the \fBline_list\fR task. + +.nh 2 +Dispersion Solution + + The problem with selecting a line list and doing the dispersion solution +in separate operations is that the dispersion solution is invaluable as an aid +for identifying lines and for rejecting lines. Having a routine which merely +tweaks up the positions of lines in an existing lineset (e.g., \fBalinid\fR) +is not all that useful. I would like to suggest the following alternate +procedure for performing the dispersion solution for a set of calibration +spectra which have roughly the same dispersion. + +.ls +.ls [1] Generate Lineset [and fit dispersion] +.sp +Interactively determine the lineset to be used, i.e., wavelength (or whatever) +and approximate line position in pixel units for N lines. Input is one or more +comparison spectra and optionally a list of candidate lines in the region +of interest. Output is the order for the dispersion curve and a linelist of +the following (basic) form: + + L# X Wavelength [Weight] + +It would be very useful if the program, given a rough guess at the dispersion, +could match the standard linelist with the spectra and attempt to automatically +identify the lines thus detected. The user would then interactively edit the +resultant line set using plots of the fitted dispersion curve to reject +misidentified or blended lines and to adjust weights until a final lineset +is produced. +.le + +.ls [2] Fit Dispersion +.sp +Given the order and functional type of the curve to be fitted and a lineset +determined in step [1] (or a lineset produced some any other means, e.g. with +the editor), for each spectrum in the input data group tweak the center of +each line in the lineset via an automatic centering algorithm, fit the +dispersion curve, and save the coefficients of the fitted curve in the +image header. The approximate line positions would be used to find and measure +the positions of the actual lines, and the dispersion curve would be fitted and +saved in the image header of each calibration spectrum. + +While this operator would be intended to be used noninteractively, the default +textual and graphics output devices could be the terminal. To use the program +in batch mode the user would redirect both the standard output and the graphics +output (if any), e.g., + +.nf + cl> dispsol "night1.type=comp", linelistfile, order, + >>> device=stdplot, > dispsol.spool & +.fi + +Line shifts, correlation functions, statistical errors, the computed residuals +in the fitted dispersion curves, plots of various terms of the dispersion +curves, etc. may be generated to provide a means for later checking for +erroneous solutions to the individual spectra. There is considerable room for +innovation in this area. +.le + +.ls [3] Second Order Correction +.sp +If it is desired to interpolate the dispersion curve in some additional +dimension such as time or hour angle, fit the individual dispersion solutions +produced by [1] or [2] as a group to one or more additional dimensions, +generating a dispersion solution of one, two or more dimensions as output. +If the output is another one dimensional dispersion solution, the input +solutions are simply averaged with optional weights. This "second order" +correction to a group of dispersion solutions is probably best performed by +a separate program, rather than building it into \fBalineid\fR, \fBdispsol\fR, +etc. This makes the other programs simpler and makes it possible to exclude +spectra from the higher dimensional fit without repeating the dispersion +solutions. +.le +.le + +If the batch run [2] fails for selected spectra the dispersion solution for +those spectra can be repeated interactively with operator [1]. +The curve fitting package should be used to fit the dispersion curve (we can +extend the package to support \fBonedspec\fR if necessary). + +.nh 2 +Dispersion Correction + + This function of this procedure is to change the dispersion of a +spectrum or group of spectra from one functional form to another. +At a mimimum it must be possible to produce spectra linear in wavelength or +log wavelength (as specified), but it might also be useful to be able +to match the dispersion of a spectrum to that of a second spectrum, e.g., to +minimize the amount of interpolation required to register spectra, or +to introduce a nonlinear dispersion for testing purposes. This might be +implemented at the CL parameter level by having a string parameter which +takes on the values "linear" (default), "log", or the name of a record +defining the dispersion solution to be matched. + +It should be possible for the output spectrum to be a different size than +the input spectrum, e.g., since we are already interpolating the data, +it might be nice to produce an output spectrum of length 2**N if fourier +analysis is to be performed subsequently. It should be possible to +extract only a portion of a spectrum (perform subraster extraction) in the +process of correcting the dispersion, producing an output spectrum of a +user-definable size. It should be possible for an output pixel to lie at +a point outside the bounds of the input spectrum, setting the value of the +output pixel to INDEF or to an artificially generated value. Note that +this kind of generality can be implemented at the \fBonedspec\fR level +without compromising the simplicity of dispersion correction for a particular +instrument at the \fBimred\fR level. + +.nh 3 +Line Centering Algorithms + + For most data, the best algorithm in the set described is probably the +parabola algorithm. To reject nearby lines and avoid degradation of the +signal to noise the centering should be performed within a small aperture, +but the aperture should be allowed to move several pixels in either direction +to find the peak of the line. + +The parabola algorithm described has these features, +but as described it finds the extrema within a window about the +initial position. It might be preferable to simply walk up the peak nearest +to the initial center. This has the advantage that it is possible to center +on a line which has a nearby, stronger neighbor which cannot itself be used +for some reason, but which might fall within \fBparextent\fR pixels of the +starting center. The parabola algorithm as described also finds a local extrema +rather than a local maximum; probably not what is desired for a dispersion +solution. The restriction to 3 pixels in the final center determination is +bad; the width of the centering function must be a variable to accommodate +the wide range of samplings expected. + +The parabola algorithm described is basically a grid search over +2*\fIparextent\fR pixels for the local extrema. What I am suggesting is +an iterative gradient search for the local maximum. The properties of the +two algorithms are probably sufficiently different to warrant implementation +of both as an option (the running times are comparable). I suspect that +everyone else who has done this will have their own favorite algorithm as +well; probably we should study half a dozen but implement only one or two. + +.nh 2 +Field Flattening + + It is not clear that we need special flat fielding operators for +\fBonedspec\fR. We have a two-dimensional operator which fits image lines +independently which might already do the job. Probably we should experiment +with both the smoothing spline and possibly fourier filtering for removing +the difficult medium frequency fluctuations. The current \fBimred\fR flat field +operator implements the cubic smoothing spline (along with the Chebyshev and +Legendre polynomials), and is available for experimentation. + +Building interactive graphics into the operator which fits a smooth curve to +the continuum is probably not necessary. If a noninteractive \fBimred\fR or +\fBimages\fR operator is used to fit the continuum the interactive graphics +can still be available, but might better reside in a higher level CL script. +The basic operator should behave like a subroutine and not write any output +to the terminal unless enabled by a hidden parameter (we have been calling +this parameter \fIverbose\fR in other programs). + +.nh 3 +Extinction Correction and Flux Calibration + + I did not have time to review any of this. + +.nh +Standard Library Packages + + The following standard IRAF math library packages should be used in +\fBonedspec\fR. The packages are very briefly described here but are +fully documented under \fBhelp\fR on the online (kpnob:xcl) system. + +.nh 2 +Curve Fitting + + The curve fitting package (\fBcurfit\fR) is currently capable of fitting +the Chebyshev and Legendre polynomials and the cubic smoothing spline. +Weighting is supported as an option. +We need to add a piecewise linear function to support the +dispersion curves for the high resolution FTS spectra. We may have to add a +double precision version of the package to provide the 8-10 digits of +precision needed for typical comparison line wavelength values, but +normalization of the wavelength values may make this unnecessary for moderate +resolution spectra. + +Ordinary polynomials are not supported because their numerical properties are +very much inferior to those of orthogonal polynomials (the ls matrix can have +a disastrously high condition number, and lacking normalization the function +begin fitted is not invariant with respect to scale changes and translations +in the input data). For low order fits the Chebyshev polynomials are +considered to have the best properties from an approximation theoretic point +of view, and for high order fits the smoothing spline is probably best because +it can follow arbitrary trends in the data. + +.nh 2 +Interpolation + + The image interpolation package (\fBiminterp\fR) currently supports the +nearest neighbor, linear, third and fifth order divided differences, +cubic interpolating spline, and sinc function interpolators. +We should add the zeroth and first order partial pixel ("flux conserving") +interpolants because they offer unique properties not provided by any +of the other interpolants. + +.nh 2 +Interactive Graphics + + We will define a standard interactive graphics utility package for +interactive operations upon data vectors (to be available in a system library +in object form). It should be possible to define a general package which +can be used anywhere a data vector is to be plotted and +examined interactively (not just in \fBonedspec\fR). Standard keystrokes +should be defined for common operations such as expanding a region of +the plot and restoring the original scale. This will not be attempted +until an interactive version of the GIO interface is available later this +fall. +.endhelp diff --git a/noao/onedspec/doc/sys/TODO b/noao/onedspec/doc/sys/TODO new file mode 100644 index 00000000..0dfa136b --- /dev/null +++ b/noao/onedspec/doc/sys/TODO @@ -0,0 +1,28 @@ +scombine: + 1. Combine with weights: + By signal level + By sigma spectrum + +doc: + Install SENSFUNC memo in the doc directory. (8/14) + +calibrate: + Have calibrate apply neutral density filter function. This may also + have to be included in STANDARD and SENSFUNC. (2/25/87) + +splot: + Add a deblend option for PCYGNI profiles. (Tyson, 3/19/87) + +Tim Heckman (U. Maryland) came by with questions and requests +concerning deblending in SPLOT. Tim's comments are indicated in +quotations. + +2. "The deblending should allow additional constraints if known. +Specifically fixing the ratios of lines based on atomic physics." + +3. "The deblending should provide some uncertainty estimates." I added +that there has also been a request to use known statistics in the +pixel data themselves to generate uncertainty estimates. + +4. "It would be useful to provide other choices for the profile rather +than just gaussians." diff --git a/noao/onedspec/doc/sys/coincor.ms b/noao/onedspec/doc/sys/coincor.ms new file mode 100644 index 00000000..1b4d29cc --- /dev/null +++ b/noao/onedspec/doc/sys/coincor.ms @@ -0,0 +1,46 @@ +.EQ +delim $$ +.EN +.OM +.TO +IIDS Users +.FR +F. Valdes +.SU +IIDS count rate corrections +.PP +The IRAF task \fBcoincor\fR transforms the observed count rates to +something proportional to the input count rate. The correction applied +to the observed count rates depends upon the count rate and is instrument +dependent. One correction common to photomultiplier detectors and the +IIDS is for coincident events, which is the origin of the task name. +The parameter \fIccmode\fR selects a particular type of correction. +The value \fIccmode\fR = "iids" applies the following transformation to +observed IIDS count rates. + +.EQ (1) + C sup ' ~=~(- ln (1- deadtime C)/ deadtime ) sup power +.EN + +where $C$ is the orginal count rate, $C sup '$ is the corrected count +rate, and $deadtime$ and $power$ are \fBcoincor\fR parameters. The term +inside the parenthesis is the correction for dead-time in the counting +of coincident events on the back phospher of the image tube. The power +law correction is due to the non-linearity of the IIDS image tube chain. +.PP +The correction applied with the Mountain Reduction Code is only for +coincidences, i.e. equation (1) with $power = 1$. To obtain just this +correction with \fBcoincor\fR set $power = 1$. To take mountain reduced +data and correct only for the non-linearity set \fIccmode\fR = "power". +With raw IIDS data use \fBcoincor\fR with the default +parameters. + +.LP +References: +.IP (1) +L. Goad, \fBSPIE 172\fR, 1979, p. 86. +.IP (2) +G. Jacoby, Some Notes on the ONEDSPEC Package, \fBIRAF Handbook\fR +.IP (3) +P. Massey and J. De Veny, How Linear is the IIDS, \fBNOAO Newsletter\fR, +#6, June 1986. diff --git a/noao/onedspec/doc/sys/identify.ms b/noao/onedspec/doc/sys/identify.ms new file mode 100644 index 00000000..6a69204b --- /dev/null +++ b/noao/onedspec/doc/sys/identify.ms @@ -0,0 +1,347 @@ +.RP +.TL +Radial Velocity Measurements with IDENTIFY +.AU +Francisco Valdes +.AI +IRAF Group - Central Computer Services +.K2 +P.O. Box 26732, Tucson, Arizona 85726 +August 1986 +Revised August 1990 +.AB +The IRAF task \fBidentify\fP may be used to measure radial velocities. +This is done using the classical method of determining +the doppler shifted wavelengths of emission and absorption lines. +This paper covers many of the features and techniques available +through this powerful and versatile task which are not immediately +evident to a new user. +.AE +.sp 3 +.NH +\fBIntroduction\fP +.PP +The task \fBidentify\fP is very powerful and versatile. It can +be used to measure wavelengths and wavelength shifts for +doing radial velocity measurements from emission and +absorption lines. When combined with the CL's ability +to redirect input and output both from the standard text +streams and the cursor and graphics streams virtually +anything may be accomplished either interactively or +automatically. This, of course, requires quite a bit of +expertise and experience with \fBidentify\fP and with +the CL which a new user is not expected to be aware of initially. +This paper attempts to convey some of the possibilities. +There are many variations on these methods which the user +will learn through experience. +.PP +I want to make a caveat about the suggestions made in +this paper. I wrote the \fBidentify\fP task and so I am +an expert in its use. However, I am not a spectroscopist, +I have not been directly involved in the science of +measuring astronomical radial velocities, and I am not +very familiar with the literature. Thus, the suggestions +contained in this paper are based on my understanding of +the basic principles and the abilities of the \fBidentify\fP +task. +.PP +The task \fBidentify\fP is used to measure radial velocities +by determining the wavelengths of individual emission +and absorption lines. The user must compute the +radial velocities separately by relating the observed +wavelengths to the known rest wavelengths via the Doppler +formula. This is a good method when the lines are +strong, when there are only one or two features, and +when there are many, possibly, weaker lines. The +accuracy of this method is determined by the accuracy +of the line centering algorithm. +.PP +The alternative method is to compare an observed spectrum +to a template spectrum of known radial velocity. This +is done by correlation or fourier ratio methods. These +methods have the advantage of using all of the spectrum +and are good when there are many very weak and possibly +broad features. Their disadvantages are confusion +with telluric lines, they don't work well with just a +few real features, and they require a fair amount of +preliminary manipulation of the spectrum to remove +continuum and interpolate the spectrum in logarithmic +wavelength intervals. IRAF tasks for correlation +and fourier ratio methods are under development at +this time. Many people assume that these more abstract +methods are inherently better than the classical method. +This is not true, it depends on the quality and type of +data. +.PP +Wavelength measurements are best done on the original +data rather than after linearizing the wavelength +intervals. This is because 1) it is not necessary as +will be shown below and 2) the interpolation used to +linearize the wavelength scale can change the shape +of the lines, particularly strong, narrow emission +lines which are the best ones for determining radial +velocities. +.PP +This paper is specifically about \fBidentify\fP but one +should be aware of the task \fBsplot\fP which also may +be used to measure radial velocities. It differs in +several respects from \fBidentify\fP. \fBSplot\fP works +only on linearized data; the wavelength and pixel +coordinates are related by a zero point and wavelength +interval. The line centering algorithms are different; +the line centering is generally less robust (tolerant +of error) and often less accurate. It has many nice +features but is not designed for the specific purpose +of measuring positions of lines and, thus, is not as +easy to use for this purpose. +.PP +There are a number of sources of additional information +relating to the use of the task \fBidentify\fP. The +primary source is the manual pages for the task. As +with all manual pages it is available online with the +\fBhelp\fP command and in the \fIIRAF User Handbook\fP. +The NOAO reduction guides or cookbooks for the echelle +and IIDS/IRS include additional examples and discussion. +The line centering algorithm is the most critical +factor in determining dispersion solutions and radial +velocities. It is described in more detail under the +help topic \fBcenter1d\fP online or in the handbook. +.NH +Method 1 +.PP +In this method, arc calibration images are used to determine +a wavelength scale. The dispersion solution is then transferred +to the object spectrum and the wavelengths of emission and +absorption lines are measured and recorded. This is +relatively straightforward but some tricks will make this easier +and more accurate. +.NH 2 +Transferring Dispersion Solutions +.PP +There are several ways to transfer the dispersion solution +from an arc spectrum to an object spectrum differing in the +order in which things are done. +.IP (1) +One way is to determine the dispersion solution for all the arc images +first. To do this interactively specify all the arc images as the +input to \fBidentify\fP. After determining the dispersion solution for +the first arc and quitting (\fIq\fP key) the next arc will be displayed +with the previous dispersion solution and lines retained. Then use the +cursor commands \fIa\fP and \fIc\fP (all center) to recenter and +\fIf\fP (fit) to recompute the dispersion solution. If large shifts +are present use \fIs\fP (shift) or \fIx\fR (correlate peaks) to shift, +recenter, and compute a wavelength zero point shift to the dispersion +function. A new dispersion function should then be fit with \fIf\fP. +These commands are relatively fast and simple. +.IP +An important reason for doing all the arc images first +is that the same procedure can be done mostly noninteractively +with the task \fBreidentify\fP. After determining a +dispersion solution for one arc image \fBreidentify\fP +does the recenter (\fIa\fP and \fIc\fP), shift and +recenter (\fIs\fP), or correlation features, shift, and +recenter (\fIx\fP) to transfer the dispersion solutions +between arcs. This is usually done as a background task. +.IP +To transfer the solution to the object spectra specify +the list of object spectra as input to \fBidentify\fP. +For each image begin by entering the colon command +\fI:read arc\fP where arc is the name of the arc image +whose dispersion solution is to be applied; normally +the one taken at the same time and telescope position as +the object. This will read the dispersion solution and arc +line positions. Delete the arc line positions with the +\fIa\fP and \fId\fP (all delete) cursor keys. You +can now measure the wavelengths of lines in the spectrum. +.IP (2) +An alternative method is to interactively alternate between +arc and object spectra either in the input image list or +with the \fI:image name\fP colon command. +.NH 2 +Measuring Wavelengths +.IP (1) +To record the feature positions at any time use the \fI:features +file\fP colon command where \fIfile\fP is where the feature +information will be written. Repeating this with the same +file appends to the file. Writing to the database with the +\fI:write\fP colon command also records this information. +Without an argument the results are put in a file with +the same name as the image and a prefix of "id". You +can use any name you like, however, with \fI:write +name\fP. The \fI:features\fP command is probably preferable +because it only records the line information while the +database format includes the dispersion solution and +other information not needed for computing radial +velocities. +.IP (2) +Remember that when shifting between emission and absorption +lines the parameter \fIftype\fP must be changed. This may be done +interactively with the \fI:ftype emission\fP and \fI:ftype +absorption\fP commands. This parameter does not need to be +set except when changing between types of lines. +.IP (3) +Since the centering of the emission or absorption line is the +most critical factor, one should experiment with the parameter +\fIfwidth\fP. To change this parameter type \fI:fwidth value\fP. +The positions of the marked features are not changed until a +center command (\fIc\fP) command is given. +.IP +A narrow \fIfwidth\fP is less influenced by blends and wings but +has a larger uncertainty. A broad \fIfwidth\fP uses all of the +line profile and is thus stable but may be systematically influenced +by blending and wings. One possible approach is to measure +the positions at several values of \fIfwidth\fP and decide which +value to use or use some weighting of the various measurements. +You can record each set of measurements with the \fI:fe +file\fP command. +.IP (4) +For calibration of systematic effects from the centering one should +obtain the spectrum of a similar object with a known radial +velocity. The systematic effect is due to the fact that the +centering algorithm is measuring a weighted function of the +line profile which may not be the true center of the line as +tabulated in the laboratory or in a velocity standard. By +using the same centering method on an object with the same line +profiles and known velocity this effect can be eliminated. +.IP (5) +Since the arcs are not obtained at precisely the same time +as the object exposures, there may be a wavelength shift relative +to the arc dispersion solution. This may be calibrated from +night sky lines in the object itself (the night sky lines are +"good" in this case and should not be subtracted away). There are +generally not enough night sky lines to act as the primary +dispersion calibrator but just one can determine a possible +wavelength zero point shift. Measure the night sky line +positions at the same time the object lines are measured. +Determine a zero point shift from the night sky to be +taken out of the object lines. +.NH +Method 2 +.PP +This method is similar to the correlation method in that a +template spectrum is used and the average shift relative +to the template measures the radial velocity. This has the +advantage of not requiring the user to do a lot of calculations +(the averaging of the line shifts is done by identify) but is +otherwise no better than method 1. The template spectrum must +have the same features as the object spectrum. +.IP (1) +Determine a dispersion solution for the template spectrum +either from the lines in the spectrum or from an arc calibration. +.IP (2) +Mark the features to be correlated in the template spectrum. +.IP (3) +Transfer the template dispersion solution and line positions +to an object spectrum using one of the methods described +earlier. Then, for the current feature, point the cursor near +the same feature in the object spectrum and type \fIs\fP. The +mean shift in pixels, wavelength, and fractional wavelength (like +a radial velocity without the factor of the speed of light) +for the object is determined and printed. A new dispersion +solution is determined but you may ignore this. +.IP (4) +When doing additional object spectra, remember to start over +again with the template spectrum (using \fI:read template\fP) +and not the solution from the last object spectrum. +.IP (5) +This procedure assumes that the dispersion solution between +the template and object are the same. Checks for zero point +shifts with night sky lines, as discussed earlier, should be +made if possible. The systematic centering bias, however, is +accounted for by using the same lines from the template radial +velocity standard. +.IP (6) +One possible source of error is attempting to use very weak +lines. The recentering may find the wrong lines and affect +the results. The protections against this are the \fIthreshold\fP +parameter and setting the centering error radius to be relatively small. +.NH +Method 3 +.PP +This method uses only strong emission lines and works with +linearized data without an \fBidentify\fP dispersion +solution; though remember the caveats about rebinning the +spectra. The recipe involves measuring +the positions of emission lines. The +strongest emission lines may be found automatically using +the \fIy\fP cursor key. The number of emission lines to +be identified is set by the \fImaxfeatures\fP parameter. +The emission line positions are then written to a data file +using the \fI:features file\fP colon command. This may +be done interactively and takes only a few moments per +spectrum. If done interactively, the images may be chained +by specifying an image template. The only trick required +is that when proceeding to the next spectrum the previous +features are deleted using the cursor key combination \fIa\fP +and \fId\fP (all delete). +.PP +For a large number of images, on the order of hundreds, this +may be automated as follows. A file containing the cursor +commands is prepared. The cursor command format consists +of the x and y positions, the window (usually window 1), and +the key stroke or colon command. Because each new image from +an image template does not restart the cursor command file, +the commands would have to be repeated for each image in +the list. Thus, a CL loop calling the task each time with +only one image is preferable. Besides redirecting the +cursor input from a command file, we must also redirect the +standard input for the response to the database save query, the +standard output to discard the status line information, and , +possibly, the graphics to a metacode file which can then be +reviewed later. The following steps indicate what is to be +done. +.IP (1) +Prepare a file containing the images to be measured (one per line). +This can usually be done using the sections command to expand +a template and directing the output into a file. +.IP (2) +Prepare a cursor command file (let's call it cmdfile) +containing the following two lines. +.RS +.IP +.nf +.ft CW +1 1 1 y +1 1 1 :fe positions.dat +.ft P +.fi +.RE +.IP (3) +Enter the following commands. +.RS +.IP +.nf +.ft CW +list="file" +while (fscan (list,s1) !=EOF){ +print ("no") \(or identify (sl,maxfeatures=2, cursor="cmdfile", +>"dev$null", >G "plotfile") +} +.ft P +.fi +.RE +.LP +Note that these commands could be put in a CL script and executed +using the command +.sp +.IP +.ft CW +on> cl