Initial commit

1 files changed, 551 insertions, 0 deletions

diff --git a/noao/onedspec/doc/standard.hlp b/noao/onedspec/doc/standard.hlp
new file mode 100644
index 00000000..d0c84aef
--- /dev/null
+++ b/noao/onedspec/doc/standard.hlp
@@ -0,0 +1,551 @@
+.help standard Jan00 noao.onedspec
+.ih
+NAME
+standard -- Add standard stars to sensitivity file
+.ih
+USAGE
+standard input [records] output
+.ih
+PARAMETERS
+.ls input
+List of input standard star spectra or root names if using the record number
+extension format.  All spectra of the same aperture must be of the same
+standard star.  In beam switch mode or when the same star parameter is set
+all spectra must be of the same standard star regardless of aperture number.
+Normally the spectra will not be extinction corrected but if they are
+then the extinction file should also be given and the same extinction
+file should be used with \fBsensfunc\fR.
+.le
+.ls records (imred.irs and imred.iids only)
+List of records or ranges of records to be appended to the input spectra
+names when using record number extension format.  The
+syntax of this list is comma separated record numbers or ranges of record
+numbers.  A range consists of two numbers separated by a hyphen.
+A null list may be used if no record number extensions are
+desired.  This is a positional query parameter only if the record
+format is specified.
+.le
+.ls output
+The name of a text file which will contain the output from \fBstandard\fR.
+Each execution of \fBstandard\fR appends to this file information about the
+standard stars, the calibration bandpasses, and observed counts (see the
+DESCRIPTION section for more details).  The output must be explicitly
+deleted by the user if the filename is to be reused.
+.le
+.ls samestar = yes
+Is the same star in all apertures?  If set to no then each aperture may
+contain a different standard star.  The standard star name is queried
+each time a new aperture is encountered.  Note that this occurs only
+once per aperture and multiple spectra with the same aperture number
+must be of the same star.  If set to yes the standard star name is only
+queried once.  When in beam switch mode this parameter is ignored since
+all apertures must contain the same star.
+.le
+.ls beam_switch = no
+Beam switch the spectra?  If yes then a beam switch mode is used for the spectra
+in which successive pairs of object and sky observations from the same aperture
+are sky subtracted.  This requires that the object type flag OFLAG be present
+and that the spectra are appropriately ordered.  All object observations must be
+of the same standard star and the \fIsamestar\fR parameter is ignored.
+.le
+.ls apertures = ""
+List of apertures to be selected from the input list of spectra.  If no list
+is specified then all apertures are selected.  The syntax is the same as the
+record number extensions.
+.le
+.ls bandwidth = INDEF, bandsep = INDEF
+Bandpass widths and separations in wavelength units.  If INDEF then the
+default bandpasses are those given in the standard star calibration
+file.  If values for these parameters are specified then a default set
+of bandpasses of equal width and separation are defined over the range
+of the input spectrum.  In both cases the default bandpasses can be
+changed interactively if desired.
+.le
+.ls fnuzero = 3.68e-20
+The absolute flux per unit frequency at an AB magnitude of zero.  This is used
+to convert the calibration  AB magnitudes to absolute flux by the formula
+
+.nf
+    f_nu = fnuzero * 10. ** (-0.4 * m_AB)
+.fi
+
+The flux units are also determined by this parameter.  However, the
+frequency to wavelength interval conversion assumes frequency in hertz.
+The default value is based on a calibration of Vega at 5556 Angstroms of
+3.52e-20 ergs/cm2/s/Hz for an AB magnitude of 0.0336.  This default value
+is that used in earlier versions of this task which did not allow the
+user to change this calibration.
+.le
+.ls extinction = <no default>
+Extinction file used to make second order extinction corrections across
+the bandpasses.  The default value is  redirected to the package
+parameter of the same name.  See \fBlcalib\fR for a list of standard
+extinction files.  Normally the input spectra will not be extinction
+corrected.  But if they are this file will be used to remove the
+extinction and then the same file should be specified in \fBsensfunc\fR.
+Note that one can choose to use a null extinction file in both.
+.le
+.ls caldir = ")_.caldir"
+Calibration directory containing standard star data.  The
+default value of ")_.caldir" means to use the package parameter "caldir".
+A list of standard calibration directories may be obtained by listing the
+file "onedstds$README"; for example:
+
+.nf
+    cl> page onedstds$README
+.fi
+
+The user may copy or create their own calibration files and specify the
+directory.  The directory "" refers to the current working directory.  The
+standard calibration directory for blackbody curves is
+"onedstds$blackbody/".
+.le
+.ls observatory = ")_.observatory"
+Observatory at which the spectra were obtained if not specified in the
+image header by the keyword OBSERVAT.  The default is a redirection to look
+in the parameters for the parent package for a value.  The observatory may
+be one of the observatories in the observatory database, "observatory" to
+select the observatory defined by the environment variable "observatory" or
+the parameter \fBobservatory.observatory\fR, or "obspars" to select the
+current parameters set in the \fBobservatory\fR task.  See help for
+\fBobservatory\fR for additional information.
+.le
+.ls interact = no
+If set to no, then the default wavelength set (either that from the star
+calibration file or the set given by the \fIbandwidth\fR and \fIbandsep\fR
+parameters) is used to select wavelength points along the spectrum where the
+sensitivity is measured. If set to yes, the spectra may be plotted
+and the bandpasses adjusted.
+.le
+.ls graphics = "stdgraph"
+Graphics output device for use with the interactive mode.  Normally this is
+the user's graphics terminal.
+.le
+.ls cursor = ""
+Graphics cursor input for use with the interactive mode.  When null the
+standard graphics cursor is used otherwise the specified file is used.
+.le
+.ls star_name
+The name of the star observed in the current series of spectra.  Calibration
+data for the star must be in the specified calibration directory "caldir".
+This is normally a interactive query parameter and should not be specified on
+the command line unless all spectra are of the same standard star.
+.le
+
+The following three queried parameters apply if the selected calibration
+file is for a blackbody.
+.ls mag
+The magnitude of the observed star in the band given by the
+\fImagband\fR parameter.  If the magnitude is not in the same band as
+the blackbody calibration file then the magnitude may be converted to
+the calibration band provided the "params.dat" file containing relative
+magnitudes between the two bands is in the calibration directory
+.le
+.ls magband
+The standard band name for the input magnitude.  This should generally
+be the same band as the blackbody calibration file.  If it is
+not the magnitude will be converted to the calibration band.
+.le
+.ls teff
+The effective temperature (deg K) or the spectral type of the star being
+calibrated.  If a spectral type is specified a "params.dat" file must exist
+in the calibration directory.  The spectral types are specified in the same
+form as in the "params.dat" file.  For the standard blackbody calibration
+directory the spectral types are specified as A0I, A0III, or A0V, where A
+can be any letter OBAFGKM, the single digit subclass is between 0 and 9,
+and the luminousity class is one of I, III, or V.  If no luminousity class
+is given it defaults to dwarf.
+.le
+
+The following two parameters are queried if the image does not contain
+the information.
+.ls airmass, exptime
+If the airmass and exposure time are not in the header nor can they be
+determined from other keywords in the header then these query parameters
+are used to request the airmass and exposure time.  The values are updated
+in the image.
+.le
+
+The following parameter is for the task to make queries.
+.ls answer
+Interactive query parameter.
+.le
+.ih
+CURSOR KEYS
+.nf
+?  Display help page
+a  Add a new band by marking the endpoints
+d  Delete band nearest the cursor in wavelength
+r  Redraw current plot
+q  Quit with current bandpass definitions
+w  Window plot  (follow with '?' for help)
+I  Interrupt task immediately
+
+:show	Show current bandpass data
+.fi
+.ih
+DESCRIPTION
+Observations of standard stars are integrated over calibration bandpasses
+and written to an output file along with the associated calibration
+fluxes.  The fluxes are obtained from tabulated standard star calibration
+files or a model flux distribution (currently just a blackbody) based on
+the magnitude and spectral type of the star.  The output data is used by
+the task \fBsensfunc\fR to determine the detector sensitivity function and
+possibly the extinction.  The spectra are required to be dispersion
+corrected.  The input spectra may be in either "onedspec" or "echelle"
+format and may have many different observation apertures.  The spectra may
+also be beam switched and use the a record number extension format.
+
+The input spectra are specified by a list of names or root names if using
+the record number extension format.  In the latter case each name in the
+list has each of the specified record numbers appended.  A subset of the
+input spectra may be selected by their aperture numbers using the parameter
+\fIapertures\fR.  The spectrum name, aperture number, and title are printed
+to the standard output.  The airmass is required but if absent from the image
+header it may be computed from the observation header parameters and the
+latitude task parameter (normally obtained from the \fBobservatory\fR task).
+If the airmass cannot be computed, due to missing keywords, then a
+query is made for the airmass.  The airmass is then updated in the header.
+
+The name of the standard star or blackbody curve is obtained by querying
+the user.  If the parameter \fIsamestar\fR is yes or beam switch mode is
+selected then all spectra are assumed to be of the same standard star and
+the query is made once.  If the parameter is no then a query is made for
+each aperture.  This allows each aperture to contain a different standard
+star.  Note however that multiple observations with the same aperture
+number must be of the same standard star.
+
+The standard star name is either the name of an actual standard star or of
+a blackbody calibration.  The latter generally have a star name consisting
+of just the standard bandpass identifier.  If the standard star name is not
+recognized a menu of the available standard stars in the calibration
+directory, the file "standards.men", is printed and then the query is
+repeated.  Thus, to get a list you can type ?  or help.
+
+The standard star names must map to a file containing tabulated
+calibration data.  The calibration filename is formed from the star
+name with blanks, "+", and "-" removed, converted to lower case, and
+the extension ".dat" added.  This name is appended to a calibration
+directory, so the directory name must have an appropriate directory
+delimiter such as "$" or "/".  Generally one of the system calibration
+directories is used but one may copy and modify or create new
+calibration files in a personal directory.  For the current working
+directory the calibration directory is either null or "./".
+
+The calibration files may include comment parameter information consisting
+of the comment character '#', a parameter name, and the parameter value.
+These elements are separated by whitespace.  Any other comment where the
+first word does not match one of the allowed parameter names is ignored by
+the program.  The parameter names are "type" identifying the type of
+calibration file, "units" identifying wavelength units, "band" identifying
+the band for magnitudes, and "weff" identifying the effective wavelength of
+the band.
+
+There are two types of standard star calibration files as described
+below.
+
+.ls STANDARD STAR CALIBRATION FILES
+This type of file is any file that does not contain the parameter "type"
+with a value of "blackbody".  The only other parameter used by this type of
+calibration file is the "units" parameter for the wavelength units.  If the
+units are not specified then the wavelengths default to Angstroms.  All
+older calibration files will have no parameter information so they are
+interpreted as standard star calibration files with wavelengths in
+Angstroms.
+
+The calibration files consist of lines with wavelengths, calibration
+magnitudes, and bandpass widths.  The magnitudes are m_AB defined as
+
+.nf
+    m_AB(star) = -2.5 * log10 (f_nu) - 48.60
+.fi
+
+where f_nu is in erg/cm^2/s/Hz.  The m_AB calibration magnitudes
+are converted to absolute flux per unit frequency using the
+parameter \fIfnuzero\fR defined by
+
+.nf
+    f_nu = fnuzero * 10. ** (-0.4 * m_AB)
+.fi
+
+Thus, \fIfnuzero\fR is the flux at m_AB of zero.  The flux units are
+determined by this number.  The default value was chosen such that Vega
+at 5556 Angstroms has an AB magnitude of 0.0336 and a flux of 3.52e-20
+ergs/cm2/s/Hz.  This is the same value that was used by all previous
+versions of this task.
+.le
+
+.ls BLACKBODY CALIBRATION FILES
+This type of file has the comment parameter "type" with a value of
+"blackbody".  It must also include the "band" and "weff"
+comment parameters.  If no "units" comment parameter is given then
+the default units are Angstroms.
+
+The rest of the file consists of lines with wavelengths, m_AB of a zero
+magnitude star (in that band magnitude system), and the bandpass widths.
+The m_AB are defined as described previously.  Normally all the m_AB values
+will be the same though it is possible to adjust them to produce a
+departure from a pure blackbody flux distribution.
+
+The actual m_AB calibration magnitudes for the star are obtained by
+the relation
+
+.nf
+    m_AB(star) = mag + m_AB(m=0) -
+        2.5 * log10 (B(weff,teff)/B(w,teff))
+.fi
+
+where m is the magnitude of the star in the calibration band, m_AB(m=0) is
+the calibration value in the calibration file representing the magnitude of
+a m=0 star (basically the m_AB of Vega), weff is the effective wavelength
+for the calibration file, and teff is the effective temperature of the
+star.  The function B(w,T) is the blackbody function in f_nu that provides
+the shape of the calibration.  Note how the normalization is such that at
+weff the last term is zero and m_AB(star) = m + m_AB(m=0).
+
+The m_AB(star) computed using the calibration values and the blackbody
+function are then in the same units and form as for the standard
+star files.  The conversion to f_nu and the remaining processing
+proceeds in the same way as for standard star calibration data.
+
+The parameters \Imag\fR and \fIteff\fR are specified by the user for each
+star as described in the section BLACKBODY PARAMETERS.  These parameters
+are queried by the task for each star (unless forced to a value on the
+command line).
+.le
+
+The beam switch mode is selected with the \fIbeam_switch\fR parameter.
+This mode requires that all apertures are of the same star, the header
+keyword OFLAG be present to identify object and sky spectra, and that
+the sequence of spectra specified are paired such that if an object
+spectrum is encountered first the next spectrum for that aperture
+(spectra from other apertures may appear in between) is a sky spectrum
+or the reverse.  These restrictions are not fundamental but are made so
+that this mode behaves the same as with the previous version of this
+task.  The sky spectrum is subtracted from the object spectrum and the
+result is then used in generating the observed intensities in the calibration
+bandpasses.
+
+If the spectra have been extinction corrected (EX-FLAG = 0) the
+extinction correction is removed.  The specified extinction file is
+used for this operation and so must be the same as that used when the
+extinction correction was made.  The airmass is also required in this step
+and, if needed to compute the airmass, the observatory specified in the
+image or observatory parameter is used.  The
+treatment of extinction in this task is subtle.  The aim of this task
+is to produce observed integrated instrumental intensities without
+extinction correction.  Thus, the extinction correction is removed from
+extinction corrected spectra.  However, a correction is made for an
+extinction gradient across the bandpasses.  This is done by applying an
+extinction correction, integrating across the bandpass, and then
+correcting the integrated intensity for the extinction at the center of
+the bandpass.  An alternative way to look at this is that the integral
+is weighted by the ratio of the extinction correction at each pixel to
+the extinction correction at the center of the bandpass.  This
+correction or weighting is why the extinction file and latitude are
+parameters in this task even though for nonextinction corrected spectra
+they appear not to be needed.
+
+The observed instrumental intensities are integrated within a set of
+bandpasses by summing the pixels using partial pixels at the bandpass
+edges.  Initial bandpasses are defined in one of two ways.  A set of
+evenly spaced bandpasses of constant width covering the range of the
+input spectrum may be specified using the parameters \fIbandwidth\fR
+and \fIbandsep\fR in the same units as the spectrum dispersion.  If
+these parameters have the value INDEF then the bandpasses from the
+calibration file which are entirely within the spectrum are selected.
+Generally these bandpasses are the actual measured bandpasses though
+one is free to make calibration files using estimated points.  The
+calibration bandpasses are preferable because they have been directly
+measured and they have been placed to avoid troubles with spectral
+lines.  However, when the coverage or resolution is such that these
+bandpasses do not allow a good determination of the instrumental
+response the evenly spaced bandpasses may be needed.  The calibration
+fluxes are linearly interpolated (or extrapolated) from the calibration
+data points to the defined bandpasses.
+
+Each spectrum adds a line to the output file containing the spectrum image
+name, the sky spectrum image name if beam switching, the aperture or beam
+number, the number of points in the spectrum, the exposure time, airmass,
+wavelength range, and title.  If the airmass is not found in the image
+header it is computed using the latitude parameter and observation
+information from the header.  If the airmass cannot be computed, due to
+missing keywords, then a query is made for the airmass.
+
+Following the spectrum information, calibration data is added for each
+bandpass.  The bandpass wavelength, absolute flux (per Angstrom),
+bandpass width, and observed instrumental intensity in the bandpass are
+added to the output file.  As discussed above, the observed intensity
+does not include an extinction term but does apply a small correction
+or weighting for the variation of the extinction across the bandpass.
+
+The setting and editing of the bandpasses may be performed
+interactively if the \fIinteract\fR flag is set.  In this case the user
+is queried for each spectrum.  The answers to this query may be "no" or
+"yes" to skip editing or edit the bandpasses for this spectrum, "NO" or
+"YES" to skip or not skip editing all spectra of the same aperture with
+no further queries for this aperture, and "NO!" or "YES!" to skip
+editing or edit all spectra with no further queries.
+
+When editing the bandpasses a graph of the spectrum is made with the
+bandpasses plotted at the computed intensity per pixel.  The cursor and
+colon commands available are summarized in the section CURSOR KEYS.
+Basically bandpasses may be added or deleted and the current bandpass
+data may be examined.  Additional keys allow the usual windowing and
+cursor mode operations.  When satisfied with the bandpasses exit with
+'q'.  The edited bandpasses for that aperture remain in effect until
+changed again by the user.  Thus if there are many spectra from the
+same aperture one may reply with "NO" to queries for the next spectra
+to accept the current bandpasses for all other spectra of the same
+aperture.
+
+BLACKBODY PARAMETERS
+
+When a blackbody calibration is selected (the calibration file selected by
+the \fIstar_name\fR parameter has "# type blackbody") there are two
+quantities needed to scale the blackbody to the observation.  These are the
+magnitude of the star in the same band as the observation and the effective
+temperature.  The magnitude is used for the flux scaling and the effective
+temperature for the shape of the flux distribution.  The values are
+obtained or derived from the user specified parameters \fImag\fR,
+\fImagband\fR, and \fIteff\fR.  This section describes how the the
+values are derived from other parameters using the data file "params.dat"
+in the calibration directory.
+
+The effective temperature in degrees Kelvin may be specified directly or it
+may be derived from a spectral type for the star.  In the latter case the
+file "params.dat" is searched for the effective temperature.  The file
+consists of lines with the first value being the spectral type and the
+second the effective temperature.  Other columns are described later.  The
+spectral type can be any string without whitespace that matches what is in
+the file.  However, the program finds the last spectral type that matches
+the first two characters when there is no complete match.  This scheme is
+intended for the case where the spectral types are of the form A0I, A0III,
+or A0V, where A can be any spectral type letter OBAFGKM, the single digit
+subtype is between 0 and 9, and the luminousity class is one of I, III, or
+V.  The two character match selects the last spectral type independent of
+the luminosity class.  The standard file "onedstds$blackbody/params.dat"
+uses these spectral type identifiers with the dwarf class acting as the
+default.
+
+The magnitude band is specified along with the input magnitude.  If the
+band is the same as the calibration band given in the calibration file then
+no further transformation is required.  However if the magnitude is
+specified in a different band, a conversion is performed using information
+from the "params.dat" file based on the spectral type of the star.
+
+When an effective temperature is specified rather and a spectral type then
+the nearest tabulated temperature for the spectral types that have "V" as
+the third character is used.  For the standard spectral type designations
+this means that when an effective temperature is specified the dwarf
+spectral type is used for the magnitude transformation.
+
+As mentioned previously, the "params.dat" data file has additional columns
+following the spectral type and effective temperature.  These columns are
+relative magnitudes in various bands.  The standard file has V magnitudes
+of zero so in this case the columns are also the X-V colors (where X is the
+appropriate magnitude).  Given the spectral type the relative magnitudes
+for the calibration band, m_1, and the input magnitude band, m_2, are found
+and the calibration magnitude for the star is given by
+
+.nf
+    m_calibration = m_input + m_1 - m_2
+.fi
+
+If one of the magnitudes is missing,  given as "INDEF" because the
+transformation is not available for the spectral type, the last spectral
+type matching the first two characters which does specify the two
+magnitudes will be used.  For example if there is no information for a
+B3III star for a M-J color then the spectral type B3V might be used.
+
+In order for the program to determine the bands for each column in the data
+file there must be a comment before the data with the column names.  It must
+begin with "# Type Teff" and then be followed by the same band identifiers
+used in the blackbody calibration files and as specified by the
+\fImagband\fR parameter.  Any amount whitespace (space or tab) is used to
+separate the various fields in the comment and in the fields of the table.
+For example the file might have the comment
+
+.nf
+    # Type    Teff     V      J      H      K      L   Lprime    M
+.fi
+
+identifying the third column of the file as the V magnitude and the
+ninth file as the M magnitude.
+.ih
+EXAMPLES
+1.  To compile observations of three standard stars using a beam
+switched instrument like the IIDS:
+
+.nf
+    cl> standard.recformat=yes
+    cl> standard nite1 1001-1008 std beam_switch+ interact-
+    [nite1.1001][0]: HZ 44 - Night 1
+    [nite1.1004][0]: HZ 44 - Night 1
+    [nite1.1005][0]: HZ 44 - Night 1
+    [nite1.1008][0]: HZ 44 - Night 1
+    Star name in calibration list: hz 44
+    cl> standard nite1 1009-1016 std beam_switch+ interact-
+    	...
+    cl> standard nite1 1017-1024 std beam_switch+ interact-
+    	...
+.fi
+
+This will create a file "std" which will contain sensitivity measurements
+from the beam-switched observations of the three standard stars given.
+Note that \fBstandard\fR is run separately for each standard star.
+
+The spectra will be from the images: nite1.1001, nite.1002 ... nite1.1024,
+and the default calibration file, "onedstds$irscal.dat" will be used.
+
+2.  For echelle spectra all apertures, the orders, are of the same star and
+so the samestar parameter is set.  Usually the resolution is much higher than
+the calibration data so in order to get sufficient coverage bandpasses must
+be interpolated from the calibration data.  Therefore the evenly spaced
+bandpasses are used.
+
+.nf
+    cl> standard.recformat=no
+    cl> standard.samestar=yes
+    cl> standard ech001.ec std bandwidth=10 bandsep=15
+    [ech001.ec][0]: Feige 110
+    Star name in calibration list: feige 110
+    [ech001.ec][0]: Edit bandpasses? (no|yes|NO|YES|NO!|YES!): yes
+    [ech001.ec][1]: Edit bandpasses? (no|yes|NO|YES|NO!|YES!): yes
+    [ech001.ec][2]: Edit bandpasses? (no|yes|NO|YES|NO!|YES!): NO!
+.fi
+
+3. To use a blackbody infrared calibration where the V magnitude of
+the star is known.
+
+.nf
+    cl> standard std1.ms std caldir=onedstds$blackbody/
+    std1.ms(1): Standard Star
+    Star name in calibration list: J
+    Magnitude of star: 10.3
+    Magnitude type (|V|J|H|K|L|Lprime|M|): V
+    Effective temperature or spectral type: B3III
+    WARNING: Effective temperature for B3III not found - using B3V
+    Blackbody: V = 10.30, J = 10.32, Teff = 19000
+    std1[1]: Edit bandpasses? (no|yes|NO|YES|NO!|YES!) (yes): 
+.fi
+
+Note the warning message and the confirmation information.
+.ih
+REVISIONS
+.ls STANDARD V2.10.4
+The calibration files can be defined to compute blackbody values.
+.le
+.ls STANDARD V2.10.3
+A query for the airmass and exposure time is now made if the information
+is not in the header and cannot be computed from other header keywords.
+.le
+.ls STANDARD V2.10
+Giving an unrecognized standard star name will page a list of standard
+stars available in the calibration directory and then repeat the
+query.
+.le
+.ih
+SEE ALSO
+observatory, lcalib, sensfunc
+.endhelp