Getting Started Documentation Glish Learn More Programming Contact Us
Version 1.9 Build 1556
News FAQ
Search Home

next up previous contents
Up: NOTE 236 - DISH: User's Manual Previous: sditerator



SDFITS is a convention for the use FITS binary tables to store single dish data. This appendix will eventually be turned into a full fledged note. At the present time, it is simply a summary of the various rules regarding the interpretation of keywords and columns which, taken together, constute the Single Dish FITS convention.

A FITS binary table is also a SDFITS binary table if it follows these rules.

EXTNAME keyword

The EXTNAME keyword must have a value of ``SINGLE DISH''. A table having this value for EXTNAME is assumed to be fully compliant with this convention.

Virtual columns

Most keywords should be thought of as a column of the same name which has a constant value for all rows in the table.

There are a few exceptions to this rule. FITS keywords which are required to describe the structure of the table are not virtual columns. These include NAXIS, NAXIS1, NAXIS2, BITPIX, XTENSION,
[0]EXTNAME, EXTVER, EXTLEVEL, PCOUNT, GOUNT, TFIELDS, TFORM, TTYPE, TUNIT, TNULL, and TDISP. The TDIMnnn keyword is the only table description keyword which may be a column as described elsewhere in this appendix.

DATAMAX and DATAMIN are special keywords. When used as keywords it is most likely that the writer of that table meant them to reflect the range of all of the data found in that table and not to be used on a row-by-row sense. If the writer feels a need to supply row-by-row values for these two keywords, they should explicitly make them true columns.

When creating a table, a column may be made virtual if it's value can be represented as a single keyword (if it is constant over all rows) and if that constant value is NOT an IEEE special value (it has a standard ASCII representation) and the name of the column is 8 character or less.

If a column exists which has the same name as a keyword, the column values should be assumed to take precedence (writers should attempt to ensure that this confusing situation does not happen).

The DATA column and the DATA axes

The DATA column containsthe primary data array. It is required. Each row of this column contains an n-dimensional array of data. The axis descriptions are handled in a similar way to FITS images.

The TDIMnnn convention
This is how the shape of the DATA array should be specified.
TDIMnnn = '(n1,n2,n3,n4...)'
This convention may be used with other columns which do NOT use the same axis description (these will be site specific columns and readers are free to ignore these columns).
Axis description
This description applies to any column which has
TMATXnnn = T. It is assumed that TMATXnnn = T for the DATA column even when not present. The use of TMATXnnn = F for the DATA column is an error.

Axes descriptor keywords/columns include (not all need be present for each axis):

The type of physical coordinate on axis n.
The value of the physical coordinate on axis n at the reference pixel.
The array location of the reference pixel along axis n. CRPIX may be a fractional pixel and/or be outside of the limits of the array. This descriptor is optional for degenerate axes.
The increment in physical coordinates along axis n. This descriptor is optional for degenerate axes.
The axis rotation
The unit of coordinate values along this axis.
Note that these are the original FITS axes description keywords. It is anticipated that when an agreement is reached on the WCS convention that the appropriate keywords specified in that convention will be used to describe the axes here (e.g. CROTA is deprecated in favor of a more general mechanism).

Due to the virtual column convention, the following conflict may arrise:

TFORM1  = '1E'
TUNIT10 = 'radian'
CUNIT4  = 'degree'
Writers should avoid this conflict. Readers encountering such a conflict should report this as an error in the FITS table. However, readers may also choose to proceed by arbitrarily resolving the conflict so that some attempt may be made within the anaysis package to deal with this error. It is recommended that the CUNITxxx specification take precedence over any TUNITxxx specification. In any case, this conflict and the readers resolution of the conflict (if at all) should be reported to the user.

The other standard FITS Image axis keywords may be used here. This will include all of the WCS convention keywords when they become accepted as part of the FITS standard.

Defined axis types (CTYPEnnn values) for this convention (others are allowed but their values may be ignored by readers) are:

An 8 character string consisting of the 4 character axis type plus 4 characters describing the reference frame. An axis having this type is required.
axis types
  • 'FREQ' - frequency (Hz)
  • 'VELO' - velocity (m/s) (radio convention, unless overridden by use of the VELDEF SHARED keyword)
  • 'FELO' - regularly gridded in frequency but expressed as velocity in the optical convention (m/s)
reference frames
  • '-LSR' : Local Standard of Rest
  • '-HEL' : heliocentric (barycentric)
  • '-OBS' : the frame of rest of the observer/telescope (topocentric)
  • 'LSRK' : LSR as a kinematical definition
  • '-GEO' : Geocentric
  • 'REST' : rest frequency
  • '-GAL' : Galactocentric
'RA','GLON','ELON' plus an optional WCS projection code (degrees). This axis is required.
'DEC','GLAT,'ELAT' plus an optional WCS projection code (degrees). This axis is required.
The time since DATE-OBS (seconds) If the TIMESYS keyword is present, that keyword defines the time system for this table, including this column, otherwise UTC is assumed. This axis is optional. If not present, a value of 0.0 should be assumed. This axis will often be absent if DATE-OBS contains a time as well as a date.
The Stokes parameter of the data.
  • 1, 2, 3, 4 $ \Rightarrow$ I,Q,U,V
  • -1, - 2, - 3, - 4 $ \Rightarrow$ RR, LL, RL, LR
  • -5, - 6, - 7, - 8 $ \Rightarrow$ XX, YY, XY, YX
This axis is optional. If not present, a value of 1 (Stokes I) should be assumed.
Beam ID. This axis is optional. If not present, a value of 1 should be assumed.
receiver ID. This axis is optional. If not present, a value of 1 should be assumed.

CORE keywords and columns

These must be provided in all SDFITS tables. They are essential and common to all observations and telescopes. All single dish FITS readers and writers must acknowledge (write and properly interpret) all CORE keywords.

A string value giving an object name.
A string value giving the telescope name.
The total bandwidth of the backend in units of Hertz.
A string giving the observation date and optionally the time at the start using the new FITS y2k convention. The TIMESYS keyword may be used to indicate the time system. UTC is assumed if TIMESYS is absent.
The effective integration time in seconds.
The system temperature in Kelvin.

SHARED keywords and columns

These have agreeded definitions and interpretions however their presense is obtional. These are largely common to all observations and telescopes but not essential. These may be ignored by a single dish FITS reader.
A string giving the observer's name.
A string describing the observation.
A string describing the project.
A scan ID number. Typically this is an identification number given to a chunk of data when the data is taken. Not all telescopes provide a scan ID number.
The type of data and observing mode (8 characters total). The type (LINE, CONT, PULS, etc) + the mode (PSSW, FQSW, BMSQ, PLSQ, LDSW, TLPW, etc). These rules do NOT define these observing modes. Writers are strongly encouraged to use the FITS comments to document these modes.
A string used as a line identifier (with TRANSITI).
A string used as a line identifier (with MOLECULE.)
A string describing the scaling applied to reach the output intensity scale (``TB'',``TA'',``TA*'',``TR'',``TR*'').
A string giving the name of the front end device.
A string giving the name of the back end device.
The calibration temp (K).
The hot load temp (K).
The cold load temp (K).
The receiver temp (K).
The frequency resolution in Hz. This may differ from the channel spacing.
The time system which applies to all time columns and keywords (see the y2k FITS DATE agreement).
The velocity definition and frame (8 characters). The first 4 characters describe the velicity definition. Possible definitions include:
The second 4 characters describe the reference frame (e.g. ``-LSR'', ``-HEL'', ``-OBS''). If the frequency-like axis gives a frame, then the frame in VELDEF only applies to any velocities given as columns or keywords (virtual columns).
The radial velocity of the reference frame wrt the observer. Vframe - Vtelescope.
The radial velocity, Vsource - Vtelescope.
The observed frequency (Hz) at the reference pixel of the frequency-like axis.
The image sideband freq (Hz) corresp. to OBSFREQ.
The LST (seconds) at the start of scan.
The azimuth at TIME (deg) (if the TIME axis is non-degenerate, then this is the azimuth at the TIME of the first pixel on the TIME axis.
The elevation at TIME (deg) (same caveat as for AZIMUTH)
The opacity at OBSFREQ.
The opacity at IMAGFREQ.
The opacity per unit air mass.
The relative humidity (fraction, 0..1).
The ambient temp (K).
The atmospheric pressure (mm Hg).
The dew point (K).
The wind speed (m/s).
The wind direction (deg. west of north).
The main-beam efficiency.
The antenna aperture efficiency.
The rear spillover and scattering efficiency.
The forward spillover and scattering efficiency.
K per Jy.
The major main-beam FWHM (deg).
The minor main-beam FWHM (deg).
The beam position angle (degrees east of north).
The site longitude (deg).
The site latitude (deg).
The site elevation (m).
The rest frequency (Hz).

Other columns

Any additional columns not explicitly mentioned here can be added to an SDFITS table, although, obviously, most readers will not be able to propertly interpret those columns.

Multiple SDFITS tables in a single file

Any number of FITS binary tables can be attached to the same FITS table. This convention doesn't have anything to say about how the tables in such a file might be related. This strategy, attaching multiple SDFITS binary tables to a single FITS file, is one possible strategy for storing variable length DATA. DATA with similar sizes could be stored in separate tables, minimizing the amount of padding required in any one table without resorting to using the table heap convention to store variable length arrays. SDFITS readers should be capable of appending the contents of several SDFITS tables to a single result.

next up previous contents
Up: NOTE 236 - DISH: User's Manual Previous: sditerator   Contents
Please send questions or comments about AIPS++ to
Copyright © 1995-2000 Associated Universities Inc., Washington, D.C.

Return to AIPS++ Home Page