Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatools/ms.py: 60%
169 statements
« prev ^ index » next coverage.py v7.6.4, created at 2024-10-31 17:39 +0000
1##################### generated by xml-casa (v2) from ms.xml ########################
2##################### 419aab85376c97dfba31215cad1c384f ##############################
3from __future__ import absolute_import
4from .__casac__.ms import ms as _ms
6from .errors import create_error_string
7from .typecheck import CasaValidator as _validator
8_pc = _validator( )
9from .coercetype import coerce as _coerce
10from .table import table as _wrap_table
11from .msmetadata import msmetadata as _wrap_msmetadata
13class ms:
14 _info_group_ = """ms"""
15 _info_desc_ = """Operations on measurement sets"""
16 ### self
17 def __init__(self, *args, **kwargs):
18 """This is the most commonly used constructor. It creates an ms tool
19 which is attached to the specified measurement set table.
21 By default the table is opened read only to prevent you from
22 accidently making changes to the measurement set. Set nomodify to
23 False you you do intend to make changes.
25 Setting the lock argument to True will permanently lock the table
26 preventing other processes from writing to the measurement set.
27 Unless you expect this to happen, and want to prevent it, you
28 should leave the lock argument at the default value which implies
29 auto-locking.
31 The host argument specifies which machine the precompiled ms
32 process should be started on. The default value starts it on the
33 same machine as the one that casapy is running on.
35 In order to run the ms tool on a remote machine you need to
36 satisfy all the following conditions.
37 begin{itemize}
38 item It must be possible to start casa on the remote machine
39 item You must be able to log onto the remote machine without
40 having to type a password
41 item The CASAPATH environment variable must be defined on the
42 remote machine. You may want to set this up in the relevant
43 ``dot'' file eg., adding a line like
44 texttt{source~/usr/local/aips++/aipsinit.csh} in your
45 .cshrc file (for csh).
46 end{itemize}
47 One quick way to check if all three conditions are met is to type,
48 on your local machine (rsh host 'echo $CASAPATH') where host is
49 replaced by the name of the remote machine. If the value of the
50 CASAPATH variable that is printed does not contain something like
51 {aips-root~architecture~site~host} and that all the values are
52 correct for the remote machine you can be certain that starting the
53 ms tool, or any casa server, on the remote host will not work.
55 Each ms tool can only run one function at a time. To solve this
56 you start two servers. The forcenewserver argument allows you to
57 do this by overriding the default behaviour of having each ms tool
58 share the same server.
60 This function returns an ms tool or fail if something went wrong,
61 like an error in the measurement set name.
64 """
65 self._swigobj = kwargs.get('swig_object',None)
66 if self._swigobj is None:
67 self._swigobj = _ms()
69 def open(self, thems='', nomodify=True, lock=False, check=False):
70 """Use this function when you have detached (using the close function)
71 the ms tool from a measurement set table and wish to reattach to another
72 measurement set table.
74 If check=true, additional referential integrity checks on the MS
75 are run. If any of these fail, an exception is thrown and the MS
76 is not open (since it is not a valid MS).
78 """
79 return self._swigobj.open(thems, nomodify, lock, check)
81 def reset(self):
82 """This function re-attaches the ms tool to the original MS,
83 effectively discarding any prior operations, in particular any
84 data selection operations using msselect function.
86 """
87 return self._swigobj.reset()
89 def close(self):
90 """This function detaches the ms tool from the associated
91 measurement set table after flushing all the cached changes.
92 After calling this function the ms tool is not associated with
93 any measurement set and using any function other than open or fromfits
94 will result in an error message being sent to the logger.
96 This function can be useful to avoid synchronization problems
97 which can occur when different processes have the same ms open.
99 """
100 return self._swigobj.close()
102 def done(self):
103 """You should call close() when you are finished using the ms tool
104 to close the measurement set table and free any associated file
105 locks. The measurement set is not deleted.
108 """
109 return self._swigobj.done()
111 def name(self):
112 """This function returns the name of the measurement set table that
113 is being manipulated. If the ms tool is not attached to any
114 measurement set, this function will return the string ``none''.
116 """
117 return self._swigobj.name()
119 def iswritable(self):
120 """This function returns True if the underlying MeasurementSet
121 was opened for writing/update.
123 """
124 return self._swigobj.iswritable()
126 def nrow(self, selected=False):
127 """This function returns the number of rows in the measurement set.
128 If the optional argument selected is set to True, it returns the
129 number of currently selected rows, otherwise it returns the
130 number of rows in the original measurement set.
132 """
133 return self._swigobj.nrow(selected)
135 def getdata(self, items=[ ], ifraxis=False, ifraxisgap=int(0), increment=int(1), average=False):
136 """This function reads the specified items from the currently
137 selected measurement set and returns them in fields of a record.
138 The main difference between this and direct access of the table,
139 using the table tool, is that this function reads data from the
140 selected measurement set, provides access to derived
141 quantities like amplitude and flag_sum, and can reorder the
142 data.
144 As with the ms.range function, the items to read are specified
145 using a vector of strings. Allowable items include: 'amplitude',
146 'corrected_amplitude', 'model_amplitude', 'ratio_amplitude',
147 'residual_amplitude', 'obs_residual_amplitude', 'antenna1',
148 'antenna2', 'axis_info', 'data', 'corrected_data', 'float_data',
149 'model_data', 'ratio_data', 'residual_data',
150 'obs_residual_data', 'feed1', 'feed2', 'field_id', 'flag',
151 'flag_row', 'flag_sum', 'ha' (added to 'axis_info'),
152 'ifr_number', 'imaginary', 'corrected_imaginary',
153 'model_imaginary', 'ratio_imaginary', 'residual_imaginary',
154 'obs_residual_imaginary', 'last' (added to 'axis_info'),
155 'phase', 'corrected_phase', 'model_phase', 'ratio_phase',
156 'residual_phase', 'obs_residual_phase', 'real',
157 'corrected_real', 'ratio_real', 'residual_real',
158 'obs_residual_real', 'scan_number', 'sigma', 'data_desc_id',
159 'time', 'ut' (added to 'axis_info'), 'uvw', 'u', 'v', 'w',
160 'uvdist', and 'weight'. Unrecognized items will result in a
161 warning being sent to the logger. Corrected, model, and float
162 visibilities will result in a warning if these columns do not
163 exist. Duplicate items are silently ignored.
165 Note that 'ha', 'last', and 'ut' must be requested along with
166 'axis_info' and ifraxis=True. This data will be found in a
167 subrecord of the returned record's 'axis_info' with the key in
168 uppercase. For example, for 'ut', the data is found in:
169 rec['axis_info']['time_axis']['UT']. See more information
170 about 'axis_info' below.
172 The record that is returned contains fields that correspond to
173 each of the specified items. Most fields will contain an array.
174 The array may be one, two or three dimensional depending on
175 whether the corresponding row in the measurement set is a
176 scalar, one-, or two-dimensional. Unless the ifraxis argument
177 is set to True, the length of the last axis on these arrays
178 will correspond to the number of rows in the selected
179 measurement set.
181 If the ifraxis argument is set to True, the row axis is split
182 into an interferometer axis and a time axis. For example, a
183 measurement set with 90 rows, in an array with 6 telescopes (so
184 that there are 15 interferometers), may have a data array of
185 shape [4,32,90] if ifraxis is False, or [4,32,15,6] if ifraxis
186 is True (assuming there are 4 correlations and 32 channels). If
187 there are missing rows, as will happen if not all
188 interferometers were used for all time-slots, then a default
189 value will be inserted.
191 This splitting of the row axis may not happen for items where
192 there is only a single value per row. For some items the
193 returned vector will contain only as many values as there are
194 interferometers and it is implicit that the same value should
195 be used for all time slots. The antenna1, antenna2, feed1,
196 feed2 and ifr_number items fall in this category. For other
197 items, the returned vector will have as many values as there
198 are time slots and it is implicit that the same value should be
199 used for all interferometers. The field_id, scan_number,
200 data_desc_id, and time items fall into this category.
202 The 'axis_info' item provides data labelling information. It
203 returns a record with the following fields: corr_axis,
204 freq_axis, ifr_axis, and time_axis. The latter two fields are
205 not present if ifraxis is set to False.
207 1. The corr_axis field contains a string vector with elements like
208 'RR' or 'XY' that indicates which polarizations were correlated
209 together to produce the data. The length of this vector will
210 always be the same as the length of the first axis of the data
211 array.
213 2. The freq_axis field contains a record with two fields, chan_freq
214 and resolution. Each of these fields contains vectors which
215 indicate the centre frequency and spectral resolution (FWHM)
216 of each channel. The length of these vectors will be the same
217 as the length of the second axis in the data.
219 3. The ifr_axis field contains fields: ifr_number, ifr_name,
220 ifr_shortname and baseline. The ifr_number is the same as
221 returned by the 'ifr_number' item, 1000*antenna1+antenna2.
222 The ifr_name and ifr_shortname are string vectors containing
223 descriptions of the interferometer; ifr_name contains the names
224 of the antenna pair separated by a hyphen, and ifr_shortname
225 contains the ids of the antenna pair separated by a hyphen.
226 The baseline is the Euclidian distance in meters between the two
227 antennas. All of these vectors have a length equal to the number
228 of interferometers in the selected measurement set, i.e., to the
229 length of the third axis in the data when ifraxis is True.
231 4. The time_axis field contains the MJD seconds field and
232 optionally the HA, UT, and LAST fields. To include the optional
233 fields, you need to add 'ha', 'last' or 'ut' strings to the list
234 of requested items. All of the fields in the time_axis record
235 contain vectors that indicate the time at the midpoint of the
236 observation and are in seconds. The MJD seconds field is since
237 0 hours on the day having a modified julian day number of zero
238 and the rest are since midnight prior to the start of the
239 observation.
241 An optional gap size can be specified to visually separate
242 groups of interferometers with the same antenna1 index (handy
243 for identifying antennas in an interferometer vs time display).
244 The default is no gap.
246 An optional increment can be specified to return data from every
247 row matching the increment only.
249 When the average flag is set, the data will be averaged over the
250 time axis if the ifraxis is True or the row axis i.e., different
251 interferometers and times may be averaged together. In the
252 latter case, some of the coordinate information, like
253 antenna_id, will no longer make sense. When all data to be
254 averaged is unflagged, the result is the averaged value and the
255 corresponding flag is False. When all data is flagged, the
256 result is set to zero and the corresponding flag is True. When
257 data to be averaged is mixed (unflagged and flagged), only the
258 unflagged values are averaged and the flag is set to False.
260 You need to call selectinit before calling this function.
261 If you haven't then selectinit will be called for you with
262 default arguments.
264 Items prefixed with corrected, model, residual or obs_residual
265 are not available unless your measurement set has been processed
266 either with the imager or calibrator tools.
268 """
269 return self._swigobj.getdata(items, ifraxis, ifraxisgap, increment, average)
271 def putdata(self, items={ }):
272 """This function allows you to write values from casapy variables
273 back into the measurement set table. The main difference between
274 this and directly accessing the table using the table tool is
275 that this function writes data to the selected measurement set.
277 Unlike the getdata function, you can only put items that
278 correspond to actual table columns. You cannot change the data
279 shape either so that the number of correlations, channels and
280 rows (or interferometers/time slots) must match the values in
281 the selected measurement set. If the values were obtained using
282 the getdata function with ifraxis argument set to True, then
283 any default values added to fill in missing
284 interferometer/timeslots pairs will be ignored when writing
285 the modified values back using this function.
287 Allowable items include: 'data', 'corrected_data',
288 'model_data', 'flag', 'flag_row', 'sigma', and 'weight'.
289 'float_data' is currently not implemented for putdata.
291 The measurement set has to be opened for read/write access
292 (nomodify=False) to be able to use this function.
294 You need to call selectinit before calling this function.
295 If you haven't then selectinit will be called for you with
296 default arguments.
298 Items prefixed with corrected, model, residual or obs_residual
299 are not available unless your measurement set has been processed
300 either with the imager or calibrator tools.
302 """
303 return self._swigobj.putdata(items)
305 def fromfits(self, msfile='', fitsfile='', nomodify=True, lock=False, obstype=int(0), host='', forcenewserver=False, antnamescheme='old'):
306 """This function will convert a uvfits file to a measurement set table
307 and then open the measurement set table. The newly created
308 measurement set table will continue to exist after the tool has
309 been closed.
311 Setting the lock argument to True will permanently lock the table
312 preventing other processes from writing to the measurement set.
313 Unless you expect this to happen, and want to prevent it, you
314 should leave the lock argument at the default value which implies
315 auto-locking.
317 Note that the variety of fits files that fromfits is able to
318 interpret correctly is limited mostly to files similar to those
319 produced by classic AIPS. In particular, it understands only binary
320 table extensions for the antenna (AN), frequency (FQ) and source
321 (SU) information and ignores other extensions.
323 This function returns True if it successfully attaches the ms tool
324 to a newly created Measurement Set or False if something went
325 wrong, like an error in a file name.
327 NOTE ON WEIGHTS
329 ms.fromfits() will generate a WEIGHT_SPECTRUM column in which it
330 will fill the absolute value of the weight associated with each
331 visibility in the uvfits file. Negative weights will have the
332 associated FLAGs set to True. It will compute the associated WEIGHT
333 value for that MS row to be the sum of the absolute values of the
334 associated WEIGHT_SPECTRUM values.
336 """
337 return self._swigobj.fromfits(msfile, fitsfile, nomodify, lock, obstype, host, forcenewserver, antnamescheme)
339 def fromfitsidi(self, msfile='', fitsfile='', nomodify=True, lock=False, obstype=int(0)):
340 """This function will convert a uvfits file to a measurement set table
341 and then open the measurement set table. The newly created
342 measurement set table will continue to exist after the tool has
343 been closed.
345 Setting the lock argument to True will permanently lock the table
346 preventing other processes from writing to the measurement set.
347 Unless you expect this to happen, and want to prevent it, you
348 should leave the lock argument at the default value which implies
349 auto-locking.
351 Note that the variety of fits files that fromfits is able to
352 interpret correctly is limited mostly to files similar to those
353 produced by classic AIPS. In particular, it understands only binary
354 table extensions for the antenna (AN), frequency (FQ) and source
355 (SU) information and ignores other extensions.
357 This function returns True if it successfully attachs the ms tool
358 to a newly created Measurement Set or False if something went
359 wrong, like an error in a file name.
361 """
362 return self._swigobj.fromfitsidi(msfile, fitsfile, nomodify, lock, obstype)
364 def tofits(self, fitsfile='', column='corrected', field=[ ], spw=[ ], baseline=[ ], time='', scan=[ ], uvrange=[ ], taql='', writesyscal=False, multisource=False, combinespw=False, writestation=False, padwithflags=False, overwrite=False):
365 """This function writes a uvfits file that contains the data in the
366 measurement set associated with this tool. The fits file is always
367 written in floating point format and the data are always stored in
368 the primary array of the fits file.
370 IMPORTANT NOTE: In general, some of the data averaging features of
371 this method have never worked properly. In general, users should
372 run mstransform to select and average data prior to running
373 tofits(). The associated input parameters are slowly being
374 deprecated and removed.
376 If the measurement set has been imaged or calibrated in CASA, it
377 may contain additional data columns. You need to select ONE of
378 these columns to be written to the fits file. The possible
379 options are:
381 1. observed This is the raw data as collected by the telescope. All
382 interferometric measurement sets must contain this column.
383 A synonym for 'observed' is 'data'.
384 2. corrected This is the calibrated data. A synonym for 'corrected' is
385 'corrected_data'.
386 3. model This is the visibilites that would be measured using
387 the current model of the sky. A synonym for 'model' is
388 'model_data'.
390 The parsing of these strings is case insensitive. If any other
391 option is specified then the observed data will be written.
393 By default a single-source uvfits file is written, but if the
394 measurement set contains more than one field or if you set the
395 multisource argument to True a multi-source uvfits file will be
396 written. Because of limitations in the uvfits format you have to
397 ensure that the data shape is fixed for all the data you intend to
398 write to one fits file. See the general description of this tool
399 for how you can select data to meet this condition.
401 The combinespw argument is used to control whether data from
402 different spectral windows will be written as different entries in
403 the fits FQ (frequency) table or combined as different IF's
404 within one entry in the FQ table. You should normally only set
405 this to True if you know that the data from different spectral
406 windows were observed simultaneously, and the data in the
407 measurement set can be equally divided between all the spectral
408 windows (i.e. each window should have the same width). Use of
409 this switch is recommended for data to be processed in classic
410 AIPS and difmap (if possible, e.g., standard dual IF observations).
412 The padwithflags argument is only relevant if combinespw is True.
413 If true, it will fill in data that is 'missing' with flags to fit
414 the IF structure. This is appropriate if the MS had a few
415 frequency-dependent flags applied, and was then time-averaged by
416 split. If the spectral windows were observed at different times,
417 padwithflags=True will add a large number of flags, making the
418 output file significantly longer. It does not yet support spectral
419 windows with different widths.
421 The fits GC (gain curve) and TY (system temperature) tables can
422 be optionally written by setting the writesyscal argument to True.
423 This is a rather WSRT-specific operation at the moment and may not
424 work correctly for measurement sets from other telescopes.
426 One may overwrite the specified output file if it exists by
427 specifying overwrite=True.
429 NOTE ON WEIGHTS
431 If the MS has no WEIGHT_SPECTRUM column, or if it does, but that
432 column does not contain any data, ms.tofits() will compute the
433 associated weight it writes to the uvfits file by taking the
434 associated WEIGHT column value in the MS and dividing it by the
435 number of channels associated with the spectral window of that
436 visibility.
438 """
439 return self._swigobj.tofits(fitsfile, column, field, spw, baseline, time, scan, uvrange, taql, writesyscal, multisource, combinespw, writestation, padwithflags, overwrite)
441 def listfits(self, fitsfile):
442 """List HDU and typical data rows in a uvfits file
444 """
445 return self._swigobj.listfits(fitsfile)
447 def asdmref(self, abspath=''):
448 """If the MS is imported from an ASDM with option lazy=True, the DATA
449 or FLOAT_DATA column of the MS is virtual and directly reads the
450 visibilities from the ASDM. A reference to the original ASDM is
451 stored with the MS. If the ASDM needs to be moved to a different
452 path, the reference to it in the MS needs to be updated. This can
453 be achieved with ms.asdmref().
455 When called with an empty string (default), the method just reports
456 the currently set ASDM path.
458 Return value is a string containing the new path if the path was
459 successfully set or (in the case abspath was empty) the MS indeed
460 contains a ASDM reference, i.e. was lazily imported.
462 If the ASDM does not contain an ASDM reference, the method returns
463 an empty string. If abspath is not empty and there was an error
464 setting the new reference, the method throws an exception.
466 """
467 return self._swigobj.asdmref(abspath)
469 def concatenate(self, msfile='', freqtol=[ ], dirtol=[ ], weightscale=float(1.), handling=int(0), destmsfile='', respectname=False):
470 """This function concatenates two measurement sets together.
472 The data is copied from the measurement set specified in the
473 msfile arguement to the end of the measurement set attached to the
474 ms tool. If a lot of data needs to be copied this function may
475 take some time. You need to open the measurement set for writing
476 in order to use this function.
478 """
479 return self._swigobj.concatenate(msfile, freqtol, dirtol, weightscale, handling, destmsfile, respectname)
481 def testconcatenate(self, msfile='', freqtol=[ ], dirtol=[ ], respectname=False):
482 """This function acts like ms.concatenate() with handling==3 (do not
483 concatenate the MAIN and POINTING tables). This is useful for
484 generating, e.g., SPECTRAL_WINDOW and FIELD tables which contain
485 all used SPW and FIELD ids for a set of MSs without having to
486 actually carry out a time-consuming concatenation on disk. The MAIN
487 table in the resulting output MS is that of the original MS, i.e.
488 it is not touched.
490 """
491 return self._swigobj.testconcatenate(msfile, freqtol, dirtol, respectname)
493 def virtconcatenate(self, msfile='', auxfilename='', freqtol=[ ], dirtol=[ ], weightscale=float(1.), respectname=True):
494 """This function virtually concatenates two measurement sets together
495 such that they can later be turned into a multi-MS with
496 createmultims().
498 You need to open the measurement set for writing in order to use
499 this function.
501 """
502 return self._swigobj.virtconcatenate(msfile, auxfilename, freqtol, dirtol, weightscale, respectname)
504 def createmultims(self, outputTableName, tables, subtables, nomodify=True, lock=False, copysubtables=False, omitsubtables=[ ]):
505 """
506 """
507 return self._swigobj.createmultims(outputTableName, tables, subtables, nomodify, lock, copysubtables, omitsubtables)
509 def ismultims(self):
510 """
511 """
512 return self._swigobj.ismultims()
514 def split(self, outputms='', field=[ ], spw=[ ], step=[ int(1) ], baseline=[ ], timebin=[ ], time='', scan=[ ], uvrange=[ ], taql='', whichcol='DATA', tileshape=[ ], subarray=[ ], combine='', correlation='', intent='', obs=''):
515 """This function splits out part of the MS into a new MS. Time and
516 channel averaging can be performed in the process (but not in
517 the same call).
519 When splitting multiple spectral windows, the parameters nchan,
520 start, and step can be vectors, so that each spectral window has
521 its own selection on averaging and number of output channels. But
522 the option of using only one value for each of these parameters
523 means that it will be replicated for all the spectral windows
524 selected.
526 """
527 return self._swigobj.split(outputms, field, spw, step, baseline, timebin, time, scan, uvrange, taql, whichcol, tileshape, subarray, combine, correlation, intent, obs)
529 def partition(self, outputms='', field=[ ], spw=[ ], baseline=[ ], timebin=[ ], time='', scan=[ ], uvrange=[ ], taql='', whichcol='DATA', tileshape=[ ], subarray=[ ], combine='', intent='', obs=''):
530 """This function splits out part of the MS into a new MS. Time
531 averaging can be performed in the process. Unlike split, the
532 subtables and IDs (ANTENNA1, DATA_DESCRIPTION_ID, etc.) are never
533 changed to account for the selection.
535 As a side effect of that property, partition cannot select by
536 channel or correlation, or average channels. It CAN select by
537 spectral window(s).
539 """
540 return self._swigobj.partition(outputms, field, spw, baseline, timebin, time, scan, uvrange, taql, whichcol, tileshape, subarray, combine, intent, obs)
542 def summary(self, verbose=False, listfile='', listunfl=False, cachesize=float(50), overwrite=False, wantreturn=True):
543 """This method will print a summary of the measurement set to the
544 system logger. The verbose argument provides some control on how
545 much information is displayed.
547 For especially large datasets, the cachesize parameter can be
548 increased for possibly better performance.
550 This method can also return, in the header argument, a record
551 containing the following fields:
552 1. nrow Number of rows in the measurement set
553 2. name Name of the measurement set
555 DESCRIPTION OF ALGORITHM TO CALCULATE THE NUMBER OF UNFLAGGED ROWS
557 The number of unflagged rows will only be computed if listunflis
558 True. The number of unflagged rows (the nUnflRows columns in the
559 scans and fields portions of the listing) is calculated by summing
560 the fractional unflagged bandwidth for each row (and hence why the
561 number of unflagged rows, in general, is not an integer). Thus a
562 row which has half of its total bandwidth flagged contributes 0.5
563 rows to the unflagged row count. A row with 20 of 32 channels of
564 homogeneous width contributes 20/32 = 0.625 rows to the unflagged
565 row count. A row with a value of False in the FLAG_ROW column is
566 not counted in the number of unflagged rows.
568 """
569 return self._swigobj.summary(verbose, listfile, listunfl, cachesize, overwrite, wantreturn)
571 def getscansummary(self):
572 """This function will return a summary of the main table as a
573 structure
575 """
576 return self._swigobj.getscansummary()
578 def getspectralwindowinfo(self):
579 """This method will get a summary of the spectral window actually
580 used in this ms. To be precise those reference by the data
581 description table.
583 """
584 return self._swigobj.getspectralwindowinfo()
586 def getreferencedtables(self):
587 """
588 """
589 return self._swigobj.getreferencedtables()
591 def getfielddirmeas(self, dircolname='PHASE_DIR', fieldid=int(0), time=float(0), format='measure'):
592 """This function returns the direction measures from the given
593 direction column of the MS FIELD table as a either a measure
594 dictionary or sexigesimal string representation.
595 If there is an ephemeris attached, this will give you the time dependent
596 direction for the given direction column including the offset which each
597 field may have to the ephemeris it is referencing. You can use the value
598 "EPHEMERIS_DIR" for parameter "dircolname" to access the unaltered ephemeris
599 direction without any potential mosaic offsets.
601 """
602 return self._swigobj.getfielddirmeas(dircolname, fieldid, time, format)
604 def listhistory(self):
605 """This function lists the contents of the measurement set history
606 table.
608 """
609 return self._swigobj.listhistory()
611 def writehistory(self, message='', parms='', origin='MSHistoryHandler::addMessage()', msname='', app='ms'):
612 """This function adds a row to the history table of the specified
613 measurement set containing any message that the user wishes to
614 record. By default the history entry is written to the history
615 table of the measurement set that is currently open, the message
616 origin is recorded as 'MSHistoryHandler::addMessage()', the
617 originating application is 'ms' and the input parameters field is
618 empty.
620 """
621 return self._swigobj.writehistory(message, parms, origin, msname, app)
623 def writehistory_batch(self, messages=[ ], parms='', origin='MSHistoryHandler::addMessage()', msname='', app='ms'):
624 """This function works as writehistory but adds a list of messages to
625 the history table, instead of a single message. Each message is written
626 into in a new row. It is recommended for efficiency, as adding rows one
627 at a time can be rather slow, causing for example a delay of the order
628 of 10-30 seconds when writing the history at the end of a normal flagdata
629 command (with 70+ parameter rows).
631 """
632 return self._swigobj.writehistory_batch(messages, parms, origin, msname, app)
634 def statistics(self, column='', complex_value='', useflags=True, useweights=False, spw='', field='', baseline='', uvrange='', time='', correlation='', scan='', intent='', array='', obs='', reportingaxes='', timeaverage=False, timebin='0s', timespan='', maxuvwdistance=float(0.0), doquantiles=True):
635 """This function computes descriptive statistics on the measurement
636 set. It returns the statistical values as a python dictionary. The
637 given column name must be a numerical column. If it is a complex
638 valued column, the parameter complex_value defines which derived
639 real value is used for the statistics computation.
641 """
642 return self._swigobj.statistics(column, complex_value, useflags, useweights, spw, field, baseline, uvrange, time, correlation, scan, intent, array, obs, reportingaxes, timeaverage, timebin, timespan, maxuvwdistance, doquantiles)
644 def statisticsold(self, column='', complex_value='', useflags=True, spw='', field='', baseline='', uvrange='', time='', correlation='', scan='', array='', obs=''):
645 """DEPRECATED: Please use the ms::statistics() function in place of
646 ms::statisticsold().
648 This function computes descriptive statistics on the measurement
649 set. It returns the statistical values as a python dictionary. The
650 given column name must be a numerical column. If it is a complex
651 valued column, the parameter complex_value defines which derived
652 real value is used for the statistics computation.
654 """
655 return self._swigobj.statisticsold(column, complex_value, useflags, spw, field, baseline, uvrange, time, correlation, scan, array, obs)
657 def range(self, items=[ ], useflags=True, blocksize=int(10)):
658 """This function returns the range of values in the currently
659 selected measurement set for the items specified.
661 Possible items include 'amplitude', 'corrected_amplitude',
662 'model_amplitude', 'antenna1', 'antenna2', 'antennas',
663 'array_id', 'chan_freq', 'corr_names', 'corr_types', 'feed1',
664 'feed2', 'field_id', 'fields', 'float_data', 'ifr_number'
665 (1000*antenna1 + antenna2), 'imaginary', 'corrected_imaginary',
666 'model_imaginary', 'num_corr', 'num_chan', 'phase',
667 'corrected_phase', 'model_phase', 'phase_dir', 'real',
668 'corrected_real', 'model_real', 'ref_frequency', 'rows',
669 'scan_number', 'sigma', 'data_desc_id', 'time', 'times', 'u',
670 'v', 'w', 'uvdist', and 'weight'. Note that corrected, model,
671 and float versions are available only if these columns are
672 present in the data.
674 You specify items in which you are interested using a string
675 vector where each element is a case insensitive item name. This
676 function will then return a record that has fields corresponding
677 to each of the specified items. Each field will contain the
678 range of the specified item. For many items the range will be
679 the minimum and maximum values but for some it will be a list of
680 unique values. Unrecognized items are ignored.
682 By default the FLAG column is used to exclude flagged data
683 before any ranges are determined, but you can set useflags=False
684 to include flagged data in the range. However, if you average
685 in frequency, flagging will still be applied.
687 You can influence the memory use and the reading speed using
688 the blocksize argument - it specifies how big a block of data
689 to read at once (in MB). For large datasets on machines with
690 lots of memory you may speed things up by setting this higher
691 than the default (10 MB).
693 For some items, you need to call selectinit to select a portion
694 of the data with a unique shape prior to calling this function.
696 Items prefixed with corrected, model, residual or obs_residual
697 are not available unless your measurement set has been processed
698 either with the imager or calibrator tools.
700 """
701 return self._swigobj.range(items, useflags, blocksize)
703 def lister(self, options='', datacolumn='data', field='', spw='', antenna='', timerange='', correlation='', scan='', feed='', array='', observation='', uvrange='', average='', showflags=False, msselect='', pagerows=int(50), listfile=''):
704 """This tool lists measurement set visibility data under a number of
705 input selection conditions. The measurement set data columns that
706 can be listed are: the raw data, corrected data, model data, and
707 residual (corrected - model) data.
709 The output table format is dynamic. Field, Spectral Window, and
710 Channel columns are not displayed if the column contents are
711 uniform. For example, if ``spw = `1' '' is specified, the spw
712 column will not be displayed. When a column is not displayed, a
713 message is sent to the logger and terminal indicating that the
714 column values are uniform and listing the uniform value.
716 Table column descriptions:
718 Date/Time Average date and time of data sample interval
719 Intrf Interferometer baseline (antenna names)
720 UVDist uv-distance (units of wavelength)
721 Fld Field ID
722 SpW Spectral Window ID
723 Chn Channel number
724 Correlated polarization Correlated polarizations (eg: RR, LL, XY)
726 Sub-columns:
728 Amp Visibility amplitude
729 Phs Visibility phase
730 Wt Weight of visibility measurement
731 F Flag: `F' = flagged datum; ` ' = unflagged
733 """
734 return self._swigobj.lister(options, datacolumn, field, spw, antenna, timerange, correlation, scan, feed, array, observation, uvrange, average, showflags, msselect, pagerows, listfile)
736 def metadata(self, cachesize=float(50)):
737 """Get the MS metadata associated with this MS.
738 """
739 return _wrap_msmetadata(swig_object=self._swigobj.metadata(cachesize))
741 def msselect(self, items={ }, onlyparse=False):
742 """A return value of True implies that the combination of all
743 selection expressions resulted in a non-Null combined TaQL
744 expression. False implies that the combined TaQL could not be
745 formed (i.e. it is Null, and the "selected MS" will be the same as
746 the input MS).
748 The details of selection expressions are desribed in the
749 MSSelection Memo.
751 Note that this function can be called multiple times but the
752 result is cumulative. Each selection will work on the data
753 already selected from all previous calls of this function. Use
754 the function reset() to reset all selections to NULL (original
755 dataset).
757 """
758 return self._swigobj.msselect(items, onlyparse)
760 def msselectedindices(self):
761 """The return indices are the result of parsing the MSSelection
762 expressions provided in the msselect function.
764 """
765 return self._swigobj.msselectedindices()
767 def msseltoindex(self, vis='', spw=[ ], field=[ ], baseline=[ ], time=[ ], scan=[ ], uvrange=[ ], observation=[ ], polarization=[ ], taql=''):
768 """Utility function that will return the ids of the selection used.
770 """
771 return self._swigobj.msseltoindex(vis, spw, field, baseline, time, scan, uvrange, observation, polarization, taql)
773 def selectinit(self, datadescid=int(0), reset=False):
774 """A measurement set can contain data with a variety of different
775 shapes (as described in the overall description to this tool). To
776 allow functions to return data in fixed shape arrays you need to
777 select, using this function, rows that contain the same data shape.
778 You do not need to use this function if all the data in your
779 measurement set has only one shape.
781 The DATA_DESC_ID column in the measurement set contains a value
782 that maps to a particular row in the POLARIZATION and
783 SPECTRAL_WINDOW subtables. Hence all rows with the same value in
784 the DATA_DESC_ID column must have the same data shape. To select
785 all the data where the DATA_DESC_ID value is N you call this
786 function with the datadescid argument set to N.
788 It is possible to have a measurement set with differing values in
789 the DATA_DESC_ID column but where all the data is a fixed shape.
790 For example this will occur if the reference frequency changes but
791 the number of spectral channels is fixed. In cases like this all
792 the data can be selected and this function does not need to be
793 used.
795 To return to the completely unselected measurement set, set the
796 reset argument to True. This will allow you to access the full
797 range of rows in the measurement set, rather than just the
798 selected measurement set.
800 The datadescid must always be a non-negative integer.
802 """
803 return self._swigobj.selectinit(datadescid, reset)
805 def select(self, items={ }):
806 """This function will select a subset of the current measurement set
807 based on the range of values for each field in the input record.
808 The range function will return a record that can be altered and
809 used as the argument for this function. A successful selection
810 returns True. Unrecognized fields are ignored.
812 Allowable items for select include: 'antenna1', 'antenna2',
813 'array_id', 'feed1', 'feed2', 'field_id', 'ifr_number', 'rows',
814 'scan_number', 'data_desc_id', 'time', 'times', 'u', 'v', 'w',
815 and 'uvdist'.
817 You need to call selectinit before
818 calling this function. If you haven't then selectinit will be
819 called for you with default arguments.
821 Repeated use of this function, with different arguments, will
822 further refine the selection, resulting in a successively smaller
823 selected measurement set. If the selected measurement set does not
824 contain any rows then this function will return False and send a
825 warning message in the logger. Otherwise this function will return
826 True. To undo all the selections you need to use the selectinit
827 function (with reset=True).
829 """
830 return self._swigobj.select(items)
832 def selecttaql(self, msselect=''):
833 """This function will select a subset of the current measurement set
834 based on the standard TaQL selection string given.
836 Repeated use of this function, with different arguments, will
837 further refine the selection, resulting in a successively smaller
838 selected measurement set. If the selected measurement set does not
839 contain any rows then this function will return False and send a
840 warning message in the logger. Otherwise this function will return
841 True. To undo all the selections you need to use the selectinit
842 function (with reset=True). Note that index values used in the
843 TaQL string are zero-based as are all tool indices.
845 """
846 return self._swigobj.selecttaql(msselect)
848 def selectchannel(self, nchan=int(1), start=int(0), width=int(1), inc=int(1)):
849 """This function allows you to select a subset of the frequency
850 channels in the current measurement set. This function can also
851 average, over frequency channels, prior to providing the values to
852 the user.
854 Selection on channels is not allowed using either the select or
855 command functions, as they can only select entire rows in a
856 measurement set. Channel selection involves accessing only some of
857 the values in a row. Like all the selection functions, this
858 function does not change the current measurement but updates the
859 measurement set selection parameters so that functions like
860 getdata will return the desired subset of the data. Repeated use
861 of this function will overwrite any previous channel selection.
863 There are four parameters, the number of output channels, the
864 first input channel to use, the number of input channels to
865 average into one output channel, and the increment in the input
866 spectrum for the next output channel. All four parameters need to
867 be specified.
869 When all data to be averaged is unflagged, the result is the
870 averaged value and the corresponding flag is False. When all data
871 is flagged, the result is set to zero and the corresponding flag is
872 True. When data to be averaged is mixed (unflagged and flagged),
873 only the unflagged values are averaged and the flag is set to
874 False.
876 This function return True if the selection was successful, and
877 False if not. In the latter case an error message will also be sent
878 to the logger.
880 You need to call selectinit before calling this function.
881 If you haven't then selectinit will be called for you with default
882 arguments.
884 """
885 return self._swigobj.selectchannel(nchan, start, width, inc)
887 def selectpolarization(self, wantedpol=[ ]):
888 """This function allows you to select a subset of the polarizations
889 in the current measurement set. This function can also setup
890 conversion to different polarization representations.
892 You specify the polarizations using a string vector. Allowable
893 strings are include I, Q, U, V, RR, RL, LR, LL, XX, YY, XY,
894 YX. These string must be specified in upper case. If the
895 polarizations match those present in the measurement set they will
896 be selected directly, otherwise all polarizations are read and
897 then a conversion step is done. If the conversion cannot be done
898 then an error will be produced when you try to access the data.
900 This function return True if the selection was successful, and
901 False if not.
903 You need to call selectinit before calling this function.
904 If you haven't then selectinit will be called for you with default
905 arguments.
907 """
908 return self._swigobj.selectpolarization(wantedpol)
910 def statwt(self, combine='', timebin=int(1), slidetimebin=False, chanbin='spw', minsamp=int(2), statalg='classic', fence=float(-1), center='mean', lside=True, zscore=float(-1), maxiter=int(-1), fitspw='', excludechans=False, wtrange=[ ], preview=False, datacolumn='corrected'):
911 """IF NOT RUN IN PREVIEW MODE, THIS APPLICATION WILL MODIFY THE
912 WEIGHT, WEIGHT SPECTRUM, FLAG, AND FLAG_ROW COLUMNS OF THE INPUT
913 MS. IF YOU WANT A PRISTINE COPY OF THE INPUT MS TO BE PRESERVED,
914 YOU SHOULD MAKE A COPY OF IT BEFORE RUNNING THIS APPLICATION.
916 This application computes weights for the WEIGHT and
917 WEIGHT_SPECTRUM (if present) columns based on the variance of
918 values in the CORRECTED_DATA or DATA column. If the MS does not
919 have the specified data column, the application will fail. The
920 following algorithm is used:
922 1. For unflagged data in each sample, create two sets of values,
923 one set is composed solely of the real part of the data values,
924 the other set is composed solely of the imaginary part of the
925 data values.
926 2. Compute the weighted (by exposure time) variance of each of
927 these sets, v_r and v_i. The weighted variance per unit
928 inverse eposure time, v, is computed using
930 v = sum(e_i * (V_i - <V>)^2)/N,
932 where e_i is the exposure time for real/imaginary part of
933 visibility V_i and
935 <V> = sum(e_i * V_i)/sum(e_i)
937 is the weighted mean of all the visibilities in the set, and N
938 is the number of (unflagged) visibilities.
939 3. Compute v_eq = (v_r + v_i)/2.
940 4. Compute the normalized variance, v_norm = v_eq * <e>, where
942 <e> = sum(e_i)/N
944 is the mean of the exposure times. The associated weight of
945 visibility V_i is e_i/v_eq. The weight will have unit of (data
946 unit)^(-2), e.g., Jy^(-2). The visibility weights are what this
947 application computes and writes.
949 Data are aggregated on a per-baseline, per-data description ID
950 basis. Data are aggregated in bins determined by the specified
951 values of the timebin and chanbin parameters. By default, data for
952 separate correlations are aggregated separately. This behavior can
953 be overridden by specifying combine="corr" (see below).
955 RULES REGARDING CREATING/INITIALIZING WEIGHT_SPECTRUM COLUMN
957 1. If run in preview mode (preview=True), no data are modified and
958 no columns are added.
959 2. Else if datacolumn equals 'residual' or 'residual_data' and
960 a CORRECTED_DATA column exists, the WEIGHT and WEIGHT_SPECTRUM
961 columns are not modified.
962 3. Else if the MS already has a WEIGHT_SPECTRUM and this column has
963 been initialized (has values), it will be populated with
964 the new weights. The WEIGHT column will be populated with the
965 corresponding median values of the associated WEIGHT_SPECTRUM
966 array.
967 4. Else if the frequency range specified for the sample is not the
968 default ("spw"), the WEIGHT_SPECTRUM column will be created (if
969 it doesn't already exist) and the new weights will be written to
970 it. The WEIGHT column should be populated with the
971 corresponding median values of the WEIGHT_SPECTRUM array.
972 5. Otherwise the single value for each spectral window will be
973 written to the WEIGHT column; the WEIGHT_SPECTRUM column will
974 not be added if it doesn't already exist, and if it does, it
975 will remain uninitialized (no values will be written to it).
977 In cases where columns are added and initialized, the
978 WEIGHT_SPECTRUM values will be set equal to the corresponding
979 WEIGHT values, and the SIGMA_SPECTRUM values will be set to the
980 corresponding SIGMA values.
982 CAUTION: For some cases when only a subset of data is selected
983 and the WEIGHT_SPECTRUM and/or SIGMA_SPECTRUM columns are created,
984 there is a known code issue in which these columns are not properly
985 created and initialized for the specified subset of data, although
986 they are properly initialized for the entire dataset. In such cases,
987 an exception will be thrown. Because the columns are created for the
988 entire dataset, the user simply needs to rerun the statwt task using
989 the same parameters and the task should complete as expected. Should
990 this condition occur when the user is using the ms.statwt() tool
991 method, the user should close the ms tool, and then reopen it using
992 the same data set and configure the same selection, and rerun
993 ms.statwt(). The tool method should then complete as expected.
995 RULES FOR MODIFYING WEIGHT, WEIGHT_SPECTRUM, SIGMA, and SIGMA_SPECTRUM
997 1. If datacolum='corrected' or 'residual' then values are written
998 to the WEIGHT and WEIGHT_SPECTRUM (if applicable) columns only.
999 2. If datacolumn='data' or 'residual_data' and the 'CORRECTED_DATA'
1000 column does not exist, then values are written to the WEIGHT and
1001 WEIGHT_SPECTRUM (if applicable) columns and values in the SIGMA
1002 and SIGMA_SPECTRUM are set to 1/sqrt(newly computed weight). If
1003 a weight value is 0, the corresponding sigma value is -1.
1004 3. If datacolumn='data' or 'residual_data' and the 'CORRECTED_DATA'
1005 column does exist, then the WEIGHT and WEIGHT_SPECTRUM columns
1006 are not updated and values in the SIGMA and
1007 SIGMA_SPECTRUM are set to 1/sqrt(of the newly computed weight).
1008 If a weight value is 0, the corresponding sigma value is -1.
1009 In this case, you should either split out the DATA column and
1010 run statwt, or run with datacolumn='corrected' or 'residual'
1011 to update WEIGHT/WEIGHT_SPECTRUM. Otherwise the data are
1012 internally not consistent.
1014 TIME BINNING
1016 One of two algorithms can be used for time binning. If
1017 slidetimebin=True, then a sliding time bin of the specified width
1018 is used. If slidetimebin=False, then block time processing is used.
1019 The sliding time bin algorithm will generally be both more memory
1020 intensive and take longer than the block processing algorithm. Each
1021 algorithm is discussed in detail below.
1023 If the value of timebin is an integer, this value represents the
1024 number of contiguous, unique time stamps (from the MS TIME column)
1025 that should be used for averaging.
1027 Block Time Processing
1029 The data are processed in contiguous time blocks in this case. This
1030 means that all WEIGHT_SPECTRUM values will be set to the same value
1031 for all data within the same time bin/channel bin/correlation bin
1032 (see the section on channel binning and description of combine="corr"
1033 for more details on channel binning and correlation binning).
1035 If timebin is specified as a time quantity (eg, '110s'), then the
1036 time bins are not necessarily contiguous and are not necessarily the
1037 same width. The start of a bin is always coincident with a value
1038 from the TIME column, So for example, if values from the TIME column
1039 are [20s, 60s, 100s, 140s, 180s, 230s], and timebin = 110s, the
1040 first bin would start at 20s and run to 130s, so that data from
1041 timestamps 20s, 60s, and 100s will be included in the first bin. The
1042 second bin would start at 140s, so that data for timestamps 140s,
1043 180s, and 230s would be included in the second bin.
1045 In the case where timebin is an integer, this denotes the number of
1046 contigous timestamps that should be binned together. Note that, in
1047 this case, for rows "left over" in the upper edge of the bin, their
1048 values are computed using timebin that would include rows with times
1049 earlier than them. For example, in an MS with 8 rows in one block
1050 to be processed and timebin=3, timestamps 1, 2, and 3 would be used
1051 to compute the weights of the first three three rows, and rows 4, 5,
1052 and 6 would be used to compute weights for the next three rows as
1053 expected. Rows 7 and 8 are "left over" rows, but three rows (as per
1054 the integer timebin specification) are still used to compute them.
1055 Row 7 and 8 weights are computed by combining data in rows 6, 7, and 8.
1057 Sliding Time Window Processing
1059 In the sliding time window case, in the case where timebin is a time
1060 quantity, the time window is always centered on the timestamp of the
1061 row in question and extends +/-timebin/2 around that timestamp, subject
1062 the the time block boundaries.
1064 In the case where timebin is an integer, there are two cases to
1065 consider:
1067 timebin is odd: In this case the target row's data and the data from
1068 the +/-(n-1)/2 rows around the target row are also used.
1070 timebin is even: In this case, the target row's data and the data from
1071 the n/2 rows after the target row and the n/2 - 1 rows before the target
1072 row are used.
1074 When timebin is an int, for "edge" rows, the timebin extends from the
1075 edge of the block to the corresponding timebin value of rows away from
1076 the edge, so that the timebin is not symmetrical around the target rows,
1077 but includes the number of rows specified by the timebin value.
1079 OVERRIDING DEFAULT BLOCK BOUNDARIES
1081 Rows with the same baselines and data description IDs which are included
1082 in that window are used for determining the weight of that row. The
1083 boundaries of the time block to which the window is restricted are
1084 determined by changes in FIELD_ID, ARRAY_ID, and SCAN_NUMBER. One can
1085 override this behavior for FIELD_ID and/or SCAN_NUMBER by specifying the
1086 combine parameter (see below). Unlike the time block processing algorithm,
1087 this sliding time window algorithm requires that details of all rows for
1088 the time window in question are kept in memory, and thus the sliding
1089 window algorithm in general and the block processing row when timebin is
1090 an int, requires more memory than the block processing method when
1091 timebin is a quantity. Also, unlike the block processing method which
1092 computes a single value for all weights within a single bin, the sliding
1093 window method requires that each row (along with each channel and
1094 correlation bin) be processed individually, so in general the sliding
1095 window method will take longer than the block processing method.
1097 CHANNEL BINNING
1099 The width of channel bins is specified via the chanbin parameter.
1100 Channel binning occurs within individual spectral windows; bins
1101 never span multiple spectral windows. Each channel will be included
1102 in exactly one bin.
1104 The default value "spw" indicates that all channels in each
1105 spectral window are to be included in a single bin.
1107 Any other string value is interpreted as a quantity, and so should
1108 have frequency units, eg "1MHz". In this case, the channel
1109 frequencies from the CHAN_FREQ column of the SPECTRAL_WINDOW
1110 subtable of the MS are used to determine the bins. The first bin
1111 starts at the channel frequency of the 0th channel in the spectral
1112 window. Channels with frequencies that differ by less than the
1113 value specified by the chanbin parameter are included in this bin.
1114 The next bin starts at the frequency of the first channel outside
1115 the first bin, and the process is repeated until all channels have
1116 been binned.
1118 If specified as an integer, the value is interpreted as the number
1119 of channels to include in each bin. The final bin in the spectral
1120 window may not necessarily contain this number of channels. For
1121 example, if a spectral window has 15 channels, and chanbin is
1122 specified to be 6, then channels 0-5 will comprise the first bin,
1123 channels 6-11 the second, and channels 12-14 the third, so that
1124 only three channels will comprise the final bin.
1126 MINIMUM REQUIRED NUMBER OF VISIBILITIES
1128 The minsamp parameter allows the user to specify the minimum number
1129 of unflagged visibilities that must be present in a sample for that
1130 sample's weight to be computed. If a sample has less than this
1131 number of unflagged points, the associated weights of all the
1132 points in the sample are set to zero, and all the points in the
1133 sample are flagged.
1135 AGGREGATING DATA ACROSS BOUNDARIES
1137 By default, data are not aggregated across changes in values in the
1138 columns ARRAY_ID, SCAN_NUMBER, STATE_ID, FIELD_ID, and
1139 DATA_DESC_ID. One can override this behavior for SCAN_NUMBER,
1140 STATE_ID, and FIELD_ID by specifying the combine parameter. For
1141 example, specifying combine="scan" will ignore scan boundaries when
1142 aggregating data. Specifying combine="field, scan" will ignore both
1143 scan and field boundaries when aggregating data.
1145 Also by default, data for separate correlations are aggregated
1146 separately. Data for all correlations within each spectral window
1147 can be aggregated together by specifying "corr" in the combine
1148 parameter.
1150 Any combination and permutation of "scan", "field", "state", and
1151 "corr" are supported by the combine parameter. Other values will be
1152 silently ignored.
1154 STATISTICS ALGORITHMS
1156 The supported statistics algorithms are described in detail in the
1157 imstat and ia.statistics() help. For the current application, these
1158 algorithms are used to compute vr and vi (see above), such that the
1159 set of the real parts of the visibilities and the set of the
1160 imaginary parts of the visibilities are treated as independent data
1161 sets.
1163 RANGE OF ACCEPTABLE WEIGHTS
1165 The wtrange parameter allows one to specify the acceptable range
1166 (inclusive, except for zero) for weights. Data with weights
1167 computed to be outside this range will be flagged. If not specified
1168 (empty array), all weights are considered to be acceptable. If
1169 specified, the array must contain exactly two nonnegative numeric
1170 values. Note that data with weights of zero are always flagged.
1172 INCLUDING CHANNELS
1174 Channels can be included in the computation of the weights by
1175 specifying the fitspw parameter. This parameter accepts a
1176 valid MS channel selection string. Data associated with the
1177 selected channels will be used in computing the weights; all other
1178 channels will be excluded from the computation of weights. By
1179 default (empty string), all channels are included.
1181 PREVIEW MODE
1183 By setting preview=True, the application is run in "preview" mode.
1184 In this mode, no data in the input MS are changed, although the
1185 amount of data that the application would have flagged is reported.
1187 DATA COLUMN
1189 The datacolumn parameter can be specified to indicate which data
1190 column should be used for computing the weights. The values
1191 "corrected" for the CORRECTED_DATA column and "data" for the DATA
1192 column are supported (minimum match, case insensitive). One may
1193 specify 'residual' in which case the values used are the result of
1194 the CORRECTED_DATA column - model, or 'residual_data' in which
1195 case the values used are the DATA column - model, where model
1196 is the CORRECTED_DATA column if it exists, or if it doesn't,
1197 the virtual source model if one exists, or if that doesn't, then
1198 no model is used and the 'residual' and 'residual_data' cases
1199 are equivalent to the 'corrected' and 'data' cases, respectively.
1200 The last two options are to allow for operation on timescales or
1201 frequency ranges which are larger than that over which the sky
1202 signal is expected to be constant. This situation arises in eg,
1203 OTF mapping, and also perhaps with sources with significant
1204 spectral structure. In cases where a necessary column doesn't
1205 exist, an exception will be thrown and no data will be changed.
1206 NOTE: It is the user's responsibility to ensure that a model has
1207 been set for all selected fields before using datacolumn='residual'
1208 or 'residual_data'.
1210 RETURN VALUE
1212 In all cases, the mean and variance of the set of all weights computed
1213 by the application is reported and returned in a dictionary with keys
1214 'mean' and 'variance'. Weights for which there are corresponding flags
1215 (=True) prior to running the application are excluded from the
1216 computation of these statistics. If the WEIGHT_SPECTRUM values are
1217 available, they are used to compute the statistics, otherwise,
1218 the WEIGHT values are used. The returned statistics are always computed
1219 using the classic algorithm; the value of statalg has no impact on how
1220 they are computed.
1222 OTHER CONSIDERATIONS
1224 Flagged values are not used in computing the weights, although the
1225 associated weights of these values are updated.
1227 If the variance for a set of data is 0, all associated flags for
1228 that data are set to True, and the corresponding weights are set to
1229 0.
1231 Because data are modified in the input MS, the nomodify parameter
1232 must be set to False when opening the associated MS tool.
1234 """
1235 return self._swigobj.statwt(combine, timebin, slidetimebin, chanbin, minsamp, statalg, fence, center, lside, zscore, maxiter, fitspw, excludechans, wtrange, preview, datacolumn)
1237 def oldstatwt(self, dorms=False, byantenna=True, sepacs=True, fitspw=[ ], fitcorr=[ ], combine='', timebin=[ ], minsamp=int(3), field=[ ], spw=[ ], antenna='', timerange='', scan=[ ], intent='', array=[ ], correlation='', obs='', datacolumn='corrected_data'):
1238 """NOT IMPLEMENTED YET.
1240 This function estimates the noise from the scatter of the
1241 visibilities, sets SIGMA to it, and WEIGHT to SIGMA**-2.
1243 Ideally the visibilities used to estimate the scatter, as selected
1244 by fitspw and fitcorr, should be pure noise. If you know for
1245 certain that they are, then setting dorms to True will give the
1246 best result. Otherwise, use False (standard sample standard
1247 deviation). More robust scatter estimates like the interquartile
1248 range or median absolute deviation from the median are not offered
1249 because they require sorting by value, which is not possible for
1250 complex numbers.
1252 To beat down the noise of the noise estimate, the sample size per
1253 estimate can be made larger than a single spw and baseline. (Using
1254 combine='spw' is to interpolate between spws with line-free
1255 channels is recommended when an spw has no line-free channels.)
1256 timebin smooths the noise estimate over time. windowtype sets the
1257 type of time smoothing.
1259 WEIGHT and SIGMA will not be changed for samples that have fewer
1260 than minsamp visibilities. Selected visibilities for which no
1261 noise estimate is made will be flagged. Note that minsamp is
1262 effectively at least 2 if dorms is False, and 1 if it is True.
1264 """
1265 return self._swigobj.oldstatwt(dorms, byantenna, sepacs, fitspw, fitcorr, combine, timebin, minsamp, field, spw, antenna, timerange, scan, intent, array, correlation, obs, datacolumn)
1267 def regridspw(self, outframe='LSRK', mode='chan', restfreq=float(-3E30), interpolation='LINEAR', start=float(-3E30), center=float(-3E30), bandwidth=float(-1.), chanwidth=float(-1.), hanning=True):
1268 """This function permits you to transform the spectral data of your
1269 measurement set to a given reference frame. The present reference
1270 frame information in the MS is examined and the transformation
1271 performed accordingly. Since all such transformations are linear in
1272 frequency, a pure change of reference frame only affects the
1273 channel boundary definitions.
1275 In addition, the function permits you to permanently regrid the
1276 data, i.e. reduce the channel number and/or move the boundaries
1277 using several interpolation methods (selected using parameter
1278 "interpolation"). The new channels are equidistant in frequency (if
1279 parameter "mode" is chosen to be vrad or freq, or equidistant in
1280 wavelength if parameter "mode" is chosen to be vopt or wave). If
1281 "mode" is chosen to be "chan", the regridding is performed by
1282 combining the existing channels, i.e. not moving but just
1283 eliminating channel boundaries where necessary.
1285 The regridding is applied to the channel definition and all data of
1286 the MS, i.e. all columns which contain arrays whose dimensions
1287 depend on the number of channels. The input parameters are verified
1288 before any modification is made to the MS.
1290 The target reference frame can be set by providing the name of a
1291 standard reference frame (LSRK, LSRD, BARY, GALACTO, LGROUP, CMB,
1292 TOPO, GEO, or SOURCE, default = no change of frame) in parameter
1293 "outframe". For each field in the MS, the channel frequencies are
1294 transformed from their present reference frame to the one given by
1295 parameter "outframe".
1297 If the regridding parameters are set, they are interpreted in the
1298 "outframe" reference frame. The regridding is applied to the data
1299 after the reference frame transformation.
1301 """
1302 return self._swigobj.regridspw(outframe, mode, restfreq, interpolation, start, center, bandwidth, chanwidth, hanning)
1304 def cvel(self, mode='channel', nchan=int(-1), start=[ ], width=[ ], interp='linear', phasec=[ ], restfreq=[ ], outframe='', veltype='radio', hanning=True):
1305 """This function permits you to transform the spectral data of your
1306 measurement set to a given reference frame and/or regrid it. It
1307 will combine all spectral windows of the MS into one.
1309 """
1310 return self._swigobj.cvel(mode, nchan, start, width, interp, phasec, restfreq, outframe, veltype, hanning)
1312 def hanningsmooth(self, datacolumn='corrected'):
1313 """This function Hanning smooths the frequency channels with a
1314 weighted running average of:
1315 smoothedData[i] = 0.25*correctedData[i-1] + 0.50*correctedData[i]
1316 + 0.25*correctedData[i-1]
1317 The first and last channels are flagged. Inclusion of a flagged
1318 value in an average causes that averaged data value to be flagged.
1320 """
1321 return self._swigobj.hanningsmooth(datacolumn)
1323 def cvelfreqs(self, spwids=[ int(0) ], fieldids=[ int(0) ], obstime='', mode='channel', nchan=int(-1), start=[ ], width=[ ], phasec=[ ], restfreq=[ ], outframe='', veltype='radio', verbose=True):
1324 """Take the spectral grid of a given spectral window, tranform and
1325 regrid it as prescribed by the given grid parameters (same as in
1326 cvel and clean) and return the transformed values as a list. The MS
1327 is not modified. Useful for tests of gridding parameters before
1328 using them in cvel or clean.
1330 """
1331 return self._swigobj.cvelfreqs(spwids, fieldids, obstime, mode, nchan, start, width, phasec, restfreq, outframe, veltype, verbose)
1333 def contsub(self, outputms='', fitspw=[ ], fitorder=int(1), combine='', spw='*', unionspw='*', field='', scan='', intent='', correlation='', obs='', whichcol='CORRECTED_DATA'):
1334 """DEPRECATED: This function is deprecated and will be removed in an
1335 upcoming release.
1337 NOT FULLY IMPLEMENTED YET. uvcontsub uses the cb tool for now.
1338 (The only reason to implement it in ms is to save time and disk
1339 space.)
1341 This function estimates the continuum emission of the MS and writes
1342 a MS with that estimate subtracted, using the ms tool. The
1343 estimate is made, separately for the real and imaginary parts of
1344 each baseline, by fitting a low order polynomial to the unflagged
1345 visibilities selected by fitspw (depending on combine).
1347 """
1348 return self._swigobj.contsub(outputms, fitspw, fitorder, combine, spw, unionspw, field, scan, intent, correlation, obs, whichcol)
1350 def continuumsub(self, field=[ ], fitspw=[ ], spw=[ ], solint=[ ], fitorder=int(0), mode='subtract'):
1351 """DEPRECATED: This function is deprecated and will be removed in an
1352 upcoming release.
1354 This function provides a means of continuum determination and
1355 subtraction by fitting a polynomial of desired order to a subset of
1356 channels in each time-averaged uv spectrum. The fit is used to
1357 model the continuum in all channels (not just those used in the
1358 fit), for subtraction, if desired.
1360 Use the fitspw parameter to limit the spectral windows processed and
1361 the range of channels used to estimate the continuum in each (avoid
1362 channels containing spectral lines).
1364 The default solution interval 'int' will result in per-integration
1365 continuum fits for each baseline.
1367 The mode parameter indicates how the continuum model (the result of
1368 the fit) should be used:
1369 - 'subtract' will store the continuum model in the MODEL_DATA column
1370 and subtract it from the CORRECTED_DATA column
1371 - 'replace' will replace the CORRECTED_DATA column with the
1372 continuum model (useful if you want to image the continuum model
1373 result)
1374 - 'model' will only store the continuum model in the MODEL_DATA
1375 column (the CORRECTED_DATA is unaffected).
1377 It is important to start the ms tool with nomodify=False so that
1378 changes to the dataset will be allowed (see example below). For
1379 now, the only way to recover the un-subtracted CORRECTED_DATA
1380 column is to use calibrater.correct() again.
1382 Note that the MODEL_DATA and CORRECTED_DATA columns must be present
1383 for continuumsub to work correctly. The function will warn the
1384 user if they are not present, and abort. To add these scratch
1385 columns, close the ms tool, then start a calibrater or an imager
1386 tool, which will add the scratch columns. Then restart the ms
1387 tool, and try continuumsub again.
1389 """
1390 return self._swigobj.continuumsub(field, fitspw, spw, solint, fitorder, mode)
1392 def uvsub(self, reverse=False):
1393 """This function subtracts model visibility data from corrected
1394 visibility data leaving the residuals in the corrected data column.
1395 If the parameter reverse is set True, this process is reversed.
1397 """
1398 return self._swigobj.uvsub(reverse)
1400 def addephemeris(self, id=int(-1), ephemerisname='', comment='', field=[ ]):
1401 """
1402 """
1403 return self._swigobj.addephemeris(id, ephemerisname, comment, field)
1405 def timesort(self, newmsname=''):
1406 """This function sorts the main table of the measurement set by the
1407 contents of the column TIME in ascending order and writes a copy of
1408 the MS with the sorted main table into newmsfile.
1410 If no newmsname is given, a sorted copy of the MS is written into a
1411 new MS under the name x.sorted (where x is the name of the original
1412 MS). The original MS is then closed and deleted. The new MS is
1413 renamed to the name of the original MS and then reopened.
1415 """
1416 return self._swigobj.timesort(newmsname)
1418 def sort(self, newmsname='', columns=[ ]):
1419 """This function sorts the main table of the measurement set by the
1420 contents of the input set of columns in ascending order and writes
1421 a copy of the MS with the sorted main table into newmsfile.
1423 If no newmsname is given, a sorted copy of the MS is written into a
1424 new MS under the name x.sorted (where x is the name of the original
1425 MS). The original MS is then closed and deleted. The new MS is
1426 renamed to the name of the original MS and then reopened.
1428 """
1429 return self._swigobj.sort(newmsname, columns)
1431 def iterinit(self, columns=[ ], interval=float(0.0), maxrows=int(0), adddefaultsortcolumns=True):
1432 """Specify the columns to iterate over and the time interval to use
1433 for the TIME column iteration. The columns are specified by their
1434 MS column name and must contain scalar values.
1436 Note that the following default sort columns are always added to
1437 the specified columns: array_id, field_id, data_desc_id and time.
1438 This is so that the iterator can keep track of the coordinates
1439 associated with the data (field direction, frequency, etc.). If you
1440 want to sort on these columns last instead of first, you need to
1441 include them in the columns specified. If you don't want to sort on
1442 these columns at all, you can set adddefaultsortcolumns to False.
1444 You may want to use iteration for a large dataset. After calling
1445 iterinit, you must call iterorigin before attempting to retrieve
1446 data with getdata.
1448 You need to call selectinit before calling this.
1450 """
1451 return self._swigobj.iterinit(columns, interval, maxrows, adddefaultsortcolumns)
1453 def iterorigin(self):
1454 """Set or reset the iterator to the start of the currently specified
1455 iteration. You need to call this after iterinit, before attempting
1456 to retrieve data with getdata. You may also use iterorigin to set
1457 the iterator back to the start before you reach the end of the
1458 data.
1460 """
1461 return self._swigobj.iterorigin()
1463 def iternext(self):
1464 """This sets the currently selected table (as accessed with getdata)
1465 to the next iteration. If there is no more data, the function
1466 returns False and the selection is reset to that before the
1467 iteration started. You need to call iterinit and iterorigin
1468 before calling this.
1470 """
1471 return self._swigobj.iternext()
1473 def iterend(self):
1474 """This sets the currently selected table (as accessed with
1475 getdata) to the table that was selected before iteration
1476 started. Use this to end the iteration prematurely. There is no
1477 need to call this if you continue iterating until iternext
1478 returns False.
1480 See the example below.
1482 """
1483 return self._swigobj.iterend()
1485 def ngetdata(self, items=[ ], ifraxis=False, ifraxisgap=int(0), increment=int(1), average=False):
1486 """DEPRECATED: Please use the ms::getdata() function in place
1487 of ms::ngetdata().
1489 This method extracts the data as specified in the items
1490 parameter. The data is returned as a record with each item
1491 as a separate key in the record (all in lower case).
1493 Unless the iterator was initialized with a niterinit(), this
1494 method initializes the iterator as niterinit([".."],0.0,0,False).
1496 """
1497 return self._swigobj.ngetdata(items, ifraxis, ifraxisgap, increment, average)
1499 def niterinit(self, columns=[ ], interval=float(0.0), maxrows=int(0), adddefaultsortcolumns=True):
1500 """DEPRECATED: Please use the ms::iterinit() function in place
1501 of ms::niterinit().
1503 """
1504 return self._swigobj.niterinit(columns, interval, maxrows, adddefaultsortcolumns)
1506 def niterorigin(self):
1507 """DEPRECATED: Please use the ms::iterorigin() function in place
1508 of ms::niterorigin().
1510 Set or reset the iterator to the start of the currently
1511 specified iteration. You need to call this before attempting to
1512 iteratively retrieve data with ngetdata. You can set the
1513 iteration back to the start before you reach the end of the
1514 data. You need to call iterinit before calling this. See the
1515 example below.
1517 """
1518 return self._swigobj.niterorigin()
1520 def niternext(self):
1521 """DEPRECATED: Please use the ms::iternext() function in place
1522 of ms::niternext().
1524 This sets the currently selected table (as accessed with
1525 ngetdata) to the next iteration. If there is no more data, the
1526 function returns False. You need to call iterinit and
1527 iterorigin before calling this. See the example below.
1529 """
1530 return self._swigobj.niternext()
1532 def niterend(self):
1533 """DEPRECATED: Please use the ms::iterend() function in place
1534 of ms::niterend().
1536 The serves redundant purpose and is here only for backward
1537 compatibility.
1539 This method returns True if there are no more iterations left.
1540 I.e., the iterations have ended. This same information is also
1541 returned by niternext().
1543 With the use of the VisibilityIterator in the niterinit(),
1544 niterorigin(), niternext() methods, the iterator is set to the
1545 original state by calling niterinit() at any time.
1547 See the example below.
1549 """
1550 return self._swigobj.niterend()
1552 def nrowold(self, selected=False):
1553 """DEPRECATED: Please use the ms::nrow() function in place of
1554 ms::nrowold().
1556 This function returns the number of rows in the measurement
1557 set. If the optional argument selected is set to True, it returns
1558 the number of currently selected rows, otherwise it returns the
1559 the number of rows in the original measurement.
1561 """
1562 return self._swigobj.nrowold(selected)
1564 def rangeold(self, items=[ ], useflags=True, blocksize=int(10)):
1565 """DEPRECATED: Please use the ms::range() function in place of
1566 ms::rangeold().
1568 This function will return the range of values in the currently
1569 selected measurement set for the items specified. Possible items
1570 include most scalar columns, interferometer number
1571 (1000*antenna1+antenna2), uvdist(ance), u, v, w, amplitude, phase,
1572 real and imaginary components of the data (and corrected and model
1573 versions of these - if these columns are present). See the table
1574 at the top of the document to find the exact list.
1576 You specify items in which you are interested using a string
1577 vector where each element is a case insensitive item name. This
1578 function will then return a record that has fields corresponding
1579 to each of the specified items. Each field will contain the range
1580 of the specified item. For many items the range will be the
1581 minimum and maximum values but for some it will be a list of
1582 unique values. Unrecognized items are ignored.
1584 By default the FLAG column is used to exclude flagged data before
1585 any ranges are determined, but you can set useflags=False to
1586 include flagged data in the range. However, if you average in
1587 frequency, flagging will still be applied.
1589 You can influence the memory use and the reading speed using
1590 the blocksize argument - it specifies how big a block of data
1591 to read at once (in MB). For large datasets on machines with lots
1592 of memory you may speed things up by setting this higher than the
1593 default (10 MB).
1595 For some items, you need to call selectinitold to select a portion
1596 of the data with a unique shape prior to calling this function.
1598 Items prefixed with corrected, model, residual or obs_residual
1599 are not available unless your measurement set has been processed
1600 either with the imager or calibrator tools.
1602 """
1603 return self._swigobj.rangeold(items, useflags, blocksize)
1605 def selectinitold(self, datadescid=int(0), reset=False):
1606 """DEPRECATED: Please use the ms::selectinit() function in place of
1607 ms::selectinitold().
1609 A measurement set can contain data with a variety of different
1610 shapes (as described in the overall description to this tool). To
1611 allow functions to return data in fixed shape arrays you need to
1612 select, using this function, rows that contain the same data
1613 shape. You do not need to use this function if all the data in
1614 your measurement set has only one shape.
1616 The DATA_DESC_ID column in the measurement set contains a
1617 value that maps to a particular row in the POLARIZATION and
1618 SPECTRAL_WINDOW subtables. Hence all rows with the same
1619 value in the DATA_DESC_ID column must have the same data
1620 shape. To select all the data where the DATA_DESC_ID value
1621 is $N$ you call this function with the datadescid argument set to
1622 $N$.
1624 It is possible to have a measurement set with differing values in
1625 the DATA_DESC_ID column but where all the data is a fixed
1626 shape. For example this will occur if the reference frequency
1627 changes but the number of spectral channels is fixed. In cases
1628 like this all the data can be selected, using this function with
1629 an argument of zero. If the data shape does change and you call
1630 this function with an datadescid set to zero the return value will be False. In all other cases it
1631 will be True.
1633 To return to the completely unselected measurement set, set the
1634 reset argument to True. This will allow you to access the full
1635 range of rows in the measurement set, rather than just the
1636 selected measurement set.
1638 The datadescid must always be a non-negative integer.
1640 """
1641 return self._swigobj.selectinitold(datadescid, reset)
1643 def selectold(self, items={ }):
1644 """DEPRECATED: Please use the ms::select() function in place of
1645 ms::selectold().
1647 This function will select a subset of the current measurement set
1648 based on the range of values for each field in the input record.
1649 The rangeold function will return a record that can be altered and
1650 used as the argument for this function. A successful selection
1651 returns True. Unrecognized fields are ignored.
1653 Allowable items for selectold include: antenna1, antenna2,
1654 array_id, feed1, feed2, field_id, ifr_number, rows, scan_number,
1655 data_desc_id, time, times, u, v, w, and uvdist.
1657 You need to call selectinitold before
1658 calling this function. If you haven't then selectinitold will be
1659 called for you with default arguments.
1661 Repeated use of this function, with different arguments, will
1662 further refine the selection, resulting in a successively smaller
1663 selected measurement set. If the selected measurement set does not
1664 contain any rows then this function will return False and send a
1665 warning message in the logger. Otherwise this function will return
1666 True. To undo all the selections you need to use the selectinitold
1667 function (with reset=True).
1669 """
1670 return self._swigobj.selectold(items)
1672 def selecttaqlold(self, msselect=''):
1673 """DEPRECATED: Please use the ms::selecttaql() function in place of
1674 ms::selecttaqlold().
1676 This function will select a subset of the current measurement set
1677 based on the standard TaQL selection string given.
1679 Repeated use of this function, with different arguments, will
1680 further refine the selection, resulting in a successively smaller
1681 selected measurement set. If the selected measurement set does not
1682 contain any rows then this function will return False and send a
1683 warning message in the logger. Otherwise this function will return
1684 True. To undo all the selections you need to use the selectinitold
1685 function (with reset=True). Note that index values used in the TaQL
1686 string are zero-based as are all tool indices.
1689 """
1690 return self._swigobj.selecttaqlold(msselect)
1692 def selectchannelold(self, nchan=int(1), start=int(0), width=int(1), inc=int(1)):
1693 """DEPRECATED: Please use the ms::selectchannel() function in place of
1694 ms::selectchannelold().
1696 This function allows you to select a subset of the frequency
1697 channels in the current measurement set. This function can also
1698 average, over frequency channels, prior to providing the values to
1699 the user.
1701 Selection on channels is not allowed using either the select or
1702 command functions as they can only select entire rows in a
1703 measurement set. Channel selection involves accessing only some of
1704 the values in a row. Like all the selection functions this
1705 function does not change the current measurement but updates the
1706 measurement set selection parameters so that functions like
1707 getdataold will return the desired subset of the data. Repeated
1708 use of this function will overwrite any previous channel selection.
1710 There are four parameters, the number of output channels, the
1711 first input channel to use, the number of input channels to
1712 average into one output channel, and the increment in the input
1713 spectrum for the next output channel. All four parameters need to
1714 be specified.
1716 When all data to be averaged is unflagged, the result is the
1717 averaged value and the corresponding flag is False. When all data
1718 is flagged, the result is set to zero and the corresponding flag is
1719 True. When data to be averaged is mixed (unflagged and flagged),
1720 only the unflagged values are averaged and the flag is set to
1721 False.
1723 This function return True if the selection was successful, and
1724 False if not. In the latter case an error message will also be sent
1725 to the logger.
1727 You need to call selectinitold before
1728 calling this function. If you haven't then selectinitold will be
1729 called for you with default arguments.
1731 """
1732 return self._swigobj.selectchannelold(nchan, start, width, inc)
1734 def selectpolarizationold(self, wantedpol=[ ]):
1735 """DEPRECATED: Please use the ms::selectpolarization() function in
1736 place of ms::selectpolarizationold().
1738 This function allows you to select a subset of the polarizations
1739 in the current measurement set. This function can also setup
1740 conversion to different polarization representations.
1742 You specify the polarizations using a string vector. Allowable
1743 strings are include I, Q, U, V, RR, RL, LR, LL, XX, YY, XY,
1744 YX. These string must be specified in upper case. If the
1745 polarizations match those present in the measurement set they will
1746 be selected directly, otherwise all polarizations are read and
1747 then a conversion step is done. If the conversion cannot be done
1748 then an error will be produced when you try to access the data.
1750 This function return True if the selection was successful, and
1751 False if not.
1753 You need to call selectinitold before
1754 calling this function. If you haven't then selectinitold will be
1755 called for you with default arguments.
1757 """
1758 return self._swigobj.selectpolarizationold(wantedpol)
1760 def getdataold(self, items=[ ], ifraxis=False, ifraxisgap=int(0), increment=int(1), average=False):
1761 """DEPRECATED: Please use the ms::getdata() function in place
1762 of ms::getdataold().
1764 This function will read the specified items from the currently
1765 selected measurement set and returns them in fields of a record.
1766 The main difference between this and direct access of the table,
1767 using the table tool, is that this function reads data from the
1768 selected measurement set, it provides access to derived
1769 quantities like amplitude and flag_sum and it can reorder the
1770 data.
1772 The items to read are specified, as with the rangeold function,
1773 using a vector of strings. Allowable items include: amplitude,
1774 corrected_amplitude, model_amplitude, ratio_amplitude,
1775 residual_amplitude, obs_residual_amplitude, antenna1, antenna2,
1776 axis_info, data, corrected_data, model_data, ratio_data,
1777 residual_data, obs_residual_data, feed1, feed2, field_id, flag,
1778 flag_row, flag_sum, ha (added to axis_info), ifr_number, imaginary,
1779 corrected_imaginary, model_imaginary, ratio_imaginary,
1780 residual_imaginary, obs_residual_imaginary, last (added to
1781 axis_info), phase, corrected_phase, model_phase, ratio_phase,
1782 residual_phase, obs_residual_phase, real, corrected_real,
1783 ratio_real, residual_real, obs_residual_real, scan_number, sigma,
1784 data_desc_id, time, ut (added to axis_info), uvw, u, v, w, uvdist,
1785 and weight. Unrecognized items will result in a warning being sent
1786 to the logger. Duplicate items are silently ignored.
1788 The record that is returned contains fields that correspond to
1789 each of the specified items. Most fields will contain an array. The
1790 array may be one, two or three dimensional depending on whether the
1791 corresponding row in the measurement set is a scalar, one or two
1792 dimensional. Unless the ifraxis argument is set to True the length
1793 of the last axis on these arrays will correspond to the number of
1794 rows in the selected measurement set.
1796 If the ifraxis argument is set to True, the row axis is split into
1797 an interferometer axis and a time axis. For example a measurement
1798 set with 90 rows, in an array with 6 telescopes (so that there are
1799 15 interferometers), may have a data array of shape [4,32,90]
1800 if ifraxis is False or [4,32,15,6], if ifraxis is True (assuming
1801 there are 4 correlations and 32 channels). If there are missing
1802 rows as will happen if not all interferometers where used for all
1803 time-slots then a default value will be inserted.
1805 This splitting of the row axis may not happen for items where
1806 there is only a single value per row. For some items the returned
1807 vector will contain only as many values as there are
1808 interferometers and it is implicit that the same value should be
1809 used for all time slots. The antenna1, antenna2, feed1, feed2, and
1810 ifr_number items fall in this category. For other items the
1811 returned vector will have as many values as there are time slots
1812 and it is implicit that the same value should be used for all
1813 interefometers. The field_id, scan_number, data_desc_id, and
1814 time items fall into this category.
1816 The axis_info item provides data labelling information. It
1817 returns a record with the following fields: corr_axis, freq_axis,
1818 ifr_axis and time_axis. The latter two fields are not present if
1819 ifr_axis is set to False. The corr_axis field contains a string
1820 vector with elements like 'RR' or 'XY' that indicates which
1821 polarizations where correlated together to produce the data. The
1822 length of this vector will always be the same as the length of the
1823 first axis of the data array. The freq_axis field contains a record
1824 with two fields, chan_freq and resolution. Each of these fields
1825 contains vectors which indicate the centre frequency and spectral
1826 resolution (FWHM) of each channel. The length of these vectors will
1827 be the same as the length of the second axis in the data. The
1828 ifr_axis field contains fields: ifr_number, ifr_name,
1829 ifr_shortname, and baseline. The ifr_number is the same as returned
1830 by the ifr_item, the ifr_name and ifr_shortname are string vecors
1831 containing descriptions of the interferometer and the baseline is
1832 the Euclidian distance, in meters between the two antennas. All of
1833 these vectors have a length equal to the number of interferometers
1834 in the selected measurement set ie., to the length of the third
1835 axis in the data when ifraxis is True. The time_axis field contains
1836 the MJD seconds field and optionally the HA, UT, and LAST fields.
1837 To include the optional fields you need to add the ha, last or ut
1838 strings to the list of requested items. All the fields in the
1839 time_axis record contain vectors that indicate the time at the
1840 midpoint of the observation and are in seconds. The MJD seconds
1841 field is since 0 hours on the day having a modified julian day
1842 number of zero and the rest are since midnight prior to the start
1843 of the observation.
1845 An optional gap size can be specified to visually separate groups
1846 of interferometers with the same antenna1 index (handy for
1847 identifying antennas in an interferometer vs time display). The
1848 default is no gap.
1850 An optional increment can be specified to return data from every
1851 row matching the increment only.
1853 When the average flag is set, the data will be averaged over the
1854 time axis if the ifraxis is True or the row axis i.e., different
1855 interferometers and times may be averaged together. In the latter
1856 case, some of the coordinate information, like antenna_id, will
1857 no longer make sense. When all data to be averaged is unflagged,
1858 the result is the averaged value and the corresponding flag is
1859 False. When all data is flagged, the result is set to zero and the
1860 corresponding flag is True. When data to be averaged is mixed
1861 (unflagged and flagged), only the unflagged values are averaged and
1862 the flag is set to False.
1864 You need to call selectinitold before
1865 calling this function. If you haven't then selectinitold will be
1866 called for you with default arguments.
1868 Items prefixed with corrected, model, residual or obs_residual are
1869 not available unless your measurement set has been processed either
1870 with the imager or calibrator tools.
1872 """
1873 return self._swigobj.getdataold(items, ifraxis, ifraxisgap, increment, average)
1875 def putdataold(self, items={ }):
1876 """DEPRECATED: Please use the ms::putdata() function in place
1877 of ms::putdataold().
1879 This function allows you to write values from casapy variables back
1880 into the measurement set table. The main difference between this
1881 and directly accessing the table using the table tool is that this
1882 function writes data to the selected measurement set.
1884 Unlike the getdataold function you can only put items that
1885 correspond to actual table columns. You cannot change the data
1886 shape either so that the number of correlations, channels and rows
1887 (or intereferometers/time slots) must match the values in the
1888 selected measurement set. If the values were obtained using the
1889 getdataold function with ifraxis argument set to True, then any
1890 default values added to fill in missing intereferometer/timeslots
1891 pairs will be ignored when writing the modified values back using
1892 this function.
1894 Allowable items include: data, corrected_data, model_data, flag,
1895 flag_row, sigma, and weight.
1897 The measurement set has to be opened for read/write access to be
1898 able to use this function.
1900 You need to call selectinitold before
1901 calling this function. If you haven't then selectinitold will be
1902 called for you with default arguments.
1904 Items prefixed with corrected, model, residual or obs_residual are
1905 not available unless your measurement set has been processed either
1906 with the imager or calibrator tools.
1908 """
1909 return self._swigobj.putdataold(items)
1911 def iterinitold(self, columns=[ ], interval=float(0.0), maxrows=int(0), adddefaultsortcolumns=True):
1912 """DEPRECATED: Please use the ms::iterinit() function in place
1913 of ms::iterinitold().
1915 Specify the columns to iterate over and the time interval to use
1916 for the TIME column iteration. The columns are specified by their
1917 MS column name and must contain scalar values.
1919 Note that the following columns are always added to the specified
1920 columns: array_id, field_id, data_desc_id and time. This is so that
1921 the iterator can keep track of the coordinates associated with the
1922 data (field direction, frequency, etc.). If you want to sort on
1923 these columns last instead of first, you need to include them in
1924 the columns specified. If you don't want to sort on these columns
1925 at all, you can set adddefaultsortcolumns to False.
1927 You may want to use iteration for a large dataset. After calling
1928 iterinitold, you must call iteroriginold before attempting to
1929 retrieve data with getdataold.
1931 You need to call selectinitold before calling this.
1933 """
1934 return self._swigobj.iterinitold(columns, interval, maxrows, adddefaultsortcolumns)
1936 def iteroriginold(self):
1937 """DEPRECATED: Please use the ms::iterorigin() function in place
1938 of ms::iteroriginold().
1940 Set or reset the iterator to the start of the currently specified
1941 iteration. You need to call this after iterinitold, before
1942 attempting to retrieve data with getdataold. You may also use
1943 iteroriginold to set the iteration back to the start before you
1944 reach the end of the data.
1946 """
1947 return self._swigobj.iteroriginold()
1949 def iternextold(self):
1950 """DEPRECATED: Please use the ms::iternext() function in place
1951 of ms::iternextold().
1953 This sets the currently selected table (as accessed with
1954 getdataold) to the next iteration. If there is no more data, the
1955 function returns False and the selection is reset to that before
1956 the iteration started. You need to call iterinitold and
1957 iteroriginold before calling this.
1959 """
1960 return self._swigobj.iternextold()
1962 def iterendold(self):
1963 """DEPRECATED: Please use the ms::iterend() function in place
1964 of ms::iterendold().
1966 This sets the currently selected table (as accessed with
1967 getdataold) to the table that was selected
1968 before iteration started. Use this to end the iteration
1969 prematurely. There is no need to call this if you continue
1970 iterating until iternextold returns False.
1972 See the example below.
1974 """
1975 return self._swigobj.iterendold()
1977 def continuumsubold(self, field=[ ], fitspw=[ ], spw=[ ], solint=[ ], fitorder=int(0), mode='subtract'):
1978 """DEPRECATED: This function is deprecated and will be removed in an
1979 upcoming release.
1981 This function provides a means of continuum determination and
1982 subtraction by fitting a polynomial of desired order to a subset
1983 of channels in each time-averaged uv spectrum. The fit is used
1984 to model the continuum in all channels (not just those used in
1985 the fit), for subtraction, if desired. Use the fitspw parameter
1986 to limit the spectral windows processed and the range of channels
1987 used to estimate the continuum in each (avoid channels
1988 containing spectral lines). The default solution interval 'int'
1989 will result in per-integration continuum fits for each baseline.
1990 The mode parameter indicates how the continuum model (the result
1991 of the fit) should be used: 'subtract' will store the continuum
1992 model in the MODEL_DATA column and subtract it from the
1993 CORRECTED_DATA column; 'replace' will replace the CORRECTED_DATA
1994 column with the continuum model (useful if you want to image the
1995 continuum model result); and 'model' will only store the
1996 continuum model in the MODEL_DATA column (the CORRECTED_DATA is
1997 unaffected).
1999 It is important to open the dataset with nomodify=False so that
2000 changes will be allowed (see example below).
2002 For now, the only way to recover the un-subtracted CORRECTED_DATA
2003 column is to use calibrater.correct() again.
2005 Note that the MODEL_DATA and CORRECTED_DATA columns must be
2006 present for continuumsubold to work correctly. The function will
2007 warn the user if they are not present, and abort. To add these
2008 scratch columns, close the ms tool, then start a calibrater or an
2009 imager tool, which will add the scratch columns. Then restart
2010 the ms tool, and try continuumsubold again.
2012 """
2013 return self._swigobj.continuumsubold(field, fitspw, spw, solint, fitorder, mode)