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

Last change on this file since 2135 was 1871, checked in by Malte Marquarding, 14 years ago

minor doc edit

File size: 6.4 KB
RevLine 
[1852]1=====================
2Scantable Description
3=====================
4
5Introduction
6============
7
8The Scantable is the ASAP single-dish data container. It was designed
9based on the data abstraction of the PKSreader API.
10
[1854]11ASAP data handling works on objects called scantables. A scantable holds your
12data, and also provides functions to operate upon it.
13
14The building block of a scantable is an integration, which is a single row of
15a scantable. Each row contains just one spectrum for each beam, IF and
16polarisation. For example Parkes OH-multibeam data would normally contain
1713 beams, 1 IF and 2 polarisations, Parkes methanol-multibeam data would
18contain 7 beams, 2 IFs and 2 polarisations while the Mopra 8-GHz MOPS
19filterbank will produce one beam, many IFs, and 2-4 polarisations.
20
21All of the combinations of Beams/IFs an Polarisations are contained in separate
22rows. These rows are grouped in cycles (same time stamp).
23
24A collection of cycles for one source is termed a scan (and each scan has a
25unique numeric identifier, the SCANNO). A scantable is then a collection of
26one or more scans. If you have scan-averaged your data in time, i.e. you
27have averaged all cycles within a scan, then each scan would hold just
28one (averaged) integration.
29
[1852]30Schema
31======
32
33The Scantable consist of a main (casacore) Table and several sub-tables which
[1854]34are referenced via **ID**. The following descriptions use the following syntax
[1852]35
[1854]36 **COLUMN/KEYWORD NAME** - *DATA_TYPE(N)=DEFAULT_VALUE*
37
38where *DEFAULT_VALUE* is optional and *(N)* indicates a Vector of that type
39
[1852]40----------
41Main Table
42----------
43
44The main table consists of global data (keywords) and row-based data (columns)
45
[1854]46
47Keywords
48--------
49
50* **VERSION** - *uInt*
51
52 the version of the scantable for compatibility tests
53
54* **POLTYPE** - *String=linear*
55
56 the polarisation type, i.e. *stokes*, *linear* or *circular*
57
58* **DIRECTIONREF** - *String=J2000*
59
60 the reference frame of the direction (coordinate) [redundant?!]
61
62* **OBSMODE** - *String=""*
63
64 no idea...
65
66* **UTC** - *String*
67
68 most likely the starting time of the observation (file)
69
70* **AntennaName** - *String*
71
72 the name of the antenna
73
74* **AntennaPosition** - *Double(3)*
75
76 the WGS position of the antenna
77
78* **FluxUnit** - *String*
79
80 the unit of the channel values i.e. *Jy* or *K*
81
82* **Observer** - *String*
83
84 the name of the observer
85
86* **Obstype** - *String*
87
88 probably telescope specific name/encoding
89
90* **Project** - *String*
91
92 e.g. proposal project number, survey name
93
94* **Bandwidth** - *Double*
95
96 self-explanatory
97
98* **nIF, nBeam, nPol, nChan** - *Int*
99
100 the number of IF, Beam, Polarisation and Channel values in the scantable
101 This is currently **FIXED**
102
103* **FreqRefFrame** - *String*
104
105 redundant info - also in **FREQUENCIES** sub-table
106
107* **FreqRefVal** - *Double*
108
109 no idea...
110
[1852]111Columns
112-------
113
114* **SPECTRA** - *Float(nchannel)*
115
116 the spectral channel data.
117
118* **FLAGTRA** - *uChar(nchannel)*
119
120 the corresponding flags
121
122* **TSYS** - *Float(nchannel)*
123
124 the channel-based system temperature values
125
[1854]126* **FLAGROW** - *uInt=-1*
[1852]127
128 spectrum based flags
129
130* **TIME** - *MEpoch*
131
132 The mjd time when the observation took place
133
134* **INTERVAL** - *Double*
135
136 the integration time in seconds
137
138* **DIRECTION** - *MDirection*
139
140 the associated direction on the sky
141
142* **AZIMUTH, ELEVATION** - *Float*
143
144 the azimuth/elevation when the spectrum was collected
145
146* **SRCNAME** - *string*
147
148 the name of the source observered
149
[1854]150* **SRCTYPE** - *Int=-1*
[1852]151
152 the tyep of the source, i.e. indicating if it is an on source scan or
153 off source. This will be used for calibration
154
155* **SCANNO, BEAMNO, POLNO, IFNO, CYCLENO** - *uInt*
156
157 These columns index (0-based) the respective values.
158
159 * SCANNO: the number odf the scan. A scan is usually multiple integrations
160 (cycles)
161
162 * CYCLENO: the integration number within a scan (sub-scan?)
163
164 * IFNO: the index of the IF (spectral window)
165
166 * BEAMNO: the index of the beam (in a multibeam system)
167
168 * POLNO: the index of the polarisation, e.g. XX=0, YY=1, Real(XY)=2,
169 Imag(XY)=3
170
[1854]171* **REFBEAMNO** - *Int=-1*
[1852]172
173 optional index of the reference beam in a multibeam obervation
174
[1854]175* **FREQ_ID, MOLECULE_ID, TCAL_ID, FOCUS_ID, WEATHER_ID, FIT_ID** - *Int*
[1852]176
[1854]177 the reference indeces to the sub-tables
[1852]178
[1854]179* **FIELDNAME** - *string*
180
181 the name of the field the source belongs to
182
183* **OPACITY** - *Float*
184
185 maybe redundant - not used anywhere
186
187* **SRCPROPERMOTION, SRCVELOCITY, SRCDIRECTION**
188
189 see livedata docs - not used in ASAP
190
191* **SCANRATE**
192
193 see livedata docs - not used in ASAP
194
[1852]195----------
196Sub-Tables
197----------
198
199FREQUENCY
200---------
201
[1854]202""""""""
203Keywords
204""""""""
[1852]205
[1854]206* **BASEFRAME** - *String=TOPO*
207* **FRAME** - *String=TOPO*
208* **EQUINOX** - *String=J2000*
209* **UNIT** - *String=""*
210* **DOPPLER** - *String=RADIO*
[1852]211
[1854]212"""""""
213Columns
214"""""""
215
216* **REFPIX** - *Double*
217
218* **REFVAL** - *Double*
219
220* **INCREMENT** - *Double*
221
222MOLECULES
223---------
224
225""""""""
226Keywords
227""""""""
228
229* **UNIT** - *String=Hz*
230
231"""""""
232Columns
233"""""""
234
235* **RESTFREQUENCY** - *Double()*
236* **NAME** - *String()*
237* **FORMATTEDNAME** - *String()*
238
[1871]239FOCUS
240-----
241
242""""""""
243Keywords
244""""""""
245
246* **PARALLACTIFY** - *Bool=False*
247
248 indicates whether the observation was parallactified i.e. observed in such
249 a way that the sum of the phases is zero.
250
251"""""""
252Columns
253"""""""
254
255* **PARANGLE** - *Float*
256
257 the parallacticle angle of the observation
258
259* **ROTATION** - *Float*
260
261 feed rotation
262
263* **AXIS** - *Float*
264
265 ? ask Mark Calabretta
266
267* **TAN** - *Float*
268
269 ? ask Mark Calabretta
270
271* **HAND** - *Float*
272
273 the sign of the polarisation i.e. 1 for XY and '-1' for YX
274
275* **USERANGLE** - *Float*
276
277 A user definable phase correction term
278
279* **MOUNT** - *Float*
280
281 ? ask Jim Caswell
282
283* **XYOFFSET** - *Float*
284
285 ? ask Jim Caswell
286
287* **XYPHASEOFFSET** - *Float*
288
289 ? ask Jim Caswell
290
[1858]291.. todo:: add all sub-table descriptions
[1854]292
[1852]293========================
294Mapping to other formats
295========================
296
297MS
298==
[1854]299
300MeasurementSets are specifically designed for synthesis data. As such one of the
301main dfferences between the Scantable and a MS is how spectra are stored.
[1871]302An MS stores those in an n_pol x n_channel complex matrix (DATA column) and/or
303a n_pol x n_channel float matrix (FLOAT_DATA column) whereas the Scantable
304stores each polarisation seperately. In case of polarimetry data the (complex)
305cross-polarisation is serialised into real and imaginary parts, e.g. a total of
306four rows would describe one polarisation.
Note: See TracBrowser for help on using the repository browser.