NRAO Home > CASA > MS V2

Calibration table definition version 2.0

Calibration table definition version 2.0

A.J. Kemball (NRAO)

January 01, 2001

A postscript version of this note is available (59kB).


This note describes the format of calibration tables in CASA/AIPS++. The calibration table format is currently at revision v2.0.


The calibration and imaging formalism used in AIPS++is based closely on the generic instrument model of Hamaker, Bregman and Sault (1996). This formalism, referred to as the Measurement Equation (ME), is instrument-independent and represents calibration effects in both the visibility and image plane as Jones matrices, with arbitrary parametrization and polarization basis. It's use in AIPS++is described by Cornwell (1995) and Noordam (1995), and references therein.

The calibration table format used in AIPS++was designed to support the fundamental principles on which the ME formalism is based. The definition of a standard calibration table format allows calibration components to be stored permanently for subsequent retrieval, application or modification. The current calibration table format revision level is v2.0.

The underlying principles on which the calibration table data format is based are described below.

Calibration table format

This section describes and defines all fields in the calibration table format. At the highest level, the calibration table consists of a main table, CAL_MAIN, and two sub-tables stored as table keywords CAL_DESC and CAL_HISTORY. The CAL_DESC sub-table describes the shape and coordinates of the array columns in the main calibration table. CAL_HISTORY references the associated calibration history for each row in the main table. All tables are described separately below.


The ME contains several different Jones matrix calibration components which are enumerated in the references listed above. In general, the Jones matrix calibration components fall into the following broad categories:

Antenna-based, visibility-plane, non-solvable: i) P - parallactic angle; and, ii) C - polarization configuration.

Antenna-based, visibility-plane, solvable: i) T - atmospheric correction; ii) G - electronic gain; iii) D - instrumental polarization; iv) B - bandpass; and v) F - ionosphere correction.

Interferometer-based, visibility-plane, solvable: The only supported interferometer-based correction at present is a multiplicative, solvable term (M). An additive term is also allowed by the ME.

Antenna-based, image-plane, non-solvable: i) P - parallactic angle.

Antenna-based, image-plane, solvable: i) T - atmosphere correction; ii) D - instrumental polarization; iii) F - ionosphere correction; and iv) E - voltage pattern.

Note that the same Jones matrix can appear as both a visibility-plane and image-plane correction in the ME, as appropriate. In addition, an individual Jones matrix component may either be discretely sampled or modeled using arbitrary parameters.

Jones matrices of different types (time-variable, solvable, baseline-based, antenna-based and parametrized) share as many common sections in the CAL_MAIN table as appropriate, thus representing the inheritance and specialization inherent to the family of Jones matrix types. This inheritance relationship is illustrated by the VisJones and SkyJones class families in the AIPS++library. Each calibration table holds only Jones calibration matrices of one type (e.g. GJones, or PJones etc.).

The key sections in the CAL_MAIN table are as follows:


The CAL_DESC sub-table defines the dimensions of the array-based columns in CAL_MAIN, and specifies the coordinates of the array axes. These coordinates include frequency, receptor polarization, and for image-plane components, directions and regions in the image-plane.

The frequency labeling of discretely sampled calibration gain values, as well as parametrized calibration models, may differ from the frequency labeling in the associated MS, if calibration is derived by aggregating or sub-dividing the MS spectral windows. Hence, the spectral windows and frequency channels along the calibration array axes, as described in CAL_DESC, may differ from the MS itself. Where there is a direct mapping to MS spectral windows and channel ranges, this is recorded.

The polarization axis is defined in terms of a list of receptor polarizations. As an enumerated coordinate, these overlap with those used in the associated MS.

For parametrized calibration components, the coordinate axes in CAL_DESC define the coordinate ranges over which the parameters are valid, and also the dimensions of the model parameters stored as arrays. In this case, the frequency and direction coordinates also define the units and frame for the parameters.

The image-plane direction array axis is defined by specifying an array or directions and associated regions about each direction in the image plane. This allows arbitrary discrete sampling of image-plane Jones calibration matrices, as well as arbitrary parameter domains for image-plane calibration models.


The CAL_HISTORY sub-table records the calibration context for the solutions recorded in each main calibration table row. This includes the parameters used by the calibration solver, the other calibration tables which may have been applied in the solution, any data selection, as well as an arbitrary set of notes the user may wish to attach to the calibration entry for future reference. All CAL_HISTORY fields are in string form, with a general keyword-value format.

CAL_MAIN: antenna-based, non-solvable, visibility-plane components

CAL_MAIN: antenna-based, non-solvable, visibility-plane components
Name Format Units Measure Comments
Primary MS indices
TIME Double s EPOCH Interval midpoint
TIME_EXTRA_PREC Double s Extra TIME precision
INTERVAL Double s Calibration interval
ANTENNA1 Int Antenna no.
FEED1 Int Feed on ANTENNA1
FIELD_ID Int Field id.
ARRAY_ID Int Subarray number
OBSERVATION_ID Int Observation id.
SCAN_NUMBER Int Scan number
PROCESSOR_ID Int Processor id.
PHASE_ID Int Phase id.
STATE_ID Int State id.
PULSAR_BIN Int Pulsar bin number
PULSAR_GATE_ID Int Pulsar gate id.
Secondary MS fields
FREQ_GROUP Int Freq. group
FREQ_GROUP_NAME String Freq. group name
FIELD_NAME String Field name
FIELD_CODE String Field code
SOURCE_NAME String Source name
SOURCE_CODE String Source code
CALIBRATION_GROUP Int Source cal. group
Gain values
GAIN Complex(a) Gain values
REF_ANT Int(b) Ref. antenna
REF_FEED Int(b) Ref. feed
REF_RECEPTOR Int(b) Ref. receptor
MEAS_FREQ_REF Int Measures freq. ref.
MEAS_DIR_REF Int Measures dir. ref.
Sub-table pointers


(i) The dimensions of the array-based columns, which can vary by row, and are defined in the CAL_DESC sub-table are as follows: (a) (Njones, Njones, Nspw, Nchan); and (b) (Nreceptors, Nspw, Nchan).

(ii) All MS primary indices point into the associated MS, as defined in the CAL_DESC sub-table as MS_NAME. See AIPS++note 229 for a full description of the MS data format.

Mid-point (not centroid) of calibration interval.

Extra TIME precision.

Time interval for which this calibration solution is valid, or over which it was determined.

Antenna number ($ \geq$ 0), and a direct index into the ANTENNA sub-table rownr of the associated MS.

Feed number ($ \geq$ 0).

Field identifier ($ \geq$ 0).

Subarray identifier ( $ \geq$ 0), which identifies data in separate subarrays.

Observation identifier ( $ \geq$ 0), which identifies data from separate observations.

Arbitrary scan number to identify data taken in the same logical scan. Not required to be unique.

Processor indentifier ($ \geq$ 0), and a direct index into the PROCESSOR sub-table rownr.

Switching phase identifier ($ \geq$ 0)

State identifier ( $ \geq$ 0), as defined in Section 3.1.5.

Pulsar bin number for the data record. Pulsar data may be measured for a limited number of pulse phase bins. The pulse phase bins are described in the PULSAR sub-table and indexed by this bin number.

Pulsar gate identifier ($ \geq$ 0), and a direct index into the PULSAR_GATE sub-table rownr.

The frequency group to which the spectral window belongs. This is used to associate spectral windows for joint calibration purposes.

The frequency group name; user specified.

Field name; user specified.

Field code indicating special characteristics of the field; user specified.

Source name; user specified.

Source code, used to describe any special characteristics f the source, such as the nature of a calibrator. Reserved keyword, including ("BANDPASS CAL").

Calibration group number to which this source belongs; user specified.

Array of calibration gain values, expressed as Jones matrices in an array of dimension (b), which is defined together with the array coordinates in the CAL_DESC sub-table.

Array of reference antenna numbers, of dimension (b).

Array of reference feed numbers, of dimension (b).

Array of reference receptor numbers, of dimension (b).

Array of reference frequencies, of dimension (b).

Array of reference frequency Measure references, of dimension (b).

Array of reference directions, of dimension (b).

Array of reference direction Measure references, of dimension (b).

CAL_MAIN: additions for antenna-based, solvable, visibility-plane components

CAL_MAIN: additions for antenna-based, solvable, visibility-plane components
Name Format Units Measure Comments
Solution statistics
TOTAL_SOLUTION_OK Bool Validity of total solution
TOTAL_FIT Float Total fit
TOTAL_FIT_WEIGHT Float Total fit weight
SOLUTION_OK Bool(a) Solution validity mask
FIT Float(a) Fit array
FIT_WEIGHT Float(a) Fit weight array


(i) The dimension (a) of the array-based columns is: (Njones, Njones, Nspw, Nchan). These dimensions are defined in the CAL_DESC sub-table, and can vary by row.

False if the current calibration solution interval is flagged, else True.

Total fit for the solution interval as a whole, as $ \sqrt{{\chi^2}\over{\Sigma {\rm weight}}}$.

Total fit weight for the solution interval as a whole ($ \Sigma$weight).

Validity mask for each element of the calibration solution array, of dimension (a).

Fit for each element of the calibration solution array, of dimension (a), as defined in the TOTAL_FIT_WEIGHT description above.

Fit weight for each element of the calibration solution array, of dimension (a).

CAL_MAIN: additions for interferometer-based, solvable, visibility-plane components

CAL_MAIN: additions for interferometer-based, solvable, visibility-plane components
Name Format Units Measure Comments
MS primary indices
ANTENNA2 Int Second antenna no.
FEED2 Int Feed on ANTENNA2


Second antenna number ($ \geq$ 0) of the interferometer pair, and a direct index into the ANTENNA sub-table rownr of the associated MS.

Feed number ($ \geq$ 0) on ANTENNA2.

CAL_DESC: calibration array dimensions and coordinates

CAL_DESC: calibration array dimensions and coordinates
Name Format Units Measure Comments
NUM_SPW Int No. cal. spw ids
NUM_CHAN Int No. cal. freq. chan.
NUM_RECEPTORS Int No. cal. receptors
N_JONES Int Jones matrix dim.
SPECTRAL_WINDOW_ID Int(Nspw) Associated MS spw ids
CHAN_FREQ Double( Nspw, Nchan) Hz FREQUENCY Cal chan. freq.
MEAS_FREQ_REF Int Measures freq. ref.
CHAN_WIDTH Double( Nspw, Nchan) Hz Cal. chan. width
CHAN_RANGE Int( 2, Nspw, Nchan) Associated MS chan. range
POLARIZATION_TYPE String( Nreceptors) Receptor polarization
JONES_TYPE String Matrix type
MS_NAME String MS name


Number of calibration spectral windows.

Number of calibration frequency channels.

Number of calibration polarization receptors.

Dimension of the Jones matrix. For antenna-based corrections this is less than or equal to the number of polarization receptors (one or two).

Associated MS spectral window id.'s. Set to -1 if the calibration frequency windows span multiple MS spectral windows.

Array of calibration array frequencies.

Measures reference for the calibration frequencies.

Array of calibration frequency channel widths.

Associated MS frequency channel range.

Receptor polarization type (e.g. "R", "L", "X" etc.)

The matrix type, as a reserved keyword ("DIAGONAL", "SCALAR", or "GENERAL").

Name of the associated MeasurementSet.

CAL_DESC: additions for image-plane components

CAL_DESC: additions for image-plane components
Name Format Units Measure Comments
NUM_DIR Int No. of directions
DIRECTION Doube(2, Ndir) DIRECTION Direction array
MEAS_DIR_REF Int Meas. dirn. ref.
REGION Record(Ndir) Associated regions.


(i) Note that the array dimensions in CAL_MAIN are increased by (Ndir) for the case of image-plane calibration components.

Number of image-plane calibration directions.

Array or image-plane calibration directions.

Measures direction reference.

Associated region for each direction.

CAL_HISTORY: calibration table history

CAL_HISTORY: calibration table history
Name Format Units Measure Comments
CAL_PARMS String Solver parameters
CAL_TABLES String Associated cal. tables
CAL_SELECT String Calibration selection
CAL_NOTES String Calibration notes


(i) All CAL_HISTORY fields are in string form in a general keyword-value format.

The parameters used for the solver in deriving the calibration solution.

Associated calibration tables applied when solving for the current Jones component.

Data selection applied when deriving the calibration solution.

Associated user notes for the calibration solution.