Document Title	WFCAM HDS container and FITS headers
Document Number
Issue	1.1
Date	2003-Oct-27

Document Prepared By:	Alan Pickup	Signature and Date
Document Prepared By:		Signature and Date
Document Prepared By:		Signature and Date

Change Record

Issue	Date	Section Affected	Change Description
0.1	2002-Oct-16	all	1st version for time of Software CDR
0.2	2003-Feb-10	all	Tables include comment records; new headers including “TSCAN”s
0.3	2003-Feb-13	all	Correction of typos (thanks to Jim Lewis); some additional comments; addition of sections listing example headers.
0.4	2003-Feb-14	all	“TSCAN” becomes “JITTER”; added READOUT; expanded environment headers (from JAC); updated examples.
0.5	2003-Feb-24	all	Document title changed form WFCAM FITS headers to WFCAM HDS container and FITS headers New section on contents of HDS container New astrometric (WCS) headers: CDi_j and PV1_n New examples
0.6	2003-Mar-05	all	Removed NOFFSETS header Added SURVEY, SURVEY_I, DETECTID, PCSYSID, SDSUID, CAMROLE and GAIN headers New HDSTRACE and examples
1.0	2003-Oct-21	all	Added TILENUM, MJD-OBS Revised WCS items following discussions Added section on WFCAM WCS usage Added types for FITS values New HDSTRACE and examples
1.1	2003-Oct-27	3.1	PV3_3 corrected to PV2_3
1.1	2003-Oct-27	4	Minor changes and corrections

Introduction

This document illustrates the contents of a typical HDS container file into which WFCAM data is written and provides a list of FITS headers for that instrument. The FITS headers were based initially on those used for imaging with UIST but have been modified in the light of discussions, primarily in the area of the World Coordinate System headers.

Data from each of the four WFCAM cameras is to be written as NDF structures into separate HDS container files, usually as one file for each camera for each frame in a microstep pattern.

For a microstep frame, each container holds two NDF structures:

• The first, named I1, holds the image data frame, typically a 2048×2048 array of type _REAL. Associated with this is an array of character strings in MORE.FITS that contains the FITS headers specifically associated with this frame.
• The second NDF structure is named HEADER and is a repository for a more comprehensive array of FITS headers associated with the observation, again in a MORE.FITS extension. As all NDF structures must, HEADER contains its own DATA_ARRAY but in this case, it is simply a dummy one.

The reason for having separate HEADER and I1 structures is to make it possible to add additional I2, I3 etc. structures in the same container, with the contents of HEADER being common to all the frames. At present, this facility will be exploited for focus tests, with frames at multiple focus positions being written as separate NDF structures into one container, each with its own focus setting encoded in its own frame level MORE.FITS.

See the following section for a listing of the typical structure of a WFCAM HDS container file.

Example HDSTRACE of WFCAM Container File

The following listing illustrates the structure of a typical WFCAM container file, generated using the HDSTRACE command.

TEXT VERSION BELOW:

X20031020_00008 <UKIRT_HDS>

I1 <NDF> {structure}

DATA_ARRAY <ARRAY> {structure}

DATA(2048,2048) <_INTEGER> 5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,

… 21,21,21,21,21,21,21,21,21,21,21

ORIGIN(2) <_INTEGER> 1,1

HISTORY <HISTORY> {structure}

CREATED <_CHAR*24> ‘2003-OCT-20 22:04:46.000’

CURRENT_RECORD <_INTEGER> 1

RECORDS(10) <HIST_REC> {array of structures}

Contents of RECORDS(1)

DATE <_CHAR*24> ‘2003-OCT-20 22:04:46.000’

COMMAND <_CHAR*9> ‘<unknown>’

USER <_CHAR*5> ‘wfcam’

HOST <_CHAR*15> ‘wfdr2.roe.ac.uk’

DATASET <_CHAR*48> ‘/home/wfcam/data/raw/20031020/…’

TEXT(2) <_CHAR*72> ‘Arguments: <unknown>’,’Softwar…’

AXIS(2) <AXIS> {array of structures}

Contents of AXIS(1)

DATA_ARRAY <ARRAY> {structure}

DATA(2048) <_REAL> 0.5,1.5,2.5,3.5,4.5,5.5,6.5,

… 2044.5,2045.5,2046.5,2047.5

ORIGIN(1) <_INTEGER> 1

MORE <EXT> {structure}

FITS(4) <_CHAR*80> ‘UTSTART = 14.409722 /…’

… ‘FOC_OFF = 0.00…’

HEADER <NDF> {structure}

DATA_ARRAY <ARRAY> {structure}

DATA(1,1) <_REAL> 0

ORIGIN(2) <_INTEGER> 1,1

HISTORY <HISTORY> {structure}

CREATED <_CHAR*24> ‘2003-OCT-20 22:04:47.000’

CURRENT_RECORD <_INTEGER> 1

RECORDS(10) <HIST_REC> {array of structures}

Contents of RECORDS(1)

DATE <_CHAR*24> ‘2003-OCT-20 22:04:47.000’

COMMAND <_CHAR*9> ‘<unknown>’

USER <_CHAR*5> ‘wfcam’

HOST <_CHAR*15> ‘wfdr2.roe.ac.uk’

DATASET <_CHAR*52> ‘/home/wfcam/data/raw/20031020/…’

TEXT(2) <_CHAR*72> ‘Arguments: <unknown>’,’Softwar…’

MORE <EXT> {structure}

FITS(129) <_CHAR*80> ‘ ‘,’ …’

… ‘DET_TEMP= 25….’

End of Trace.

WFCAM FITS Headers

Two tables are provided:

• A table in section 3.1 of top-level headers which appears in the MORE.FITS section of an NDF structure called HEADER in the HDS container file;
• A table in section 3.2 of frame level headers that appear in the MORE.FITS section of each integration within the HDS container file.

Each table lists the:

• FITS keyword of the header;
• Comment field in the FITS string;
• Source of the FITS value when WFCAM is used on UKIRT (see below);
• The usual source of the FITS value during engineering tests;
• Type of the FITS value (either logical, character string, integer, or floating-point).

The possible sources of the FITS value are:

• fix – The value is fixed in the header definition table;
• om – Set from the sequencer level of observation control via the OM Translator and the OOS task. This is likely to be blank (see below) when WFCAM is run from its non-OM engineering interface;
• inst – Set from the instrument control level (the WFIS);
• TCS – Read from the telescope control system;
• EPICS – Obtained from the EPICs database. When this is not available during engineering tests, this may be a fixed value;
• data – Obtained as attribute alongside data received from the camera controller;
• DHS – Set within the DHS system;
• CSO – Obtained from CSO monitor task;
• blank – The FITS value field will be blank.

Note that these sources are as seen from the point of view of the DHS. The ones in the “om” may, in turn, originate in some aspect of a survey definition, be specified by the Observer, or be specified or derived in some other way, for example from an entry in a lookup table read by the OT.

Definition of Top Level FITS Headers

FITS Name	FITS Comment	UKIRT Source	Eng Source	Type
	Identification:
TELESCOP	Telescope name	fix	fix	string
INSTRUME	Instrument	fix	fix	string
CAMNUM	Number of this camera	data	data	integer
DHSVER	Data handling version	fix	fix	string
HDTFILE	Name of global hdt file	fix	fix	string
OBSERVER	Observers names	om	om	string
USERID	Userid logged in as	om	om	string
OBSREF	PATT or other reference	om	om	string
PROJECT	Time-allocation code	om	om	string
SURVEY	Survey name	om	om	string
SURVEY_I	Pointing ID within survey	om	om	string
MSBID	Id min.schedulable block	om	om	string
OBJECT	Object name from telescope	TCS	blank	string
	Data Reduction:
RECIPE	Data reduction recipe to be used	om	om	string
OBSTYPE	Type (BIASIDARKIFLATIOBJECTISKYIFOCUS)	inst	inst	string
OBSNUM	Observation number	DHS	DHS	integer
GRPNUM	Group number applied to all members	DHS	DHS	integer
GRPMEM	Group membership	om	om	logical
TILENUM	Tile number applied to all members	DHS	DHS	integer
STANDARD	Is the target a standard star	om	om	logical
NJITTER	Number of positions in telescope jitter pattern	om	om	integer
JITTER_I	Serial number of this telescope jitter pattern	om	om	integer
JITTER_X	[arcsec] X (RA) offset in telescope jitter pattern	om	om	float
JITTER_Y	[arcsec] Y (Dec) offset in telescope jitter pattern	om	om	float
NUSTEP	Number of positions in microstep pattern	om	om	integer
USTEP_I	Serial number in this microstep pattern	om	om	integer
USTEP_X	[arcsec] X (RA) offset in microstep pattern	om	om	float
USTEP_Y	[arcsec] Y (Dec) offset in microstep pattern	om	om	float
NFOC	Number of positions in focus scan	inst	inst	integer
NFOCSCAN	Number of focus scans in focus test	inst	inst	integer
	Astrometric and time information:
UTDATE	UT date as integer in yyyymmdd format	inst	inst	string
DATE-OBS	Date and time (UTC) of start of observation	date	date	string
DATE-END	Date and time (UTC) of end of observation	date	date	string
MJD-OBS	DATE-OBS as Modified Julian Date	data	data	float
WCSAXES	Number of axes in world co-ordinate system	fix	fix	integer
RADESYS	Mean IAU 1984 equatorial co-ordinates	fix	fix	string
EQUINOX	[yr] Equinox of object position	TCS	fix	float
CTYPE1	Algorithm type for axis 1	fix	fix	string
CTYPE2	Algorithm type for axis 2	fix	fix	string
CRPIX1	[pixel] Reference pixel along axis 1 (RA)	inst	inst	float
CRPIX2	[pixel] Reference pixel along axis 2 (Dec)	inst	inst	float
CRVAL1	[deg] Right ascension at the reference pixel	TCS	fix	float
CRVAL2	[deg] Declination at the reference pixel	TCS	fix	float
CRUNIT1	Unit of right ascension co-ordinates	fix	fix	string
CRUNIT2	Unit of declination co-ordinates	fix	fix	string
CD1_1	Transformation matrix element	inst	inst	float
CD1_2	Transformation matrix element	inst	inst	float
CD2_1	Transformation matrix element	inst	inst	float
CD2_2	Transformation matrix element	inst	inst	float
PV2_1	Pol. coefficient. for pixel -> celestial coord.	inst	inst	float
PV2_2	Pol. coefficient. for pixel -> celestial coord.	inst	inst	float
PV2_3	Pol. coefficient. for pixel -> celestial coord.	inst	inst	float
RABASE	[h] Right ascension of base position	TCS	fix	float
DECBASE	[deg] Declination of base position	TCS	fix	float
TRAOFF	[arcsec] Right ascension telescope offset	TCS	fix	float
TDECOFF	[arcsec] Declination telescope offset	TCS	fix	float
AMSTART	Airmass at start of observation	TCS	fix	float
AMEND	Airmass at end of observation	TCS	fix	float
TELRA	[h] Current telescope right ascension	TCS	fix	float
TELDEC	[deg] Current telescope declination	TCS	fix	float
GSRA	[h] Right ascension of guide star	TCS	fix	float
GSDEC	[deg] Declination of guide star	TCS	fix	float
	Instrument detector configuration:
DETECTOR	Type of detector array used	fix	fix	string
DETECTID	Serial number of detector array	data	data	string
NINT	Number of integrations in observation	data	data	integer
DROWS	[pixel] Number of detector rows	data	data	integer
DCOLUMNS	[pixel] Number of detector columns	data	data	integer
RDOUT_X1	Start column of array readout	data	data	integer
RDOUT_X2	End column of array readout	data	data	integer
RDOUT_Y1	Start row of array readout	data	data	integer
RDOUT_Y2	End row of array readout	data	data	integer
PIXLSIZE	[arcsec] Pixel size	inst	inst	float
	Detector controller:
PCSYSID	PC system identifier	inst	inst	string
SDSUID	Serial number of SDSU controller	inst	inst	string
READMODE	Name of camera readmode	inst	inst	string
CAPPLICN	Name of camera readout application	data	data	string
CAMROLE	Camera role (masterlslavelunsync)	inst	inst	string
READOUT	Camera readout (CDSINDRISARIRRR)	data	data	string
EXP_TIME	[s] Integration time per exposure	inst	inst	float
NEXP	Number of exposures in integration	inst	inst	integer
READINT	[s] Interval between reads	data	data	float
NREADS	Number of reads per exposure	data	data	integer
GAIN	[electrons/ADU] Detector gain	data	data	gloat
	Instrument optical configuration:
FILTER	Filter name	EPICS	EPICS	string
FOC_MM	[mm] Base focus position	EPICS	EPICS	string
	Environment:
AIRTEMP	[degC] Air temperature	EPICS	fix	float
BARPRESS	Ambient pressure	EPICS	fix	float
DEWPOINT	[degC] Dewpoint	EPICS	fix	float
DOMETEMP	[degC] Dome temperaure	EPICS	fix	float
HUMIDITY	Relative humidity	EPICS	fix	float
MIRRBSW	[degC] Temperature mirror B SW	EPICS	fix	float
MIRR_NE	[degC] MIrror temperature NE	EPICS	fix	float
MIRR_NW	[degC] Mirror temperature NW	EPICS	fix	float
MIRR_SE	[degC] Mirror temperature NE	EPICS	fix	float
MIRR_SW	[degC] Mirror temperature SW	EPICS	fix	float
MIRRBTNW	[degC] Mirror bottom temp. NW	EPICS	fix	float
MIRRTPNW	[degC] Mirror top temp. NW	EPICS	fix	float
SECONDAR	[degC] Temperature of secondary	EPICS	fix	float
TOPAIRNW	[degC] Top air NW	EPICS	fix	float
TRUSSENE	[degC] Truss leg ENE	EPICS	fix	float
TRUSSWSW	[degC] Truss les WSW	EPICS	fix	float
WIND_DIR	[deg] Truss leg ENE	EPICS	fix	float
WIND_SPD	[km/h] Wind speed	EPICS	fix	float
CSOTAU	Tau at 225 GHz from CSO	CSO	fix	float
TAUDATE	Time and date of Tau reading	CSO	fix	string
TAUSRC	Source or opacity data	CSO	fix	string
	Engineering:
CNFINDEX	Configuration index	EPICS	EPICS	integer
DET_TEMP	[K] Array temperature	EPICS	EPICS	float
	< More camera engineering data will go here >

Example of Top Level FITS Headers

TEXT VERSION BELOW:

Identification:

TELESCOP= ‘UKIRT ‘ / Telescope name

INSTRUME= ‘WFCAM ‘ / Instrument

CAMNUM = 2 / Number of WFCAM camera (1, 2, 3 or 4)

DHSVER = ‘UKDHS 2002 Oct 31 ‘ / Data handling version

HDTFILE = ‘wfcam.hdt ‘ / Name of global hdt file

HDTFILE2= ‘wfcam2.hdt ‘ / Name of camera-specific hdt file

OBSERVER= ‘Mrs Observer’ / Observers names

USERID = ‘abc ‘ / Userid logged in as

OBSREF = ‘notPATT99’ / PATT or other reference

PROJECT = ‘Example WFCAM data’ / Time-allocation code

SURVEY = ‘Demo survey 123’ / Survey name

SURVEY_I= ‘B1.99.4 ‘ / Pointing ID within survey

MSBID = ’42 ‘ / Id min.-schedulable block

OBJECT = ‘Laboratory wall’ / Object name from telescope

Data Reduction:

RECIPE = ‘QUICK_LOOK’ / Data reduction recipe to be used

OBSTYPE = ‘OBJECT ‘ / BIAS|DARK|SKYFLAT|DOMEFLAT|OBJECT|SKY|FOCUS

OBSNUM = 8 / Observation number

GRPNUM = 8 / Group number applied to all members

GRPMEM = T / Group membership

TILENUM = 0 / Tile number applied to all members

STANDARD= F / Is the target a standard star observation?

NJITTER = 4 / Number of positions in tel jitter pattern

JITTER_I= 1 / Serial number in this tel jitter pattern

JITTER_X= 0.00 / [arcsec] X (RA) offset in tel jitter pattern

JITTER_Y= 0.00 / [arcsec] Y (Dec) offset in tel jitter pattern

NUSTEP = 4 / Number of positions in microstep pattern

USTEP_I = 1 / Serial number in this microstep pattern

USTEP_X = 0.00 / [arcsec] X (RA) offset in microstep pattern

USTEP_Y = 0.00 / [arcsec] Y (Dec) offset in microstep pattern

NFOC = 0 / Number of positions in focus scan

NFOCSCAN= 0 / Number of focus scans in focus test

Astrometric and time information:

UTDATE = ‘20031020’ / UT date as integer in yyyymmdd format

DATE-OBS= ‘2003-10-20T14:24:35Z’ / Date and time (UTC) of start of observation

DATE-END= ‘2003-10-20T14:24:39Z’ / Date and time (UTC) of end of observation

MJD-OBS = 52932.60040 / DATE-OBS as Modified Julian Date

WCSAXES = 2 / Number of axes in world co-ordinate system

RADESYS = ‘FK5 ‘ / Mean IAU 1984 equatorial co-ordinates

EQUINOX = 2000.000 / [yr] Equinox of object position

CTYPE1 = ‘RA—ZPN’ / Algorithm type for axis 1

CTYPE2 = ‘DEC–ZPN’ / Algorithm type for axis 2

CRPIX1 = -1000.0 / [pixel] Reference pixel along axis 1 (RA)

CRPIX2 = -1000.0 / [pixel] Reference pixel along axis 2 (Rec)

CRVAL1 = 300.16419 / [deg] Right ascension at the reference pixel

CRVAL2 = 29.9749447 / [deg] Declination at the reference pixel

CRUNIT1 = ‘deg ‘ / Unit of right ascension co-ordinates

CRUNIT2 = ‘deg ‘ / Unit of declination co-ordinates

CD1_1 = 0.000000E+00 / Transformation matrix element

CD1_2 = -1.000000E+00 / Transformation matrix element

CD2_1 = 5.000000E-01 / Transformation matrix element

CD2_2 = -5.000000E-01 / Transformation matrix element

PV2_1 = 1.000000E+00 / Pol.coeff. for pixel -> celestial coord

PV2_2 = 0.000000E+00 / Pol.coeff. for pixel -> celestial coord

PV2_3 = 7.500000E+01 / Pol.coeff. for pixel -> celestial coord

RABASE = 20.0109458 / [h] Right ascension of base position

DECBASE = 29.9749447 / [deg] Declination of base position

TRAOFF = 0.000 / [arcsec] Right ascension telescope offset

TDECOFF = 0.000 / [arcsec] Declination telescope offset

AMSTART = 1.771 / Airmass at start of observation

AMEND = 1.769 / Airmass at end of observation

TELRA = 20.0123456 / [h] Current telescope right ascension

TELDEC = 29.9876543 / [deg] Current telescope declination

GSRA = 20.0103456 / [h] Right ascension of guide star

GSDEC = 29.9806543 / [deg] Declination of guide star

Instrument detector configuration:

DETECTOR= ‘RSC Hawaii 2’ / Type of detector array used

DETECTID= ‘a.bc.234’ / Serial number of detector array

NINT = 1 / Number of integrations in observation

DROWS = 2048 / [pixel] Number of detector rows

DCOLUMNS= 2048 / [pixel] Number of detector columns

RDOUT_X1= 1 / Start column of array readout

RDOUT_X2= 2048 / Start column of array readout

RDOUT_Y1= 1 / Start row of array readout

RDOUT_Y2= 2048 / Start row of array readout

PIXLSIZE= 0.4000 / [arcsec] Pixel size

Detector controller:

PCSYSID = ‘wfacq2 ‘ / PC system identifier

SDSUID = ‘00223 ‘ / Serial number of SDSU controller

READMODE= ‘CDS_v1 ‘ / Name of camera readmode

CAPPLICN= ‘applic01’ / Name of camera readout application

CAMROLE = ‘master ‘ / Camera role (master|slave|unsync)

READOUT = ‘CDS ‘ / Camera readout (CDS|NDR|SAR|RRR)

EXP_TIME= 1.000000 / [s] Integration time per exposure

NEXP = 1 / Number of exposures in integration

READINT = 1.000000 / [s] Interval between reads

NREADS = 0 / Number of reads per exposure

GAIN = 1.0 / [electrons/ADU] Detector gain

Instrument optical configuration:

FILTER = ‘whatever’ / Filter name

FOC_MM = 12.34 / [mm] Base focus position

Environment:

AIRTEMP = 5.785 / [degC] Air temperature

BARPRESS= 650.000 / Ambient pressure

DEWPOINT= 2.000 / [degC] Dewpoint

DOMETEMP= 7.095 / [degC] Dome temperature

HUMIDITY= 35.450 / Relative humidity

MIRRBSW = 7.123 / [degC] Temperature mirror B SW

MIRRNE = 7.124 / [degC] Mirror temperature NE

MIRRNW = 7.125 / [degC] Mirror temperature NW

MIRRSE = 7.126 / [degC] Mirror temperature SE

MIRRSW = 7.127 / [degC] Mirror temperature SW

MIRRBTNW= 7.128 / [degC] Mirror bottom temp. NW

MIRRTPNW= 7.129 / [degC] Mirror top temp. NW

SECONDAR= 7.130 / [degC] Temperature of secondary

TOPAIRNW= 7.131 / [degC] Top air NW

TRUSSENE= 7.132 / [degC] Truss leg ENE

TRUSSWSW= 7.133 / [degC] Truss leg WSW

WIND_DIR= 106.987 / [deg] Wind direction, azimuth

WIND_SPD= 16.089 / [km/h] Wind speed

CSOTAU = 0.047 / Tau at 225 GHz from CSO

TAUDATE = ‘2001-11-30T04:07’ / Time and date of Tau reading

TAUSRC = ‘CSO ‘ / Source of opacity data

Engineering:

CNFINDEX= 1 / Configuration index

DET_TEMP= 25.0 / [K] Detector array temperature

Definition of Frame Level FITS Headers

FITS Name	FITS Comment	UKIRT Source	Eng Source	Type
UTSTART	[h] Start time of integration	data	data	float
UTEND	[h] End time of integration	data	data	float
FOC_I	Serial number in focus scan	data	data	integer
FOC_OFF	[mm] Offset from base focus position	data	data	float

Example of Frame Level FITS Headers

TEXT VERSION BELOW:

UTSTART = 14.409722 / [h] Start time of integration

UTEND = 14.410833 / [h] End time of integration

FOC_I = 0 / Serial number in focus scan

FOC_OFF = 0.000 / [mm] Offset from base focus position

WFCAM WCS usage

Several items in the top-level FITS headers are connected with World Coordinate System (WCS) information. Thanks to Andy Vick for the explanations.

Note that all but the CTYPEn values are candidates for being updated with new values during commissioning.

1. CTYPEn FITS items

CTYPE1 and CTYPE2 give the output format. That is to say, they give the format for the coordinates after you have applied all the transformations. In our case CTYPE1 is “RA—ZPN” and CTYPE2 is “DEC—ZPN”. This implies that the transformation is a zenith polynomial one.

2. CRVAL and CRPIX FITS items

These define the position of the reference pixel, which will initially be set to as near the optical axis of the instrument as possible.

3. CD FITS items

The CD FITS items (CD1_1, etc) specify a transformation from pixel space with respect to a reference point to projection plane coordinates with respect to a reference point.

4. PV FITS items

A comment in the ITS WCS document states in order to do a radial expansion, as in ZPN, then the coefficients go in the PV matrix keywords appropriate for the ‘latitude’ axis, which in our case is the second axis. The information is carried by the FITS keywords of the form PV2_n, and the PV1_n keywords are not used.

The initial values are:

• PV2_1 = 1.0
• PV2_2 = 0.0
• PV2_3 = 75.0