diff options
Diffstat (limited to 'noao/astutil/doc/setairmass.hlp')
| -rw-r--r-- | noao/astutil/doc/setairmass.hlp | 243 |
1 files changed, 243 insertions, 0 deletions
diff --git a/noao/astutil/doc/setairmass.hlp b/noao/astutil/doc/setairmass.hlp new file mode 100644 index 00000000..bbb1cbb8 --- /dev/null +++ b/noao/astutil/doc/setairmass.hlp @@ -0,0 +1,243 @@ +.help setairmass Nov00 astutil +.ih +NAME +setairmass -- update image headers with the effective airmass +.ih +USAGE +setairmass images +.ih +PARAMETERS +.ls images +The list of images for which to calculate the airmass. The image headers may +optionally be updated with the airmass and the mid-UT of the exposure. +.le +.ls observatory = ")_.observatory" +Observatory for which airmasses are to be computed if the observatory is 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. If the input consists of images +then the observatory is defined by the OBSERVAT keyword if present. +.le +.ls intype = "beginning" +The time stamp of the observation as recorded at the telescope for the time +dependent header keywords. The choices are the "beginning", "middle" or "end" +of the observation. +.le +.ls outtype = "effective" +The output time stamp desired for the airmass. The choices are the "effective" +airmass, or the airmass at the "beginning", "middle" or "end" of the +observation. +.le +.ls ra = "ra" +The name of the keyword that contains the right ascension. The right ascension +is assumed to be in hours unless ra is one of the standard CRVALn keywords in +which case it is assumed to be in degrees. +.le +.ls dec = "dec" +The name of the keyword that contains the declination in degrees. +.le +.ls equinox = "epoch" +The name of the keyword that contains the equinox of the right ascension and +declination coordinates in years. +.le +.ls st = "st" +The name of the keyword containing the sidereal time in hours. +.le +.ls ut = "ut" +The name of the keyword containing the ut time. This keyword can either +be in date plus time format or in hours. Note that this allows setting +both the "date-obs" and "ut". If no time is found then +a time of 0hrs is used. +.le +.ls date = "date-obs" +The name of the keyword that contains the UT date of the observation. The +format should be `DD/MM/YY' (old FITS format), YYYY-MM-DD (new FITS format), +or YYYY-MM-DDTHH:MM:SS (new FITS format with time). If there is a time +and no time is found in the ut keyword then it is used for the ut. +.le +.ls exposure = "exptime" +The name of the keyword that contains the exposure time (in seconds) of the +image. +.le +.ls airmass = "airmass" +The name of the output keyword that will receive the computed airmass. +.le +.ls utmiddle = "utmiddle" +The name of the output keyword that will receive the universal time for +the middle of the observation. The format of the keyword will be the same +as that specifying the universal time. +.le +.ls scale = 750.0 +The atmospheric scale height. +.le +.ls show = yes +Print the airmasses and mid-UT's for each image? +.le +.ls update = yes +Update the image headers with the airmasses and the mid-UT's? +.le +.ls override = yes +If updating the image headers, override values that were previously recorded ? +.le + +.ih +DESCRIPTION + +SETAIRMASS will calculate the effective airmass of an astronomical image, as +described below under "ALGORITHMS". The task requires the instantaneous +zenith distance at the beginning, middle and end of the exposure. These are +calculated using the right ascension, declination, and equinox as well as the +sidereal time, exposure time, UT date, and observatory from the image header. +If the observatory is not available in the image header under the keyword +OBSERVAT, the observatory is defined by the \fIobservatory\fR parameter. See +help for \fIobservatory\fR for further information. + +The right ascension and declination will be precessed from the given equinox to +the date of observation. The name of the right ascension, declination, equinox, +sidereal time, ut time, exposure time, and date keywords can be specified as +parameters. These keywords should express the right ascension in hours, +the declination in degrees, the equinox in years, the sidereal time in hours, +the universal time in hours, the exposure time in seconds, and the date in +FITS format. If any of the required keywords are missing from the image +headers, they can be added using the hedit or asthedit tasks. Note that +the universal time keyword may be in either a date plus time format or +in hours and any output middle universal time will be in the same format. + +Before using this task, you will need to know the "time stamp" of the time +varying header quantities (e.g. sidereal time). Do the recorded values +represent the beginning, the middle or the end of the exposure ? This should +be set in the \fBintype\fR parameter. + +If for some reason the effective airmass is not desired, the value of the +airmass at the beginning, middle or end of the exposure can be recorded in the +header keyword specified by the \fIairmass\fR parameter. The \fBshow\fR +parameter can be used to control the output to the terminal. The \fBupdate\fR +and \fBoverride\fR parameters control the header keyword output. + +SETAIRMASS will also calculate the universal time of the middle of the exposure +and place the value in the header keyword specified by the \fIutmiddle\fR +parameter. This assumes that the value for the UT is in the date keyword +or ut keyword, with the same time stamp as the sidereal time. The +mid-observation UT is useful for interpolating calibration arc dispersion +solutions using REFSPECTRA, especially when the exposure time is +long. + +.ih +ALGORITHMS +The mean airmass is calculated uses the formula described in "Some +Factors Affecting the Accuracy of Stellar Photometry with CCDs" by P. +Stetson, DAO preprint, September 1988. This simple formula is: + +.nf + AM (eff) = [AM (beginning) + 4*AM (middle) + AM (end)] / 6 +.fi + +and is derived by using Simpson's 1/3 rule to approximate the integral +that represents the mean airmass. + +The beginning, middle and end airmasses are calculated using the +relation between airmass and elevation (or zenith distance) in John +Ball's book on Algorithms for the HP-45: + +.nf + AM = sqrt (x**2 + 2*scale + 1) - x, where + + x = scale * sin(elevation) = scale * cos(ZD) +.fi + +The atmospheric scaling parameter is \fIscale\fR (see "Astrophysical +Quantities" by Allen, 1973 p.125,133). + +.ih +KEYWORDS +The input keywords are: +.ls OBSERVAT +Observatory at which the data was taken. If absent the observatory is +determined using the \fIobservatory\fR parameter. +.le +.ls \fIra\fR +Right ascension in hours at the beginning, middle, or end of the observation. +If ra is one of the CRVALn keywords it is assumed to be in degrees. +.le +.ls \fIdec\fR +Declination in degrees at the beginning, middle, or end of the observation. +.le +.ls \fIequinox\fR +The equinox of the coordinates. The right ascension and declination will +be precessed from this epoch to the date of the observation before being +used. +.le +.ls \fIst\fR +Sidereal time in hours at the beginning, middle, or end of the observation. +.le +.ls \fIut\fR +Universal time in hours at the beginning, middle, or end of the observation. +This may be in either date plus time format or just in hours. +.le +.ls \fIdate\fR +The value of the date parameter is the keyword name to be used for the date of +the observation. The date must be in either the old or new FITS format. +.le +.ls \fIexposure\fR +The value of the exposure parameter is the keyword name to be used for the +exposure time in seconds. +.le + +The output keywords are: +.ls \fIairmass\fR +The value of the airmass parameter is the keyword name to be used for +the computed airmass at either the beginning, middle, or end of the +exposure, or for the weighted effective value over the exposure. +.le +.ls \fIutmiddle\fR +The value of the utmiddle parameter is the keyword name to be used for +the universal time at the middle of the exposure. +.le + +.ih +EXAMPLES + +1. Calculate the effective airmass of the IRAF test picture, dev$pix. + +.nf + cl> setairmass dev$pix exposure=itime update- +.fi + +Note that the test picture does not have the correct coordinate epoch +listed in its header, so no precession will be performed. + +2. Calculate the effective airmass of the IRAF test picture dev$ypix in two +ways. + +.nf + cl> setairmass dev$ypix exposure=itime update- + + cl> setairmass dev$ypix ra=crval1 dec=crval2 equinox=equinox \ + exposure=itime update- +.fi + +Note the first way gives the same results as example 1. The second way +uses the J2000 equatorial system rather then the ra and dec at the time +of observation. + +.ih +REVISIONS +.ls SETAIRMASS V2.11.4 +The ut keyword now has precedence over any time in the date keyword +and it can be either date plus time or hours. +.le +.ls SETAIRMASS V2.11.3 +The right ascension, declination, equinox, st, and ut keywords were made +parameters rather than being hard wired. +.le +.ls SETAIRMASS V2.11.2 +Y2K update: This task was updated to use the new FITS date format. +.le +.ih +SEE ALSO +airmass, hedit, refspectra, observatory +.endhelp |