setairmass: Compute effective airmass and middle UT for an exposure

Package: irs

Usage

setairmass images

Parameters

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.

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 observatory.observatory, or "obspars" to select the current parameters set in the observatory task. See help for observatory for additional information. If the input consists of images then the observatory is defined by the OBSERVAT keyword if present.

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.

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.

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.

dec = "dec": The name of the keyword that contains the declination in degrees.

equinox = "epoch": The name of the keyword that contains the equinox of the right ascension and declination coordinates in years.

st = "st": The name of the keyword containing the sidereal time in hours.

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.

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.

exposure = "exptime": The name of the keyword that contains the exposure time (in seconds) of the image.

airmass = "airmass": The name of the output keyword that will receive the computed airmass.

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.

scale = 750.0: The atmospheric scale height.

show = yes: Print the airmasses and mid-UT's for each image?

update = yes: Update the image headers with the airmasses and the mid-UT's?

override = yes: If updating the image headers, override values that were previously recorded ?

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 observatory parameter. See help for observatory 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 intype 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 airmass parameter. The show parameter can be used to control the output to the terminal. The update and override 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 utmiddle 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.

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:

AM (eff) = [AM (beginning) + 4*AM (middle) + AM (end)] / 6

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:

AM = sqrt (x**2 + 2*scale + 1) - x, where

 x = scale * sin(elevation) = scale * cos(ZD)

The atmospheric scaling parameter is scale (see "Astrophysical Quantities" by Allen, 1973 p.125,133).

Keywords

The input keywords are:

OBSERVAT: Observatory at which the data was taken. If absent the observatory is determined using the observatory parameter.

ra: 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.

dec: Declination in degrees at the beginning, middle, or end of the observation.

equinox: 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.

st: Sidereal time in hours at the beginning, middle, or end of the observation.

ut: 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.

date: 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.

exposure: The value of the exposure parameter is the keyword name to be used for the exposure time in seconds.

The output keywords are:

airmass: 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.

utmiddle: The value of the utmiddle parameter is the keyword name to be used for the universal time at the middle of the exposure.

Examples

1. Calculate the effective airmass of the IRAF test picture, dev$pix.

cl> setairmass dev$pix exposure=itime update-

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.

cl> setairmass dev$ypix exposure=itime update-

cl> setairmass dev$ypix ra=crval1 dec=crval2 equinox=equinox \
    exposure=itime update-

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.

Revisions

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.

SETAIRMASS V2.11.3: The right ascension, declination, equinox, st, and ut keywords were made parameters rather than being hard wired.

SETAIRMASS V2.11.2: Y2K update: This task was updated to use the new FITS date format.