.help setjd Jan92 astutil
.ih
NAME
setjd -- set various Julian dates in image headers
.ih
USAGE
setjd images
.ih
PARAMETERS
.ls images
The list of images for which to compute Julian dates.  If the \fIlistonly\fR
parameter is not set the image headers will be modified to add or update
the calculated Julian date values.
.le
.ls observatory = ")_.observatory"
Observatory of observation, used to define the time zone relative to
Greenwich, 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 \fBobservatory\fR for
additional information.
.le
.ls date = "date-obs"
Date of observation keyword.  The value must be in FITS format.
This is one of DD/MM/YY (old FITS format), YYYY-MM-DD (new FITS format),
or YYYY-MM-DDTHH:MM:SS (new FITS format with time).  The date should be
in universal time though the \fIutdate\fR parameter can be used if
this is not the case.  If a time is included it is used in preference
to the \fItime\fR value.
.le
.ls time = "ut"
Time of observation keyword with value given in decimal hours or HH:MM:SS.S
format.  The date may be a local time or universal time as selected by the
\fIuttime\fR parameter.  The time is used as is
unless an exposure time keyword is specified, in which case
the time will be corrected to the midpoint of the exposure from the
beginning or end of the exposure.  This time is not used if a time
is given in the date keyword.
.le
.ls exposure = "exptime"
Exposure time keyword with value in seconds.  If specified the time
is corrected to the midpoint of the exposure.  The time is assumed
to be the beginning of the exposure unless
the exposure time keyword name begins with a minus sign, for example
"-exptime", in which case the time is used as the end of the exposure.
.le
.ls ra = "ra", dec = "dec", epoch = "epoch"
If the heliocentric Julian date is requested the right ascension (in hours)
and declination (in degrees) of the observation is determined from these
keywords.  The values may be in either decimal or sexagesimal notation.
An epoch keyword is optional and if given is used to precess
the coordinates from the specified epoch to the observation epoch.
If an epoch keyword is given but is not found in the header or can't
be interpreted then it is an error.  The epoch keyword value may begin
with 'B' or 'J'.  If the value is before 1800 or after 2100 a warning
will be printed though the task will still compute the values.
.le

.ls jd = "jd"
If specified compute the geocentric Julian day (Greenwich) at the
midpoint of the exposure and record the value in the specified
header keyword.
.le
.ls hjd = "hjd"
If specified compute the heliocentric Julian day (Greenwich) at the
midpoint of the exposure and record the value in the specified
header keyword.
.le
.ls ljd = "ljd"
If specified compute the local Julian day number.  This is an integer
number which is constant for all observations made during the same night.
It may be used to group observations by night in such tasks as
\fBrefspectra\fR.
.le

.ls utdate = yes, uttime = yes
Define whether the date and time of observation are in local standard
time or in universal time.
.le
.ls listonly = no
List the computed values only and do not modify the image headers.
When simply listing the images need not have write permission.
.le
.ih
DESCRIPTION
\fBSetjd\fR computes the geocentric, heliocentric, and integer
local Julian dates from information given in the headers of
the input list of images.  This information may simply be listed or
the values may be added or modified in the image headers.  Only
those values which have a keyword specified are computed, printed,
and entered in the images.  Thus, one need not compute all values
and the dependent image header parameters required for computing them
need not be present.  For example, if the coordinates of the
observation are not available one should set the \fIhjd\fR parameter
to an empty string.

Often the date and time of observation are recorded either at the
beginning or the end of an exposure.  To compute the Julian dates
at the midpoint of the exposure the exposure keyword is specified.
A negative sign preceding the keyword name defines correcting from
the end of the exposure otherwise the correction is from the
beginning of the exposure.  The exposure time must be in seconds and
there is no allowance made for exposures which are interrupted.
See also the task \fBsetairmass\fR which may be used to compute a
universal time midexposure value.

The date and time of observations should be given either in universal
time.  However, if they are given in local standard time (there is no
provisions for daylight savings times) the \fIutdate\fR and \fIuttime\fR
parameters may be used.  Conversion between local and universal times, as
well as the computation of the local integer date, requires the time zone
in (positive) hours behind Greenwich or (negative) hours ahead of
Greenwich.  This information is determined from the observatory at which
the observations were made.  If the observatory is specified in the image
header under the keyword OBSERVAT with a value which has an entry in the
NOAO, local, or user observatory database then the value from the database
is used.  This is the safest way since the observatory is tied to the
actual image.  Otherwise, the \fIobservatory\fR parameter defines the
observatory.  The special value "observatory" allows defining a default
observatory with an environment variable or the \fBobservatory\fR task.
Explicitly use the parameter \fIobservatory.timezone\fR use the value
"obspars".  For more information see help under \fBobservatory\fR.

The heliocentric Julian date is computed by defining a keyword for
this value and also defining the keywords for the right ascension (in hours)
and declination (in degrees).  An optional epoch keyword may be
used if the RA and DEC are not for the observation epoch.

The local integer Julian day number is the Julian date which begins at
local noon.  Thus, all observations made during a night will have the
same day number.  This day number may be useful in grouping
observations by nights.  Note that in some time zones the UT
date of observation may also be constant over a night.

Among the uses for this task is to define keywords to be used by the task
\fBrefspectra\fR.  In particular, the exposure midpoint geocentric Julian
date makes a good sort parameter and the local Julian day number makes a
good group parameter.
.ih
EXAMPLES
1.  Compute all the Julian date quantities for 4 arc exposures with
header parameters given below.

.nf
    demoarc1:
	OBSERVAT= 'KPNO              '  /  observatory
	EXPTIME =                  60.  /  actual integration time
	DATE-OBS= '26/11/91          '  /  date (dd/mm/yy) of obs.
	UT      = '12:11:30.00       '  /  universal time
	RA      = '06:37:02.00       '  /  right ascension
	DEC     = '06:09:03.00       '  /  declination
	EPOCH   =               1991.9  /  epoch of ra and dec

    demoarc2:
	OBSERVAT= 'KPNO              '  /  observatory
	EXPTIME =                  60.  /  actual integration time
	DATE-OBS= '26/11/91          '  /  date (dd/mm/yy) of obs.
	UT      = '12:41:30.00       '  /  universal time
	RA      = '06:37:02.00       '  /  right ascension
	DEC     = '06:09:03.00       '  /  declination
	EPOCH   =               1991.9  /  epoch of ra and dec

    demoarc3:
	OBSERVAT= 'CTIO              '  /  observatory
	EXPTIME =                  60.  /  actual integration time
	DATE-OBS= '27/11/91          '  /  date (dd/mm/yy) of obs.
	UT      = '11:11:30.00       '  /  universal time
	RA      = '06:37:02.00       '  /  right ascension
	DEC     = '06:09:03.00       '  /  declination
	EPOCH   =               1991.9  /  epoch of ra and dec

    demoarc4:
	OBSERVAT= 'CTIO              '  /  observatory
	EXPTIME =                  60.  /  actual integration time
	DATE-OBS= '27/11/91          '  /  date (dd/mm/yy) of obs.
	UT      = '12:21:30.00       '  /  universal time
	RA      = '06:37:02.00       '  /  right ascension
	DEC     = '06:09:03.00       '  /  declination
	EPOCH   =               1991.9  /  epoch of ra and dec

    cl> setjd demoarc?.imh
    # SETJD: Observatory parameters for Kitt Peak ...
    #              Image            JD           HJD   LOCALJD
	    demoarc1.imh  2448587.0083  2448587.0127   2448586
	    demoarc2.imh  2448587.0292  2448587.0336   2448586
    # SETJD: Observatory parameters for Cerro Tololo ...
	    demoarc3.imh  2448587.9667  2448587.9711   2448587
	    demoarc4.imh  2448588.0153  2448588.0197   2448587
.fi

Note the use of the observatory parameter to switch observatories and
the local Julian day number which is constant over a night even though
the Julian date may change during the observations.

2.  To compute only the geocentric Julian date from the "DATE" and
"TIME" keywords in an image,

.nf
    cl> setjd obs1 date=date time=time exp="" hjd="" ljd=""
.fi
.ih
REVISIONS
.ls SETJD V2.11.2
Y2K update:  Updated to use the new FITS format for the date.  If the
time is given in the date keyword it is used in preference to the
time keyword.
.le
.ls SETJD V2.11
The checking of the epoch keyword value was improved.  Previously if
there was a problem with the keyword value (missing or malformed) the
task would use the epoch of the observation.  Now it is an error
if an epoch keyword is specified but the epoch value can't be determined.
Also a leading 'B' or 'J' is allowed and a warning will be given if
the epoch value is unlikely.
.le
.ih
SEE ALSO
setairmass, hedit, refspectra, observatory
.endhelp
