# HOW-TO Work with dates and times in AWE¶

Observing nights and timestamps (valid ranges) are important concepts in AWE. These concepts are inherently confusing and some understanding of our conventions is necessary. This HOW-TO describes how to work with dates and times.

## Observing nights¶

When an astronomer does observations with a telescope this happens during the night at that telescope. We define a night for a particular telescope as the period between noon and noon the next day at that telescope. This concept is only valid in terms of local time. Since all relevant times that are stored in the database are stored in UTC, depending on the telescope, a conversion from local time to UTC and vice versa is necessary.

The following raw science images observed by WFC@INT are observed in the same night. This is the night of 30 March 2005 in our terminology.

WFC.2005-03-30T19:18:55.8.fits
WFC.2005-03-30T20:00:29.6.fits
WFC.2005-03-30T21:11:19.7.fits
WFC.2005-03-30T22:32:10.8.fits
WFC.2005-03-30T23:12:01.1.fits
WFC.2005-03-31T00:00:41.9.fits
WFC.2005-03-31T01:06:57.2.fits


In fact all data with observing dates (filenames) between WFC.2005-03-30T12:00:00.fits and WFC.2005-03-31T12:00:00.fits are considered part of the night of 30 March 2005 for WFC (see Table 2).

## Input from the user¶

Based on input from the user, namely the night for which to process data, both science images and calibration images are selected in the database and used/created. This input is always called “date” and is an argument for command line driven interfaces as well as the web services.

Examples:

awe> task = ReadNoiseTask(date='2000-04-28', instrument='WFI', chip='ccd50')

awe> query = RawScienceFrame.select(date='2000-04-28', instrument='WFI',
...                                 object='CDF4_B_1')
awe> for f in query: print f.DATE_OBS
...
2000-04-29 00:04:29.00
2000-04-29 00:04:29.00
2000-04-29 01:05:58.00
2000-04-29 00:04:29.00
2000-04-29 00:04:29.00
2000-04-29 00:04:29.00
2000-04-29 01:05:58.00
2000-04-29 01:05:58.00
2000-04-29 01:05:58.00
2000-04-29 01:05:58.00
2000-04-29 00:04:29.00
2000-04-29 01:05:58.00
2000-04-29 00:04:29.00
2000-04-29 00:04:29.00
2000-04-29 01:05:58.00
2000-04-29 01:05:58.00


In fact all data with observing dates (filenames) between WFI.2000-04-29T16:00:00.fits and WFI.2000-04-30T16:00:00.fits are considered part of the night of 29 April 2000 for WFI (see Table 2).

## Time stamps¶

To be able to automatically select appropriate calibration files (bias, flat etc.) from the database for a given science image or as a result of the “date” input by the user, timestamps are assigned to each calibration file that define a period for which this calibration file is valid. All dates that are stored in the database and used for this purpose are in UTC. See also Table 1. Calibration files are valid for a certain multiple of observing nights, depending on the type of file.

## Dates in the database¶

Table 1: Dates as stored in the database

raw images and science images
description name (header item) type of value
observing date DATE-OBS datetime type (UTC)
observing date UTC float
observing date (modified julian date) MJD-OBS float
observing date (local siderial time) LST float
FITS file write time DATE datetime type (UTC)
(if available) start of observing block (…)OBS START datetime type (UTC)
(if available) start of template (…)TPL START datetime type (UTC)
calibration images
description name type of value
start of valid range timestamp_start datetime type (UTC)
end of valid range timestamp_end datetime type (UTC)
creation date creation_date datetime type (UTC)
start of observing block (observing_block.)date_obs datetime type (UTC)
start of template (template.)date_obs datetime type (UTC)

## Conversions between local time and UTC¶

A night in terms of UTC is determined by converting “noon” to UTC. No correction is made for any daylight saving time. The shift in the timestamps is exactly equal to the timezone of the instrument.

Table 2: Instrument time zones

instrument timezone typical timestamp start (UTC) typical timestamp end (UTC)
WFC @ INT 0 2005-01-05T12:00:00 2005-01-06T12:00:00
WFI @ 2.2m 4 2005-01-05T16:00:00 2005-01-06T16:00:00
OCAM @ VST 4 2005-01-05T16:00:00 2005-01-06T16:00:00
MDM8K @ 2.4m 7 2005-01-05T19:00:00 2005-01-06T19:00:00