This attribute specifies how many digits of precision are required by default when a co-ordinate value is formatted for a Frame  axis (e.g. when producing annotated plot axes). Its value may be set either for a Frame as a whole, or (by subscripting the attribute name with the number of an axis) for each axis individually. Any value set for an individual axis will override the value for the Frame as a whole.

Note that the Digits value acts only as a means of determining a default value for the Format  attribute. Its effects are overridden if a Format string is set explicitly for an axis.

The default Digits value for a Frame is 7. If a value fewer than 1 is supplied, then 1 is used instead.

If the Frame is actually a SkyFrame  (e.g.  describes celestial longitude and latitude), then the Digits value specifies the total number of digits in the formatted axis value–-that is, the sum of the hours (or degrees), minutes and seconds digits.

wcsattrib m51 set digits 4

This sets the Digits attribute to the value 4 for all axes in the current Frame of the NDF m51. This results in axis values being formatted with four digits of precision when they are displayed by any application, so long as no value has been set for the Format attribute.

wcsattrib m51 set digits(1) 4

This is like the previous example, except that the Digits value is only set for the first axis in the current Frame of the NDF.

This attribute contains a string that identifies the physical domain of the co-ordinate system that a Frame  describes.

The Domain attribute also controls how Frames align with each other. If the Domain value in a Frame is set, then only Frames with the same Domain value can be aligned with it.

Some Frames are given standard Domain values when they are created (e.g. GRID, FRACTION, PIXEL, AXIS, SKY, SPECTRUM, CURPIC, NDC, BASEPIC, GRAPHICS). Frames created by the user (for instance, using WCSADD) can have any Domain value, but the standard Domain names should be avoided unless the standard meanings are appropriate for the Frame being created.

wcsattrib m51 set domain oldpixel

If the current co-ordinate Frame in the NDF m51 is the PIXEL Frame, then this command takes a ‘snap-shot’ of the PIXEL Frame and stores it as a new Frame with Domain OLDPIXEL in the WCS component. Subsequent changes to the PIXEL Frame (for instance, produced by applications that rotate, or move the contents of the NDF) will not effect the OLDPIXEL Frame, which will thus provide a ‘frozen’ record of the original PIXEL Frame.

• All Domain values are converted to uppercase and white space is removed before use.

This attribute specifies the central position of interest in a dual-sideband spectrum. Its sole use is to determine the local oscillator frequency (the frequency which marks the boundary between the lower and upper sidebands). See the description of the IF (intermediate frequency) attribute for details of how the local oscillator frequency is calculated. The sideband containing this central position is referred to as the "observed" sideband, and the other sideband as the "image" sideband.

The value is accessed as a position in the spectral system specified by the System  attribute, but is stored internally as topocentric frequency. Thus, if the System attribute of the DSBSpecFrame is set to "VRAD", the Unit  attribute set to "m/s" and the StdOfRest  attribute set to "LSRK", then values for the DSBCentre attribute should be supplied as radio velocity in units of "m/s" relative to the kinematic LSR (alternative units may be used by appending a suitable units string to the end of the value). This value is then converted to topocentric frequency and stored. If (say) the Unit attribute is subsequently changed to "km/s" before retrieving the current value of the DSBCentre attribute, the stored topocentric frequency will be converted back to LSRK radio velocity, this time in units of "km/s", before being returned.

The default value for this attribute is 30 GHz.

• The attributes which define the transformation to or from topocentric frequency should be assigned their correct values before accessing this attribute. These potentially include System, Unit, StdOfRest, ObsLon, ObsLat, ??, Epoch, RefRA, RefDec, and RestFreq.

This attribute is used to qualify the co-ordinate system described by a Frame, by giving the moment in time when the co-ordinates are known to be correct. Often, this will be the date of observation.

The Epoch value is important in cases where the co-ordinate system changes with time. For instance, when considering celestial co-ordinate systems, possible reasons for change include: (i) changing aberration of light caused by the observer’s velocity (e.g. due to the Earth’s motion around the Sun), (ii) changing gravitational deflection by the Sun due to changes in the observer’s position with time, (iii) fictitious motion due to rotation of non-inertial co-ordinate systems (e.g. the old FK4 system), and (iv) proper motion of the source itself (although this last effect is not handled by the SkyFrame  class because it affects individual sources rather than the co-ordinate system as a whole).

The Epoch attribute is stored as a Modified Julian Date, and is not usually changed.

• Care must be taken to distinguish the Epoch value, which relates to motion (or apparent motion) of the source, from the superficially similar Equinox  value. The latter is used to qualify a co-ordinate system which is itself in motion in a (notionally) predictable way as a result of being referred to a slowly moving reference plane (e.g. the equator).

• See the description of the System  attribute for details of which qualifying attributes apply to each celestial co-ordinate system.

The formats accepted when setting an Epoch  value are listed below. They are all case-insensitive and are generally tolerant of extra white space and alternative field delimiters.

• Besselian Epoch: Expressed in decimal years, with or without decimal places ("B1950" or "B1976.13" for example).

• Julian Epoch: Expressed in decimal years, with or without decimal places ("J2000" or "J2100.9" for example).

• Year: Decimal years, with or without decimal places ("1996.8" for example). Such values are interpreted as a Besselian epoch (see above) if less than 1984.0 and as a Julian epoch otherwise.

• Julian Date: With or without decimal places ("JD 2454321.9" for example).

• Modified Julian Date: With or without decimal places ("MJD 54321.4" for example).

• Gregorian Calendar Date: With the month expressed either as an integer or a 3-character abbreviation, and with optional decimal places to represent a fraction of a day ("1996-10-2" or "1996-Oct-2.6" for example). If no fractional part of a day is given, the time refers to the start of the day (zero hours).

• Gregorian Date and Time: Any calendar date (as above) but with a fraction of a day expressed as hours, minutes and seconds ("1996-Oct-2 12:13:56.985" for example).

When enquiring Epoch values, the format used is the “Year” format described under “Input Formats”. This is a value in decimal years, which will be a Besselian epoch if less than 1984.0, and a Julian epoch otherwise.

This attribute is used to qualify those celestial co-ordinate systems described by a SkyFrame  that are notionally based on the ecliptic (the plane of the Earth’s orbit around the Sun) and/or the Earth’s equator.

Both of these planes are in motion and their positions are difficult to specify precisely. In practice, therefore, a model ecliptic and/or equator are used instead. These, together with the point on the sky that defines the co-ordinate origin (the intersection of the two planes termed the ‘mean equinox’) move with time according to some models that remove the more-rapid fluctuations. The SkyFrame class supports both the old FK4 and the current FK5 models.

The position of a fixed source expressed in any of these co-ordinate systems will appear to change with time due to movement of the co-ordinate system itself (rather than motion of the source). Such co-ordinate systems must therefore be qualified by a moment in time (the ‘epoch of the mean equinox’ or ‘equinox’ for short) which allows the position of the model co-ordinate system on the sky to be determined. This is the rôle of the Equinox attribute.

The Equinox attribute is stored as a Modified Julian Date, but when setting or getting its value you may use the same formats as for the Epoch  attribute (q.v.).

• Care must be taken to distinguish the Equinox value, which relates to the definition of a time-dependent co-ordinate system (based on solar-system reference planes which are in motion), from the superficially similar Epoch value. The latter is used to qualify co-ordinate systems where the positions of sources change with time (or appear to do so) for a variety of other reasons, such as aberration of light caused by the observer’s motion, etc.

• See the description of the System  attribute for details of which qualifying attributes apply to each celestial co-ordinate system.

This attribute specifies the format to be used when displaying co-ordinate values associated with a particular Frame  axis (i.e. to convert values from binary to character form).

If no Format value is set for a Frame axis, a default value is supplied instead. This is based on the value of the Digits, or Digits(axis) attribute and is chosen so that it displays the requested number of digits of precision.

The interpretation of this string depends on whether or not the Frame is a SkyFrame. If it is not, the string is interpreted as a format-specification string to be passed to the C “printf” function (e.g. "%1.7G") in order to format a single co-ordinate value (supplied as a double-precision number).

For SkyFrames, the syntax and default value of the Format string is re-defined to allow the formatting of sexagesimal values as appropriate for the particular celestial co-ordinate system being represented. The syntax of SkyFrame Format strings is described (below) in the “SkyFrame Formats”  section.

The Format string supplied for a SkyFrame  should contain zero or more of the following characters. These may occur in any order, but the following is recommended for clarity.

• "$+$": Indicates that a plus sign should be prefixed to positive values. By default, no plus sign is used.

• "z": Indicates that leading zeros should be prefixed to the value so that the first field is of constant width, as would be required in a fixed-width table (leading zeros are always prefixed to any fields that follow). By default, no leading zeros are added.

• "i": Use the standard ISO field separator (a colon) between fields. This is the default behaviour.

• "b": Use a blank to separate fields.

• "l": Use a letter ("h"/"d", "m" or "s" as appropriate) to separate fields.

• "g": This is the same as "l", except that the separator characters are displayed as small superscripts when drawn on a graphical device.

• "d": Include a degrees field. Expressing the angle purely in degrees is also the default if none of "h", "m", "s" or "t" are given.

• "h": Express the angle as a time and include an hours field (where 24 hours correspond to 360 degrees). Expressing the angle purely in hours is also the default if "t" is given without either "m" or "s".

• "m": Include a minutes field. By default this is not included.

• "s": Include a seconds field. By default this is not included. This request is ignored if "d" or "h" is given, unless a minutes field is also included.

• "t": Express the angle as a time (where 24 hours correspond to 360 degrees). This option is ignored if either "d" or "h" is given and is intended for use where the value is to be expressed purely in minutes and/or seconds of time (with no hours field). If "t" is given without "d", "h", "m" or "s" being present, then it is equivalent to "h".

• ".": Indicates that decimal places are to be given for the final field in the formatted string (whichever field this is). The "." should be followed immediately by an unsigned integer which gives the number of decimal places required. By default, no decimal places are given.

All of the above format specifiers are case-insensitive. If several characters make conflicting requests (e.g. if both "i" and "b" appear), then the character occurring last takes precedence, except that "d" and "h" always override "t".

wcsattrib my_data set format(1) %10.5G

This sets the Format attribute for Axis 1 in the current co-ordinate Frame in the NDF called my_data, so that axis values are formatted as floating-point values using a minimum field width of ten characters, and displaying five significant figures. An exponent is used if necessary.

wcsattrib ngc5128 set format(2) bdms.2

This sets the Format attribute for Axis 2 in the current co-ordinate Frame in the NDF called ngc5128, so that axis values are formatted as separate degrees, minutes and seconds field, separated by blanks. The seconds field has two decimal places. This assumes the current co-ordinate Frame in the NDF is a celestial co-ordinate Frame (i.e. a SkyFrame).

• When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies.

This attribute specifies the (topocentric) intermediate frequency in a dual-sideband spectrum. Its sole use is to determine the local oscillator (LO) frequency (the frequency which marks the boundary between the lower and upper sidebands). The LO frequency is equal to the sum of the centre frequency and the intermediate frequency. Here, the "centre frequency" is the topocentric frequency in Hz corresponding to the current value of the DSBCentre  attribute. The value of the IF attribute may be positive or negative: a positive value results in the LO frequency being above the central frequency, whilst a negative aattIF value results in the LO frequency being below the central frequency. The sign of the IF attribute value determines the default value for the SideBand  attribute.

When setting a new value for this attribute, the units in which the frequency value is supplied may be indicated by appending a suitable string to the end of the formatted value. If the units are not specified, then the supplied value is assumed to be in units of GHz. For instance, the following strings all result in an IF of 4 GHz being used: "4.0", "4.0 GHz", "4.0E9 Hz", etc.

When getting the value of this attribute, the returned value is always in units of GHz. The default value for this attribute is 4 GHz.

This is a read-only attribute of a dual-sideband spectrum that gives the frequency corresponding to the rest frequency, but in the opposite sideband.

The value is calculated by first transforming the rest frequency (given by the RestFreq  attribute) from the standard of rest of the source (given by the SourceVel and SourceVRF  attributes) to the standard of rest of the observer (i.e. the topocentric standard of rest). The resulting topocentric frequency is assumed to be in the same sideband as the value given for the DSBCentre  attribute (the "observed" sideband), and is transformed to the other sideband (the "image" sideband). The new frequency is converted back to the standard of rest of the source, and the resulting value is returned as the attribute value, in units of GHz.

This attribute specifies a label to be attached to each axis of a Frame when it is represented (e.g.) in graphical output.

If a Label value has not been set for a Frame axis, then a suitable default is supplied, depending on whether or not the Frame is a SkyFrame.

The default for simple Frames is the string "Axis <n>", where <$$n> is 1, 2, etc. for each successive axis.

The default labels for specialised Frames (SkyFrames, SpecFrames, etc.) depend on the particular co-ordinate system represented by the Frame (e.g. "Right ascension", "Galactic latitude", "Frequency", "Wavelength in air", etc.).

wcsattrib my_data set label(2) "IRAS data (marked in white)"

This sets the Label for Axis 2 in the current Frame in the NDF called my_data, to the string "IRAS data (marked in white)".

• Axis labels are intended purely for interpretation by human readers and not by software.

• When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies.

This specifies the offset from UTC to Local Time, in hours, for a TimeFrame. Fractional hours can be supplied. It is positive for time zones east of Greenwich. AST uses the figure as given, without making any attempt to correct for daylight saving. The default value is zero.

This is a read-only attribute giving the number of axes in a Frame (i.e. the number of dimensions of the co-ordinate space that the Frame describes). This value is determined when the Frame is created.

wcsattrib my_data get naxes

This displays the number of axes in the current Frame of the NDF called my_data.

This attribute specifies the geodetic latitude of the observer, in degrees. Together with the ObsLon, Epoch, RefRA, and RefDec  attributes, it defines the Doppler shift introduced by the observers diurnal motion around the Earth’s axis, which is needed when converting SpecFrames  to or from the topocentric standard of rest. The maximum velocity error, which can be caused by an incorrect value, is 0.5 km/s. The default value for the attribute is zero.

The value is stored internally in radians, but is converted to and from a degrees string for access. Some example input formats are: "22:19:23.2", "22 19 23.2", "22:19.387", "22.32311", "N22.32311", "-45.6", "S45.6". As indicated, the sign of the latitude can optionally be indicated using characters "N" and "S" in place of the usual "$+$" and "-". When converting the stored value to a string, the format "[s]dd:mm:ss.s" is used, when "[s]" is "N" or "S".

This attribute specifies the geodetic (or equivalently, geocentric) longitude of the observer, in degrees, measured positive eastwards. See also attribute ObsLat. The default value is zero.

The value is stored internally in radians, but is converted to and from a degrees string for access. Some example input formats are: "155:19:23.2", "155 19 23.2", "155:19.387", "155.32311", "E155.32311", "-204.67689", "W204.67689". As indicated, the sign of the longitude can optionally be indicated using characters "E" and "W" in place of the usual "$+$" and "-". When converting the stored value to a string, the format "[s]ddd:mm:ss.s" is used, when "[s]" is "E" or "W" and the numerical value is chosen to be less than 180 degrees.

This attribute specifies the FK5 J2000.0 declination of a reference point on the sky. See the description of attribute RefRA  for details. This attribute has a default value of zero.

This attribute, together with the RefDec  attribute, specifies the FK5 J2000.0 co-ordinates of a reference point on the sky. For one-dimensional spectra, this should normally be the position of the source. For spectral data with spatial coverage (spectral cubes, etc.), this should be close to centre of the spatial coverage. It is used to define the correction for Doppler shift to be applied when converting between different standards of rest.

The RefRA and RefDec attributes are stored internally in radians, but are converted to and from a string for access. The format "hh:mm:ss.ss" is used for RefRA, and "dd:mm:ss.s" is used for RefDec.

RefRA has a default value of zero.

This attribute specifies the frequency corresponding to zero velocity. It is used when converting between between velocity-based spectral co-ordinate systems and and other co-ordinate systems (such as frequency, wavelength, energy, etc.). The default value is 1.0E5 GHz.

When setting a new value for this attribute, the new value can be supplied either directly as a frequency, or indirectly as a wavelength or energy, in which case the supplied value is converted to a frequency before being stored. The nature of the supplied value is indicated by appending text to the end of the numerical value indicating the units in which the value is supplied. If the units are not specified, then the supplied value is assumed to be a frequency in units of GHz. If the supplied unit is a unit of frequency, the supplied value is assumed to be a frequency in the given units. If the supplied unit is a unit of length, the supplied value is assumed to be a (vacuum) wavelength. If the supplied unit is a unit of energy, the supplied value is assumed to be an energy. For instance, the following strings all result in a rest frequency of around 1.4E14 Hz being used: "1.4E5", "1.4E14 Hz", "1.4E14 s$\ast$$\ast$-1", "1.4E5 GHz", "2.14E-6 m", "21400 Angstrom", "9.28E-20 J", "9.28E-13 erg", "0.58 eV", etc.

When getting the value of this attribute, the returned value is always a frequency in units of GHz.

This attribute indicates whether a dual-sideband spectrum currently represents its lower or upper sideband, or an offset from the local oscillator frequency. When querying the current value, the returned string is always one of "usb" (for upper sideband), "lsb" (for lower sideband), or "lo" (for offset from the local oscillator frequency). When setting a new value, any of the strings "lsb", "usb", "observed", "image" or "lo" may be supplied (case insensitive). The "observed" sideband is which ever sideband (upper or lower) contains the central spectral position given by attribute DSBCentre, and the "image" sideband is the other sideband. It is the sign of the IF  attribute which determines if the observed sideband is the upper or lower sideband. The default value for SideBand is the observed sideband.

This attribute (together with SourceVRF, RefRA, and RefDec) defines the ‘Source’ standard of rest (see attribute StdOfRest). This is a rest frame that is moving towards the position given by RefRA and RefDec at a velocity given by SourceVel (in km/s). When setting a value for SourceVel  using WCSATTRIB, the velocity should be supplied in the rest frame specified by the SourceVRF attribute. Likewise, when getting the value of SourceVel, it will be returned in the rest frame specified by the SourceVRF attribute.

The default value is zero.

This attribute identifies the rest frame in which the source velocity is stored (the source velocity is accessed using attribute SourceVel). When setting a new value for the SourceVel attribute, the source velocity should be supplied in the rest frame indicated by this attribute. Likewise, when getting the value of the SourceVel attribute, the velocity will be returned in this rest frame.

If the value of SourceVRF is changed, the value stored for SourceVel will be converted from the old to the new rest frame.

The values that can be supplied are the same as for the StdOfRest  attribute (except that SourceVRF cannot be set to "Source"). The default value is "Helio".

This attribute identifies the standard of rest to which the spectral axis values of a SpecFrame  refer, and may take any of the values listed in the “Standards of Rest”  section (below).

The default StdOfRest value is "Helio".

The SpecFrame  class supports the following StdOfRest values (all are case-insensitive).

• "Topocentric", "Topocent" or "Topo": The observers rest-frame (assumed to be on the surface of the earth). Spectra recorded in this standard of rest suffer a Doppler shift which varies over the course of a day because of the rotation of the observer around the axis of the earth. This standard of rest must be qualified using the ObsLat, ObsLon, Epoch, RefRA, and RefDec  attributes.

• "Geocentric", "Geocentr" or "Geo": The rest-frame of the earth centre. Spectra recorded in this standard of rest suffer a Doppler shift which varies over the course of a year because of the rotation of the earth around the Sun. This standard of rest must be qualified using the Epoch, RefRA, and RefDec attributes.

• "Barycentric", "Barycent" or "Bary": The rest-frame of the solar-system barycentre. Spectra recorded in this standard of rest suffer a Doppler shift which depends both on the velocity of the Sun through the Local Standard of Rest, and on the movement of the planets through the solar system. This standard of rest must be qualified using the Epoch, RefRA, and RefDec attributes.

• "Heliocentric", "Heliocen" or "Helio": The rest-frame of the Sun. Spectra recorded in this standard of rest suffer a Doppler shift which depends on the velocity of the Sun through the Local Standard of Rest. This standard of rest must be qualified using the RefRA and RefDec attributes.

• "LSR", "LSRK": The rest-frame of the kinematical Local Standard of Rest. Spectra recorded in this standard of rest suffer a Doppler shift which depends on the velocity of the kinematical Local Standard of Rest through the galaxy. This standard of rest must be qualified using the RefRA and RefDec attributes.

• "LSRD": The rest-frame of the dynamical Local Standard of Rest. Spectra recorded in this standard of rest suffer a Doppler shift which depends on the velocity of the dynamical Local Standard of Rest through the galaxy. This standard of rest must be qualified using the RefRA and RefDec attributes.

• "Galactic", "Galactoc" or "Gal": The rest-frame of the galactic centre. Spectra recorded in this standard of rest suffer a Doppler shift which depends on the velocity of the galactic centre through the local group. This standard of rest must be qualified using the RefRA and RefDec attributes.

• "Local_group", "Localgrp" or "LG": The rest-frame of the local group. This standard of rest must be qualified using the RefRA and RefDec attributes.

• "Source", or "src": The rest-frame of the source. This standard of rest must be qualified using the RefRA, RefDec, and SourceVel  attributes.

Where more than one alternative System  value is shown above, the first of these will be returned when an enquiry is made.

This attribute specifies a short-form symbol to be used to represent co-ordinate values for a particular axis of a Frame. This might be used (e.g.) in algebraic expressions where a full description of the axis would be inappropriate. Examples include "RA" and "Dec" (for right ascension and declination).

If a Symbol value has not been set for a Frame axis, then a suitable default is supplied.

The default Symbol value supplied for simple Frames is the string “$<$Domain$>$$<$n$>$”, where $<$n$>$ is 1, 2, etc. for successive axes, and $<$Domain$>$ is the value of the Frame’s Domain  attribute (truncated if necessary so that the final string does not exceed 15 characters). If no Domain value has been set, "x" is used as the $<$Domain$>$ value in constructing this default string.

Specialised Frames (SkyFrame, SpecFrame,etc.) re-define the default Symbol value to be appropriate for the particular co-ordinate system being represented.

wcsattrib my_data set symbol(2) AR

This sets the Symbol for Axis 2 in the current Frame in the NDF called my_data, to the string "AR".

• When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies.

In general it is possible for positions within a given physical domain to be described using one of several different co-ordinate systems. For instance, the SkyFrame  class can use galactic co-ordinates, equatorial co-ordinates etc. to describe positions on the sky. As another example, the SpecFrame  class can use frequency, wavelength, velocity etc. to describe a position within an electromagnetic spectrum. The System attribute identifies the particular co-ordinate system represented by a Frame. Each class of Frame defines a set of acceptable values for this attribute, as listed below (all are case insensitive). Where more than one alternative System  value is shown, the first of will be returned when an enquiry is made.

Frame

SkyFrame

SpecFrame

TimeFrame

This specifies the origin from which all time values are measured within a TimeFrame. The default value (zero) results in the TimeFrame describing absolute time values in the system given by the System  attribute (e.g. MJD, Julian epoch, etc). If a TimeFrame is to be used to describe elapsed time since some origin, the TimeOrigin attribute should be set to hold the required origin value. The TimeOrigin value stored inside the TimeFrame structure is modified whenever TimeFrame attribute values are changed so that it refers to the original moment in time.

The formats accepted when setting a TimeOrigin value are listed below. They are all case-insensitive and are generally tolerant of extra white space and alternative field delimiters:

• Besselian Epoch: Expressed in decimal years, with or without decimal places ("B1950" or "B1976.13" for example).

• Julian Epoch: Expressed in decimal years, with or without decimal places ("J2000" or "J2100.9" for example).

• Units: An unqualified decimal value is interpreted as a value in the system specified by the TimeFrame’s System attribute, in the units given by the TimeFrame’s Unit  attribute. Alternatively, an appropriate unit string can be appended to the end of the floating point value ("123.4 d" for example), in which case the supplied value is scaled into the units specified by the Unit attribute.

• Julian Date: With or without decimal places ("JD 2454321.9" for example).

• Modified Julian Date: With or without decimal places ("MJD 54321.4" for example).

• Gregorian Calendar Date: With the month expressed either as an integer or a three-character abbreviation, and with optional decimal places to represent a fraction of a day ("1996-10-2" or "1996-Oct-2.6" for example). If no fractional part of a day is given, the time refers to the start of the day (zero hours).

• Gregorian Date and Time: Any calendar date (as above) but with a fraction of a day expressed as hours, minutes and seconds ("1996-Oct-2 12:13:56.985" for example). The date and time can be separated by a space or by a "T" (as used by ISO8601 format).

When enquiring TimeOrigin values, the returned formatted floating point value represents a value in the TimeFrame’s System, in the unit specified by the TimeFrame’s Unit attribute.

This attribute identifies the time scale to which the time axis values of a TimeFrame refer, and may take any of the values listed in the "Time Scales" section (below).

The default TimeScale value depends on the current System value; if the current TimeFrame system is "Besselian epoch" the default is "TT", otherwise it is "TAI". Note, if the System attribute is set so that the TimeFrame represents Besselian Epoch, then an error will be reported if an attempt is made to set the TimeScale to anything other than TT.

Note, the supported time scales fall into two groups. The first group containing UT1, GMST, LAST and LMST define time in terms of the orientation of the earth. The second group (containing all the remaining time scales) define time in terms of an atomic process. Since the rate of rotation of the earth varies in an unpredictable way, conversion between two timescales in different groups relies on a value being supplied for the Dut1 attribute. This attribute specifies the difference between the UT1 and UTC time scales, in seconds, and defaults to zero. See the documentation for the Dut1 attribute in SUN/210 for further details.

The TimeFrame class supports the following TimeScale values (all are case-insensitive):

• "TAI" – International Atomic Time

• "UTC" – Coordinated Universal Time

• "UT1" – Universal Time

• "GMST" – Greenwich Mean Sidereal Time

• "LAST" – Local Apparent Sidereal Time

• "LMST" – Local Mean Sidereal Time

• "TT" – Terrestrial Time

• "TDB" – Barycentric Dynamical Time

• "TCB" – Barycentric Coordinate Time

• "TCG" – Geocentric Coordinate Time

• "LT" – Local Time (the offset from UTC is given by attribute LTOffset)

An very informative description of these and other time scales is available at
http://www.ucolick.org/$\sim$sla/leapsecs/timescales.htm.

UTC should ideally be expressed using separate hours, minutes and seconds fields (or at least in seconds for a given date) if leap seconds are to be taken into account. Since the TimeFrame class represents each moment in time using a single floating point number (the axis value) there will be an ambiguity during a leap second. Thus an error of up to 1 second can result when using AST to convert a UTC time to another time scale if the time occurs within a leap second. Leap seconds occur at most twice a year, and are introduced to take account of variation in the rotation of the earth. The most recent leap second occurred on 1st January 1999. Although in the vast majority of cases leap second ambiguities won’t matter, there are potential problems in on-line data acquisition systems and in critical applications involving taking the difference between two times.

This attribute holds a string that is used as a title in (e.g.) graphical output to describe the co-ordinate system that a Frame represents. Examples might be "Detector Co-ordinates" or "Galactic Co-ordinates".

If a Title value has not been set for a Frame, then a suitable default is supplied.

The default supplied by the Frame class is "<n>-d co-ordinate system", where <n> is the number of Frame axes (Naxes  attribute).

Specialised Frames (SkyFrame, SpecFrame, etc.) re-define the default Title value to be appropriate to the particular co-ordinate system being represented.

wcsattrib my_data set Title "My own data"

This sets the Title for the current Frame in the NDF called my_data, to the string "My own data".

• A Frame’s Title is intended purely for interpretation by human readers and not by software.

This attribute contains a textual representation of the physical units used to represent co-ordinate values on a particular axis of a Frame.

Specialised Frames (SkyFrame, SpecFrame, etc.) re-define the default Unit values to be appropriate to the particular co-ordinate system being represented.

For most classes, the Unit attribute is a purely descriptive comment intended for human readers and makes no difference to the operation of the software. However, there are some classes that have active Unit attributes. Changing the Unit attribute for such classes will result in the Mappings  within the WCS FrameSet  being modified in order to reflect the change in units. By default, only SpecFrames have an active Unit attribute.

In general, the syntax of the Unit attribute should follow the recommendations made in the FITS standard (see the paper “Representation of world coordinates in FITS” by Greisen & Calabretta (available at http://www.cv.nrao.edu/fits/documents/wcs/wcs.html).

• When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies (unless the Frame has only one axis).