path: root/noao/onedspec/doc/standard.hlp

.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