SSW Keyword/Tag Definitions

Last Revision: 5-July-2005

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 ( and 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 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 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:

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 Tags

Details about units and coordinate systems

Tag Status Source Definition
FITS std The width and height of the image, respectively, in pixels.
FITS std The reference pixel coordinates. For example, if alignment is with respect to the lower left corner of the image, CRPIX1 and CRPIX2 should both be set to 1. If alignment is with respect to the center of the image, then CRPIX1 should be set to (NAXIS1+1)/2 and CRPIX2 should be set to (NAXIS2+1)/2

May be zero
FITS std The reference data coordinates corresponding to CRPIX1 and CRPIX2. For example, if the pixel coordinates specify the origin, then set CRVAL1 and CRVAL2 to zero.

FITS std The width and heighth of a pixel in data units. For square pixels, CDELT1 = CDELT2

FITS std
Definition of the data units - ie., the interpretation of CDELT1 and CDELT2. For example, "SOLAR_X", "SOLAR_Y".

REQ (if non-zero, and PCi_j not used)
FITS std Rotation angle of the image about the axis perpendicular to the plane of the image, through the point CRPIX1,CRPIX2. The rotation is specified in degrees CCW. If these fields are not specified, they are assumed to be zero. Set both CROTA1 and CROTA2 to the same value. The sense of the rotation is such that the coordinates x and y are calculated via
a = CROTA2
x = CRVAL1 + CDELT1*cos(a)*(i-CRPIX1) - CDELT2*sin(a)*(j-CRPIX2)
y = CRVAL2 + CDELT1*sin(a)*(i-CRPIX1) + CDELT2*cos(a)*(j-CRPIX2)
CUNIT1, CUNIT2 Suggested World Coordinate System Units along the data axes, e.g. "arcsec", "deg". See Greisen and Calabretta below for more information.
PC1_1, PC1_2, PC2_1, PC2_2 Suggested (if CROTAi not used) World Coordinate System Transformation matrix, used in place of CROTA1,CROTA2. See Greisen and Calabretta below for more information. The PCi_j and CROTAi keywords cannot be used simultaneously.
XCEN Suggested De Facto Solar Convention East-West FOV center of image relative to sun center in CDELT1 units, positive West.
XCEN is related to the above FITS keywords by:
XCEN = CRVAL1 + CDELT1 * [(NAXIS1+1)/2 - CRPIX1 ]
YCEN Suggested De Facto Solar Convention North-South FOV center of image relative to sun center in CDELT2 units, positive North.
YCEN is related to the above FITS keywords by:
YCEN = CRVAL2 + CDELT2 * [(NAXIS2+1)/2 - CRPIX2 ]

Timing tags

Tag Status Source Definition
REQ (*)
FITS std The time and date of the start of the observation, in UT at the observatory or spacecraft, in CCSDS ASCII Calendar Segmented (ISO 8601). Example: 1988-01-18T17:20:43.123
At least one of DATE-OBS or DATE_OBS is required. (When both are in the header, to access this tag in an IDL structure, remember to use DATE_d$OBS.)
REQ (*)
W.Thompson, R.Howard The time and date of the start of the observation, in Earth-adjusted UT in CCSDS ASCII Calendar Segmented (ISO 8601). Example: 1988-01-18T17:20:43.123
FITS Std The duration of the observation, in seconds (floating point). Permits calculation the "mean time" of an observation with the agreed standard for DATE_OBS.
Yohkoh / SOHO Milliseconds of day (long integer)
SOHO Modified Julian Day (long integer). Used in conjunction with TIME to provide efficient binary time representation.
SMM / Yohkoh Integer number of days since 1-1-79 (short integer). Used in conjunction with TIME to provide efficient binary time representation.
Common usage The time at which the start of the observation occurred, UT. This tag is not explicitly defined in the FITS standard, but has been adopted into common usage. (To access this tag in an IDL structure, remember to use TIME_d$OBS.)

Auxiliary tags

The following auxiliary tags are suggested for bookeeping and may permit cross referencing ephemeris and other SSW database information.
Tag Status Source Definition
W.Thompson, R.Howard
The name of the telescope, observatory, or mission (string) .
For example,"Yohkoh", "SOHO", "GOES-M", "TRACE". Important for space based observatories which do not have an earth-like view (L1 for example) since transformations will depend on satellite and 'apparent' solar ephemeris.
W.Thompson, R.Howard
The name of the specific instrument (string).
For example, "SXT", "EIT", "SXI-M", "TRACE"
W.Thompson, R.Howard Wavelength of observation. Some SSW instruments have chosen to use a string descriptor, particularily for broadband observations

A note about time conversions...

Although DATE-OBS and/or DATE_OBS is specified as a required item, it is the definition which is important. The function (by R.A.Schwartz et al), which is included in the SSW generic library, can produce this format from all known time standards used in the solar physics community. The function anytim is the suggested single point time conversion routine for SolarSoft applications. The function is intended to be Y2K compliant as it properly handles all conversions within the range January 1, 1950 through December 31, 2049. There are no time range restrictions for either of the binary formats ( TIME and DAY or TIME and MJD) or for string formats which use the fully qualified (4 digit) year, including the formal definition of DATE-OBS above. Inclusion of one of the binary formats is suggested for efficient downline processing, although the time string to binary conversion using anytim is trivial.


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 universally accepted 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". 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.



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.

Reference Time

The de facto (and now formal) standard for DATE-OBS is 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.

Time Zones

As instruments get spread around the solar system, speed-of-light effects become important to observation timing. The SOHO standard for the time in the DATE_OBS stamp is "Earth-adjusted UT" -- that is, the UT time at Earth when an observer would have seen the same feature as is pictured.

One should be aware that the solar radius is 2.3 light seconds. This leads to some small temporal effects for spacecraft (such as STEREO) that will subtend significant elongation angles. For low-altitude coronal studies that require less precision than, say 10 seconds this should not be a problem. However, angle-induced timing errors of up to 1 minute will be seen in wide-field spectrographs in other parts of the solar system. If STEREO does indeed include LASCO-type instruments, we will probably need to deal with this.

On the other hand, the FITS standard keyword DATE-OBS is defined to be the time at the observatory, i.e. unadjusted for speed-of-light effects. This puts the onus on the analysis software, but avoids such viewpoint ambiguities. The expectation is that the SOHO DATE_OBS keyword will be superceded by the new standard for DATE-OBS.


FITS Standards Documents

FITS Standard
The official standard is maintained by the NASA/GSFC Fits Support Office.
HEASARC Conventions
FITS information from the NASA/GSFC High Energy Astrophysics Science Archive Research Center
FITS archive at NRAO
FITS information from the National Radio Astronomical Observatory
World Coordinate System
Information about the FITS World Coordinate System is available from Mark Calabretta's and Eric Greisen's home pages.
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.