[NOAO logo] [IRAF logo]

NOAO is operated by the Association of Universities for Research in Astronomy (AURA), Inc. under cooperative agreement with the National Science Foundation

Francisco Valdes, January 27, 2000

Classes Describing Astronomical Observations

1. Introduction

This document defines classes which describe elements of an astronomical observation. A class consists of a number of specific items or elements of information. The power of this approach lies in allowing elements to be instances of another class. This leads to a class hierarchy. Another powerful feature is that elements may be a set or array of like pieces of information. This is used to described such things as multiple objects or apertures in an observation.

There is certainly no unique way to decompose a general astronomical observation into a set of classes. But most classes are really quite obvious as is the idea of defining classes that follow the elements of a observation, telescope system, data acquisition system, data processing system, and archive system. Clearly it is not possible to define a priori all the information for every type of astronomical observation. However, an advantage of the class approach is that it can be easily extended in a systematic way. This is done by adding additional elements to a class or adding new classes. Instrument or system specific classes, such as for a particular instrument or detector array controller, may be added to define parameters which do not fit any general class or observation model.

One application of the class description is for documenting an astronomical observation. For examples of where this has been used see NOAO Image Data Structure Definitions and Description of 2D Spectroscopic Image Data. For an observation resulting in a FITS image the set of class elements is translated to a set of FITS keywords. This document is organized into a section describing various classes and a section describing how to map the classes to FITS keywords.

The class description presented here is a work in progress. Because there are a very large number of potential classes and elements of information there may be some contradictions or omissions. It will be continually expanded or improved as circumstances require and time permits. It primary role is to serve as a way to organize information for mapping into a FITS keywords dictionary. It has proven quite useful for this purpose and so it is recommended that others may follow the same class description or, at least, the same methodology.

2. Class Definitions

This section presents definitions and descriptions for a large number of classes. These classes were defined as part of the process of defining the data format for the NOAO Mosaics and for future NOAO image data. Appendix A lists all the classes. When viewed with a hyperlink viewer the appendix can be used to go to a particular class of interest. Also elements of a class which are themselves classes provide links to the class definitions.

The syntax for the class definitions has the following conventions. A class is identified by a name entirely in upper case. An element in a class which is an instance of another class is identified by a name with the first letter capitalized. The element name will often be the same as the name of the class, but if it is not the class it will be identified in the description. When an element is shown in brackets this means a class may be defined for a specific instrument or system. An element describing an individual piece of information is identified by a lower case name. When an element may be an array of zero or more instances it have "[n]" appended to the name. Elements that apply to the axes of an image array have "[i]" or "[i,j]" appended to the name.


The OBSERVE class is the top level class describing an astronomical observation. It is organized into defaults for the entire class hierarchy and broad subclasses which conceptually follow the information path from the astronomical object or objects, through the instrumentation, to the final archive.

The default units, coordinate, and time are included to provide global defaults for other elements in the mapping to FITS keywords. All the MJD keywords which are not part of the TIME class are given in the default time system. For example, if the data system does not provide separate coordinate information for the objects(s), telescope, detector, etc. then the single global coordinate will apply for all these logically distinct coordinates. This is described further in the next section.

         Units - Default units
    Coordinate - Default coordinate
          Time - Default time
     Object[n] - Information about the astronomical object(s) 
          Site - Information about the observing site
          Dome - Information about the telescope dome
     Telescope - Information about the telescope and other systems 
       Adapter - Information about the adapter
            Tv - Information about the acquisition TV
        Guider - Information about the guider
   Aperture[n] - Information about the apertures
    Instrument - Information about the instrument
  Disperser[n] - Information about the dispersers
     Filter[n] - Information about the filters
       Shutter - Information about the shutter
        Camera - Information about the camera
      Detector - Information about the detector
   Observation - Information about the observation
         Image - Information about the image data and format
      Observer - Information about the observer and proposal
    Processing - Information about processing
       Archive - Information about archiving

Some of the general systems in the light path may actually be parts of other systems. For instance the filters may be in the telescope, instrument, camera, or detector. Similarly the shutter may occur at various points in the light path. However, the logical classes are used for these elements regardless of where they actually occur. Similarly the atmospheric dispersion compensator and correctors are included in the TELESCOPE class though they may also be located elsewhere in a particular telescope system.


The OBJECT class encapsulates information about an observed target astronomical object. In this class the object name is a standard reference name (see The Second Reference Dictionary of the Nomenclature of Celestial Objects, A&AS, 107 193 and IAU Guide). The user specified name for the object/observation is part of the OBSERVATION class. The standard object type is from a dictionary of types. The goal of this class is to provide names and identifications that can be used by an archive system.

The OBJECT class is not used for calibration observations. Details about the calibration source are part of the OBSERVATION class.

          name - Standard astronomical reference name
          type - Standard object type
    Coordinate - Astronomical coordinate of the object
SITE Class

The SITE class encapsulates information about the observing site. The standardized observatory name is used as a key to look up site information such as the latitude, longitude, and altitude. The photometric conditions and the seeing estimates are intended to aid archival selection. Seeing estimates may be derived in several ways from guiders, separate detectors, or from the image data. The best estimate for the image data should be recorded as the primary value and additional ones can be included as desired. The ENVIRONMENT subclass defines information about the temperature, wind, humidity, etc.

   observatory - Standard observatory name
       weather - General weather conditions
   photometric - Photometric conditions
     seeing[n] - Seeing estimates (FWHM of star profiles)
 seeing-mjd[n] - Time for seeing estimates
   Environment - Site environment
DOME Class

The DOME class includes information about the dome status, various sensor information, and environment in the dome, primarily temperature and wind.

        status - Dome status
       Sensors - Dome sensors
   Environment - Dome environment

The TELESCOPE class encapsulates information about the telescope systems. There are various subsystems that may be in use and other subsystem classes may be added.

          name - Telescope name
        config - Telescope configuration
       Version - Telescope hardware and software versions
        status - Telescope status
    Coordinate - Telescope pointing coordinate
         Altaz - Altitude/azimuth pointing coordinates
           mjd - MJD of telescope parameters
        zenith - Zenith distance
     hourangle - Hour angle
         focus - Telescope focus
   ratrackrate - Telescope tracking rate in right ascension
  dectrackrate - Telescope tracking rate in declination
       Sensors - Telescope sensor information
  corrector[n] - Correctors
           Adc - Atmospheric dispersion compensator system
      Adaptive - Adaptive optics system
        Active - Active optics system
          Chop - Chopping system
           Nod - Nodding system
  dectrackrate - Telescope tracking rate in declination
       [Other] - Other systems

The ADAPTER class includes various types of sensor information. The most likely information is the position angle.

       Version - Adapter hardware and software versions
        status - Adapter status
       Sensors - Adapter sensor information
TV Class

The TV class describes a television system. There are currently two instances of this class. The Observe.Tv instance describes the acquisition TV. The Observe.Guider.Tv instance describes the guider TV. Often the acquisition and guider TVs are the same system in which case the acquisition TV should be described. If there is a TV position it is given by the Sensors.position elements.

          name - TV name
        status - TV status
       Version - TV hardware and software versions
       Sensors - TV sensor information
     Filter[n] - TV filters

The GUIDER class describes the guiding system. This may be a manual system, no guiding, or some autoguider. When an autoguider is fed by a TV system the Tv subclass is used. When the same TV system is used for acquisition and guiding the acquisition TV should be described. The position of a guide probe is given by the positions in the Sensors subclass. When a guide object is used the coordinate of the object may be included.

          name - Guider name (including "manual" and "none")
        status - Guider status
       Version - Guider hardware and software versions
            Tv - Guider TV information
       Sensors - Guider sensor information
    Coordinate - Guider coordinate
          rate - Guider rate

The APERTURE class describes apertures, primarily those for spectrographs. A spectrum is a subclass of an aperture. For the case of aperture-less spectroscopy, e.g. objective prism spectroscopy, the aperture type is set to "none" and the other attributes are not used.

    apertureid - Aperture identification
  aperturetype - Aperture type
    Coordinate - Aperture coordinate
      diameter - Aperture diameter for circular apertures and fibers
        length - Aperture length for slit apertures
         width - Aperture width for slit apertures
        apunit - Aperture dimensions unit
      posangle - Aperture position angle
       fiberid - Compact fiber identification
        slitid - Compact slit identification
      Spectrum - Spectrum projected on the detector

The INSTRUMENT class consists of a few common parameters and then specific instrument subclasses; for example, a HYDRA subclass. The specific instruments will have their own parameters in addition to the common ones. Note that while apertures, filters, dispersers, camera, and detector may be part of the instrument these are logically separated out. So only information which cannot be described by those classes is included.

          name - Instrument name
        config - Instrument configuration
       Version - Instrument hardware and software versions
        status - Instrument status
       Sensors - Instrument sensor information
         focus - Instrument focus
  [Instrument] - Other instrument specific information

The DISPERSER class describes the dispersers in the optical path. Note that the effective central wavelength and dispersion are given in the PROJECTION class. The most common disperser parameter is a grating position or angle which are given by the appropriate sensor parameter.

          name - Disper identification
       Sensors - Disperser sensor information

The FILTER class describes the filter(s) in use. A distinction is made between the astronomical or observer's filter name and the technical or observatory identification. Since many filter systems consist of a holder with several filters, the position parameter indicates which specific filter holder is in the optical path.

          name - Filter reference name (i.e. U, V, Gunn R)
          type - Filter technical name (i.e. OG480, CuS, KP1408)
      position - Filter bolt/wheel position

The SHUTTER class primarily provides information about the shutter speed as well as identifying the hardware.

       Version - Shutter hardware and software versions
        status - Shutter status/mode
       Sensors - Shutter sensor information
          open - Shutter time to open
         close - Shutter time to close

The CAMERA class provides a few generic parameters and specialized camera subclasses.

          name - Camera name
        config - Camera configuration
       Version - Camera hardware and software versions
        status - Camera status
       Sensors - Camera sensors
         focus - Camera focus
      [Camera] - Additional camera subclasses

The DETECTOR class describes the detector characteristics, geometry, world coordinate system, and so forth. A detector is considered to be made up of one or more physical detectors such as CCDs or IR detectors. The physical detectors are described as a separate class. The CCD class is defined here, but the IR class is not yet defined. Other physical detector classes may be defined in the future. The reason for defining the DETECTOR class as a set of physical detectors is to allow detector systems which consist of a mosaic of physical detectors.

          name - Detector name
        config - Detector configuration
       Version - Detector hardware and software versions
        status - Detector status
       Sensors - Detector sensor information
    Projection - Sky and disperser projections on the detector
    Coordinate - Coordinate of detector center
          size - Size of detector pixel raster

         nccds - Number of CCD detectors
         namps - Number of amplifiers
        Ccd[n] - CCD information
           nir - Number of IR detectors
         Ir[n] - IR detectors
    [Detector] - Other detectors
         Dewar - Dewar information

The OBSERVATION class describes aspects of the observation which are not tied to the telescope, instrument, detector, etc. or given elsewhere. Some of these parameters may have the same value as other parameters. For instance the observation name may be the same as the object name and the coordinate may be the same as the telescope coordinate.

The observation and image identification are the fundamental parameters linking observations consisting of multiple images. This occurs, for example, with observations using multiple amplifiers in a CCD or multiple physical detectors in a mosaic detector. For more on this see section 2.1 of NOAO Image Data Structure Definitions and section 3.1.

The error messages report errors in the observation from all systems. Errors are not part of every class to minimize the number of error parameters. It is also reasonable because most errors are likely to abort the observation and so would not appear in a data header.

         title - Observation title or name
        status - Observation status
       Obstype - Observation type (object, flat, zero, dark, etc.)
    Coordinate - Observation coordinate
         obsid - Unique observation identification (usually observatory-wide)
       imageid - Image identification (one for each image in an observation)
    exprequest - Requested exposure time
       airmass - Airmass of observation
   airmass-mjd - Time of airmass
      error[n] - Error messages

The IMAGE class describes the recorded image. Many of the parameters are directly related to those in the FITS standard. Other standard FITS parameters may be added. The END keyword is, of course, required at the end of the FITS header.

The use of the extension name and version is discussed in in section 3.1.

        simple - File conforms to FITS standard
        bitpix - Bits per pixel
         naxis - Number of image axes
      naxis[n] - Number of image pixels along each axis
        bscale - Scale factor
         bzero - Zero factor
        pcount - Number of pixels following image
        gcount - Number of groups
        extend - FITS extensions present
      xtension - FITS extension type
       extname - Extension name
        extver - Extension version
       inherit - Inherit global header in image extensions?
       nextend - Number of image extensions
      filename - Filename of originally recorded image
       comment - General comment 
       history - General history
      Header - Time header is created (TIME class)
      Checksum - Image check sum information
       Version - Image creation system version
           end - End of header

The OBSERVER class records the name(s) of the observers, the name(s) of the proposer(s), and information about the proposal. The comment elements provide a mechanism for the observer to add comments.

       name[n] - Observer name
   proposer[n] - Proposer name
      proposal - Proposal/project title
    proposalid - Proposal/project identification
    comment[n] - Comments

The PROCESSING class gives information about any processing performed on the data after the observation is completed. Details of this are yet to be determined. One common type of processing is a standard pipeline. This processing is described by the PIPELINE class. One standard result of processing is calibration of the data into pixel values which are proportional to photon counts. The photoncal flag indicates if this type of calibration has been done. For CCD data this implies bias, zero level, dark count, and flat field calibrations.

        status - Processing status
        log[n] - Processing log information
      Pipeline - Pipeline processing
     photoncal - Is the pixel data linearly related to photon counts?

The ARCHIVE class gives information about the archive system and the unique identifications for the observation. The dictionary element is important to tie the observation header to the precise definitions of each parameter.

          name - Archive name
       Version - Archiving system and software version
     archiveid - Archive identification of observation (if different)
    dictionary - Keyword dictionary name

The COORDINATE Class is a collections of subclasses for each type of coordinate which might be used. The subclasses then provide the elments necessary to specify a particular coordinate. The definition here is not complete.

The two most common types of astronomical observations are imaging and spectroscopy. Both of these use some type of celestial coordinate. The most common type of celestial coordinate, at least for optical ground-based observations is an equitorial coordinate. In addition for the type of observation where the imaged light of an object or any point in the field is dispersed the DISPERSION coordinate class adds a dispersion coordinate.

    Equatorial - Equatorial coordinates
        Dispersion - Dispersion coordinate

The EQUATORIAL class is used in many parent classes to specify celestial equatorial coordinates (i.e. right ascension and declination) such as for objects, telescope pointing, instrument apertures, and world coordinate systems. An equatorial coordinate consists of a coordinate system with an equinox and the coordinate with an epoch. Often everything but the actual coordinate will default to a global default value; i.e. all coordinates are likely to be specified in the same system with the same units.

        system - Coordinate system
            ra - Right ascension
           dec - Declination
        raunit - Right ascension unit
       decunit - Latitude unit
       equinox - Equinox of coordinate system
         epoch - Epoch
Dispersion Class

The DISPERSION Class defines a coordinate for a spectrum where one dimension is dispersion. The dispersion coordinates are referred to a standard of rest given by the dispersion reference frame. In addition dispersion coordinates depend on the location of the observer relative to the reference frame as defined for the observatory and telescope. The zero point of velocity dispersion units are defined relative to some frequency or wavelength given by the velrest parameters.

       dispval - Dispersion coordinate value
      dispunit - Dispersion unit
     dispframe - Dispersion reference frame name
       velzero - Dispersion value for zero velocity
   velzerounit - Unit of velocity reference dispersion
UNIT Class

These define the units for various quantities. Others may be added as needed.

          ra - right ascension unit
         dec - declination unit
   longitude - longitude unit
    latitude - latitude unit
     azimuth - azimuth unit
    altitude - altitude unit
    aperture - Aperture dimensions
    sepangle - celestial separation angle unit
    posangle - position angle unit
   timeofday - time of day unit
        rate - celestial rate of motion

      length - length unit
        time - time unit
    velocity - velocity unit
        mass - mass unit
       angle - plane angle unit
      sangle - solid angle unit
 temperature - temperature unit
     current - current unit
lumintensity - luminous intensity unit
   frequency - frequency unit
      energy - energy unit
       power - power unit
        volt - voltage unit
       force - force unit
    pressure - pressure unit
      charge - charge unit
  resistance - resistance unit
 conductance - conductance unit
 capacitance - capacitance unit
     magflux - magnetic flux unit
  magdensity - magnetic flux density unit
  inductance - inductance unit
     lumflux - luminous flux unit
 illuminance - illuminance unit
  luminosity - luminosity unit
       event - event unit
        flux - flux density unit
     magetic - magnetic field unit
        area - area unit

The ALTAZ class allows recording telescope altitude or elevation and azimuth for "altaz" telescopes.

   altitude[n] - Altitude or elevation
    azimuth[n] - Azimuth
        mjd[n] - Time of altitude/azimuth
TIME Class

The TIME class provides detailed time stamps for times in parent classes. All times are in the specified time system except for utc. Time stamps in most classes are provided by just a modified Julian date rather than a TIME class element since the date, time, and lst can be derived from the modified Julian date.

          date - Date
           utc - Coordinated universal time
           mjd - Modified Julian date
           lst - Local siderial time
       timesys - Time system identifier (UTC, TAI, etc)
          time - Time in specified system 

Many classes reference the VERSION class. In some cases either of the hardware or software versions may not make sense.

      hardware - Hardware version
      software - Software version

The SENSORS class is a general class for various engineering sensor information. In some cases specific sensor information, such as encoder positions for focus, grating tilts, etc., is defined separately in various classes. In other cases some of the sensor types will not be meaningful. Note that the MJD time of sensor class measurements are in the default time system.

temperature[n] - Temperature sensor(s)
    voltage[n] - Voltage sensor(s)
   position[n] - Position sensor(s)
   pressure[n] - Voltage sensor(s)
   posangle[n] - Position angle sensor(s)
        mjd[n] - Time of sensor measurement in default time system

The ENVIRONMENT class describes the environmental conditions at some place (outside the dome, inside the dome, etc.) and time.

temperature[n] - Temperature
   pressure[n] - Atmospheric pressure
   humidity[n] - Relative humidity
 watervapor[n] - Water vapor content
  windspeed[n] - Average wind speed over sampling period
    winddir[n] - Average wind direction over sampling period
  windgusts[n] - Maximum wind speed over sampling period
     period[n] - Sampling period
        mjd[n] - Time for parameters

The DEWAR class identifies the dewar used and various sensor data. Typically the dewar temperature is monitored.

          name - Dewar identification name
       Version - Dewar hardware and software versions
        status - Dewar status
       Sensors - Dewar sensors

The PROJECTION class gives information about the projection of the sky and dispersion on the detector other than that given in the world coordinate system WCS class. Note that both a right ascension and declination position angle are needed to indicate right or left-handed axes.

    raposangle - Position angle of RA axis relative to detector axes
   decposangle - Position angle of DEC axis relative to detector axes
   pixscale[i] - Pixel scale in arc seconds
      dispaxis - Dispersion axis on image
    wavelength - Approximate central wavelength on detector
   wdispersion - Pixel scale in wavelength

The SPECTRUM class describes a 2D/3D spectrum on the detector. This consists a coordinate system description mapping pixel coordinates to dispersion and celestial coordinates and a region in pixel or world coordinates containing the spectrum. It also includes a measure of the profile width. Since the path of the dispersion (the dispersion axis) may be tilted relative to the image pixel axes one is generally interested in the boundaries of the spectrum in world coordinates of constant dispersion coordinate (such as wavelength) and spatial coordinate.

The profile width is mainly relevant for optical fiber spectra and possibly stellar spectra. For fiber spectra where the fibers are closely packed and overlapping this information would be useful for profile fitting and separating of the spectra.

The spectrum description may be approximate. In particular, the spectrum limits may be offset from the true spectrum on the detector by a translation. The data reduction software will adjust regions to match the data. Similarly the dispersion WCS may be approximate allowing the reduction software to refine it automatically.

           Wcs - Spectrum WCS
     Wcsregion - Region specifying boundaries of spectrum
          fwhm - FWHM of spectrum profile
CCD Class

The CCD class describes a single CCD chip and its dewar. Each CCD may use multiple amplifiers. The CCD may be part of a larger mosaic of CCDs in which case the section parameter defines the array coordinates of the region given by the size parameter. The amplifiers may be read out in drift scan mode in which case there is a distinction between the effective size and the CCD size. The sizes are the full sizes even if there is only a partial readout of the amplifier.

          name - Identification of the CCD chip
       Version - Hardware and software version
       Sensors - Sensor information such as the temperature
         Dewar - CCD dewar information
      preflash - Preflash
          size - Effective size (unbinned pixels, driftscan)
       ccdsize - Size of CCD (if different from effective size)
    pixsize[i] - Size of pixel on each axis
    Coordinate - Coordinate information for the center of the CCD
         namps - Number of CCD amplifiers
        Amp[n] - Information about each amplifier used
     Badpixels - Information about bad pixels
AMP Class

The AMP class is the basic unit of a CCD detector or mosaic CCD detector. The section parameter maps the amplifier data array to a part of the CCD data array which may, in turn, be mapped to a part of a CCD mosaic data array. The amplifier readout is expected to be stored in an image array as a data section and one or more bias sections. The bias sections contain prescan or overscan data. In drift scan mode some or all of the initial readout lines, those which have not been integrated over the maximum number of lines may or may not be discarded. The minscan parameter indicates how many lines have been integrated to form the first recorded line. Subsequent lines increase up to maxnscan.

          name - Amplifier identification
           Exp - Exposure information
          size - Size of the full amplifier readout
       section - Section of full CCD read (in unbinned pixels)
       binning - Binning of pixels
    biassec[n] - Regions of image containing bias data (pre/overscan)
       trimsec - Region in image of good data
      maxnscan - Maximum averaged lines in drift scan
      minnscan - Minimum averaged lines in drift scan (first recorded line)
      Amptrans - CCD to amplifier transformation
    Imagetrans - CCD to image transformation
      Dettrans - CCD to detector transformation
           Wcs - World coordinate system
    Controller - Information about the controller

The PIXTRANS class defines a linear coordinate transformation between CCD pixel coordinates and other pixel coordinate system. In particular transformation to amplifier, image, and detector coordinates. The section parameter uses the transformation to map the CCD section to a section in the other pixel coordinate system. In the definition of the header keywords a identify transformation may be specified by omitting the keywords.

       tm[i,j] - Transformation matrix
         tv[i] - Transformation vector
       section - Mapping of CCD section

The BADPIXELS class describes the location of known bad pixels in the CCD detector. This class is preliminary. The current usage is a parameter specifying a filename and the implementation is an IRAF mask file.

     badpixels - Bad pixel description
EXP Class

The EXP class describes the exposure intervals during which photons are collected. Often there will only be a single exposure but if there are subintegrations or the exposure is interrupted for clouds or other reasons the separate intervals can be recorded as a starting time and an exposure interval. When there is a series of equal length subexposures only the nsubexposures and subexptime parameters need be recorded. For charge shuffling the number of subexposures refers to the number of charge shuffled exposure positions. The subexposure times refer to the total time for each shuffled exposure position.

      Expstart - start of exposure (TIME class)
        Expend - end of exposure (TIME class)
       exptime - total active exposure time
      darktime - total time dark counts are accumulating
 nsubexposures - number of subexposures
 subutstart[n] - start 
 subexptime[n] - subexposure time
WCS Class

The WCS class encapsulates a coordinate mapping between image pixels and user or world coordinates. This WCS description follows the FITS standard as much as possible. The latest FITS proposal is here .

The WCS ties a reference pixel in the image to a world coordinate. This reference coordinate and its associated attributes is defined by the COORDINATE class. The scales in the coordinate rotation and scale matrix are in the same coordinate system as the reference coordinate.

The type of WCS depends on the type of data. For 2D imaging the reference coordinate is a 2D celestial coordinate, most commonly equitorial. For spectra the WCS also includes a 2D celestial coordinate and adds a dispersion coordinate. Note that though the WCS for a spectrum is 3D the image may be 2D in which case the missing spatial axis is handled by the FITS WCS Dimensionality conventions.

Fiber spectra are unusual in that the spatial coordinates are scrambled. It is recommended that one still use the 3D spectral world coordinate system since the celestial coordinate is meaningful for the observation. The spatial axes of the coordinate rotation and scale matrix would still need to be defined in the same celestial units as the reference point but the rotation would be arbitrary. However, one might also chose to relegate the fiber coordinate to the APERTURE.COORDINATE Class and use a simple pixel coordinate for the spatial axis.

A recommended convention for ordering the world coordinate axes is that those with just a celestial coordinate define the longitude coordinate as the first world coordinate axis. For spectra the first world coordinate axis is dispersion and the second is the longitude axis. For those unfamiliar with the FITS WCS methods, the relation of the world coordinate axes to the image pixel axes is handled through the coordinate rotation matrix so fixing the world axes does not restrict with image axis corresponds to which world coordinate.

    Coordinate - Reference coordinate
      crpix[i] - Coordinate reference pixel
       cd[i,j] - Coordinate rotation and scale matrix
      ctype[i] - Coordinate type
     wcsastrom - Astrometry source for WCS description
    IRAF WCS - IRAF WCS description

This class currently describes rectangular regions in pixel space and world coordinate space using lower and upper limits. The defined region is the intersection of the two. If one is not specified it defaults to the whole space.

       pmin[i] - Lower limit for pixel coordinates
       pmax[i] - Upper limit for pixel coordinates
       cmin[i] - Lower limit for world coordinates
       cmax[i] - Upper limit for world coordinates

The IRAF WCS class contains information not in the standard WCS class.

        wcsdim - Dimensionality of the physical coordinate system
     wat[i][n] - WCS attribute strings

The CONTROLLER class consists of a few common parameters and then specific controller subclasses. The specific controllers will have their own parameters in addition to the common ones. The current NOAO classes are KP2901 and ARCON.

          name - Controller name
       Version - Controller hardware and software versions
        status - Controller status
       Sensors - Controller sensor information
          gain - Amplifier gain
     readnoise - Amplifier readout noise
      saturate - Saturation value
   integration - Amplifier integration time
      readtime - Amplifier pixel read time
        sample - Amplifier sampling method
  [Controller] - Additional controller parameters

The ARCON class contains parameters specific to the ARCON controller.

     gainindex - Gain index (index into Gain Table)
          gain - Predicted gain
     readnoise - Predicted readout noise
      wavemode - Waveform options enabled
      wavedate - Waveform compilation date

The OBSTYPE class describes the type of observation. The types have standardized values so that software may identify calibration and astronomical observations. For calibration observations this class gives additional calibration information.

          type - Standardized observation types (flat, dark, object, focus, etc.)
          Lamp - Calibration lamp
      Focusseq - Focus sequence information
LAMP Class

The LAMP class specifies information about calibration lamps. The lamp type is standardized for arc lamps so that software may determine the type of arc lines observed.

          name - Lamp name
          type - Lamp type from standard list
       Sensors - Lamp sensors

The FOCUSSEQ class describes focus calibration sequences. A sequence may be a set of independent images at different focus values or a single multiple exposure image with shifts of the detector (either by electronically moving the image, moving the detector, or moving the telescope) between exposures and focus values.

    nexposures - Number of focus exposures in a sequence
         start - Starting instrumental focus value
          step - Step in instrumental focus value
         shift - Shift between focus exposures in multiple exposure sequence

The CHECKSUM class models the proposed FITS checksum standard for verifying the data integrity.

        header - Header checksum
          data - Data checksum
       version - Checksum version

The PIPELINE class describes standardized processing that is applied to the image data after the observation is completed. The standardized pipeline processing is characterized by a name and version. The pipeline is presumed to be well-documented. Any log information is recorded in the processing log elements. The individual [Pipeline] classes give specific parameters of the pipeline.

For example a pipeline might be "Standard IRAF CCDPROC Pipeline" and the CCDPROC class would be defined to have the parameters produced by CCDPROC -- OVERSCAN, FLATCOR, etc. --that include the calibration images used.

          name - Name of pipeline
       Version - Version
    [Pipeline] - Pipeline classes
ADC Class

The ADC class describes the atmospheric dispersion compensation system.

       Version - ADC hardware and software versions
        status - ADC status
       Sensors - ADC sensor information

The ACTIVE class describes the active optics system. The frequency parameter indicates the update frequency.

       Version - Active optics hardware and software versions
        status - Active optics status
       Sensors - Active optics sensor information
     frequency - Active optics frequency

The ADAPTIVE class describes the adaptive optics system. The frequency parameter indicates the update frequency. If a natural object is used for the wavefront monitoring its coordinate is given. In that case it is likely that the guider information is not needed.

       Version - Adaptive optics hardware and software versions
        status - Adaptive optics status
       Sensors - Adaptive optics sensor information
     frequency - Adaptive optics frequency
          type - Wavefront monitor object type
    Coordinate - Wavefront monitor object coordinate
CHOP Class

The CHOP class describes the chopping system such as a chopping secondary.

       Version - Chopping hardware and software versions
        status - Chopping status
       Sensors - Chopping sensor information
     frequency - Chopping frequency
        cycles - Chopping cycles
         angle - Chopping angle
      distance - Chopping distance
NOD Class

The NOD class describes the nodding system.

       Version - Nodding hardware and software versions
        status - Nodding status
       Sensors - Nodding sensor information
     frequency - Nodding frequency
        cycles - Nodding cycles
         angle - Nodding angle
      distance - Nodding distance

3. The FITS Header

This section defines the mapping of the logical observation header to the FITS header. There are, of course, many possible mappings. The logical header is very general and could be used by many observatories. The particular mapping given here is for NOAO, though it could also be used by other observatories such as Gemini.

Every piece of information identified by the logical model has both a logical name and a FITS keyword. The logical names are obtained by combining the element names from the root class, through the subclasses, to a final node element using a "dot" delimiter. By convention the root "Observe" class name is not included. As an example, the right ascension of an observed object is:


The array elements are generally left unexpanded and the array index number is used as a numerical suffix in the FITS keyword.

The FITS keyword names are eight or fewer characters as required by the FITS standard. The FITS keyword names will be comprised of upper case alphabetic characters, digits, and hyphens. The keywords will begin with an alphabetic character and hyphens will only be used for keywords already in common use or defined in the basic FITS standard.

Because of the limitation to eight characters the FITS keywords must be severely abbreviated. An attempt is made to use straightforward abbreviations. Also related keywords will generally use a common two or three character prefix. The final reference for a keyword is the keyword dictionary and any new keywords must be selected to avoid conflict with previously defined keywords.

There are a large number of items in the logical header. However, there is no requirement that all them appear in the FITS header. There are several reasons why items will not appear. Some items do not make sense for particular instruments and some items may not be available to the data acquisition system.

In addition to missing items the mapping from the logical header to the FITS header need not be one-to-one. While the logical header identifies each possible item separately, many items will have the same value. These can be mapped to a single FITS keyword. An example of this is the coordinate system identification which may apply to all coordinates; i.e. all coordinates are given in FK5 with equinox J2000. Items may also map to the same keyword because there is no precise value but a related value is approximately correct. An example of this is if the location of the center of the detector on the sky is not known then the telescope position my be substituted.

The mapping between the logical header items and the FITS keywords is given in Table 1. This is automatically extracted from the reference dictionary. The table gives the primary FITS keyword, the default keyword (which may itself default to another keyword), and the logical name. If an item does not have an default then if it is missing the information is undefined.

The indexed items have the following convention. The first element either uses a separate keyword if one is given or uses the keyword without a numeric suffix. Further elements have the index as a numeric suffix with leading zeros to make up the number of digits indicated. For example, the first astronomical target object (and in most cases the only one) uses the keyword OBJNAME or OBJECT. The second object uses OBJ0002. The first (and possibly only) filter is FILTER and the second filter is FILTER02.

3.1 FITS Image Extension Keywords

The FITS Image Extension format provides two keywords for each image; an extension name, EXTNAME, and an extension version, EXTVER. It is tempting to use these for the fundamental identification discussed in in section 2.1; that is, the unique observation identification common to all images from the same observation and the amplifier numbers for the detector. However, these keywords disappear when an image unit is separated into simple single FITS images. So the observation identification and amplifier number are given by other keywords (OBSID and IMAGEID).

Instead the extension name is defined for user selection. The proposed IRAF FITS Image Extension syntax allows selection of an image in the extension file by its position in the file, by its extension name, or by its extension version. There is no requirement that the extension name and version be unique so a combination of the two is also an option. One constraint is that reference by the extension name and/or version be identifiably different from the position number. This means the extension name may not begin with a number and the extension version may not be given without some qualifier.

For use at NOAO the selection options will be the position in the file or an easily typed extension name. The name uses the prefix "im" followed by the image identification. Thus, a particular amplifier readout in a FITS extension image, say obs001, would be referenced as either obj001[3] or obj001[im3]. The first case references the third image in the file (not necessarily image number 3) and the second case references image (amplifier) number 3 independently of its location in the file. The extension version is optional but if included it will be the image identification number.

3.2 Time Stamps

There are time stamps for most of the measurement parameters defined by the logical header. These time stamps are specified to be modified Julian dates with the fraction of a date based on a UTC time. The keyword mapping provides for separate keywords. However, most of the time stamps do not need to be more accurate than the time of observation or are accumulated at the time the image header is created by the software. Therefore, most of the time stamps will default either to MJDHDR, the time at which the header is created, or MJD-OBS, the time of the observation. Note that the keyword implementation explicitly defines the time of the observation as the start of the integration; i.e. the keywords DATE-OBS, MJD-OBS, UTC, and LST map to the Expstart element of the Exposure class.

3.3 Coordinate Systems

There are many logical coordinates, as instances of the COORDINATE class, in the model. In practice most of the coordinates will have common values or at least common coordinate systems (the system, the equinox, and the epoch). The FITS keyword mapping provides separate keywords for every logical coordinate. However, generally the keywords will be missing leading to the default keywords. The default keywords may, in turn, default to yet more common or global keywords. Finally if the global keywords are missing the keyword dictionary defines the system used for all coordinates.

The mapping uses the following logical scheme. The defaults lead either to the object or telescope coordinates. In particular, the instrument aperture coordinates default to the object coordinates while the guider and detector coordinates default to the telescope coordinates. Note that sub-elements of the detector, such as CCDs in a mosaic default to the detector coordinates which, in turn, default to the telescope coordinates. This scheme allows using two sets of keywords to give, for example, coordinates in a telescope system and an object or catalog system. The telescope system may use epoch of observation coordinates while the object or catalog system may use a standard epoch such as B1950 or J2000.

The telescope and object coordinate may default to a common set of more global keywords. If all coordinates are consistently given in the same coordinate system and epoch then these keywords explicitly identify them. These global keywords -- RADECSYS, EQUINOX, and EPOCH -- can be missing in which case the keyword dictionary defines the defaults. In particular, if there are no keywords for the coordinate system and epoch the coordinates are in the FK5 system with equinox J2000 and the coordinate epoch is the epoch of date as defined by the MJD-OBS keyword. However, it is recommended that the coordinate system and epoch be explicit in the FITS header.

Appendix A: List of Classes

  • ACTIVE Class
  • ADAPTER Class
  • ADAPTIVE Class
  • ADC Class
  • ALTAZ Class
  • AMP Class
  • APERTURE Class
  • ARCHIVE Class
  • ARCON Class
  • CAMERA Class
  • CCD Class
  • CHECKSUM Class
  • CHOP Class
  • DETECTOR Class
  • DEWAR Class
  • DOME Class
  • EXP Class
  • FILTER Class
  • FOCUSSEQ Class
  • GUIDER Class
  • IMAGE Class
  • IRAF WCS Class
  • LAMP Class
  • NOD Class
  • OBJECT Class
  • OBSERVE Class
  • OBSERVER Class
  • OBSTYPE Class
  • PIPELINE Class
  • PIXTRANS Class
  • SENSORS Class
  • SHUTTER Class
  • SITE Class
  • SPECTRUM Class
  • TIME Class
  • TV Class
  • UNIT Class
  • VERSION Class
  • WCS Class