SSW Keyword/Tag Definitions

S.L.Freeland, Last Rev: 14-October-1999

This document describes a minimal set of keyword definitions which permit application of SSW software tools to existing and new solar data sets. While the definitions are described as FITS Keywords, these are equivilent to the IDL structure tag definitions. Many SSW utilities operate on either FITS files or IDL structures and there are SSW routines which interconvert between the two ( fitshead2struct/.pro and struct2fitshead.pro ). One very important implication of this interconvertability is that existing FITS files which do not include one or more of these tags are easily brought into the fold by definition of a function which adds the missing tags or adjusts incorrectly defined tags to the structure interpretation. This type of function is easily written using SSW structure manipulation SW. You do not have to regenerate any FITS files! An additional implication is that there is NO file format imposed or implied by SSW - it is an IDL based system which just happens to have alot of FITS users and includes extensive FITS support utilities. For example, the routine mreadfits.pro reads multiple 2D FITS files into a vector of IDL header structures and a corresponding 3D data cube which allows vectorized treatment of the large FITS image data bases, simplifies movie making, and offers many other advantages over traditional FITS processing techniques. The routine struct2ssw.pro is available to add or modify "partially conforming" data bases - for example, if any one of a few possible time or pointing standards is present, the others are derived according to the SSW definitions described below and included in the output structures. This facilitates integration of new data bases and maximizes the use of downline software available to the data base.

Use of these suggested standards permit immediate use of many utilities available under SSW including:

• Mapping package by D.Zarro et al. for solar image comparisons, rotations and overlays
• utplot package by R.Schwartz et al. for time series analysis and inter-instrument comparisons
• Dynamic Stereoscopy package by M.Aschwanden
• ssw_track_fov differential rotation tracking and extraction of regions of interest from full disk data bases
• applications for grid overlay, limb darkening removal, differential rotation, inter-instrument solar dbase access, etc.

Many thanks to Dominic Zarro, Markus Aschwanden, Jean-Pierre Wuelser, Bill Thompson, Craig DeForrest, Richard Schwartz, Mons Morrison, Jeff Newmark, Russ Howard, and other SSW contributors for participating in discussions or providing documentation which led to distillation of these minimal SSW standards. Special thanks to Craig DeForrest for the use of his ztools WWW documentation which was used as the starting point for this document.

• Pointing
  • FITS Keywords / Tags for Pointing
  • Pixel Coordinate Systems
  • Image Coordinate Systems
• Timing
  • FITS Keywords / Tags for Timing
  • A keyword ambiguity
  • Reference Time
  • Time Zones
• FITS Keywords / Auxiliary Tags
• Standards Documents

Pointing Tags

Timing tags

Auxiliary tags

Pointing overview

Pointing registration is accomplished in 2-D by defining a Cartesian coordinate system that lays upon the natural pixel coordinate system of the image. This "unitted" coordinate system is defined by a single datum of correspondence between the two systems, a scale for the unitted system, and a rotation angle.

Pixel coordinates

Pixellized images are assumed to be arranged in horizontal rasters running left to right, which in turn are stacked from bottom to top. X coordinates run left to right and are the fastest-running index; Y coordinates bottom to top and are the slower index.

There is an additional complication: FITS uses a different pixel coordinate system than does IDL. IDL takes (0,0) to be the lower left corner of the image, while FITS takes (1,1) to be the lower left corner.

Each pixel is taken to be centered on the appropriate coordinate: the extreme lower left corner of the lower left pixel is (-0.5,-0.5) in IDL pixel coordinates; or (0.5,0.5) in FITS pixel coordinates. This is important, for example, when keeping track of CRPIXn

Image coordinates

The "unitted" coordinates in the image are themselves the subject of some ambiguity. The SOHO and Yohkoh communities seem to use "Solar" coordinates a lot; these coordinates have the names "solar-x" and "solar-y", and are angular coordinates defined only for small angles away from Sun center, from the vantage point of the Earth.

Images are usually maps of some scalar quantity against 2-D angle; however, from a particular vantage point and for small angles (such as solar images as seen from Earth), they may be converted to maps versus position. The conversion requires knowledge of the observer's position relative to the Sun . This is accomplished with by keeping track of the observer's B-angle ('colatitude'), longitude, and radius from the Sun

Many generic solar SW utilities are available under SSW for things like solar ephemeris, grid overlay, NOAA AR overlay, image co-alignment, solar feature tracking and subfield extraction from full disk data sets, etc. Major contributors in these areas include T. Metcalf, J.P.Wuelser, G.Slater, L.Wang, B.Handy, M.Morrison, C.DeForrest, D.Zarro, W.Thompson, and S.Freeland.

Dominic Zarro has recently developed a powerful, object oriented suite of image mapping, rotation, reprojection, and overlay tools which can interface to solar data sets which provide the pointing information and time references keywords described in this document.

The ztools package by Craig DeForrest provide passing support for some coordinate systems that are not semi-cartesian. In particular, heliographic coordinates and image-plane radial coordinates are supported. Currently, there is no way to specify an image's coordinate system explicitly; Craig has worked around the problem by naming the coordinates themselves. For example, a map of the solar magnetic field in heliographic coordinates would have CTYPE1="degrees-longitude" and CTYPE2="degrees-latitude" instead of merely "degrees". Craig has made a start at implementing a general coordinate-system naming regimen, with the V4 package of IDL routines; if you have a suggestion for how to incorporate coordinate system naming into FITS images, please let him know.

TIMING

Overview

It's important to specify the time at which an observation occured. Unfortunately, the standard ways to do this are complex and have been rendered more complex by some of the historical accidents of FITS interpretation with IDL in the solar community. In addition, the time given in the header is not well defined by either the FITS standard or the SOHO documentation.

Keyword ambiguity

In particular, the FITS standard defines the keyword DATE-OBS to specify the date on which an observation took place; but nothing more precise. Some teams (eg MDI/SOI data specification) use TIME-OBS to specify when an observation took place. The SOHO standard (Howard & Thompson) uses DATE_OBS to store all the time and date information.

There's an additional complication: Because of limitations of the IDL language, there has been an ambiguity between dashes and underscores in the structure returned by mreadfits.pro. So many FITS files exist which have DATE_OBS and DATE-OBS confused. (Newer versions of mreadfits.pro do not generate the same ambiguity.) So timestamp interpretation is not simple.

Reference Time

There is a problem with the definition of the timestamp tags -- neither the FITS standard nor the SOHO definitions specify the exact time to be given in the DATE_OBS or TIME-OBS tags; the observation is treated as instantaneous. This treatment is not entirely valid in solar physics, as we keep finding temporal variations in the Sun, on the shortest measureable time scales.

The de facto standard for DATE_OBS appears to be to use the start time of the observation. (Some instruments, eg MDI, use the middle of the observation, as that represents a better "mean time" for the observation as a whole; caveat emptor!) For timing critical investigations, where the mean time of the observation is needed, people can use DATE_OBS +EXPTIME/2 as the time of the observations.

The ztools use DATE_OBS for the time of an observation. If DATE_OBS is not found, then many routines try to use DATE-OBS and TIME-OBS.

Time Zones

FITS Standard maintained by the NASA/GSFC Fits Support Office. They are largely compatible with the tags used by the SOHO spacecraft instruments.

FITS Standards Documents

FITS Standard

The "Official" standard is maintained by the NASA/GSFCFits Support Office.

Howard & Thompson

A document dated 19-March-1997 that contains a proposal for SOHO FITS keyword usage.

SOI Keywords

A list of the FITS keywords used by the SOI/MDI SOHO instrument, and brief definitions for each.

DMZMAP

PRELIMINARY