source: trunk/doc/source/developer/scantable.rst@ 1906

=====================
Scantable Description
=====================

Introduction
============

The Scantable is the ASAP single-dish data container. It was designed
based on the data abstraction of the PKSreader API.

ASAP data handling works on objects called scantables. A scantable holds your
data, and also provides functions to operate upon it.

The building block of a scantable is an integration, which is a single row of
a scantable. Each row contains just one spectrum for each beam, IF and
polarisation. For example Parkes OH-multibeam data would normally contain
13 beams, 1 IF and 2 polarisations, Parkes methanol-multibeam data would
contain 7 beams, 2 IFs and 2 polarisations while the Mopra 8-GHz MOPS
filterbank will produce one beam, many IFs, and 2-4 polarisations.

All of the combinations of Beams/IFs an Polarisations are contained in separate
rows. These rows are grouped in cycles (same time stamp).

A collection of cycles for one source is termed a scan (and each scan has a
unique numeric identifier, the SCANNO). A scantable is then a collection of
one or more scans. If you have scan-averaged your data in time, i.e. you
have averaged all cycles within a scan, then each scan would hold just
one (averaged) integration.

Schema
======

The Scantable consist of a main (casacore) Table and several sub-tables which
are referenced via **ID**. The following descriptions use the following syntax

    **COLUMN/KEYWORD NAME** - *DATA_TYPE(N)=DEFAULT_VALUE*

where *DEFAULT_VALUE* is optional and *(N)* indicates a Vector of that type

----------
Main Table
----------

The main table consists of global data (keywords) and row-based data (columns)


Keywords
--------

* **VERSION** - *uInt*

    the version of the scantable for compatibility tests

* **POLTYPE** - *String=linear*

    the polarisation type, i.e. *stokes*, *linear* or *circular*

* **DIRECTIONREF** - *String=J2000*

    the reference frame of the direction (coordinate) [redundant?!]

* **OBSMODE** - *String=""*

    no idea...

* **UTC** - *String*

    most likely the starting time of the observation (file)

* **AntennaName** - *String*

    the name of the antenna

* **AntennaPosition** - *Double(3)*

    the WGS position of the antenna

* **FluxUnit** - *String*

    the unit of the channel values i.e. *Jy* or *K*

* **Observer** - *String*

    the name of the observer

* **Obstype** -  *String*

    probably telescope specific name/encoding

* **Project** -  *String*

    e.g. proposal project number, survey name

* **Bandwidth** - *Double*

    self-explanatory

* **nIF, nBeam, nPol, nChan** - *Int*

    the number of IF, Beam, Polarisation and Channel values in the scantable
    This is currently **FIXED**

* **FreqRefFrame** - *String*

    redundant info - also in **FREQUENCIES** sub-table

* **FreqRefVal** - *Double*

    no idea...

Columns
-------

* **SPECTRA** - *Float(nchannel)*

    the spectral channel data.

* **FLAGTRA** - *uChar(nchannel)*

    the corresponding flags

* **TSYS** - *Float(nchannel)*

    the channel-based system temperature values

* **FLAGROW** - *uInt=-1*

    spectrum based flags

* **TIME** - *MEpoch*

    The mjd time when the observation took place

* **INTERVAL** - *Double*

    the integration time in seconds

* **DIRECTION** - *MDirection*

    the associated direction on the sky

* **AZIMUTH, ELEVATION** - *Float*

    the azimuth/elevation when the spectrum was collected

* **SRCNAME** - *string*

    the name of the source observered

* **SRCTYPE** - *Int=-1*

    the tyep of the source, i.e. indicating if it is an on source scan or
    off source. This will be used for calibration

* **SCANNO, BEAMNO, POLNO, IFNO, CYCLENO** - *uInt*

    These columns index (0-based) the respective values.

    * SCANNO: the number odf the scan. A scan is usually multiple integrations
              (cycles)

    * CYCLENO: the integration number within a scan (sub-scan?)

    * IFNO: the index of the IF (spectral window)

    * BEAMNO: the index of the beam (in a multibeam system)

    * POLNO: the index of the polarisation, e.g. XX=0, YY=1, Real(XY)=2,
             Imag(XY)=3

* **REFBEAMNO** - *Int=-1*

    optional index of the reference beam in a multibeam obervation

* **FREQ_ID, MOLECULE_ID, TCAL_ID, FOCUS_ID, WEATHER_ID, FIT_ID** - *Int*

    the reference indeces to the sub-tables

* **FIELDNAME** - *string*

    the name of the field the source belongs to

* **OPACITY** - *Float*

    maybe redundant - not used anywhere

* **SRCPROPERMOTION, SRCVELOCITY, SRCDIRECTION**

    see livedata docs - not used in ASAP

* **SCANRATE**

    see livedata docs - not used in ASAP

----------
Sub-Tables
----------

FREQUENCY
---------

""""""""
Keywords
""""""""

* **BASEFRAME** - *String=TOPO*
* **FRAME** - *String=TOPO*
* **EQUINOX** - *String=J2000*
* **UNIT** - *String=""*
* **DOPPLER** - *String=RADIO*

"""""""
Columns
"""""""

* **REFPIX** - *Double*

* **REFVAL** - *Double*

* **INCREMENT** - *Double*

MOLECULES
---------

""""""""
Keywords
""""""""

* **UNIT** - *String=Hz*

"""""""
Columns
"""""""

* **RESTFREQUENCY** - *Double()*
* **NAME** - *String()*
* **FORMATTEDNAME** - *String()*

FOCUS
-----

""""""""
Keywords
""""""""

* **PARALLACTIFY** - *Bool=False*

    indicates whether the observation was parallactified i.e. observed in such
    a way that the sum of the phases is zero.

"""""""
Columns
"""""""

* **PARANGLE** - *Float*

    the parallacticle angle of the observation

* **ROTATION** - *Float*

    feed rotation

* **AXIS** - *Float*

    ? ask Mark Calabretta

* **TAN** - *Float*

    ? ask Mark Calabretta

* **HAND** - *Float*

    the sign of the polarisation i.e. 1 for XY and '-1' for YX

* **USERANGLE** - *Float*

    A user definable phase correction term

* **MOUNT** - *Float*

    ? ask Jim Caswell

* **XYOFFSET** - *Float*

    ? ask Jim Caswell

* **XYPHASEOFFSET** - *Float*

    ? ask Jim Caswell

.. todo:: add all sub-table descriptions

========================
Mapping to other formats
========================

MS
==

MeasurementSets are specifically designed for synthesis data. As such one of the
main dfferences between the Scantable and a MS is how spectra are stored.
An MS  stores those in an n_pol x n_channel complex matrix (DATA column) and/or
a n_pol x n_channel float matrix (FLOAT_DATA column) whereas the Scantable
stores each polarisation seperately. In case of polarimetry data the (complex)
cross-polarisation is serialised into real and imaginary parts, e.g. a total of
four rows would describe one polarisation.