Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatools/__casac__/ms.py: 51%
246 statements
« prev ^ index » next coverage.py v7.6.4, created at 2024-10-31 18:48 +0000
1# This file was automatically generated by SWIG (http://www.swig.org).
2# Version 3.0.12
3#
4# Do not make changes to this file unless you know what you are doing--modify
5# the SWIG interface file instead.
7from sys import version_info as _swig_python_version_info
8if _swig_python_version_info >= (2, 7, 0):
9 def swig_import_helper():
10 import importlib
11 pkg = __name__.rpartition('.')[0]
12 mname = '.'.join((pkg, '_ms')).lstrip('.')
13 try:
14 return importlib.import_module(mname)
15 except ImportError:
16 return importlib.import_module('_ms')
17 _ms = swig_import_helper()
18 del swig_import_helper
19elif _swig_python_version_info >= (2, 6, 0):
20 def swig_import_helper():
21 from os.path import dirname
22 import imp
23 fp = None
24 try:
25 fp, pathname, description = imp.find_module('_ms', [dirname(__file__)])
26 except ImportError:
27 import _ms
28 return _ms
29 try:
30 _mod = imp.load_module('_ms', fp, pathname, description)
31 finally:
32 if fp is not None:
33 fp.close()
34 return _mod
35 _ms = swig_import_helper()
36 del swig_import_helper
37else:
38 import _ms
39del _swig_python_version_info
41try:
42 _swig_property = property
43except NameError:
44 pass # Python < 2.2 doesn't have 'property'.
46try:
47 import builtins as __builtin__
48except ImportError:
49 import __builtin__
51def _swig_setattr_nondynamic(self, class_type, name, value, static=1):
52 if (name == "thisown"):
53 return self.this.own(value)
54 if (name == "this"):
55 if type(value).__name__ == 'SwigPyObject':
56 self.__dict__[name] = value
57 return
58 method = class_type.__swig_setmethods__.get(name, None)
59 if method:
60 return method(self, value)
61 if (not static):
62 if _newclass:
63 object.__setattr__(self, name, value)
64 else:
65 self.__dict__[name] = value
66 else:
67 raise AttributeError("You cannot add attributes to %s" % self)
70def _swig_setattr(self, class_type, name, value):
71 return _swig_setattr_nondynamic(self, class_type, name, value, 0)
74def _swig_getattr(self, class_type, name):
75 if (name == "thisown"):
76 return self.this.own()
77 method = class_type.__swig_getmethods__.get(name, None)
78 if method:
79 return method(self)
80 raise AttributeError("'%s' object has no attribute '%s'" % (class_type.__name__, name))
83def _swig_repr(self):
84 try:
85 strthis = "proxy of " + self.this.__repr__()
86 except __builtin__.Exception:
87 strthis = ""
88 return "<%s.%s; %s >" % (self.__class__.__module__, self.__class__.__name__, strthis,)
90try:
91 _object = object
92 _newclass = 1
93except __builtin__.Exception:
94 class _object:
95 pass
96 _newclass = 0
98class ms(_object):
99 """Proxy of C++ casac::ms class."""
101 __swig_setmethods__ = {}
102 __setattr__ = lambda self, name, value: _swig_setattr(self, ms, name, value)
103 __swig_getmethods__ = {}
104 __getattr__ = lambda self, name: _swig_getattr(self, ms, name)
105 __repr__ = _swig_repr
107 def __init__(self):
108 """__init__(self) -> ms"""
109 this = _ms.new_ms()
110 try:
111 self.this.append(this)
112 except __builtin__.Exception:
113 self.this = this
115 def open(self, *args, **kwargs):
116 """
117 open(self, _thems, _nomodify, _lock, _check) -> bool
121 Summary:
122 Attach the ms tool to a measurement set table
124 Description:
127 Use this function when you have detached (using the close function)
128 the ms tool from a measurement set table and wish to reattach to another
129 measurement set table.
131 If check=true, additional referential integrity checks on the MS
132 are run. If any of these fail, an exception is thrown and the MS
133 is not open (since it is not a valid MS).
136 Input Parameters:
137 thems Name of the measurement set table to open.
138 nomodify Prevent changes to the measurement set.
139 lock Lock the table for exclusive use by this tool.
140 check Run additional internal integrity checks on the MS.
142 Example:
144 ms.open('3C273XC1.MS')
145 ms.close()
146 ms.open('anotherms', nomodify=False, lock=False)
148 --------------------------------------------------------------------------------
150 """
151 return _ms.ms_open(self, *args, **kwargs)
154 def reset(self):
155 """
156 reset(self) -> bool
160 Summary:
161 Re-attach the tool to the original MS.
163 Description:
166 This function re-attaches the ms tool to the original MS,
167 effectively discarding any prior operations, in particular any
168 data selection operations using msselect function.
171 --------------------------------------------------------------------------------
173 """
174 return _ms.ms_reset(self)
177 def close(self):
178 """
179 close(self) -> bool
183 Summary:
184 Detach the ms tool from the measurement set table
186 Description:
189 This function detaches the ms tool from the associated
190 measurement set table after flushing all the cached changes.
191 After calling this function the ms tool is not associated with
192 any measurement set and using any function other than open or fromfits
193 will result in an error message being sent to the logger.
195 This function can be useful to avoid synchronization problems
196 which can occur when different processes have the same ms open.
199 Example:
201 See the example for the open function.
203 --------------------------------------------------------------------------------
205 """
206 return _ms.ms_close(self)
209 def done(self):
210 """
211 done(self) -> bool
215 Summary:
216 Closes the ms tool
218 Description:
221 You should call close() when you are finished using the ms tool
222 to close the measurement set table and free any associated file
223 locks. The measurement set is not deleted.
227 Example:
229 ms.open('3C273XC1.MS')
230 ...
231 ms.done()
233 --------------------------------------------------------------------------------
235 """
236 return _ms.ms_done(self)
239 def name(self):
240 """
241 name(self) -> string
245 Summary:
246 Name of the measurement set table the tool is attached to.
248 Description:
251 This function returns the name of the measurement set table that
252 is being manipulated. If the ms tool is not attached to any
253 measurement set, this function will return the string ``none''.
256 Example:
258 ms.open('3C273XC1.MS')
259 print 'Processing file', ms.name()
261 --------------------------------------------------------------------------------
263 """
264 return _ms.ms_name(self)
267 def iswritable(self):
268 """
269 iswritable(self) -> bool
273 Summary:
274 Returns True if the underlying Table is writable
276 Description:
279 This function returns True if the underlying MeasurementSet
280 was opened for writing/update.
283 Example:
285 ms.open('3C273XC1.MS',nomodify=False)
286 if ms.iswritable():
287 print 'MeasurementSet is writable'
288 else:
289 print 'MeasurementSet is readonly'
290 #MeasurementSet is writable
292 --------------------------------------------------------------------------------
294 """
295 return _ms.ms_iswritable(self)
298 def nrow(self, *args, **kwargs):
299 """
300 nrow(self, _selected) -> long
304 Summary:
305 Returns the number of rows in the measurement set.
307 Description:
310 This function returns the number of rows in the measurement set.
311 If the optional argument selected is set to True, it returns the
312 number of currently selected rows, otherwise it returns the
313 number of rows in the original measurement set.
316 Input Parameters:
317 selected Return number of selected rows.
319 Example:
321 ms.open('3C273XC1.MS')
322 print 'Number of rows in ms =', ms.nrow()
323 ms.msselect({'field':'3C273'})
324 print 'Number of rows in selected ms =', ms.nrow(True)
326 --------------------------------------------------------------------------------
328 """
329 return _ms.ms_nrow(self, *args, **kwargs)
332 def getdata(self, *args, **kwargs):
333 """
334 getdata(self, _items, _ifraxis, _ifraxisgap, _increment, _average) -> record *
338 Summary:
339 Read values from the measurement set.
341 Description:
344 This function reads the specified items from the currently
345 selected measurement set and returns them in fields of a record.
346 The main difference between this and direct access of the table,
347 using the table tool, is that this function reads data from the
348 selected measurement set, provides access to derived
349 quantities like amplitude and flag_sum, and can reorder the
350 data.
352 As with the ms.range function, the items to read are specified
353 using a vector of strings. Allowable items include: 'amplitude',
354 'corrected_amplitude', 'model_amplitude', 'ratio_amplitude',
355 'residual_amplitude', 'obs_residual_amplitude', 'antenna1',
356 'antenna2', 'axis_info', 'data', 'corrected_data', 'float_data',
357 'model_data', 'ratio_data', 'residual_data',
358 'obs_residual_data', 'feed1', 'feed2', 'field_id', 'flag',
359 'flag_row', 'flag_sum', 'ha' (added to 'axis_info'),
360 'ifr_number', 'imaginary', 'corrected_imaginary',
361 'model_imaginary', 'ratio_imaginary', 'residual_imaginary',
362 'obs_residual_imaginary', 'last' (added to 'axis_info'),
363 'phase', 'corrected_phase', 'model_phase', 'ratio_phase',
364 'residual_phase', 'obs_residual_phase', 'real',
365 'corrected_real', 'ratio_real', 'residual_real',
366 'obs_residual_real', 'scan_number', 'sigma', 'data_desc_id',
367 'time', 'ut' (added to 'axis_info'), 'uvw', 'u', 'v', 'w',
368 'uvdist', and 'weight'. Unrecognized items will result in a
369 warning being sent to the logger. Corrected, model, and float
370 visibilities will result in a warning if these columns do not
371 exist. Duplicate items are silently ignored.
373 Note that 'ha', 'last', and 'ut' must be requested along with
374 'axis_info' and ifraxis=True. This data will be found in a
375 subrecord of the returned record's 'axis_info' with the key in
376 uppercase. For example, for 'ut', the data is found in:
377 rec['axis_info']['time_axis']['UT']. See more information
378 about 'axis_info' below.
380 The record that is returned contains fields that correspond to
381 each of the specified items. Most fields will contain an array.
382 The array may be one, two or three dimensional depending on
383 whether the corresponding row in the measurement set is a
384 scalar, one-, or two-dimensional. Unless the ifraxis argument
385 is set to True, the length of the last axis on these arrays
386 will correspond to the number of rows in the selected
387 measurement set.
389 If the ifraxis argument is set to True, the row axis is split
390 into an interferometer axis and a time axis. For example, a
391 measurement set with 90 rows, in an array with 6 telescopes (so
392 that there are 15 interferometers), may have a data array of
393 shape [4,32,90] if ifraxis is False, or [4,32,15,6] if ifraxis
394 is True (assuming there are 4 correlations and 32 channels). If
395 there are missing rows, as will happen if not all
396 interferometers were used for all time-slots, then a default
397 value will be inserted.
399 This splitting of the row axis may not happen for items where
400 there is only a single value per row. For some items the
401 returned vector will contain only as many values as there are
402 interferometers and it is implicit that the same value should
403 be used for all time slots. The antenna1, antenna2, feed1,
404 feed2 and ifr_number items fall in this category. For other
405 items, the returned vector will have as many values as there
406 are time slots and it is implicit that the same value should be
407 used for all interferometers. The field_id, scan_number,
408 data_desc_id, and time items fall into this category.
410 The 'axis_info' item provides data labelling information. It
411 returns a record with the following fields: corr_axis,
412 freq_axis, ifr_axis, and time_axis. The latter two fields are
413 not present if ifraxis is set to False.
415 1. The corr_axis field contains a string vector with elements like
416 'RR' or 'XY' that indicates which polarizations were correlated
417 together to produce the data. The length of this vector will
418 always be the same as the length of the first axis of the data
419 array.
421 2. The freq_axis field contains a record with two fields, chan_freq
422 and resolution. Each of these fields contains vectors which
423 indicate the centre frequency and spectral resolution (FWHM)
424 of each channel. The length of these vectors will be the same
425 as the length of the second axis in the data.
427 3. The ifr_axis field contains fields: ifr_number, ifr_name,
428 ifr_shortname and baseline. The ifr_number is the same as
429 returned by the 'ifr_number' item, 1000*antenna1+antenna2.
430 The ifr_name and ifr_shortname are string vectors containing
431 descriptions of the interferometer; ifr_name contains the names
432 of the antenna pair separated by a hyphen, and ifr_shortname
433 contains the ids of the antenna pair separated by a hyphen.
434 The baseline is the Euclidian distance in meters between the two
435 antennas. All of these vectors have a length equal to the number
436 of interferometers in the selected measurement set, i.e., to the
437 length of the third axis in the data when ifraxis is True.
439 4. The time_axis field contains the MJD seconds field and
440 optionally the HA, UT, and LAST fields. To include the optional
441 fields, you need to add 'ha', 'last' or 'ut' strings to the list
442 of requested items. All of the fields in the time_axis record
443 contain vectors that indicate the time at the midpoint of the
444 observation and are in seconds. The MJD seconds field is since
445 0 hours on the day having a modified julian day number of zero
446 and the rest are since midnight prior to the start of the
447 observation.
449 An optional gap size can be specified to visually separate
450 groups of interferometers with the same antenna1 index (handy
451 for identifying antennas in an interferometer vs time display).
452 The default is no gap.
454 An optional increment can be specified to return data from every
455 row matching the increment only.
457 When the average flag is set, the data will be averaged over the
458 time axis if the ifraxis is True or the row axis i.e., different
459 interferometers and times may be averaged together. In the
460 latter case, some of the coordinate information, like
461 antenna_id, will no longer make sense. When all data to be
462 averaged is unflagged, the result is the averaged value and the
463 corresponding flag is False. When all data is flagged, the
464 result is set to zero and the corresponding flag is True. When
465 data to be averaged is mixed (unflagged and flagged), only the
466 unflagged values are averaged and the flag is set to False.
468 You need to call selectinit before calling this function.
469 If you haven't then selectinit will be called for you with
470 default arguments.
472 Items prefixed with corrected, model, residual or obs_residual
473 are not available unless your measurement set has been processed
474 either with the imager or calibrator tools.
477 Input Parameters:
478 items Item names
479 ifraxis Create interferometer axis if True.
480 ifraxisgap Gap size on ifr axis when antenna1 changes.
481 increment Row increment for data access.
482 average Average the data in time or over rows.
484 Example:
486 ms.open('3C273XC1.MS')
487 ms.selectinit(datadescid=0)
488 # Get amplitude and MJDseconds
489 d = ms.getdata(['amplitude','axis_info'], ifraxis=True)
490 tstart = min(d['axis_info']['time_axis']['MJDseconds'])
491 tstop = max(d['axis_info']['time_axis']['MJDseconds'])
492 maxamp = max(max(d['amplitude'][:,0,0,0]),
493 max(d['amplitude'][0,:,0,0]),
494 max(d['amplitude'][0,0,:,0]),
495 max(d['amplitude'][0,0,0,:]))
496 print 'MJD start time (seconds) =', tstart
497 # MJD start time (seconds) = 4121629400.0
498 print 'MJD stop time (seconds) =', tstop
499 # MJD stop time (seconds) = 4121642670.0
500 # MJDseconds Correlation amplitude
501 print 'Maximum correlation amplitude =', maxamp
502 # Maximum correlation amplitude = 33.5794372559
503 chan = 0
504 corr = 0
505 freqGHz = d['axis_info']['freq_axis']['chan_freq'][chan]/1.0E9
506 baselineStr = d['axis_info']['ifr_axis']['ifr_name'][corr]
507 corrStr = d['axis_info']['corr_axis'][corr]
508 tcoord = d['axis_info']['time_axis']['MJDseconds']
509 acoord = d['amplitude'][0,0,0,:]
510 print 'Frequency', freqGHz, 'GHz', 'Baseline', baselineStr, '(', corrStr, ')'
511 print 'MJDseconds', 'Correlation amplitude'
512 for i in range(len(tcoord)):
513 print tcoord[i], acoord[i]
514 #
515 # Frequency [ 8.085] GHz Baseline 1-2 ( RR )
516 # MJDseconds Correlation amplitude
517 # 4121629400.0 29.2170944214
518 # 4121629410.0 29.1688995361
519 # 4121629420.0 29.2497825623
520 # 4121629430.0 29.2029647827
521 # 4121629440.0 29.166015625
522 # 4121629450.0 29.2417526245
523 # 4121629460.0 29.2867794037
524 # 4121638270.0 0.0
525 # 4121638280.0 29.4539775848
526 # 4121638290.0 29.472661972
527 # 4121638300.0 29.4424362183
528 # 4121638310.0 29.4234466553
529 # 4121638320.0 29.4018745422
530 # 4121638330.0 29.3326053619
531 # 4121638340.0 29.3575496674
532 # 4121642600.0 31.1411132812
533 # 4121642610.0 31.0726108551
534 # 4121642620.0 31.1242599487
535 # 4121642630.0 31.0505466461
536 # 4121642640.0 31.0448284149
537 # 4121642650.0 30.9974422455
538 # 4121642660.0 31.0648326874
539 # 4121642670.0 31.0638961792
542 This example selects all the data from the measurement set where
543 the value in the DATA_DESC_ID column is zero. This corresponds
544 to a particular spectral window and polarization setup. It then
545 gets the correlated amplitude, and the axis information from
546 this selected measurement set. This is returned in the casapy
547 variable d. The remainder of the example prints a table of
548 'hour angle' and corresponding 'correlated amplitude' for the
549 first channel, correlation and baseline.
551 --------------------------------------------------------------------------------
553 """
554 return _ms.ms_getdata(self, *args, **kwargs)
557 def putdata(self, *args, **kwargs):
558 """
559 putdata(self, _items) -> bool
563 Summary:
564 Write new values into the measurement set.
566 Description:
569 This function allows you to write values from casapy variables
570 back into the measurement set table. The main difference between
571 this and directly accessing the table using the table tool is
572 that this function writes data to the selected measurement set.
574 Unlike the getdata function, you can only put items that
575 correspond to actual table columns. You cannot change the data
576 shape either so that the number of correlations, channels and
577 rows (or interferometers/time slots) must match the values in
578 the selected measurement set. If the values were obtained using
579 the getdata function with ifraxis argument set to True, then
580 any default values added to fill in missing
581 interferometer/timeslots pairs will be ignored when writing
582 the modified values back using this function.
584 Allowable items include: 'data', 'corrected_data',
585 'model_data', 'flag', 'flag_row', 'sigma', and 'weight'.
586 'float_data' is currently not implemented for putdata.
588 The measurement set has to be opened for read/write access
589 (nomodify=False) to be able to use this function.
591 You need to call selectinit before calling this function.
592 If you haven't then selectinit will be called for you with
593 default arguments.
595 Items prefixed with corrected, model, residual or obs_residual
596 are not available unless your measurement set has been processed
597 either with the imager or calibrator tools.
600 Input Parameters:
601 items Record with items and their new values
603 Example:
605 ms.open('3C273XC1.MS', nomodify=False)
606 ms.selectinit(datadescid=0)
607 rec = ms.getdata(['weight','data'])
608 rec['weight'][:,:] = 1
609 import numpy as np
610 meanrec = np.mean(rec['data'],axis=None)
611 print 'Mean data value = ', meanrec
612 rec['data'][:,:,:] -= meanrec
613 ms.putdata(rec)
615 This example selects all the data from the measurement set where
616 the value in the DATA_DESC_ID column is zero. This corresponds
617 to a particular spectral window and polarization setup. Note
618 that the measurement set was opened for writing as well as
619 reading. The third line reads all the weights and the data into
620 the casapy variable rec. The weights are set to one. The more
621 obscure syntax is used as typing rec['weight'] = 1 will not
622 preserve the shape of the weight array. The data then has its
623 mean subtracted from it. The mean function is defined in the
624 numpy module. Finally the data is written back into the
625 measurement set table. (NOTE: Normally one should not modify
626 the raw data column. Such adjustments are more appropriate for
627 the corrected_data column, if it exists.)
629 --------------------------------------------------------------------------------
631 """
632 return _ms.ms_putdata(self, *args, **kwargs)
635 def fromfits(self, *args, **kwargs):
636 """
637 fromfits(self, _msfile, _fitsfile, _nomodify, _lock, _obstype, _host, _forcenewserver, _antnamescheme) -> bool
641 Summary:
642 Create a measurement set from a uvfits file
644 Description:
647 This function will convert a uvfits file to a measurement set table
648 and then open the measurement set table. The newly created
649 measurement set table will continue to exist after the tool has
650 been closed.
652 Setting the lock argument to True will permanently lock the table
653 preventing other processes from writing to the measurement set.
654 Unless you expect this to happen, and want to prevent it, you
655 should leave the lock argument at the default value which implies
656 auto-locking.
658 Note that the variety of fits files that fromfits is able to
659 interpret correctly is limited mostly to files similar to those
660 produced by classic AIPS. In particular, it understands only binary
661 table extensions for the antenna (AN), frequency (FQ) and source
662 (SU) information and ignores other extensions.
664 This function returns True if it successfully attaches the ms tool
665 to a newly created Measurement Set or False if something went
666 wrong, like an error in a file name.
668 NOTE ON WEIGHTS
670 ms.fromfits() will generate a WEIGHT_SPECTRUM column in which it
671 will fill the absolute value of the weight associated with each
672 visibility in the uvfits file. Negative weights will have the
673 associated FLAGs set to True. It will compute the associated WEIGHT
674 value for that MS row to be the sum of the absolute values of the
675 associated WEIGHT_SPECTRUM values.
678 Input Parameters:
679 msfile Filename for the newly created measurement set
680 fitsfile uvfits file to read
681 nomodify Open for read access only.
682 lock Lock the table for exclusive use.
683 obstype Specify the observation type: 0=standard, 1=fastmosaic, requiring small tiles in the measurement set.
684 host Host to start ms tool on (IGNORED!!!)
685 forcenewserver Start a new server tool (IGNORED!!!).
686 antnamescheme For VLA only, antenna name scheme, old style is just antenna number, new style prepends VA or EV.
688 Example:
690 ms.fromfits('3C273XC1.MS', '3C273XC1.fits')
692 --------------------------------------------------------------------------------
694 """
695 return _ms.ms_fromfits(self, *args, **kwargs)
698 def fromfitsidi(self, *args, **kwargs):
699 """
700 fromfitsidi(self, _msfile, _fitsfile, _nomodify, _lock, _obstype) -> bool
704 Summary:
705 Create a measurement set from a fits-idi file
707 Description:
710 This function will convert a uvfits file to a measurement set table
711 and then open the measurement set table. The newly created
712 measurement set table will continue to exist after the tool has
713 been closed.
715 Setting the lock argument to True will permanently lock the table
716 preventing other processes from writing to the measurement set.
717 Unless you expect this to happen, and want to prevent it, you
718 should leave the lock argument at the default value which implies
719 auto-locking.
721 Note that the variety of fits files that fromfits is able to
722 interpret correctly is limited mostly to files similar to those
723 produced by classic AIPS. In particular, it understands only binary
724 table extensions for the antenna (AN), frequency (FQ) and source
725 (SU) information and ignores other extensions.
727 This function returns True if it successfully attachs the ms tool
728 to a newly created Measurement Set or False if something went
729 wrong, like an error in a file name.
732 Input Parameters:
733 msfile Filename for the newly created measurement set
734 fitsfile fits-idi file to read
735 nomodify Open for read access only.
736 lock Lock the table for exclusive use.
737 obstype Specify the observation type: 0=standard, 1=fastmosaic, requiring small tiles in the measurement set.
739 Example:
741 ms.fromfits('3C273XC1.MS', '3C273XC1.fits')
743 --------------------------------------------------------------------------------
745 """
746 return _ms.ms_fromfitsidi(self, *args, **kwargs)
749 def tofits(self, *args, **kwargs):
750 """
751 tofits(self, _fitsfile, _column, _field, _spw, _baseline, _time, _scan, _uvrange, _taql, _writesyscal, _multisource, _combinespw, _writestation, _padwithflags, _overwrite) -> bool
755 Summary:
756 Convert a measurement set to a uvfits file
758 Description:
761 This function writes a uvfits file that contains the data in the
762 measurement set associated with this tool. The fits file is always
763 written in floating point format and the data are always stored in
764 the primary array of the fits file.
766 IMPORTANT NOTE: In general, some of the data averaging features of
767 this method have never worked properly. In general, users should
768 run mstransform to select and average data prior to running
769 tofits(). The associated input parameters are slowly being
770 deprecated and removed.
772 If the measurement set has been imaged or calibrated in CASA, it
773 may contain additional data columns. You need to select ONE of
774 these columns to be written to the fits file. The possible
775 options are:
777 1. observed This is the raw data as collected by the telescope. All
778 interferometric measurement sets must contain this column.
779 A synonym for 'observed' is 'data'.
780 2. corrected This is the calibrated data. A synonym for 'corrected' is
781 'corrected_data'.
782 3. model This is the visibilites that would be measured using
783 the current model of the sky. A synonym for 'model' is
784 'model_data'.
786 The parsing of these strings is case insensitive. If any other
787 option is specified then the observed data will be written.
789 By default a single-source uvfits file is written, but if the
790 measurement set contains more than one field or if you set the
791 multisource argument to True a multi-source uvfits file will be
792 written. Because of limitations in the uvfits format you have to
793 ensure that the data shape is fixed for all the data you intend to
794 write to one fits file. See the general description of this tool
795 for how you can select data to meet this condition.
797 The combinespw argument is used to control whether data from
798 different spectral windows will be written as different entries in
799 the fits FQ (frequency) table or combined as different IF's
800 within one entry in the FQ table. You should normally only set
801 this to True if you know that the data from different spectral
802 windows were observed simultaneously, and the data in the
803 measurement set can be equally divided between all the spectral
804 windows (i.e. each window should have the same width). Use of
805 this switch is recommended for data to be processed in classic
806 AIPS and difmap (if possible, e.g., standard dual IF observations).
808 The padwithflags argument is only relevant if combinespw is True.
809 If true, it will fill in data that is 'missing' with flags to fit
810 the IF structure. This is appropriate if the MS had a few
811 frequency-dependent flags applied, and was then time-averaged by
812 split. If the spectral windows were observed at different times,
813 padwithflags=True will add a large number of flags, making the
814 output file significantly longer. It does not yet support spectral
815 windows with different widths.
817 The fits GC (gain curve) and TY (system temperature) tables can
818 be optionally written by setting the writesyscal argument to True.
819 This is a rather WSRT-specific operation at the moment and may not
820 work correctly for measurement sets from other telescopes.
822 One may overwrite the specified output file if it exists by
823 specifying overwrite=True.
825 NOTE ON WEIGHTS
827 If the MS has no WEIGHT_SPECTRUM column, or if it does, but that
828 column does not contain any data, ms.tofits() will compute the
829 associated weight it writes to the uvfits file by taking the
830 associated WEIGHT column value in the MS and dividing it by the
831 number of channels associated with the spectral window of that
832 visibility.
835 Input Parameters:
836 fitsfile Name of the new uvfits file.
837 column Data column to write, see above for options.
838 field Field ids (0-based) or fieldnames to split out.
839 spw Spectral windows to split.
840 baseline Antenna names or Antenna indices to select.
841 time Limit data selected to be within a given time range. Syntax is the defined in the msselection link.
842 scan Limit data selected on scan numbers. Syntax is the defined in the msselection link.
843 uvrange Limit data selected on uv distance. Syntax is the defined in the msselection link.
844 taql For the TAQL experts, flexible data selection using the TAQL syntax.
845 writesyscal Write GC and TY tables.
846 multisource Write in multisource format.
847 combinespw Export spectral windows as IFs.
848 writestation Write station name instead of antenna name.
849 padwithflags If combinespw==True, pad data with flags to fit IFs.
850 overwrite Overwrite output file if it exists?
852 Example:
854 ms.open('3C273XC1.MS')
855 ms.tofits('3C273XC1.fits', column='DATA');
856 ms.done()
858 This example writes the observed data of a measurement set to a
859 uvfits file.
862 ms.open('big.ms')
863 ms.tofits('part.fits', column='CORRECTED', field=[0,1], spw=[2])
864 ms.done()
866 This example writes part (the first two fields and the third spectral
867 window) of the corrected data to the fits file.
869 --------------------------------------------------------------------------------
871 """
872 return _ms.ms_tofits(self, *args, **kwargs)
875 def listfits(self, *args, **kwargs):
876 """
877 listfits(self, _fitsfile) -> bool
881 Summary:
884 Description:
887 List HDU and typical data rows in a uvfits file
890 Input Parameters:
891 fitsfile uvfits file to list.
893 Example:
895 ms.listfits('ngc5921.fits')
897 --------------------------------------------------------------------------------
899 """
900 return _ms.ms_listfits(self, *args, **kwargs)
903 def asdmref(self, *args, **kwargs):
904 """
905 asdmref(self, _abspath) -> string
909 Summary:
910 Test if the MS was imported with option lazy=True in importasdm and optionally change the ASDM reference.
912 Description:
915 If the MS is imported from an ASDM with option lazy=True, the DATA
916 or FLOAT_DATA column of the MS is virtual and directly reads the
917 visibilities from the ASDM. A reference to the original ASDM is
918 stored with the MS. If the ASDM needs to be moved to a different
919 path, the reference to it in the MS needs to be updated. This can
920 be achieved with ms.asdmref().
922 When called with an empty string (default), the method just reports
923 the currently set ASDM path.
925 Return value is a string containing the new path if the path was
926 successfully set or (in the case abspath was empty) the MS indeed
927 contains a ASDM reference, i.e. was lazily imported.
929 If the ASDM does not contain an ASDM reference, the method returns
930 an empty string. If abspath is not empty and there was an error
931 setting the new reference, the method throws an exception.
934 Input Parameters:
935 abspath New absolute path of the ASDM to be referenced (empty string = report current setting).
937 Example:
939 Set the path to the referenced ASDM to
940 '/home/alma/myanalysis/uid___A12345_X678_X910':
942 ms.open('uid___A12345_X678_X910.ms',False)
943 ms.asdmref('/home/alma/myanalysis/uid___A12345_X678_X910')
944 ms.close()
946 Test if the MS was imported with lazy=True and therefore references an
947 ASDM:
949 ms.open('uid___A12345_X678_X910.ms')
950 myref = ms.asdmref()
951 ms.close()
952 if myref=='':
953 print 'This MS does not reference an ASDM.'
954 else:
955 print 'This MS references the ASDM ', myref
957 --------------------------------------------------------------------------------
959 """
960 return _ms.ms_asdmref(self, *args, **kwargs)
963 def concatenate(self, *args, **kwargs):
964 """
965 concatenate(self, _msfile, _freqtol, _dirtol, _weightscale, _handling, _destmsfile, _respectname) -> bool
969 Summary:
970 Concatenate two measurement sets
972 Description:
975 This function concatenates two measurement sets together.
977 The data is copied from the measurement set specified in the
978 msfile arguement to the end of the measurement set attached to the
979 ms tool. If a lot of data needs to be copied this function may
980 take some time. You need to open the measurement set for writing
981 in order to use this function.
984 Input Parameters:
985 msfile The name of the measurement set to append.
986 freqtol Frequency difference within which 2 spectral windows are considered similar; e.g '10Hz'.
987 dirtol Direction difference within which 2 fields are considered the same; e.g '1mas'.
988 weightscale Scale the weights of the MS to be appended by this factor.
989 handling Switch for the handling of the Main and Pointing tables: 0=standard, 1=no Main, 2=no Pointing, 3=no Main and Pointing, 4=virtual.
990 destmsfile Optional support for virtual concat: empty table (no subtables) where to store the appended MS copy.
991 respectname If true, fields with a different name are not merged even if their direction agrees.
993 Example:
995 ms.open('3C273XC1.MS', nomodify=False)
996 ms.concatenate('BLLAC.ms', '1GHz', '1arcsec')
997 ms.done()
999 This example appends the data from the BLLAC measurement set to
1000 the end of the 3C273 measurement set. Its going to assume a
1001 frequency tolerance of 1GHz and position tolerance of 1 arcsec in
1002 deciding if the spw and field in the measurementsets are
1003 similar or not.
1005 --------------------------------------------------------------------------------
1007 """
1008 return _ms.ms_concatenate(self, *args, **kwargs)
1011 def testconcatenate(self, *args, **kwargs):
1012 """
1013 testconcatenate(self, _msfile, _freqtol, _dirtol, _respectname) -> bool
1017 Summary:
1018 Concatenate only the subtables of two measurement sets excluding the POINTING table (resulting MAIN and POINTING table not useful)
1020 Description:
1023 This function acts like ms.concatenate() with handling==3 (do not
1024 concatenate the MAIN and POINTING tables). This is useful for
1025 generating, e.g., SPECTRAL_WINDOW and FIELD tables which contain
1026 all used SPW and FIELD ids for a set of MSs without having to
1027 actually carry out a time-consuming concatenation on disk. The MAIN
1028 table in the resulting output MS is that of the original MS, i.e.
1029 it is not touched.
1032 Input Parameters:
1033 msfile The name of the measurement set from which the subtables should be appended.
1034 freqtol Frequency difference within which 2 spectral windows are considered similar; e.g '10Hz'.
1035 dirtol Direction difference within which 2 fields are considered the same; e.g '1mas'.
1036 respectname If true, fields with a different name are not merged even if their direction agrees.
1038 Example:
1040 tb.open('3C273XC1.MS')
1041 tb.copy('TEMP.MS', norows=True)
1042 tb.close()
1043 ms.open('TEMP.MS', nomodify=False)
1044 ms.testconcatenate('3C273XC1.ms', '1GHz', '1arcsec')
1045 ms.testconcatenate('BLLAC.ms', '1GHz', '1arcsec')
1046 ms.done()
1048 This example makes a copy of the structure of an MS and then
1049 appends the subtables data from two measurement sets to the empty
1050 structure. It will assume a frequency tolerance of 1GHz and
1051 position tolerance of 1 arcsec in deciding if the spw and field in
1052 the measurementsets are similar or not.
1054 --------------------------------------------------------------------------------
1056 """
1057 return _ms.ms_testconcatenate(self, *args, **kwargs)
1060 def virtconcatenate(self, *args, **kwargs):
1061 """
1062 virtconcatenate(self, _msfile, _auxfilename, _freqtol, _dirtol, _weightscale, _respectname) -> bool
1066 Summary:
1067 Concatenate two measurement sets virtually
1069 Description:
1072 This function virtually concatenates two measurement sets together
1073 such that they can later be turned into a multi-MS with
1074 createmultims().
1076 You need to open the measurement set for writing in order to use
1077 this function.
1080 Input Parameters:
1081 msfile The name of the measurement set to append
1082 auxfilename The name of a auxiliary file which is needed when more than two MSs are to be concatenated.
1083 freqtol Frequency difference within which 2 spectral windows are considered similar; e.g '10Hz'.
1084 dirtol Direction difference within which 2 fields are considered the same; e.g '1mas'.
1085 weightscale Scale the weights of the MS to be appended by this factor.
1086 respectname If true, fields with a different name are not merged even if their direction agrees.
1088 Example:
1090 ms.open('3C273XC1.ms', nomodify=False)
1091 ms.virtconcatenate('3C273XC1-2.ms', '3Caux.dat', '1GHz', '1arcsec')
1092 ms.virtconcatenate('3C273XC1-3.ms', '3Caux.dat', '1GHz', '1arcsec')
1093 ms.close()
1094 os.remove('3Caux.dat')
1095 ms.createmultims(concatvis,
1096 ['3C273XC1.ms','3C273XC1-2.ms','3C273XC1-3.ms'],
1097 [],
1098 True, # nomodify
1099 False,# lock
1100 True) # copysubtables from first to all other members
1101 ms.close()
1103 This example virtually appends the data from the 3C273XC1-2 and
1104 3C273XC1-3 to the end of the 3C273XC1 measurement set. Its going to
1105 assume a frequency tolerance of 1GHz and position tolerance of 1
1106 arcsec in deciding if the spw and field in the measurementsets are
1107 similar or not. The file 3Caux.dat which is created in the process
1108 is no longer needed after the last call to virtconcatenate() and
1109 can be deleted.
1111 --------------------------------------------------------------------------------
1113 """
1114 return _ms.ms_virtconcatenate(self, *args, **kwargs)
1117 def createmultims(self, *args, **kwargs):
1118 """
1119 createmultims(self, _outputTableName, _tables, _subtables, _nomodify, _lock, _copysubtables, _omitsubtables) -> bool
1123 Summary:
1126 Description:
1131 Input Parameters:
1132 outputTableName
1133 tables
1134 subtables
1135 nomodify Prevent changes to the measurement set.
1136 lock Lock the table for exclusive use by this tool.
1137 copysubtables Copy the subtables from the first to all other member MSs.
1138 omitsubtables Omit the subtables from this list when copying subtables.
1140 --------------------------------------------------------------------------------
1142 """
1143 return _ms.ms_createmultims(self, *args, **kwargs)
1146 def ismultims(self):
1147 """
1148 ismultims(self) -> bool
1152 Summary:
1155 Description:
1160 --------------------------------------------------------------------------------
1162 """
1163 return _ms.ms_ismultims(self)
1166 def split(self, *args, **kwargs):
1167 """
1168 split(self, _outputms, _field, _spw, _step, _baseline, _timebin, _time, _scan, _uvrange, _taql, _whichcol, _tileshape, _subarray, _combine, _correlation, _intent, _obs) -> bool
1172 Summary:
1173 make a new ms from a subset of an existing ms, adjusting subtables and indices
1175 Description:
1178 This function splits out part of the MS into a new MS. Time and
1179 channel averaging can be performed in the process (but not in
1180 the same call).
1182 When splitting multiple spectral windows, the parameters nchan,
1183 start, and step can be vectors, so that each spectral window has
1184 its own selection on averaging and number of output channels. But
1185 the option of using only one value for each of these parameters
1186 means that it will be replicated for all the spectral windows
1187 selected.
1190 Input Parameters:
1191 outputms The name of the resulting measurement set
1192 field Fields to include, by names or 0-based ids. ('' => all).
1193 spw Spectral windows (and :channels) to select.
1194 step Number of input per output channels - Int vector of length 1 or same as spw.
1195 baseline Antenna names or indices to select ('' => all).
1196 timebin Duration for averaging. Defaults to no averaging.
1197 time Only use data in the given time range, using the msselection syntax.
1198 scan Only use the scan numbers requested using the msselection syntax.
1199 uvrange Limit data by uv distance using the msselection syntax.
1200 taql For the TAQL experts, flexible data selection using the TAQL syntax
1201 whichcol 'DATA', 'MODEL_DATA', 'CORRECTED_DATA', 'FLOAT_DATA', 'LAG_DATA', and/or 'all'.
1202 tileshape Tile shape of the disk data columns, most users should not need to touch this parameter. [0] => normal tiling, [1] => fast mosaic style tile, [4,15,351] => a tile shape of 4 pol 15 chan and 351 rows
1203 subarray Limit data to specific (sub)array numbers.
1204 combine Ignore changes in these columns (scan, and/or state) when time averaging.
1205 correlation Limit data to specific correlations (LL, XX, LR, XY, etc.).
1206 intent Only use the requested scan intents.
1207 obs Only use the requested observation IDs.
1209 Example:
1211 ms.open('multiwin.ms')
1212 ms.split('subms.ms', field=[0], spw=[0], nchan=[10],
1213 start=[0], step=[5], whichcol='CORRECTED_DATA')
1215 In this example we split out data from the first field and first
1216 spectral window. The output data will have 10 channels which is
1217 taken from 50 channels from the input data starting at channel 0
1218 and averaging every 5.
1220 ms.open('multiwin.ms')
1221 ms.split('subms.ms', field=[0], spw=[0,1,2,3], nchan=[10],
1222 start=[0], step=[5], whichcol='CORRECTED_DATA')
1224 In this example we split out data from the 1st field and four
1225 spectral windows. The output data will have 4 spectral windows each
1226 of 10 channels which is taken from 50 channels from the input data
1227 starting at channel 0 and averaging every 5.
1229 ms.open('multiwin.ms')
1230 ms.split('subms.ms', field=[0], spw=[0,1,2,3],
1231 nchan=[10,10,30,40], start=[0,4,9,9], step=[1,10,5,2],
1232 whichcol='CORRECTED_DATA')
1234 In this example we split out data from the 1st field and four
1235 spectral windows. There will be four spectral windows in the output
1236 data, with 10, 10, 30 and 40 channels respectively. These are
1237 averages of the input spectral windows. The first output spectral
1238 window will be formed by picking 10 channels, starting at 0 with no
1239 averaging, of the input spwid 0. The second output spectral window
1240 will consists of 10 channels and is formed by picking 100 channels
1241 from spwid 1 of the input data, starting at channel 4, and every
1242 10 channels to make one output channel.
1244 ms.open('WSRT.ms')
1245 ms.split('subms.ms', timebin='20s', whichcol='all',
1246 combine='scan')
1247 ms.close()
1249 This example averages a WSRT MS into 20s bins, selecting whichever
1250 of DATA, MODEL_DATA, CORRECTED_DATA, or FLOAT_DATA, or LAG_DATA is
1251 present. Normally the bins would not cross scans, but in this MS
1252 the scan number goes up with each integration, making it redundant
1253 enough with time that it would defeat any time averaging.
1254 Therefore the combine parameter forces the SCAN column to be
1255 ignored for setting the bins.
1257 --------------------------------------------------------------------------------
1259 """
1260 return _ms.ms_split(self, *args, **kwargs)
1263 def partition(self, *args, **kwargs):
1264 """
1265 partition(self, _outputms, _field, _spw, _baseline, _timebin, _time, _scan, _uvrange, _taql, _whichcol, _tileshape, _subarray, _combine, _intent, _obs) -> bool
1269 Summary:
1270 make a new ms from a subset of an existing ms, without changing any subtables
1272 Description:
1275 This function splits out part of the MS into a new MS. Time
1276 averaging can be performed in the process. Unlike split, the
1277 subtables and IDs (ANTENNA1, DATA_DESCRIPTION_ID, etc.) are never
1278 changed to account for the selection.
1280 As a side effect of that property, partition cannot select by
1281 channel or correlation, or average channels. It CAN select by
1282 spectral window(s).
1285 Input Parameters:
1286 outputms The name of the resulting measurement set.
1287 field Fields to include, by names or 0-based ids. ('' => all).
1288 spw Spectral windows (and :channels) to select.
1289 baseline Antenna names or indices to select ('' => all).
1290 timebin Duration for averaging. Defaults to no averaging.
1291 time Only use data in the given time range, using the msselection syntax.
1292 scan Only use the scan numbers requested using the msselection syntax.
1293 uvrange Limit data by uv distance using the msselection syntax.
1294 taql For the TAQL experts, flexible data selection using the TAQL syntax.
1295 whichcol 'DATA', 'MODEL_DATA', 'CORRECTED_DATA', 'FLOAT_DATA', 'LAG_DATA', and/or 'all'.
1296 tileshape Tile shape of the disk data columns, most users should not need to touch this parameter [0] => normal tiling, [1] => fast mosaic style tile, [4,15,351] => a tile shape of 4 pol 15 chan and 351 rows.
1297 subarray Limit data to specific (sub)array numbers.
1298 combine Ignore changes in these columns (scan, and/or state) when time averaging.
1299 intent Only use the requested scan intents.
1300 obs Only use the requested observation IDs.
1302 Example:
1304 ms.open('multiwin.ms')
1305 ms.partition('partition.ms', field=[0], spw=[1],
1306 whichcol='CORRECTED_DATA')
1308 In this example we partition out data from the first field and
1309 second spectral window. Only the CORRECTED_DATA data column will
1310 be copied, and it will be written to the DATA column of
1311 partition.ms.
1313 ms.open('multiwin.ms')
1314 ms.partition('partition.ms', field=[0], spw=[0,1,2,3],
1315 whichcol='CORRECTED_DATA')
1317 In this example we partition out calibrated data from the first field
1318 and four spectral windows.
1320 ms.open('WSRT.ms')
1321 ms.partition('partition.ms', timebin='20s', whichcol='all',
1322 combine='scan')
1323 ms.close()
1325 This example averages a WSRT MS into 20s bins, selecting whichever
1326 of DATA, MODEL_DATA, CORRECTED_DATA, or FLOAT_DATA, or LAG_DATA is
1327 present. Normally the bins would not cross scans, but in this MS
1328 the scan number goes up with each integration, making it redundant
1329 enough with time that it would defeat any time averaging. Therefore
1330 combine parameter forces the SCAN column to be ignored for setting
1331 the bins.
1333 --------------------------------------------------------------------------------
1335 """
1336 return _ms.ms_partition(self, *args, **kwargs)
1339 def summary(self, *args, **kwargs):
1340 """
1341 summary(self, _verbose, _listfile, _listunfl, _cachesize, _overwrite, _wantreturn) -> record *
1345 Summary:
1346 (PARTIALLY IMPLEMENTED!!!) Summarize the measurement set
1348 Description:
1351 This method will print a summary of the measurement set to the
1352 system logger. The verbose argument provides some control on how
1353 much information is displayed.
1355 For especially large datasets, the cachesize parameter can be
1356 increased for possibly better performance.
1358 This method can also return, in the header argument, a record
1359 containing the following fields:
1360 1. nrow Number of rows in the measurement set
1361 2. name Name of the measurement set
1363 DESCRIPTION OF ALGORITHM TO CALCULATE THE NUMBER OF UNFLAGGED ROWS
1365 The number of unflagged rows will only be computed if listunflis
1366 True. The number of unflagged rows (the nUnflRows columns in the
1367 scans and fields portions of the listing) is calculated by summing
1368 the fractional unflagged bandwidth for each row (and hence why the
1369 number of unflagged rows, in general, is not an integer). Thus a
1370 row which has half of its total bandwidth flagged contributes 0.5
1371 rows to the unflagged row count. A row with 20 of 32 channels of
1372 homogeneous width contributes 20/32 = 0.625 rows to the unflagged
1373 row count. A row with a value of False in the FLAG_ROW column is
1374 not counted in the number of unflagged rows.
1377 Input Parameters:
1378 verbose Produce verbose logging output.
1379 listfile Output file.
1380 listunfl List unflagged row counts? If true, it can have significant negative performance impact.
1381 cachesize EXPERIMENTAL. Maximum size in megabytes of cache in which data structures can be held.
1382 overwrite If True, tacitly overwrite listfile if it exists.
1383 wantreturn If true, construct a record containing summary info and return it, else return nothing. If you don't need the record and just want the log output, setting this to False will provide a small performance increase.
1385 Example:
1387 ms.open('3C273XC1.MS')
1388 outr=ms.summary(verbose=True)
1389 ###print the begining of observation in this ms
1390 print qa.time(qa.quantity(outr['header']['BeginTime'],'d'),
1391 form='ymd')
1392 ###print a dictionary of the info of scan 1
1393 outr['header']['scan_1']
1395 This example will send a verbose summary of the measurement set to
1396 the logger.
1398 --------------------------------------------------------------------------------
1400 """
1401 return _ms.ms_summary(self, *args, **kwargs)
1404 def getscansummary(self):
1405 """
1406 getscansummary(self) -> record *
1410 Summary:
1411 Get the summary of the ms
1413 Description:
1416 This function will return a summary of the main table as a
1417 structure
1420 Example:
1422 ms.open('3C273XC1.MS')
1423 scanInfo = ms.getscansummary()
1425 --------------------------------------------------------------------------------
1427 """
1428 return _ms.ms_getscansummary(self)
1431 def getspectralwindowinfo(self):
1432 """
1433 getspectralwindowinfo(self) -> record *
1437 Summary:
1438 Get a summary of the spectral windows
1440 Description:
1443 This method will get a summary of the spectral window actually
1444 used in this ms. To be precise those reference by the data
1445 description table.
1448 Example:
1450 ms.open('3C273XC1.MS')
1451 spwInfo = ms.getspectralwindowinfo()
1453 --------------------------------------------------------------------------------
1455 """
1456 return _ms.ms_getspectralwindowinfo(self)
1459 def getreferencedtables(self):
1460 """
1461 getreferencedtables(self) -> std::vector< std::string >
1465 Summary:
1468 Description:
1473 --------------------------------------------------------------------------------
1475 """
1476 return _ms.ms_getreferencedtables(self)
1479 def getfielddirmeas(self, *args, **kwargs):
1480 """
1481 getfielddirmeas(self, _dircolname, _fieldid, _time, _format) -> variant *
1485 Summary:
1486 Returns the direction measure from the given FIELD table column and row
1488 Description:
1491 This function returns the direction measures from the given
1492 direction column of the MS FIELD table as a either a measure
1493 dictionary or sexigesimal string representation.
1494 If there is an ephemeris attached, this will give you the time dependent
1495 direction for the given direction column including the offset which each
1496 field may have to the ephemeris it is referencing. You can use the value
1497 'EPHEMERIS_DIR' for parameter 'dircolname' to access the unaltered ephemeris
1498 direction without any potential mosaic offsets.
1501 Input Parameters:
1502 dircolname Name of the direction column in the FIELD table or 'EPHEMERIS_DIR'.
1503 fieldid Field ID, starting at 0.
1504 time (optional) Time for ephemeris access (in seconds, as in Main table TIME column).
1505 format Output format. Either 'measure' (measure dictionary) or 'string' (sexigesimal representation). Minimum match supported.
1507 Example:
1509 ms.open('3C273XC1.MS')
1510 print 'Delay direction from FIELD table row 3 =', ms.getfielddirmeas('DELAY_DIR', 3)
1512 print 'Phase direction from ephemeris FIELD table row 4 for time = 5019988459.968 s', ms.getfielddirmeas('PHASE_DIR', 4, 5019988459.968)
1514 --------------------------------------------------------------------------------
1516 """
1517 return _ms.ms_getfielddirmeas(self, *args, **kwargs)
1520 def listhistory(self):
1521 """
1522 listhistory(self) -> bool
1526 Summary:
1527 List history of the measurement set
1529 Description:
1532 This function lists the contents of the measurement set history
1533 table.
1536 Example:
1538 ms.open('3C273XC1.MS')
1539 ms.listhistory()
1541 The history table contents are listed in the logger.
1543 --------------------------------------------------------------------------------
1545 """
1546 return _ms.ms_listhistory(self)
1549 def writehistory(self, *args, **kwargs):
1550 """
1551 writehistory(self, _message, _parms, _origin, _msname, _app) -> bool
1555 Summary:
1556 Add a row of arbitrary information to the measurement set history table
1558 Description:
1561 This function adds a row to the history table of the specified
1562 measurement set containing any message that the user wishes to
1563 record. By default the history entry is written to the history
1564 table of the measurement set that is currently open, the message
1565 origin is recorded as 'MSHistoryHandler::addMessage()', the
1566 originating application is 'ms' and the input parameters field is
1567 empty.
1570 Input Parameters:
1571 message Message to be recorded in message field.
1572 parms String to be written to input parameter field.
1573 origin String to be written to origin field.
1574 msname Name of selected measurement set.
1575 app String to be written to application field.
1577 Example:
1579 ms.open('3C273XC1.MS')
1580 ms.writehistory('an arbitrary history message')
1581 ms.listhistory()
1583 A row is appended to the measurement set history table.
1585 --------------------------------------------------------------------------------
1587 """
1588 return _ms.ms_writehistory(self, *args, **kwargs)
1591 def writehistory_batch(self, *args, **kwargs):
1592 """
1593 writehistory_batch(self, _messages, _parms, _origin, _msname, _app) -> bool
1597 Summary:
1598 Add one or more rows of arbitrary information to the measurement set history table
1600 Description:
1603 This function works as writehistory but adds a list of messages to
1604 the history table, instead of a single message. Each message is written
1605 into in a new row. It is recommended for efficiency, as adding rows one
1606 at a time can be rather slow, causing for example a delay of the order
1607 of 10-30 seconds when writing the history at the end of a normal flagdata
1608 command (with 70+ parameter rows).
1611 Input Parameters:
1612 messages Message to be recorded in message field.
1613 parms String to be written to input parameter field.
1614 origin String to be written to origin field.
1615 msname Name of selected measurement set.
1616 app String to be written to application field.
1618 Example:
1620 ms.open('3C273XC1.MS')
1621 ms.writehistory_batch(['message 1', 'message 2', 'message 3'])
1622 ms.listhistory()
1624 One or more rows are appended to the measurement set history table.
1626 --------------------------------------------------------------------------------
1628 """
1629 return _ms.ms_writehistory_batch(self, *args, **kwargs)
1632 def statistics(self, *args, **kwargs):
1633 """
1634 statistics(self, _column, _complex_value, _useflags, _useweights, _spw, _field, _baseline, _uvrange, _time, _correlation, _scan, _intent, _array, _obs, _reportingaxes, _timeaverage, _timebin, _timespan, _maxuvwdistance, _doquantiles) -> record *
1638 Summary:
1639 Get statistics on the selected measurement set
1641 Description:
1644 This function computes descriptive statistics on the measurement
1645 set. It returns the statistical values as a python dictionary. The
1646 given column name must be a numerical column. If it is a complex
1647 valued column, the parameter complex_value defines which derived
1648 real value is used for the statistics computation.
1651 Input Parameters:
1652 column Column name
1653 complex_value Which derived value to use for complex columns (amp, amplitude, phase, imag, real, imaginary)
1654 useflags Use the data flags.
1655 useweights Use the data weights.
1656 spw Spectral Window Indices or names. Example : '1,2'
1657 field Field indices or source names. Example : '2,3C48'
1658 baseline Baseline number(s). Example: '2&3;4&5'
1659 uvrange UV-distance range, with a unit. Example : '2.0-3000.0 m'
1660 time Time range, as MJDs or date strings. Example : 'xx.x.x.x.x~yy.y.y.y.y'
1661 correlation Correlations/polarizations. Example : 'RR,LL,RL,LR,XX,YY,XY,YX'
1662 scan Scan number. Example : '1,2,3'
1663 intent Scan intents. Example : '*AMPL*,*PHASE*'
1664 array Array Indices or names. Example : 'VLAA'
1665 obs Observation ID(s). Examples : '' or '1~3'
1666 reportingaxes Statistics reporting axes. Example: 'ddid,field'
1667 timeaverage Average data in time.
1668 timebin Time averaging interval.
1669 timespan Boundaries to ignore in time averaging. Example: 'scan,state'
1670 maxuvwdistance Maximum separation of start-to-end baselines that can be included in an average. (meters)
1671 doquantiles If False, quantile-like statistics are not computed. These include the first and third quartiles, the median, and the median of the absolute deviation from the median.
1673 Example:
1675 ms.open('3C273XC1.MS')
1676 ms.statistics(column='DATA', complex_value='amp', field='2')
1678 --------------------------------------------------------------------------------
1680 """
1681 return _ms.ms_statistics(self, *args, **kwargs)
1684 def statisticsold(self, *args, **kwargs):
1685 """
1686 statisticsold(self, _column, _complex_value, _useflags, _spw, _field, _baseline, _uvrange, _time, _correlation, _scan, _array, _obs) -> record *
1690 Summary:
1691 Get statistics on the selected measurement set
1693 Description:
1696 DEPRECATED: Please use the ms::statistics() function in place of
1697 ms::statisticsold().
1699 This function computes descriptive statistics on the measurement
1700 set. It returns the statistical values as a python dictionary. The
1701 given column name must be a numerical column. If it is a complex
1702 valued column, the parameter complex_value defines which derived
1703 real value is used for the statistics computation.
1706 Input Parameters:
1707 column Column name.
1708 complex_value Which derived value to use for complex columns (amp, amplitude, phase, imag, real, imaginary).
1709 useflags Use the data flags.
1710 spw Spectral Window Indices or names. Example : '1,2'
1711 field Field indices or source names. Example : '2,3C48'
1712 baseline Baseline number(s). Example: '2&3;4&5'
1713 uvrange UV-distance range, with a unit. Example : '2.0-3000.0 m'
1714 time Time range, as MJDs or date strings. Example : 'xx.x.x.x.x~yy.y.y.y.y'
1715 correlation Correlations/polarizations. Example : 'RR,LL,RL,LR,XX,YY,XY,YX'
1716 scan Scan number. Example : '1,2,3'
1717 array Array Indices or names. Example : 'VLAA'
1718 obs Observation ID(s). Examples : '' or '1~3'
1720 Example:
1722 ms.open('3C273XC1.MS')
1723 ms.statisticsold(column='DATA', complex_value='amp', field='2')
1725 --------------------------------------------------------------------------------
1727 """
1728 return _ms.ms_statisticsold(self, *args, **kwargs)
1731 def range(self, *args, **kwargs):
1732 """
1733 range(self, _items, _useflags, _blocksize) -> record *
1737 Summary:
1738 Get the range of values in the measurement set.
1740 Description:
1743 This function returns the range of values in the currently
1744 selected measurement set for the items specified.
1746 Possible items include 'amplitude', 'corrected_amplitude',
1747 'model_amplitude', 'antenna1', 'antenna2', 'antennas',
1748 'array_id', 'chan_freq', 'corr_names', 'corr_types', 'feed1',
1749 'feed2', 'field_id', 'fields', 'float_data', 'ifr_number'
1750 (1000*antenna1 + antenna2), 'imaginary', 'corrected_imaginary',
1751 'model_imaginary', 'num_corr', 'num_chan', 'phase',
1752 'corrected_phase', 'model_phase', 'phase_dir', 'real',
1753 'corrected_real', 'model_real', 'ref_frequency', 'rows',
1754 'scan_number', 'sigma', 'data_desc_id', 'time', 'times', 'u',
1755 'v', 'w', 'uvdist', and 'weight'. Note that corrected, model,
1756 and float versions are available only if these columns are
1757 present in the data.
1759 You specify items in which you are interested using a string
1760 vector where each element is a case insensitive item name. This
1761 function will then return a record that has fields corresponding
1762 to each of the specified items. Each field will contain the
1763 range of the specified item. For many items the range will be
1764 the minimum and maximum values but for some it will be a list of
1765 unique values. Unrecognized items are ignored.
1767 By default the FLAG column is used to exclude flagged data
1768 before any ranges are determined, but you can set useflags=False
1769 to include flagged data in the range. However, if you average
1770 in frequency, flagging will still be applied.
1772 You can influence the memory use and the reading speed using
1773 the blocksize argument - it specifies how big a block of data
1774 to read at once (in MB). For large datasets on machines with
1775 lots of memory you may speed things up by setting this higher
1776 than the default (10 MB).
1778 For some items, you need to call selectinit to select a portion
1779 of the data with a unique shape prior to calling this function.
1781 Items prefixed with corrected, model, residual or obs_residual
1782 are not available unless your measurement set has been processed
1783 either with the imager or calibrator tools.
1786 Input Parameters:
1787 items Item names.
1788 useflags Use the data flags.
1789 blocksize Set the blocksize in MB.
1791 Example:
1793 ms.open('3C273XC1.MS')
1794 ms.selectinit(datadescid=0)
1795 ms.range(['time','uvdist','amplitude','antenna1'])
1796 #{'amplitude': array([ 2.60339398e-02, 3.38518333e+01]),
1797 # 'antenna1': array([ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
1798 # 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25,
1799 # 26]),
1800 # 'time': array([ 4.12162940e+09, 4.12164267e+09]),
1801 # 'uvdist': array([ 46.26912101, 3727.97385983])}
1803 In this example the minimum and maximum observation times,
1804 uvdistances, data amplitudes are returned as well as a list of
1805 all the antennas in the antenna1 column.
1807 For this dataset the selectinit function did not need to be
1808 called as all the data is of one shape.
1810 --------------------------------------------------------------------------------
1812 """
1813 return _ms.ms_range(self, *args, **kwargs)
1816 def lister(self, *args, **kwargs):
1817 """
1818 lister(self, _options, _datacolumn, _field, _spw, _antenna, _timerange, _correlation, _scan, _feed, _array, _observation, _uvrange, _average, _showflags, _msselect, _pagerows, _listfile) -> bool
1822 Summary:
1823 List measurement set visibilities
1825 Description:
1828 This tool lists measurement set visibility data under a number of
1829 input selection conditions. The measurement set data columns that
1830 can be listed are: the raw data, corrected data, model data, and
1831 residual (corrected - model) data.
1833 The output table format is dynamic. Field, Spectral Window, and
1834 Channel columns are not displayed if the column contents are
1835 uniform. For example, if ``spw = `1' '' is specified, the spw
1836 column will not be displayed. When a column is not displayed, a
1837 message is sent to the logger and terminal indicating that the
1838 column values are uniform and listing the uniform value.
1840 Table column descriptions:
1842 Date/Time Average date and time of data sample interval
1843 Intrf Interferometer baseline (antenna names)
1844 UVDist uv-distance (units of wavelength)
1845 Fld Field ID
1846 SpW Spectral Window ID
1847 Chn Channel number
1848 Correlated polarization Correlated polarizations (eg: RR, LL, XY)
1850 Sub-columns:
1852 Amp Visibility amplitude
1853 Phs Visibility phase
1854 Wt Weight of visibility measurement
1855 F Flag: `F' = flagged datum; ` ' = unflagged
1858 Input Parameters:
1859 options Output options (not yet implemented)
1860 datacolumn Column to list: data, model, corrected, residual
1861 field Fields
1862 spw Spectral Windows
1863 antenna Antenna/Baselines
1864 timerange Time range
1865 correlation Polarization correlations
1866 scan Scan
1867 feed Feed (not yet implemented)
1868 array Array
1869 observation Select by observation ID(s)
1870 uvrange uv-distance (output units: wavelength)
1871 average Average mode (not yet implemented)
1872 showflags Showflags (not yet implemented)
1873 msselect TaQL expression
1874 pagerows Rows per page
1875 listfile Output file
1877 Example:
1879 ms.open('AZ136.ms')
1880 ms.lister()
1882 These commands yield the following listing:
1884 Date/Time: RR: RL: LR: LL:
1885 2001/12/01/ Intrf UVDist Fld SpW Amp Phs Wt F Amp Phs Wt F Amp Phs Wt F Amp Phs Wt F
1886 ------------|-----|------|---|---|-------------------------|------------------------|------------------------|------------------------
1887 19:30:05.0 0- 1 1400 0 0: 0.002-102.7 229035 F 0.003-178.3 239694 F 0.001 136.0 208264 F 0.001 -79.7 263599 F
1888 19:30:05.0 0- 2 7203 0 0: 0.002 127.3 267464 F 0.001 165.0 305192 F 0.003-118.2 265174 F 0.002 16.3 307829 F
1889 19:30:05.0 0- 3 9621 0 0: 0.002 -55.9 179652 F 0.002 -27.1 230130 F 0.001 -94.9 199954 F 0.003 -89.3 206764 F
1890 19:30:05.0 0- 4 1656 0 0: 0.001 133.3 199677 F 0.002 80.6 258140 F 0.001 -35.1 224291 F 0.003 23.9 229812 F
1891 19:30:05.0 0- 5 3084 0 0: 0.002 -18.4 197565 F 0.001 -83.1 228541 F 0.002 -85.1 198574 F 0.002 -28.5 227381 F
1892 19:30:05.0 0- 6 5020 0 0: 0.001-173.2 236475 F 0.002-104.0 257575 F 0.000 0.0 223800 F 0.000-142.5 272162 F
1893 19:30:05.0 0- 7 12266 0 0: 0.003 -34.6 264977 F 0.002 5.3 280113 F 0.001-152.7 243383 F 0.002 -78.8 304966 F
1894 .
1895 .
1896 .
1898 Notice that the channel column is not displayed. This measurement
1899 set contains only one channel; since the channel column values are
1900 uniform, the channel column is not displayed. Instead, message
1901 'All selected data has CHANNEL = 0' is sent to the console.
1903 --------------------------------------------------------------------------------
1905 """
1906 return _ms.ms_lister(self, *args, **kwargs)
1909 def metadata(self, *args, **kwargs):
1910 """
1911 metadata(self, _cachesize) -> casac::msmetadata *
1915 Summary:
1916 Get the MS metadata associated with this MS.
1918 Description:
1920 Get the MS metadata associated with this MS.
1922 Input Parameters:
1923 cachesize Maximum cache size, in megabytes, to use.
1925 Example:
1927 # get the number of spectral windows in the specified MS
1928 ms.open'my.ms')
1929 metadata = ms.metadata()
1930 ms.done()
1931 nspw = metadata.nspw()
1932 metadata.done()
1934 --------------------------------------------------------------------------------
1936 """
1937 return _ms.ms_metadata(self, *args, **kwargs)
1940 def msselect(self, *args, **kwargs):
1941 """
1942 msselect(self, _items, _onlyparse) -> bool
1946 Summary:
1947 Use the MSSelection module for data selection.
1949 Description:
1952 A return value of True implies that the combination of all
1953 selection expressions resulted in a non-Null combined TaQL
1954 expression. False implies that the combined TaQL could not be
1955 formed (i.e. it is Null, and the 'selected MS' will be the same as
1956 the input MS).
1958 The details of selection expressions are desribed in the
1959 MSSelection Memo.
1961 Note that this function can be called multiple times but the
1962 result is cumulative. Each selection will work on the data
1963 already selected from all previous calls of this function. Use
1964 the function reset() to reset all selections to NULL (original
1965 dataset).
1968 Input Parameters:
1969 items Record with fields contain the selection expressions. Keys recognized in the record are: 'spw', 'time', 'field', 'baseline', 'scan', 'scanintent', 'polarization', 'observation', 'array', 'uvdist' and 'taql'.
1970 onlyparse If set to True, expressions will only be parsed but not applied to the MS for selection. When set to False, a selected MS will also be generated internally. Default is False. When only parsing is requested, the selected-MS is the same as the original MS.
1972 Example:
1974 staql={'field':'3C286', 'spw':'0~7:10~55'};
1975 ms.open(MSNAME);
1976 # For only getting the list of indices
1977 # corresponding to the selection, onlyparse=True
1978 ms.msselect(staql, onlyparse=True);
1979 ndx=ms.msselectedindices();
1980 ndx['field']
1981 Out[5]: array([1], dtype=int32)
1982 :
1983 :
1984 ms.msselect(staql); # To do the actual selection.
1985 # From this point on, the ms-tool is attached to the selected MS.
1987 --------------------------------------------------------------------------------
1989 """
1990 return _ms.ms_msselect(self, *args, **kwargs)
1993 def msselectedindices(self):
1994 """
1995 msselectedindices(self) -> record *
1999 Summary:
2000 Return the selected indices of the MS database. The keys in the record are the same as those used in msselect function (i.e. 'spw', 'time', 'field', 'baseline', 'scan', 'scanintent', 'polarization' and 'uvdist').
2002 Description:
2005 The return indices are the result of parsing the MSSelection
2006 expressions provided in the msselect function.
2009 --------------------------------------------------------------------------------
2011 """
2012 return _ms.ms_msselectedindices(self)
2015 def msseltoindex(self, *args, **kwargs):
2016 """
2017 msseltoindex(self, _vis, _spw, _field, _baseline, _time, _scan, _uvrange, _observation, _polarization, _taql) -> record *
2021 Summary:
2022 Returns ids of the selection used.
2024 Description:
2027 Utility function that will return the ids of the selection used.
2030 Input Parameters:
2031 vis Measurementset for which this selection applies.
2032 spw Spectral Window Ids (0 relative) to select; -1 interpreted as all.
2033 field Field Ids (0 relative) or Field names (msselection syntax and wilcards are used) to select.
2034 baseline Antenna Ids (0 relative) or Antenna names (msselection syntax and wilcards are used) to select.
2035 time Limit data selected to be within a given time range. Syntax is the defined in the msselection link.
2036 scan Limit data selected on scan numbers. Syntax is the defined in the msselection link.
2037 uvrange Limit data selected on uv distance. Syntax is the defined in the msselection link.
2038 observation Select data by observation ID(s). The syntax is the same as for scan numbers.
2039 polarization Select data by polarization(s).
2040 taql For the TAQL experts, flexible data selection using the TAQL syntax.
2042 Example:
2044 a= ms.msseltoindex(vis='3C273XC1.MS', field='3C*')
2045 print a['field']
2046 # [0]
2047 print a
2048 #{'antenna1': array([], dtype=int32),
2049 # 'antenna2': array([], dtype=int32),
2050 # 'channel': array([], shape=(0, 0), dtype=int32),
2051 # 'field': array([0]),
2052 # 'scan': array([], dtype=int32),
2053 # 'spw': array([], dtype=int32),
2054 # 'obsids': array([], dtype=int32)}
2056 Field name '3C*', in this case 3C273, corresponds to field id 0.
2058 N.B.: The return values of unspecified fields (like antenna* and
2059 spw in the above example) will be left empty - this does not mean
2060 that selection excludes all antennas!
2062 Some fields (like 'field') are checked against the subtables of
2063 vis, but others are not. For example, field='123~132' will
2064 produce an error if vis does not have fields 123 to 132, but for
2065 scan and obsids '123~132' would just return an array of integers
2066 from 123 to 132 regardless of whether vis has those scan or
2067 observation IDs. (The difference comes from it being quicker to
2068 check a subtable than the main table.)
2070 --------------------------------------------------------------------------------
2072 """
2073 return _ms.ms_msseltoindex(self, *args, **kwargs)
2076 def selectinit(self, *args, **kwargs):
2077 """
2078 selectinit(self, _datadescid, _reset) -> bool
2082 Summary:
2083 Initialize the selection of an ms
2085 Description:
2088 A measurement set can contain data with a variety of different
2089 shapes (as described in the overall description to this tool). To
2090 allow functions to return data in fixed shape arrays you need to
2091 select, using this function, rows that contain the same data shape.
2092 You do not need to use this function if all the data in your
2093 measurement set has only one shape.
2095 The DATA_DESC_ID column in the measurement set contains a value
2096 that maps to a particular row in the POLARIZATION and
2097 SPECTRAL_WINDOW subtables. Hence all rows with the same value in
2098 the DATA_DESC_ID column must have the same data shape. To select
2099 all the data where the DATA_DESC_ID value is N you call this
2100 function with the datadescid argument set to N.
2102 It is possible to have a measurement set with differing values in
2103 the DATA_DESC_ID column but where all the data is a fixed shape.
2104 For example this will occur if the reference frequency changes but
2105 the number of spectral channels is fixed. In cases like this all
2106 the data can be selected and this function does not need to be
2107 used.
2109 To return to the completely unselected measurement set, set the
2110 reset argument to True. This will allow you to access the full
2111 range of rows in the measurement set, rather than just the
2112 selected measurement set.
2114 The datadescid must always be a non-negative integer.
2117 Input Parameters:
2118 datadescid Data description id.
2119 reset Reset to unselected state.
2121 Example:
2123 ms.open('3C273XC1.MS')
2124 ms.selectinit(datadescid=0)
2125 print ms.range(['uvdist'])
2126 ms.selectinit(reset=True)
2127 print ms.range('uvdist')
2129 In this example we display the range of uv distances for the data
2130 in the specified measurement set (the range 'items' argument is a
2131 list of strings, even if only one item is requested). The first
2132 print statement will only use data where the DATA_DESC_ID column is
2133 0. This will correspond to a specific spectral window and
2134 polarization setup. The second print statement will print the range
2135 of uv distances for all the data in the measurement set (which is
2136 the same in this case).
2138 --------------------------------------------------------------------------------
2140 """
2141 return _ms.ms_selectinit(self, *args, **kwargs)
2144 def select(self, *args, **kwargs):
2145 """
2146 select(self, _items) -> bool
2150 Summary:
2151 Select a subset of the measurement set.
2153 Description:
2156 This function will select a subset of the current measurement set
2157 based on the range of values for each field in the input record.
2158 The range function will return a record that can be altered and
2159 used as the argument for this function. A successful selection
2160 returns True. Unrecognized fields are ignored.
2162 Allowable items for select include: 'antenna1', 'antenna2',
2163 'array_id', 'feed1', 'feed2', 'field_id', 'ifr_number', 'rows',
2164 'scan_number', 'data_desc_id', 'time', 'times', 'u', 'v', 'w',
2165 and 'uvdist'.
2167 You need to call selectinit before
2168 calling this function. If you haven't then selectinit will be
2169 called for you with default arguments.
2171 Repeated use of this function, with different arguments, will
2172 further refine the selection, resulting in a successively smaller
2173 selected measurement set. If the selected measurement set does not
2174 contain any rows then this function will return False and send a
2175 warning message in the logger. Otherwise this function will return
2176 True. To undo all the selections you need to use the selectinit
2177 function (with reset=True).
2180 Input Parameters:
2181 items Record with fields of ranges or enumerations
2183 Example:
2185 ms.open('3C273XC1.MS')
2186 ms.selectinit(datadescid=0)
2187 ms.select({'antenna1':[1,3,5],'uvdist':[1200.,1900.]})
2188 ms.select({'time':[4121629420.,4121638290.]})
2189 # Or, convert time strings to seconds:
2190 start = qa.getvalue(qa.convert(qa.quantity('1989/06/27/01:03:40'),
2191 's'))[0]
2192 stop = qa.getvalue(qa.convert(qa.quantity('1989/06/27/03:31:30'),
2193 's'))[0]
2194 rec = {}
2195 rec['time'] = [start, stop]
2196 ms.select(items=rec)
2198 This example selects all the data from the measurement set where
2199 the value in the DATA_DESC_ID column is zero. This corresponds to a
2200 particular spectral window and polarization setup. It then selects
2201 all the data where the first antenna in the interferometer is
2202 number one, three or five and where the uv distance is between 1200
2203 and 1900 meters. Finally it selects all the data which was
2204 observed between 4121629420 seconds and 4121638290 seconds (since
2205 zero hours on the day where the modified Julian day is zero). Since
2206 this time in seconds is quite obscure, use the quanta tool to
2207 convert a date/time string into seconds which can then be used to
2208 perform the same time selection.
2210 The selections are cumulative so that at the end of this example
2211 only data in the specified time range, with the specified,
2212 interferometers, uv distances, spectral window and polarization
2213 setup are selected.
2215 --------------------------------------------------------------------------------
2217 """
2218 return _ms.ms_select(self, *args, **kwargs)
2221 def selecttaql(self, *args, **kwargs):
2222 """
2223 selecttaql(self, _msselect) -> bool
2227 Summary:
2228 Select a subset of the measurement set.
2230 Description:
2233 This function will select a subset of the current measurement set
2234 based on the standard TaQL selection string given.
2236 Repeated use of this function, with different arguments, will
2237 further refine the selection, resulting in a successively smaller
2238 selected measurement set. If the selected measurement set does not
2239 contain any rows then this function will return False and send a
2240 warning message in the logger. Otherwise this function will return
2241 True. To undo all the selections you need to use the selectinit
2242 function (with reset=True). Note that index values used in the
2243 TaQL string are zero-based as are all tool indices.
2246 Input Parameters:
2247 msselect TaQL selection string
2249 Example:
2251 ms.open('3C273XC1.MS')
2252 ms.selectinit(datadescid=0)
2253 ms.select({'antenna1':[0,2,4],'uvdist':[1200.,1900.]})
2254 ms.selecttaql('ANTENNA1==2')
2255 ms.range(['ANTENNA1','ANTENNA2'])
2256 # {'antenna1': array([2]),
2257 # 'antenna2': array([ 6, 9, 11, 18, 20, 21, 24])}
2259 This example selects all the data from the measurement set where
2260 the value in the DATA_DESC_ID column is zero. This corresponds to a
2261 particular spectral window and polarization setup. It then selects
2262 all the data where the first antenna in the interferometer is
2263 number zero, two or four and where the uv distance is between 1200
2264 and 1900 meters. Finally it uses a query to select all the data
2265 for which the ANTENNA1 column is 2 (this selects the middle antenna
2266 of the previous, zero-based, selection). The selections are
2267 cumulative so that at the end of this example only data in the
2268 specified time range, with the specified, interferometers, uv
2269 distances, spectral window and polarization setup are selected.
2271 --------------------------------------------------------------------------------
2273 """
2274 return _ms.ms_selecttaql(self, *args, **kwargs)
2277 def selectchannel(self, *args, **kwargs):
2278 """
2279 selectchannel(self, _nchan, _start, _width, _inc) -> bool
2283 Summary:
2284 Select and average frequency channels
2286 Description:
2289 This function allows you to select a subset of the frequency
2290 channels in the current measurement set. This function can also
2291 average, over frequency channels, prior to providing the values to
2292 the user.
2294 Selection on channels is not allowed using either the select or
2295 command functions, as they can only select entire rows in a
2296 measurement set. Channel selection involves accessing only some of
2297 the values in a row. Like all the selection functions, this
2298 function does not change the current measurement but updates the
2299 measurement set selection parameters so that functions like
2300 getdata will return the desired subset of the data. Repeated use
2301 of this function will overwrite any previous channel selection.
2303 There are four parameters, the number of output channels, the
2304 first input channel to use, the number of input channels to
2305 average into one output channel, and the increment in the input
2306 spectrum for the next output channel. All four parameters need to
2307 be specified.
2309 When all data to be averaged is unflagged, the result is the
2310 averaged value and the corresponding flag is False. When all data
2311 is flagged, the result is set to zero and the corresponding flag is
2312 True. When data to be averaged is mixed (unflagged and flagged),
2313 only the unflagged values are averaged and the flag is set to
2314 False.
2316 This function return True if the selection was successful, and
2317 False if not. In the latter case an error message will also be sent
2318 to the logger.
2320 You need to call selectinit before calling this function.
2321 If you haven't then selectinit will be called for you with default
2322 arguments.
2325 Input Parameters:
2326 nchan Number of output channels, positive integer.
2327 start First input channel to use, positive integer.
2328 width Number of input channels to average together, positive integer.
2329 inc Increment to next (group of) input channel(s), positive integer.
2331 Example:
2333 ms.fromfits('NGC5921.MS',
2334 '/usr/lib/casapy/data/demo/NGC5921.fits')
2335 ms.selectinit(datadescid=0)
2336 ms.selectchannel(3,2,5,3)
2337 rec = ms.getdata(['data'])
2339 This example selects all the data from the measurement set where
2340 the value in the DATA_DESC_ID column is zero. This corresponds to a
2341 particular spectral window and polarization setup. It then selects
2342 on frequency channels to produce 3 output channels, the first
2343 output channel is the average of channels 2,3,4,5,6 in the input,
2344 the second output channel is the average of channel 5,6,7,8,9 and
2345 the third is the average of channels 8,9,10,11,12.
2347 --------------------------------------------------------------------------------
2349 """
2350 return _ms.ms_selectchannel(self, *args, **kwargs)
2353 def selectpolarization(self, *args, **kwargs):
2354 """
2355 selectpolarization(self, _wantedpol) -> bool
2359 Summary:
2360 Selection and conversion of polarizations.
2362 Description:
2365 This function allows you to select a subset of the polarizations
2366 in the current measurement set. This function can also setup
2367 conversion to different polarization representations.
2369 You specify the polarizations using a string vector. Allowable
2370 strings are include I, Q, U, V, RR, RL, LR, LL, XX, YY, XY,
2371 YX. These string must be specified in upper case. If the
2372 polarizations match those present in the measurement set they will
2373 be selected directly, otherwise all polarizations are read and
2374 then a conversion step is done. If the conversion cannot be done
2375 then an error will be produced when you try to access the data.
2377 This function return True if the selection was successful, and
2378 False if not.
2380 You need to call selectinit before calling this function.
2381 If you haven't then selectinit will be called for you with default
2382 arguments.
2385 Input Parameters:
2386 wantedpol The polarizations wanted.
2388 Example:
2390 ms.open('3C273XC1.MS')
2391 ms.selectinit(datadescid=0)
2392 ms.selectpolarization(['I','V'])
2393 rec = ms.getdata(['data'])
2395 This example selects all the data from the measurement set where
2396 the value in the DATA_DESC_ID column is zero. This corresponds to a
2397 particular spectral window and polarization setup. It then selects
2398 the I and V polarizations and when the getdata function is called
2399 the conversion from RR, LL, LR, RL polarizations to I and V occurs.
2401 --------------------------------------------------------------------------------
2403 """
2404 return _ms.ms_selectpolarization(self, *args, **kwargs)
2407 def statwt(self, *args, **kwargs):
2408 """
2409 statwt(self, _combine, _timebin, _slidetimebin, _chanbin, _minsamp, _statalg, _fence, _center, _lside, _zscore, _maxiter, _fitspw, _excludechans, _wtrange, _preview, _datacolumn) -> record *
2413 Summary:
2414 Compute and set weights based on variance of data.
2416 Description:
2419 IF NOT RUN IN PREVIEW MODE, THIS APPLICATION WILL MODIFY THE
2420 WEIGHT, WEIGHT SPECTRUM, FLAG, AND FLAG_ROW COLUMNS OF THE INPUT
2421 MS. IF YOU WANT A PRISTINE COPY OF THE INPUT MS TO BE PRESERVED,
2422 YOU SHOULD MAKE A COPY OF IT BEFORE RUNNING THIS APPLICATION.
2424 This application computes weights for the WEIGHT and
2425 WEIGHT_SPECTRUM (if present) columns based on the variance of
2426 values in the CORRECTED_DATA or DATA column. If the MS does not
2427 have the specified data column, the application will fail. The
2428 following algorithm is used:
2430 1. For unflagged data in each sample, create two sets of values,
2431 one set is composed solely of the real part of the data values,
2432 the other set is composed solely of the imaginary part of the
2433 data values.
2434 2. Compute the weighted (by exposure time) variance of each of
2435 these sets, v_r and v_i. The weighted variance per unit
2436 inverse eposure time, v, is computed using
2438 v = sum(e_i * (V_i - <V>)^2)/N,
2440 where e_i is the exposure time for real/imaginary part of
2441 visibility V_i and
2443 <V> = sum(e_i * V_i)/sum(e_i)
2445 is the weighted mean of all the visibilities in the set, and N
2446 is the number of (unflagged) visibilities.
2447 3. Compute v_eq = (v_r + v_i)/2.
2448 4. Compute the normalized variance, v_norm = v_eq * <e>, where
2450 <e> = sum(e_i)/N
2452 is the mean of the exposure times. The associated weight of
2453 visibility V_i is e_i/v_eq. The weight will have unit of (data
2454 unit)^(-2), e.g., Jy^(-2). The visibility weights are what this
2455 application computes and writes.
2457 Data are aggregated on a per-baseline, per-data description ID
2458 basis. Data are aggregated in bins determined by the specified
2459 values of the timebin and chanbin parameters. By default, data for
2460 separate correlations are aggregated separately. This behavior can
2461 be overridden by specifying combine='corr' (see below).
2463 RULES REGARDING CREATING/INITIALIZING WEIGHT_SPECTRUM COLUMN
2465 1. If run in preview mode (preview=True), no data are modified and
2466 no columns are added.
2467 2. Else if datacolumn equals 'residual' or 'residual_data' and
2468 a CORRECTED_DATA column exists, the WEIGHT and WEIGHT_SPECTRUM
2469 columns are not modified.
2470 3. Else if the MS already has a WEIGHT_SPECTRUM and this column has
2471 been initialized (has values), it will be populated with
2472 the new weights. The WEIGHT column will be populated with the
2473 corresponding median values of the associated WEIGHT_SPECTRUM
2474 array.
2475 4. Else if the frequency range specified for the sample is not the
2476 default ('spw'), the WEIGHT_SPECTRUM column will be created (if
2477 it doesn't already exist) and the new weights will be written to
2478 it. The WEIGHT column should be populated with the
2479 corresponding median values of the WEIGHT_SPECTRUM array.
2480 5. Otherwise the single value for each spectral window will be
2481 written to the WEIGHT column; the WEIGHT_SPECTRUM column will
2482 not be added if it doesn't already exist, and if it does, it
2483 will remain uninitialized (no values will be written to it).
2485 In cases where columns are added and initialized, the
2486 WEIGHT_SPECTRUM values will be set equal to the corresponding
2487 WEIGHT values, and the SIGMA_SPECTRUM values will be set to the
2488 corresponding SIGMA values.
2490 CAUTION: For some cases when only a subset of data is selected
2491 and the WEIGHT_SPECTRUM and/or SIGMA_SPECTRUM columns are created,
2492 there is a known code issue in which these columns are not properly
2493 created and initialized for the specified subset of data, although
2494 they are properly initialized for the entire dataset. In such cases,
2495 an exception will be thrown. Because the columns are created for the
2496 entire dataset, the user simply needs to rerun the statwt task using
2497 the same parameters and the task should complete as expected. Should
2498 this condition occur when the user is using the ms.statwt() tool
2499 method, the user should close the ms tool, and then reopen it using
2500 the same data set and configure the same selection, and rerun
2501 ms.statwt(). The tool method should then complete as expected.
2503 RULES FOR MODIFYING WEIGHT, WEIGHT_SPECTRUM, SIGMA, and SIGMA_SPECTRUM
2505 1. If datacolum='corrected' or 'residual' then values are written
2506 to the WEIGHT and WEIGHT_SPECTRUM (if applicable) columns only.
2507 2. If datacolumn='data' or 'residual_data' and the 'CORRECTED_DATA'
2508 column does not exist, then values are written to the WEIGHT and
2509 WEIGHT_SPECTRUM (if applicable) columns and values in the SIGMA
2510 and SIGMA_SPECTRUM are set to 1/sqrt(newly computed weight). If
2511 a weight value is 0, the corresponding sigma value is -1.
2512 3. If datacolumn='data' or 'residual_data' and the 'CORRECTED_DATA'
2513 column does exist, then the WEIGHT and WEIGHT_SPECTRUM columns
2514 are not updated and values in the SIGMA and
2515 SIGMA_SPECTRUM are set to 1/sqrt(of the newly computed weight).
2516 If a weight value is 0, the corresponding sigma value is -1.
2517 In this case, you should either split out the DATA column and
2518 run statwt, or run with datacolumn='corrected' or 'residual'
2519 to update WEIGHT/WEIGHT_SPECTRUM. Otherwise the data are
2520 internally not consistent.
2522 TIME BINNING
2524 One of two algorithms can be used for time binning. If
2525 slidetimebin=True, then a sliding time bin of the specified width
2526 is used. If slidetimebin=False, then block time processing is used.
2527 The sliding time bin algorithm will generally be both more memory
2528 intensive and take longer than the block processing algorithm. Each
2529 algorithm is discussed in detail below.
2531 If the value of timebin is an integer, this value represents the
2532 number of contiguous, unique time stamps (from the MS TIME column)
2533 that should be used for averaging.
2535 Block Time Processing
2537 The data are processed in contiguous time blocks in this case. This
2538 means that all WEIGHT_SPECTRUM values will be set to the same value
2539 for all data within the same time bin/channel bin/correlation bin
2540 (see the section on channel binning and description of combine='corr'
2541 for more details on channel binning and correlation binning).
2543 If timebin is specified as a time quantity (eg, '110s'), then the
2544 time bins are not necessarily contiguous and are not necessarily the
2545 same width. The start of a bin is always coincident with a value
2546 from the TIME column, So for example, if values from the TIME column
2547 are [20s, 60s, 100s, 140s, 180s, 230s], and timebin = 110s, the
2548 first bin would start at 20s and run to 130s, so that data from
2549 timestamps 20s, 60s, and 100s will be included in the first bin. The
2550 second bin would start at 140s, so that data for timestamps 140s,
2551 180s, and 230s would be included in the second bin.
2553 In the case where timebin is an integer, this denotes the number of
2554 contigous timestamps that should be binned together. Note that, in
2555 this case, for rows 'left over' in the upper edge of the bin, their
2556 values are computed using timebin that would include rows with times
2557 earlier than them. For example, in an MS with 8 rows in one block
2558 to be processed and timebin=3, timestamps 1, 2, and 3 would be used
2559 to compute the weights of the first three three rows, and rows 4, 5,
2560 and 6 would be used to compute weights for the next three rows as
2561 expected. Rows 7 and 8 are 'left over' rows, but three rows (as per
2562 the integer timebin specification) are still used to compute them.
2563 Row 7 and 8 weights are computed by combining data in rows 6, 7, and 8.
2565 Sliding Time Window Processing
2567 In the sliding time window case, in the case where timebin is a time
2568 quantity, the time window is always centered on the timestamp of the
2569 row in question and extends +/-timebin/2 around that timestamp, subject
2570 the the time block boundaries.
2572 In the case where timebin is an integer, there are two cases to
2573 consider:
2575 timebin is odd: In this case the target row's data and the data from
2576 the +/-(n-1)/2 rows around the target row are also used.
2578 timebin is even: In this case, the target row's data and the data from
2579 the n/2 rows after the target row and the n/2 - 1 rows before the target
2580 row are used.
2582 When timebin is an int, for 'edge' rows, the timebin extends from the
2583 edge of the block to the corresponding timebin value of rows away from
2584 the edge, so that the timebin is not symmetrical around the target rows,
2585 but includes the number of rows specified by the timebin value.
2587 OVERRIDING DEFAULT BLOCK BOUNDARIES
2589 Rows with the same baselines and data description IDs which are included
2590 in that window are used for determining the weight of that row. The
2591 boundaries of the time block to which the window is restricted are
2592 determined by changes in FIELD_ID, ARRAY_ID, and SCAN_NUMBER. One can
2593 override this behavior for FIELD_ID and/or SCAN_NUMBER by specifying the
2594 combine parameter (see below). Unlike the time block processing algorithm,
2595 this sliding time window algorithm requires that details of all rows for
2596 the time window in question are kept in memory, and thus the sliding
2597 window algorithm in general and the block processing row when timebin is
2598 an int, requires more memory than the block processing method when
2599 timebin is a quantity. Also, unlike the block processing method which
2600 computes a single value for all weights within a single bin, the sliding
2601 window method requires that each row (along with each channel and
2602 correlation bin) be processed individually, so in general the sliding
2603 window method will take longer than the block processing method.
2605 CHANNEL BINNING
2607 The width of channel bins is specified via the chanbin parameter.
2608 Channel binning occurs within individual spectral windows; bins
2609 never span multiple spectral windows. Each channel will be included
2610 in exactly one bin.
2612 The default value 'spw' indicates that all channels in each
2613 spectral window are to be included in a single bin.
2615 Any other string value is interpreted as a quantity, and so should
2616 have frequency units, eg '1MHz'. In this case, the channel
2617 frequencies from the CHAN_FREQ column of the SPECTRAL_WINDOW
2618 subtable of the MS are used to determine the bins. The first bin
2619 starts at the channel frequency of the 0th channel in the spectral
2620 window. Channels with frequencies that differ by less than the
2621 value specified by the chanbin parameter are included in this bin.
2622 The next bin starts at the frequency of the first channel outside
2623 the first bin, and the process is repeated until all channels have
2624 been binned.
2626 If specified as an integer, the value is interpreted as the number
2627 of channels to include in each bin. The final bin in the spectral
2628 window may not necessarily contain this number of channels. For
2629 example, if a spectral window has 15 channels, and chanbin is
2630 specified to be 6, then channels 0-5 will comprise the first bin,
2631 channels 6-11 the second, and channels 12-14 the third, so that
2632 only three channels will comprise the final bin.
2634 MINIMUM REQUIRED NUMBER OF VISIBILITIES
2636 The minsamp parameter allows the user to specify the minimum number
2637 of unflagged visibilities that must be present in a sample for that
2638 sample's weight to be computed. If a sample has less than this
2639 number of unflagged points, the associated weights of all the
2640 points in the sample are set to zero, and all the points in the
2641 sample are flagged.
2643 AGGREGATING DATA ACROSS BOUNDARIES
2645 By default, data are not aggregated across changes in values in the
2646 columns ARRAY_ID, SCAN_NUMBER, STATE_ID, FIELD_ID, and
2647 DATA_DESC_ID. One can override this behavior for SCAN_NUMBER,
2648 STATE_ID, and FIELD_ID by specifying the combine parameter. For
2649 example, specifying combine='scan' will ignore scan boundaries when
2650 aggregating data. Specifying combine='field, scan' will ignore both
2651 scan and field boundaries when aggregating data.
2653 Also by default, data for separate correlations are aggregated
2654 separately. Data for all correlations within each spectral window
2655 can be aggregated together by specifying 'corr' in the combine
2656 parameter.
2658 Any combination and permutation of 'scan', 'field', 'state', and
2659 'corr' are supported by the combine parameter. Other values will be
2660 silently ignored.
2662 STATISTICS ALGORITHMS
2664 The supported statistics algorithms are described in detail in the
2665 imstat and ia.statistics() help. For the current application, these
2666 algorithms are used to compute vr and vi (see above), such that the
2667 set of the real parts of the visibilities and the set of the
2668 imaginary parts of the visibilities are treated as independent data
2669 sets.
2671 RANGE OF ACCEPTABLE WEIGHTS
2673 The wtrange parameter allows one to specify the acceptable range
2674 (inclusive, except for zero) for weights. Data with weights
2675 computed to be outside this range will be flagged. If not specified
2676 (empty array), all weights are considered to be acceptable. If
2677 specified, the array must contain exactly two nonnegative numeric
2678 values. Note that data with weights of zero are always flagged.
2680 INCLUDING CHANNELS
2682 Channels can be included in the computation of the weights by
2683 specifying the fitspw parameter. This parameter accepts a
2684 valid MS channel selection string. Data associated with the
2685 selected channels will be used in computing the weights; all other
2686 channels will be excluded from the computation of weights. By
2687 default (empty string), all channels are included.
2689 PREVIEW MODE
2691 By setting preview=True, the application is run in 'preview' mode.
2692 In this mode, no data in the input MS are changed, although the
2693 amount of data that the application would have flagged is reported.
2695 DATA COLUMN
2697 The datacolumn parameter can be specified to indicate which data
2698 column should be used for computing the weights. The values
2699 'corrected' for the CORRECTED_DATA column and 'data' for the DATA
2700 column are supported (minimum match, case insensitive). One may
2701 specify 'residual' in which case the values used are the result of
2702 the CORRECTED_DATA column - model, or 'residual_data' in which
2703 case the values used are the DATA column - model, where model
2704 is the CORRECTED_DATA column if it exists, or if it doesn't,
2705 the virtual source model if one exists, or if that doesn't, then
2706 no model is used and the 'residual' and 'residual_data' cases
2707 are equivalent to the 'corrected' and 'data' cases, respectively.
2708 The last two options are to allow for operation on timescales or
2709 frequency ranges which are larger than that over which the sky
2710 signal is expected to be constant. This situation arises in eg,
2711 OTF mapping, and also perhaps with sources with significant
2712 spectral structure. In cases where a necessary column doesn't
2713 exist, an exception will be thrown and no data will be changed.
2714 NOTE: It is the user's responsibility to ensure that a model has
2715 been set for all selected fields before using datacolumn='residual'
2716 or 'residual_data'.
2718 RETURN VALUE
2720 In all cases, the mean and variance of the set of all weights computed
2721 by the application is reported and returned in a dictionary with keys
2722 'mean' and 'variance'. Weights for which there are corresponding flags
2723 (=True) prior to running the application are excluded from the
2724 computation of these statistics. If the WEIGHT_SPECTRUM values are
2725 available, they are used to compute the statistics, otherwise,
2726 the WEIGHT values are used. The returned statistics are always computed
2727 using the classic algorithm; the value of statalg has no impact on how
2728 they are computed.
2730 OTHER CONSIDERATIONS
2732 Flagged values are not used in computing the weights, although the
2733 associated weights of these values are updated.
2735 If the variance for a set of data is 0, all associated flags for
2736 that data are set to True, and the corresponding weights are set to
2737 0.
2739 Because data are modified in the input MS, the nomodify parameter
2740 must be set to False when opening the associated MS tool.
2743 Input Parameters:
2744 combine Ignore changes in these columns (scan, field, and/or state) when aggregating samples to compute weights. The value 'corr' is also supported to aggregate samples across correlations.
2745 timebin Size of the time window that is used to determine the statistics of a weight. Can be an integer number of timestamps or a time interval in time units.
2746 slidetimebin Use a sliding window for time binning, as opposed to time block processing?
2747 chanbin Channel bin width for computing weights. Can either be integer, in which case it is interpreted as number of channels to include in each bin, or a string 'spw' or quantity with frequency units.
2748 minsamp Minimum number of visibilities required for computing weights in a sample. Must be >= 2.
2749 statalg Statistics algorithm to use for computing variances. Supported values are 'chauvenet', 'classic', 'fit-half', and 'hinges-fences'. Minimum match is supported.
2750 fence Fence value for statalg='hinges-fences'. A negative value means use the entire data set (ie default to the 'classic' algorithm). Ignored if statalg is not 'hinges-fences'.
2751 center Center to use for statalg='fit-half'. Valid choices are 'mean', 'median', and 'zero'. Ignored if statalg is not 'fit-half'.
2752 lside For statalg='fit-half', real data are <=; center? If false, real data are >= center. Ignored if statalg is not 'fit-half'.
2753 zscore For statalg='chauvenet', this is the target maximum number of standard deviations data may have to be included. If negative, use Chauvenet's criterion. Ignored if statalg is not 'chauvenet'.
2754 maxiter For statalg='chauvenet', this is the maximum number of iterations to attempt. Iterating will stop when either this limit is reached, or the zscore criterion is met. If negative, iterate until the zscore criterion is met. Ignored if statalg is not 'chauvenet'.
2755 fitspw Channels to include in the computation of weights. Specified as an MS select channel selection string.
2756 excludechans If True: invert the channel selection in fitspw and exclude the fitspw selection from the computation of the weights.
2757 wtrange Range of acceptable weights. Data with weights outside this range will be flagged. Empty array (default) means all weights are good.
2758 preview Preview mode. If True, no data is changed, although the amount of data that would have been flagged is reported.
2759 datacolumn Data column to use to compute weights. Supported values are 'data', 'corrected', 'residual, and 'residual_data' (case insensitive, minimum match supported).
2761 Example:
2763 # update the weights of an MS
2764 ms.open('my.ms', nomodify=False)
2765 # compute weights, using time bins of 300s
2766 if ms.statwt(timebin=('300s')):
2767 print 'Successfully updated weights'
2768 else:
2769 print 'Updating weights failed'
2770 ms.done()
2772 --------------------------------------------------------------------------------
2774 """
2775 return _ms.ms_statwt(self, *args, **kwargs)
2778 def oldstatwt(self, *args, **kwargs):
2779 """
2780 oldstatwt(self, _dorms, _byantenna, _sepacs, _fitspw, _fitcorr, _combine, _timebin, _minsamp, _field, _spw, _antenna, _timerange, _scan, _intent, _array, _correlation, _obs, _datacolumn) -> bool
2784 Summary:
2785 Set WEIGHT and SIGMA from the scatter of the visibilities
2787 Description:
2790 NOT IMPLEMENTED YET.
2792 This function estimates the noise from the scatter of the
2793 visibilities, sets SIGMA to it, and WEIGHT to SIGMA**-2.
2795 Ideally the visibilities used to estimate the scatter, as selected
2796 by fitspw and fitcorr, should be pure noise. If you know for
2797 certain that they are, then setting dorms to True will give the
2798 best result. Otherwise, use False (standard sample standard
2799 deviation). More robust scatter estimates like the interquartile
2800 range or median absolute deviation from the median are not offered
2801 because they require sorting by value, which is not possible for
2802 complex numbers.
2804 To beat down the noise of the noise estimate, the sample size per
2805 estimate can be made larger than a single spw and baseline. (Using
2806 combine='spw' is to interpolate between spws with line-free
2807 channels is recommended when an spw has no line-free channels.)
2808 timebin smooths the noise estimate over time. windowtype sets the
2809 type of time smoothing.
2811 WEIGHT and SIGMA will not be changed for samples that have fewer
2812 than minsamp visibilities. Selected visibilities for which no
2813 noise estimate is made will be flagged. Note that minsamp is
2814 effectively at least 2 if dorms is False, and 1 if it is True.
2817 Input Parameters:
2818 dorms How the scatter should be estimated (True -> rms, False -> stddev).
2819 byantenna How the scatters are solved for (by antenna or by baseline).
2820 sepacs If solving by antenna, treat autocorrs separately.
2821 fitspw Line-free spectral windows (and :channels) to get the scatter from. ('' => all)
2822 fitcorr Correlations (V, LL, XX, LR, XY, etc.) to get the scatter from. ('' => all)
2823 combine Ignore changes in these columns (spw, scan, and/or state) when getting the scatter.
2824 timebin Duration of the moving window over which to estimate the scatter. Defaults to 0s, with an effective minimum of 1 integration.
2825 minsamp The minimum number of visibilities for a scatter estimate.
2826 field Fields to reweight, by names or 0-based ids. ('' => all)
2827 spw Spectral windows to reweight. ('' => all)
2828 antenna Select data based on antenna/baseline.
2829 timerange Select data by time range.
2830 scan Scan numbers to reweight. ('' => all)
2831 intent Scan intents to reweight. ('' => all)
2832 array Select (sub)array(s) by array ID number.
2833 correlation Correlations (LL, XX, LR, XY, etc.) to reweight. ('' => all)
2834 obs Observation IDs to reweight. ('' => all)
2835 datacolumn Which data column to calculate the scatter from.
2837 Example:
2839 ms.open('multiwin.ms', nomodify=False)
2840 ms.oldstatwt(fitspw='0:0~123;145~211,2:124~255', field=[0],
2841 spw='0,2')
2843 In this example the noise estimates are separately made from and
2844 applied to spws 0 and 2.
2846 ms.oldstatwt(fitspw='0:0~123;145~211,2:124~255', fitorder=0,
2847 field=[0], combine='spw')
2848 ms.close()
2850 This time the estimate for each baseline is made from the line-free
2851 channels of spws 0 and 2, and applied to all the spws, including 1
2852 (which could be a completely line-filled spw).
2854 --------------------------------------------------------------------------------
2856 """
2857 return _ms.ms_oldstatwt(self, *args, **kwargs)
2860 def regridspw(self, *args, **kwargs):
2861 """
2862 regridspw(self, _outframe, _mode, _restfreq, _interpolation, _start, _center, _bandwidth, _chanwidth, _hanning) -> bool
2866 Summary:
2867 Transform spectral data to different reference frame and/or regrid the frequency channels
2869 Description:
2872 This function permits you to transform the spectral data of your
2873 measurement set to a given reference frame. The present reference
2874 frame information in the MS is examined and the transformation
2875 performed accordingly. Since all such transformations are linear in
2876 frequency, a pure change of reference frame only affects the
2877 channel boundary definitions.
2879 In addition, the function permits you to permanently regrid the
2880 data, i.e. reduce the channel number and/or move the boundaries
2881 using several interpolation methods (selected using parameter
2882 'interpolation'). The new channels are equidistant in frequency (if
2883 parameter 'mode' is chosen to be vrad or freq, or equidistant in
2884 wavelength if parameter 'mode' is chosen to be vopt or wave). If
2885 'mode' is chosen to be 'chan', the regridding is performed by
2886 combining the existing channels, i.e. not moving but just
2887 eliminating channel boundaries where necessary.
2889 The regridding is applied to the channel definition and all data of
2890 the MS, i.e. all columns which contain arrays whose dimensions
2891 depend on the number of channels. The input parameters are verified
2892 before any modification is made to the MS.
2894 The target reference frame can be set by providing the name of a
2895 standard reference frame (LSRK, LSRD, BARY, GALACTO, LGROUP, CMB,
2896 TOPO, GEO, or SOURCE, default = no change of frame) in parameter
2897 'outframe'. For each field in the MS, the channel frequencies are
2898 transformed from their present reference frame to the one given by
2899 parameter 'outframe'.
2901 If the regridding parameters are set, they are interpreted in the
2902 'outframe' reference frame. The regridding is applied to the data
2903 after the reference frame transformation.
2906 Input Parameters:
2907 outframe Name of the reference frame to transform to (LSRK, LSRD, BARY, GALACTO, LGROUP, CMB, GEO, TOPO, or SOURCE). SOURCE is meant for solar system work and corresponds to GEO + a radial velocity correction (only available for ephemeris objects). If no reference frame is given, the present reference frame given by the data is used, i.e. the reference frame is not changed. The observatory position is taken as the average of all antenna positions.
2908 mode The quantity (radio velocity (m/s), optical velocity (m/s), frequency (Hz), wavelength (m), or original channels) in which the user would like to give the regridding parameters below ('center', 'chanwidth', 'bandwidth'): vrad, vopt, freq, wave, or chan.
2909 restfreq Required in case the value of mode is 'vrad' or 'vopt': Rest frequency (Hz) for the conversion of the regrid parameters 'center', 'chanwidth', and 'bandwidth' to frequencies.
2910 interpolation Name of the interpolation method (NEAREST, LINEAR, SPLINE, CUBIC, FFTSHIFT) used in the regridding. Flagging information is combined using 'inclusive or'.
2911 start Desired lower edge of the spectral window after regridding in the units given by 'mode' and in the reference frame given by 'outframe'. If no value is given, it is determined from 'center' and 'bandwidth'.
2912 center (Alternative to setting the parameter 'start'.) Desired center of the spectral window after regridding in the units given by 'mode' and in the reference frame given by 'outframe'. If no value is given, the center is determined from 'start' and 'bandwidth' or, if 'start' is not given either, it is kept as it is.
2913 bandwidth Desired width of the entire spectral window after regridding in the units given by 'mode' and in the reference frame given by 'outframe'. If no value is given or the given width is larger than the bandwidth of the data, the width will be truncated to the maximum width possible symmetrically around the value given by 'center'.
2914 chanwidth Desired width of the channels in the units given by 'mode' and in the reference frame given by 'outframe'. This implies that channels will be equidistant in the unit given by 'mode'. If no value is given and 'mode' is vrad or freq, the function will keep the resolution as it is. If 'mode' is vopt or wave, the total number of channels will be kept as is.
2915 hanning If true, perform hanning smoothing before regridding.
2917 Example:
2919 ms.fromfits('NGC5921.MS','/usr/lib/casapy/data/demo/NGC5921.fits')
2920 ms.regridspw(outframe='LSRK')
2922 This example reads a measurement set and transforms its spectral
2923 axis to the LSRK reference frame.
2925 ms.regridspw(outframe='BARY', mode='vrad',
2926 center=73961800., chanwidth=50., bandwidth=1000.,
2927 restfreq=1420405750e6)
2929 In this example, all spectral windows in the MS will be transformed
2930 to the BARY reference frame and then be regridded such that the
2931 center of the new spectral window is at radio velocity = 73961800.
2932 m/s (BARY). If the bandwidth of the observation is large enough the
2933 total width of the spectral window will be 1000 m/s, i.e. 20
2934 channels of width 50 m/s, 10 on each side of the given center.
2936 ms.regridspw(mode='vopt', restfreq=1420405750e6)
2938 In this example the channels are regridded such that they are
2939 equidistant in optical velocity. The reference frame and number of
2940 channels is kept as is.
2942 ms.regridspw(mode='chan', center=64, chanwidth=2,
2943 bandwidth=102)
2945 In this example, the channels are regridded such that the new
2946 bandwidth is 102 of the original channels centered on the original
2947 channel 64, and the new channels are twice as wide as the original
2948 channels.
2950 --------------------------------------------------------------------------------
2952 """
2953 return _ms.ms_regridspw(self, *args, **kwargs)
2956 def cvel(self, *args, **kwargs):
2957 """
2958 cvel(self, _mode, _nchan, _start, _width, _interp, _phasec, _restfreq, _outframe, _veltype, _hanning) -> bool
2962 Summary:
2963 Transform spectral data to different reference frame and/or regrid the frequency channels
2965 Description:
2968 This function permits you to transform the spectral data of your
2969 measurement set to a given reference frame and/or regrid it. It
2970 will combine all spectral windows of the MS into one.
2973 Input Parameters:
2974 mode 'channel', 'velocity', 'frequency', or 'channel_b', default = 'channel'.
2975 nchan number of channels, default = -1 = all.
2976 start start channel, default =
2977 width new channel width, default =
2978 interp interpolation method 'nearest', 'linear', 'spline', 'cubic', 'fftshift', default =
2979 phasec phase center, default = first field
2980 restfreq rest frequency, default =
2981 outframe LSRK, LSRD, BARY, GALACTO, LGROUP, CMB, GEO, TOPO, or SOURCE default = '' = keep reference frame.
2982 veltype radio or optical, default =
2983 hanning If true, perform hanning smoothing before regridding.
2985 --------------------------------------------------------------------------------
2987 """
2988 return _ms.ms_cvel(self, *args, **kwargs)
2991 def hanningsmooth(self, *args, **kwargs):
2992 """
2993 hanningsmooth(self, _datacolumn) -> bool
2997 Summary:
2998 Hanning smooth the frequency channels to remove Gibbs ringing.
3000 Description:
3003 This function Hanning smooths the frequency channels with a
3004 weighted running average of:
3005 smoothedData[i] = 0.25*correctedData[i-1] + 0.50*correctedData[i]
3006 + 0.25*correctedData[i-1]
3007 The first and last channels are flagged. Inclusion of a flagged
3008 value in an average causes that averaged data value to be flagged.
3011 Input Parameters:
3012 datacolumn the name of the MS column into which to write the smoothed data
3014 Example:
3016 ms.open('ngc5921.ms',nomodify=False)
3017 ms.hanningsmooth('data')
3018 ms.close()
3020 --------------------------------------------------------------------------------
3022 """
3023 return _ms.ms_hanningsmooth(self, *args, **kwargs)
3026 def cvelfreqs(self, *args, **kwargs):
3027 """
3028 cvelfreqs(self, _spwids, _fieldids, _obstime, _mode, _nchan, _start, _width, _phasec, _restfreq, _outframe, _veltype, _verbose) -> std::vector< double >
3032 Summary:
3033 Calculate the transformed grid of the SPW obtained by combining a given set of SPWs (MS is not modified)
3035 Description:
3038 Take the spectral grid of a given spectral window, tranform and
3039 regrid it as prescribed by the given grid parameters (same as in
3040 cvel and clean) and return the transformed values as a list. The MS
3041 is not modified. Useful for tests of gridding parameters before
3042 using them in cvel or clean.
3045 Input Parameters:
3046 spwids The list of ids of the spectral windows from which the input grid is to be taken.
3047 fieldids The list of ids of the fields which are selected (for observation time determination), default: all
3048 obstime The observation time to assume, default: time of the first row of the MS
3049 mode 'channel', 'velocity', 'frequency', or 'channel_b'
3050 nchan Number of channels, default = all
3051 start Start channel.
3052 width New channel width.
3053 phasec Phase center, default=first field in selection.
3054 restfreq Rest frequency.
3055 outframe LSRK, LSRD, BARY, GALACTO, LGROUP, CMB, GEO, TOPO, or SOURCE default = keep reference frame.
3056 veltype Radio or optical.
3057 verbose If true, create log output.
3059 Example:
3061 ms.open('my.ms')
3062 ms.cvelfreqs(spwids=[1], mode='channel', nchan=20, start=2,
3063 width=3, outframe='LSRK')
3065 This will take the grid of SPW 1 (i.e. the second in the SPW
3066 table), regrid it as in cvel with the given grid parameters and
3067 return the resulting channel centers as an array. The MS is not
3068 modified. See help cvel for more details on the grid parameters.
3070 --------------------------------------------------------------------------------
3072 """
3073 return _ms.ms_cvelfreqs(self, *args, **kwargs)
3076 def contsub(self, *args, **kwargs):
3077 """
3078 contsub(self, _outputms, _fitspw, _fitorder, _combine, _spw, _unionspw, _field, _scan, _intent, _correlation, _obs, _whichcol) -> bool
3082 Summary:
3083 Subtract the continuum from the visibilities
3085 Description:
3088 DEPRECATED: This function is deprecated and will be removed in an
3089 upcoming release.
3091 NOT FULLY IMPLEMENTED YET. uvcontsub uses the cb tool for now.
3092 (The only reason to implement it in ms is to save time and disk
3093 space.)
3095 This function estimates the continuum emission of the MS and writes
3096 a MS with that estimate subtracted, using the ms tool. The
3097 estimate is made, separately for the real and imaginary parts of
3098 each baseline, by fitting a low order polynomial to the unflagged
3099 visibilities selected by fitspw (depending on combine).
3102 Input Parameters:
3103 outputms The name of the resulting measurement set.
3104 fitspw Line-free spectral windows (and :channels) to fit to.
3105 fitorder The order of the polynomial to use when fitting.
3106 combine Ignore changes in these columns (spw, scan, and/or state) when fitting.
3107 spw Spectral windows (and :channels) to select.
3108 unionspw The union of fitspw and spw, i.e. how much needs to be read. '*' always works, but may be more than you need.
3109 field Fields to include, by names or 0-based ids. ('' => all)
3110 scan Only use the scan numbers requested using the msselection syntax.
3111 intent Only use the requested scan intents.
3112 correlation Limit data to specific correlations (LL, XX, LR, XY, etc.).
3113 obs Only use the requested observation IDs.
3114 whichcol 'DATA', 'MODEL_DATA', 'CORRECTED_DATA', and/or 'FLOAT_DATA'
3116 Example:
3118 ms.open('multiwin.ms')
3119 ms.contsub('contsub.ms', fitspw='0:0~123;145~211,2:124~255',
3120 fitorder=0, field=[0], spw='0,2')
3122 In this example the continuum estimates are made by seperately
3123 averaging channels 0:0~123;145~211 and 2:124~255, and the separate
3124 estimates are subtracted from spws 0 and 2. The output only
3125 includes field 0 and spws 0 and 2 (now called 1).
3127 ms.contsub('contsub.ms', fitspw='0:0~123;145~211,2:124~255',
3128 fitorder=0, field=[0], combine='spw')
3129 ms.close()
3131 This time the estimate was made by simultaneously averaging
3132 channels 0:0~123;145~211 and 2:124~255, and the continuum is
3133 subtracted from all the spws, including 1 (treated as a completely
3134 line-filled spw). The output only includes field 0.
3136 --------------------------------------------------------------------------------
3138 """
3139 return _ms.ms_contsub(self, *args, **kwargs)
3142 def continuumsub(self, *args, **kwargs):
3143 """
3144 continuumsub(self, _field, _fitspw, _spw, _solint, _fitorder, _mode) -> bool
3148 Summary:
3149 Continuum fitting and subtraction in uv plane.
3151 Description:
3154 DEPRECATED: This function is deprecated and will be removed in an
3155 upcoming release.
3157 This function provides a means of continuum determination and
3158 subtraction by fitting a polynomial of desired order to a subset of
3159 channels in each time-averaged uv spectrum. The fit is used to
3160 model the continuum in all channels (not just those used in the
3161 fit), for subtraction, if desired.
3163 Use the fitspw parameter to limit the spectral windows processed and
3164 the range of channels used to estimate the continuum in each (avoid
3165 channels containing spectral lines).
3167 The default solution interval 'int' will result in per-integration
3168 continuum fits for each baseline.
3170 The mode parameter indicates how the continuum model (the result of
3171 the fit) should be used:
3172 - 'subtract' will store the continuum model in the MODEL_DATA column
3173 and subtract it from the CORRECTED_DATA column
3174 - 'replace' will replace the CORRECTED_DATA column with the
3175 continuum model (useful if you want to image the continuum model
3176 result)
3177 - 'model' will only store the continuum model in the MODEL_DATA
3178 column (the CORRECTED_DATA is unaffected).
3180 It is important to start the ms tool with nomodify=False so that
3181 changes to the dataset will be allowed (see example below). For
3182 now, the only way to recover the un-subtracted CORRECTED_DATA
3183 column is to use calibrater.correct() again.
3185 Note that the MODEL_DATA and CORRECTED_DATA columns must be present
3186 for continuumsub to work correctly. The function will warn the
3187 user if they are not present, and abort. To add these scratch
3188 columns, close the ms tool, then start a calibrater or an imager
3189 tool, which will add the scratch columns. Then restart the ms
3190 tool, and try continuumsub again.
3193 Input Parameters:
3194 field Select fields to fit.
3195 fitspw Spectral windows/channels to use for fitting the continuum; default all spectral windows in all channels.
3196 spw Select spectral windows and channels from which to subtract a continuum estimate; default: all channels in all spectral windows for which the continuum was estimated
3197 solint Continuum fit timescale (units optional).
3198 fitorder Polynomial order for fit.
3199 mode Desired use of fit model (see above).
3201 Example:
3203 ms.fromfits('ngc5921.ms','/aips++/data/demo/NGC5921.fits')
3204 ms.close()
3205 cb.open('ngc5921.ms') # add MODEL_DATA, CORRECTED_DATA columns
3206 cb.close()
3207 ms.open('ngc5921.ms', nomodify=False); # writable!
3208 ms.continuumsub(field=2, fitspw='0:5~9;50~59',
3209 solint=0.0, fitorder=1, mode='subtract')
3210 ms.done()
3212 This example will fit a linear continuum to channels 5-9 and 50-59
3213 in spectral window 0 in each scan-averaged spectrum for field 2,
3214 store the result in the MODEL_DATA column, and subtract it from the
3215 CORRECTED_DATA column.
3217 --------------------------------------------------------------------------------
3219 """
3220 return _ms.ms_continuumsub(self, *args, **kwargs)
3223 def uvsub(self, *args, **kwargs):
3224 """
3225 uvsub(self, _reverse) -> bool
3229 Summary:
3230 Subtract model from the corrected visibility data.
3232 Description:
3235 This function subtracts model visibility data from corrected
3236 visibility data leaving the residuals in the corrected data column.
3237 If the parameter reverse is set True, this process is reversed.
3240 Input Parameters:
3241 reverse When False, subtracts model from visibility data; when True, adds model to visibility data.
3243 Example:
3245 The following example subtracts a model from the visibility data
3246 leaving the residuals in the corrected data column.
3248 ms.open('ngc5921.ms',nomodify=False)
3249 ms.uvsub()
3250 ms.close()
3252 The following example adds the model back into the residuals.
3254 ms.open('ngc5921.ms',nomodify=False)
3255 ms.uvsub(reverse=True)
3256 ms.close()
3258 --------------------------------------------------------------------------------
3260 """
3261 return _ms.ms_uvsub(self, *args, **kwargs)
3264 def addephemeris(self, *args, **kwargs):
3265 """
3266 addephemeris(self, _id, _ephemerisname, _comment, _field) -> bool
3270 Summary:
3271 Connect an ephemeris table with the MS FIELD table
3273 Description:
3278 Input Parameters:
3279 id The unique id number to give to this ephemeris (will overwrite pre-existing ephemeris of same id, -1 will use next unused id).
3280 ephemerisname The name of the ephemeris table which is to be copied into the MS.
3281 comment Comment string (no spaces, will be part of a file name).
3282 field Field id(s) (0-based) or fieldname(s) to connect this ephemeris to.
3284 Example:
3286 ms.addephemeris(id=0, ephemerisname='Titan_55002-55003dUTC.tab',
3287 comment='JPLTitan', field='Titan')
3289 --------------------------------------------------------------------------------
3291 """
3292 return _ms.ms_addephemeris(self, *args, **kwargs)
3295 def timesort(self, *args, **kwargs):
3296 """
3297 timesort(self, _newmsname) -> bool
3301 Summary:
3302 Sort the main table of an MS by time
3304 Description:
3307 This function sorts the main table of the measurement set by the
3308 contents of the column TIME in ascending order and writes a copy of
3309 the MS with the sorted main table into newmsfile.
3311 If no newmsname is given, a sorted copy of the MS is written into a
3312 new MS under the name x.sorted (where x is the name of the original
3313 MS). The original MS is then closed and deleted. The new MS is
3314 renamed to the name of the original MS and then reopened.
3317 Input Parameters:
3318 newmsname Name of the output measurement set (default: overwrite original)
3320 Example:
3322 ms.open('3C273XC1.MS', nomodify=False)
3323 ms.timesort()
3324 ms.done()
3326 This example sorts the main table of 3C273XC1.MS by time. The
3327 original MS is overwritten by the sorted one.
3329 --------------------------------------------------------------------------------
3331 """
3332 return _ms.ms_timesort(self, *args, **kwargs)
3335 def sort(self, *args, **kwargs):
3336 """
3337 sort(self, _newmsname, _columns) -> bool
3341 Summary:
3342 Sort the main table of an MS using a custom set of columns
3344 Description:
3347 This function sorts the main table of the measurement set by the
3348 contents of the input set of columns in ascending order and writes
3349 a copy of the MS with the sorted main table into newmsfile.
3351 If no newmsname is given, a sorted copy of the MS is written into a
3352 new MS under the name x.sorted (where x is the name of the original
3353 MS). The original MS is then closed and deleted. The new MS is
3354 renamed to the name of the original MS and then reopened.
3357 Input Parameters:
3358 newmsname Name of the output measurement set (default: overwrite original).
3359 columns Vector of column names (case sensitive).
3361 Example:
3363 ms.open('3C273XC1.MS', nomodify=False)
3364 ms.sort(['ANTENNA1','ANTENNA2'])
3365 ms.done()
3367 This example sorts the main table of 3C273XC1.MS by ANTENNA1 and
3368 then ANTENNA2. The original MS is overwritten by the sorted one.
3370 --------------------------------------------------------------------------------
3372 """
3373 return _ms.ms_sort(self, *args, **kwargs)
3376 def iterinit(self, *args, **kwargs):
3377 """
3378 iterinit(self, _columns, _interval, _maxrows, _adddefaultsortcolumns) -> bool
3382 Summary:
3383 Initialize for iteration over an ms.
3385 Description:
3388 Specify the columns to iterate over and the time interval to use
3389 for the TIME column iteration. The columns are specified by their
3390 MS column name and must contain scalar values.
3392 Note that the following default sort columns are always added to
3393 the specified columns: array_id, field_id, data_desc_id and time.
3394 This is so that the iterator can keep track of the coordinates
3395 associated with the data (field direction, frequency, etc.). If you
3396 want to sort on these columns last instead of first, you need to
3397 include them in the columns specified. If you don't want to sort on
3398 these columns at all, you can set adddefaultsortcolumns to False.
3400 You may want to use iteration for a large dataset. After calling
3401 iterinit, you must call iterorigin before attempting to retrieve
3402 data with getdata.
3404 You need to call selectinit before calling this.
3407 Input Parameters:
3408 columns Vector of column names (case sensitive).
3409 interval Time interval in seconds (greater than 0), to group together in iteration.
3410 maxrows Max number of rows (greater than 0) to return in iteration.
3411 adddefaultsortcolumns Add the default sort columns.
3413 Example:
3415 See the example for the iterend function.
3417 --------------------------------------------------------------------------------
3419 """
3420 return _ms.ms_iterinit(self, *args, **kwargs)
3423 def iterorigin(self):
3424 """
3425 iterorigin(self) -> bool
3429 Summary:
3430 Set the iterator to the start of the data.
3432 Description:
3435 Set or reset the iterator to the start of the currently specified
3436 iteration. You need to call this after iterinit, before attempting
3437 to retrieve data with getdata. You may also use iterorigin to set
3438 the iterator back to the start before you reach the end of the
3439 data.
3442 Example:
3444 See the example for the iterend function.
3446 --------------------------------------------------------------------------------
3448 """
3449 return _ms.ms_iterorigin(self)
3452 def iternext(self):
3453 """
3454 iternext(self) -> bool
3458 Summary:
3459 Advance the iterator to the next lot of data.
3461 Description:
3464 This sets the currently selected table (as accessed with getdata)
3465 to the next iteration. If there is no more data, the function
3466 returns False and the selection is reset to that before the
3467 iteration started. You need to call iterinit and iterorigin
3468 before calling this.
3471 Example:
3473 See the example for the iterend function.
3475 --------------------------------------------------------------------------------
3477 """
3478 return _ms.ms_iternext(self)
3481 def iterend(self):
3482 """
3483 iterend(self) -> bool
3487 Summary:
3488 End the iteration and reset the selected table.
3490 Description:
3493 This sets the currently selected table (as accessed with
3494 getdata) to the table that was selected before iteration
3495 started. Use this to end the iteration prematurely. There is no
3496 need to call this if you continue iterating until iternext
3497 returns False.
3499 See the example below.
3502 Example:
3504 ms.open('3C273XC1.MS')
3505 ms.selectinit(datadescid=0)
3506 ms.iterinit(['ANTENNA1','ANTENNA2','TIME'],60.0)
3507 ms.iterorigin()
3508 rec=ms.getdata(['u','v','data'])
3509 ms.iternext()
3510 rec=ms.getdata(['u','v','data'])
3511 ms.iterend()
3513 We open the MS, select an array and spectral window and then
3514 specify an iteration over interferometer and time, with a 60s time
3515 interval. We then set the iterator to the start of the data and
3516 get out some data. Then we advance the iterator to the next lot
3517 of data, and finally end the iteration.
3519 --------------------------------------------------------------------------------
3521 """
3522 return _ms.ms_iterend(self)
3525 def ngetdata(self, *args, **kwargs):
3526 """
3527 ngetdata(self, _items, _ifraxis, _ifraxisgap, _increment, _average) -> record *
3531 Summary:
3532 Read values from the measurement set.
3534 Description:
3537 DEPRECATED: Please use the ms::getdata() function in place
3538 of ms::ngetdata().
3540 This method extracts the data as specified in the items
3541 parameter. The data is returned as a record with each item
3542 as a separate key in the record (all in lower case).
3544 Unless the iterator was initialized with a niterinit(), this
3545 method initializes the iterator as niterinit(['..'],0.0,0,False).
3548 Input Parameters:
3549 items Item names (NOT USED)
3550 ifraxis Create interferometer axis if True (NOT USED)
3551 ifraxisgap Gap size on ifr axis when antenna1 changes (NOT USED)
3552 increment Row increment for data access (NOT USED)
3553 average Average the data in time or over rows (NOT USED)
3555 --------------------------------------------------------------------------------
3557 """
3558 return _ms.ms_ngetdata(self, *args, **kwargs)
3561 def niterinit(self, *args, **kwargs):
3562 """
3563 niterinit(self, _columns, _interval, _maxrows, _adddefaultsortcolumns) -> bool
3567 Summary:
3568 Initialize for iteration over an ms.
3570 Description:
3573 DEPRECATED: Please use the ms::iterinit() function in place
3574 of ms::niterinit().
3577 Input Parameters:
3578 columns Vector of column names (case sensitive). This parameter is not used and is here only for backwards compatibility with the iterinit() method.
3579 interval Time interval in seconds (greater than 0), to group together in iteration
3580 maxrows Max number of rows (greater than 0) to return in iteration.
3581 adddefaultsortcolumns Add the default sort columns
3583 --------------------------------------------------------------------------------
3585 """
3586 return _ms.ms_niterinit(self, *args, **kwargs)
3589 def niterorigin(self):
3590 """
3591 niterorigin(self) -> bool
3595 Summary:
3596 Set the iterator to the start of the data.
3598 Description:
3601 DEPRECATED: Please use the ms::iterorigin() function in place
3602 of ms::niterorigin().
3604 Set or reset the iterator to the start of the currently
3605 specified iteration. You need to call this before attempting to
3606 iteratively retrieve data with ngetdata. You can set the
3607 iteration back to the start before you reach the end of the
3608 data. You need to call iterinit before calling this. See the
3609 example below.
3612 Example:
3614 See the example for the niterend function.
3616 --------------------------------------------------------------------------------
3618 """
3619 return _ms.ms_niterorigin(self)
3622 def niternext(self):
3623 """
3624 niternext(self) -> bool
3628 Summary:
3629 Advance the iterator to the next lot of data.
3631 Description:
3634 DEPRECATED: Please use the ms::iternext() function in place
3635 of ms::niternext().
3637 This sets the currently selected table (as accessed with
3638 ngetdata) to the next iteration. If there is no more data, the
3639 function returns False. You need to call iterinit and
3640 iterorigin before calling this. See the example below.
3643 Example:
3645 See the example for the niterend function.
3647 --------------------------------------------------------------------------------
3649 """
3650 return _ms.ms_niternext(self)
3653 def niterend(self):
3654 """
3655 niterend(self) -> bool
3659 Summary:
3660 Query if there are more iterations left in the iterator.
3662 Description:
3665 DEPRECATED: Please use the ms::iterend() function in place
3666 of ms::niterend().
3668 The serves redundant purpose and is here only for backward
3669 compatibility.
3671 This method returns True if there are no more iterations left.
3672 I.e., the iterations have ended. This same information is also
3673 returned by niternext().
3675 With the use of the VisibilityIterator in the niterinit(),
3676 niterorigin(), niternext() methods, the iterator is set to the
3677 original state by calling niterinit() at any time.
3679 See the example below.
3682 Example:
3684 ms.open('3C273XC1.MS')
3685 staql={'baseline':'1 & 2'};
3686 ms.msselect(staql);
3687 ms.niterinit([' '],60.0)
3688 ms.niterorigin()
3689 while (!ms.niterend()):
3690 rec=ms.ngetdata(['u','v','data'])
3691 ms.niternext()
3692 ms.close()
3694 We open the MS, select a baseline and then specify an iteration
3695 over time, with a 60s time interval. We then set the iterator
3696 to the start of the data and get out some data. We advance the
3697 iterator to the next lot of data and continue till the end of
3698 iterations is indicated. Finally, we close the ms tool which
3699 restores the tool to its original state.
3701 --------------------------------------------------------------------------------
3703 """
3704 return _ms.ms_niterend(self)
3707 def nrowold(self, *args, **kwargs):
3708 """
3709 nrowold(self, _selected) -> long
3713 Summary:
3714 Returns the number of rows in the measurement set
3716 Description:
3719 DEPRECATED: Please use the ms::nrow() function in place of
3720 ms::nrowold().
3722 This function returns the number of rows in the measurement
3723 set. If the optional argument selected is set to True, it returns
3724 the number of currently selected rows, otherwise it returns the
3725 the number of rows in the original measurement.
3728 Input Parameters:
3729 selected return number of selected rows
3731 Example:
3733 ms.open('3C273XC1.MS')
3734 print 'Number of rows in ms =', ms.nrowold()
3735 #Number of rows in ms = 7669
3737 --------------------------------------------------------------------------------
3739 """
3740 return _ms.ms_nrowold(self, *args, **kwargs)
3743 def rangeold(self, *args, **kwargs):
3744 """
3745 rangeold(self, _items, _useflags, _blocksize) -> record *
3749 Summary:
3750 Get the range of values in the measurement set
3752 Description:
3755 DEPRECATED: Please use the ms::range() function in place of
3756 ms::rangeold().
3758 This function will return the range of values in the currently
3759 selected measurement set for the items specified. Possible items
3760 include most scalar columns, interferometer number
3761 (1000*antenna1+antenna2), uvdist(ance), u, v, w, amplitude, phase,
3762 real and imaginary components of the data (and corrected and model
3763 versions of these - if these columns are present). See the table
3764 at the top of the document to find the exact list.
3766 You specify items in which you are interested using a string
3767 vector where each element is a case insensitive item name. This
3768 function will then return a record that has fields corresponding
3769 to each of the specified items. Each field will contain the range
3770 of the specified item. For many items the range will be the
3771 minimum and maximum values but for some it will be a list of
3772 unique values. Unrecognized items are ignored.
3774 By default the FLAG column is used to exclude flagged data before
3775 any ranges are determined, but you can set useflags=False to
3776 include flagged data in the range. However, if you average in
3777 frequency, flagging will still be applied.
3779 You can influence the memory use and the reading speed using
3780 the blocksize argument - it specifies how big a block of data
3781 to read at once (in MB). For large datasets on machines with lots
3782 of memory you may speed things up by setting this higher than the
3783 default (10 MB).
3785 For some items, you need to call selectinitold to select a portion
3786 of the data with a unique shape prior to calling this function.
3788 Items prefixed with corrected, model, residual or obs_residual
3789 are not available unless your measurement set has been processed
3790 either with the imager or calibrator tools.
3793 Input Parameters:
3794 items Item names
3795 useflags Use the data flags
3796 blocksize Set the blocksize in MB
3798 Example:
3800 ms.open('3C273XC1.MS')
3801 ms.selectinitold(datadescid=0)
3802 ms.rangeold(['time','uvdist','amplitude','antenna1'])
3803 #{'amplitude': array([ 2.60339398e-02, 3.38518333e+01]),
3804 # 'antenna1': array([ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 13,
3805 # 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26]),
3806 # 'time': array([ 4.12162940e+09, 4.12164267e+09]),
3807 # 'uvdist': array([ 46.26912101, 3727.97385983])}
3809 In this example the minimum and maximum observation times,
3810 uvdistances, data amplitudes are returned as well as a list of all
3811 the antennas in the antenna1 column.
3813 For this dataset the selectinitold function did not need to be
3814 called as all the data is of one shape.
3816 --------------------------------------------------------------------------------
3818 """
3819 return _ms.ms_rangeold(self, *args, **kwargs)
3822 def selectinitold(self, *args, **kwargs):
3823 """
3824 selectinitold(self, _datadescid, _reset) -> bool
3828 Summary:
3829 Initialize the selection of an ms
3831 Description:
3834 DEPRECATED: Please use the ms::selectinit() function in place of
3835 ms::selectinitold().
3837 A measurement set can contain data with a variety of different
3838 shapes (as described in the overall description to this tool). To
3839 allow functions to return data in fixed shape arrays you need to
3840 select, using this function, rows that contain the same data
3841 shape. You do not need to use this function if all the data in
3842 your measurement set has only one shape.
3844 The DATA_DESC_ID column in the measurement set contains a
3845 value that maps to a particular row in the POLARIZATION and
3846 SPECTRAL_WINDOW subtables. Hence all rows with the same
3847 value in the DATA_DESC_ID column must have the same data
3848 shape. To select all the data where the DATA_DESC_ID value
3849 is $N$ you call this function with the datadescid argument set to
3850 $N$.
3852 It is possible to have a measurement set with differing values in
3853 the DATA_DESC_ID column but where all the data is a fixed
3854 shape. For example this will occur if the reference frequency
3855 changes but the number of spectral channels is fixed. In cases
3856 like this all the data can be selected, using this function with
3857 an argument of zero. If the data shape does change and you call
3858 this function with an datadescid set to zero the return value will be False. In all other cases it
3859 will be True.
3861 To return to the completely unselected measurement set, set the
3862 reset argument to True. This will allow you to access the full
3863 range of rows in the measurement set, rather than just the
3864 selected measurement set.
3866 The datadescid must always be a non-negative integer.
3869 Input Parameters:
3870 datadescid Data description id
3871 reset Reset to unselected state
3873 Example:
3875 ms.open('3C273XC1.MS')
3876 ms.selectinitold(datadescid=0)
3877 print ms.rangeold(['uvdist'])
3878 ms.selectinitold(reset=True)
3879 print ms.rangeold('uvdist')
3881 In this example we display the range of uv distances for the data
3882 in the specified measurement set (the range 'items' argument is a
3883 list of strings, even if only one item is requested). The first
3884 print statement will only use data where the DATA_DESC_ID column is
3885 0. This will correspond to a specific spectral window and
3886 polarization setup. The second print statement will print the range
3887 of uv distances for all the data in the measurement set (which is
3888 the same in this case).
3890 --------------------------------------------------------------------------------
3892 """
3893 return _ms.ms_selectinitold(self, *args, **kwargs)
3896 def selectold(self, *args, **kwargs):
3897 """
3898 selectold(self, _items) -> bool
3902 Summary:
3903 Select a subset of the measurement set.
3905 Description:
3908 DEPRECATED: Please use the ms::select() function in place of
3909 ms::selectold().
3911 This function will select a subset of the current measurement set
3912 based on the range of values for each field in the input record.
3913 The rangeold function will return a record that can be altered and
3914 used as the argument for this function. A successful selection
3915 returns True. Unrecognized fields are ignored.
3917 Allowable items for selectold include: antenna1, antenna2,
3918 array_id, feed1, feed2, field_id, ifr_number, rows, scan_number,
3919 data_desc_id, time, times, u, v, w, and uvdist.
3921 You need to call selectinitold before
3922 calling this function. If you haven't then selectinitold will be
3923 called for you with default arguments.
3925 Repeated use of this function, with different arguments, will
3926 further refine the selection, resulting in a successively smaller
3927 selected measurement set. If the selected measurement set does not
3928 contain any rows then this function will return False and send a
3929 warning message in the logger. Otherwise this function will return
3930 True. To undo all the selections you need to use the selectinitold
3931 function (with reset=True).
3934 Input Parameters:
3935 items record with fields contain ranges and enumerations
3937 Example:
3939 ms.open('3C273XC1.MS')
3940 ms.selectinitold(datadescid=0)
3941 ms.selectold({'antenna1':[1,3,5],'uvdist':[1200.,1900.]})
3942 ms.selectold({'time':[4121629420.,4121638290.]})
3943 # Or, convert time strings to seconds:
3944 start = qa.getvalue(qa.convert(
3945 qa.quantity('1989/06/27/01:03:40'),'s'))[0]
3946 stop = qa.getvalue(qa.convert(
3947 qa.quantity('1989/06/27/03:31:30'),'s'))[0]
3948 rec = {}
3949 rec['time'] = [start, stop]
3950 ms.selectold(items=rec)
3952 This example selects all the data from the measurement set where
3953 the value in the DATA_DESC_ID column is zero. This corresponds to a
3954 particular spectral window and polarization setup. It then selects
3955 all the data where the first antenna in the interferometer is
3956 number one, three or five and where the uv distance is between 1200
3957 and 1900 meters. Finally it selects all the data which was
3958 observed between 4121629420 seconds and 4121638290 seconds (since
3959 zero hours on the day where the modified Julian day is zero). Since
3960 this time in seconds is quite obscure I have also illustrated how
3961 to use the quanta tool to convert a date/time string into seconds
3962 which can then be used to perform the same time selection.
3964 The selections are cumulative so that at the end of this example
3965 only data in the specified time range, with the specified,
3966 interferometers, uv distances, spectral window and polarization
3967 setup are selected.
3969 --------------------------------------------------------------------------------
3971 """
3972 return _ms.ms_selectold(self, *args, **kwargs)
3975 def selecttaqlold(self, *args, **kwargs):
3976 """
3977 selecttaqlold(self, _msselect) -> bool
3981 Summary:
3982 Select a subset of the measurement set.
3984 Description:
3987 DEPRECATED: Please use the ms::selecttaql() function in place of
3988 ms::selecttaqlold().
3990 This function will select a subset of the current measurement set
3991 based on the standard TaQL selection string given.
3993 Repeated use of this function, with different arguments, will
3994 further refine the selection, resulting in a successively smaller
3995 selected measurement set. If the selected measurement set does not
3996 contain any rows then this function will return False and send a
3997 warning message in the logger. Otherwise this function will return
3998 True. To undo all the selections you need to use the selectinitold
3999 function (with reset=True). Note that index values used in the TaQL
4000 string are zero-based as are all tool indices.
4004 Input Parameters:
4005 msselect TaQL selection string
4007 Example:
4009 ms.open('3C273XC1.MS')
4010 ms.selectinitold(datadescid=0)
4011 ms.selectold({'antenna1':[0,2,4],'uvdist':[1200.,1900.]})
4012 ms.selecttaqlold('ANTENNA1==2')
4013 ms.rangeold(['ANTENNA1','ANTENNA2'])
4014 # {'antenna1': array([2]),
4015 # 'antenna2': array([ 6, 9, 11, 18, 20, 21, 24])}
4017 This example selects all the data from the measurement set where
4018 the value in the DATA_DESC_ID column is zero. This corresponds to a
4019 particular spectral window and polarization setup. It then selects
4020 all the data where the first antenna in the interferometer is
4021 number zero, two or four and where the uv distance is between 1200
4022 and 1900 meters. Finally it uses a query to select all the data
4023 for which the ANTENNA1 column is 2 (this selects the middle antenna
4024 of the previous, zero-based, selection). The selections are
4025 cumulative so that at the end of this example only data in the
4026 specified time range, with the specified interferometers, uv
4027 distances, spectral window and polarization setup are selected.
4029 --------------------------------------------------------------------------------
4031 """
4032 return _ms.ms_selecttaqlold(self, *args, **kwargs)
4035 def selectchannelold(self, *args, **kwargs):
4036 """
4037 selectchannelold(self, _nchan, _start, _width, _inc) -> bool
4041 Summary:
4042 Select and average frequency channels
4044 Description:
4047 DEPRECATED: Please use the ms::selectchannel() function in place of
4048 ms::selectchannelold().
4050 This function allows you to select a subset of the frequency
4051 channels in the current measurement set. This function can also
4052 average, over frequency channels, prior to providing the values to
4053 the user.
4055 Selection on channels is not allowed using either the select or
4056 command functions as they can only select entire rows in a
4057 measurement set. Channel selection involves accessing only some of
4058 the values in a row. Like all the selection functions this
4059 function does not change the current measurement but updates the
4060 measurement set selection parameters so that functions like
4061 getdataold will return the desired subset of the data. Repeated
4062 use of this function will overwrite any previous channel selection.
4064 There are four parameters, the number of output channels, the
4065 first input channel to use, the number of input channels to
4066 average into one output channel, and the increment in the input
4067 spectrum for the next output channel. All four parameters need to
4068 be specified.
4070 When all data to be averaged is unflagged, the result is the
4071 averaged value and the corresponding flag is False. When all data
4072 is flagged, the result is set to zero and the corresponding flag is
4073 True. When data to be averaged is mixed (unflagged and flagged),
4074 only the unflagged values are averaged and the flag is set to
4075 False.
4077 This function return True if the selection was successful, and
4078 False if not. In the latter case an error message will also be sent
4079 to the logger.
4081 You need to call selectinitold before
4082 calling this function. If you haven't then selectinitold will be
4083 called for you with default arguments.
4086 Input Parameters:
4087 nchan Number of output channels, positive integer
4088 start First input channel to use, positive integer
4089 width Number of input channels to average together, positive integer
4090 inc Increment to next (group of) input channel(s), positive integer
4092 Example:
4094 ms.fromfits('NGC5921.MS',
4095 '/usr/lib/casapy/data/demo/NGC5921.fits')
4096 ms.selectinitold(datadescid=0)
4097 ms.selectchannelold(3,2,5,3)
4099 This example selects all the data from the measurement set where
4100 the value in the DATA_DESC_ID column is zero. This corresponds to a
4101 particular spectral window and polarization setup. It then selects
4102 on frequency channels to produce 3 output channels, the first
4103 output channel is the average of channels 2,3,4,5,6 in the input,
4104 the second output channel is the average of channel 5,6,7,8,9 and
4105 the third is the average of channels 8,9,10,11,12.
4107 --------------------------------------------------------------------------------
4109 """
4110 return _ms.ms_selectchannelold(self, *args, **kwargs)
4113 def selectpolarizationold(self, *args, **kwargs):
4114 """
4115 selectpolarizationold(self, _wantedpol) -> bool
4119 Summary:
4120 Selection and convertion of polarizations
4122 Description:
4125 DEPRECATED: Please use the ms::selectpolarization() function in
4126 place of ms::selectpolarizationold().
4128 This function allows you to select a subset of the polarizations
4129 in the current measurement set. This function can also setup
4130 conversion to different polarization representations.
4132 You specify the polarizations using a string vector. Allowable
4133 strings are include I, Q, U, V, RR, RL, LR, LL, XX, YY, XY,
4134 YX. These string must be specified in upper case. If the
4135 polarizations match those present in the measurement set they will
4136 be selected directly, otherwise all polarizations are read and
4137 then a conversion step is done. If the conversion cannot be done
4138 then an error will be produced when you try to access the data.
4140 This function return True if the selection was successful, and
4141 False if not.
4143 You need to call selectinitold before
4144 calling this function. If you haven't then selectinitold will be
4145 called for you with default arguments.
4148 Input Parameters:
4149 wantedpol The polarizations wanted
4151 Example:
4153 ms.open('3C273XC1.MS')
4154 ms.selectinitold(datadescid=0)
4155 ms.selectpolarizationold(['I','V'])
4156 rec = ms.getdataold('data')
4158 This example selects all the data from the measurement set where
4159 the value in the DATA_DESC_ID column is zero. This corresponds to a
4160 particular spectral window and polarization setup. It then selects
4161 the I and V polarizations and when the getdataold function is
4162 called the conversion from RR, LL, LR, RL polarizations to I and V
4163 occurs.
4165 --------------------------------------------------------------------------------
4167 """
4168 return _ms.ms_selectpolarizationold(self, *args, **kwargs)
4171 def getdataold(self, *args, **kwargs):
4172 """
4173 getdataold(self, _items, _ifraxis, _ifraxisgap, _increment, _average) -> record *
4177 Summary:
4178 Read values from the measurement set.
4180 Description:
4183 DEPRECATED: Please use the ms::getdata() function in place
4184 of ms::getdataold().
4186 This function will read the specified items from the currently
4187 selected measurement set and returns them in fields of a record.
4188 The main difference between this and direct access of the table,
4189 using the table tool, is that this function reads data from the
4190 selected measurement set, it provides access to derived
4191 quantities like amplitude and flag_sum and it can reorder the
4192 data.
4194 The items to read are specified, as with the rangeold function,
4195 using a vector of strings. Allowable items include: amplitude,
4196 corrected_amplitude, model_amplitude, ratio_amplitude,
4197 residual_amplitude, obs_residual_amplitude, antenna1, antenna2,
4198 axis_info, data, corrected_data, model_data, ratio_data,
4199 residual_data, obs_residual_data, feed1, feed2, field_id, flag,
4200 flag_row, flag_sum, ha (added to axis_info), ifr_number, imaginary,
4201 corrected_imaginary, model_imaginary, ratio_imaginary,
4202 residual_imaginary, obs_residual_imaginary, last (added to
4203 axis_info), phase, corrected_phase, model_phase, ratio_phase,
4204 residual_phase, obs_residual_phase, real, corrected_real,
4205 ratio_real, residual_real, obs_residual_real, scan_number, sigma,
4206 data_desc_id, time, ut (added to axis_info), uvw, u, v, w, uvdist,
4207 and weight. Unrecognized items will result in a warning being sent
4208 to the logger. Duplicate items are silently ignored.
4210 The record that is returned contains fields that correspond to
4211 each of the specified items. Most fields will contain an array. The
4212 array may be one, two or three dimensional depending on whether the
4213 corresponding row in the measurement set is a scalar, one or two
4214 dimensional. Unless the ifraxis argument is set to True the length
4215 of the last axis on these arrays will correspond to the number of
4216 rows in the selected measurement set.
4218 If the ifraxis argument is set to True, the row axis is split into
4219 an interferometer axis and a time axis. For example a measurement
4220 set with 90 rows, in an array with 6 telescopes (so that there are
4221 15 interferometers), may have a data array of shape [4,32,90]
4222 if ifraxis is False or [4,32,15,6], if ifraxis is True (assuming
4223 there are 4 correlations and 32 channels). If there are missing
4224 rows as will happen if not all interferometers where used for all
4225 time-slots then a default value will be inserted.
4227 This splitting of the row axis may not happen for items where
4228 there is only a single value per row. For some items the returned
4229 vector will contain only as many values as there are
4230 interferometers and it is implicit that the same value should be
4231 used for all time slots. The antenna1, antenna2, feed1, feed2, and
4232 ifr_number items fall in this category. For other items the
4233 returned vector will have as many values as there are time slots
4234 and it is implicit that the same value should be used for all
4235 interefometers. The field_id, scan_number, data_desc_id, and
4236 time items fall into this category.
4238 The axis_info item provides data labelling information. It
4239 returns a record with the following fields: corr_axis, freq_axis,
4240 ifr_axis and time_axis. The latter two fields are not present if
4241 ifr_axis is set to False. The corr_axis field contains a string
4242 vector with elements like 'RR' or 'XY' that indicates which
4243 polarizations where correlated together to produce the data. The
4244 length of this vector will always be the same as the length of the
4245 first axis of the data array. The freq_axis field contains a record
4246 with two fields, chan_freq and resolution. Each of these fields
4247 contains vectors which indicate the centre frequency and spectral
4248 resolution (FWHM) of each channel. The length of these vectors will
4249 be the same as the length of the second axis in the data. The
4250 ifr_axis field contains fields: ifr_number, ifr_name,
4251 ifr_shortname, and baseline. The ifr_number is the same as returned
4252 by the ifr_item, the ifr_name and ifr_shortname are string vecors
4253 containing descriptions of the interferometer and the baseline is
4254 the Euclidian distance, in meters between the two antennas. All of
4255 these vectors have a length equal to the number of interferometers
4256 in the selected measurement set ie., to the length of the third
4257 axis in the data when ifraxis is True. The time_axis field contains
4258 the MJD seconds field and optionally the HA, UT, and LAST fields.
4259 To include the optional fields you need to add the ha, last or ut
4260 strings to the list of requested items. All the fields in the
4261 time_axis record contain vectors that indicate the time at the
4262 midpoint of the observation and are in seconds. The MJD seconds
4263 field is since 0 hours on the day having a modified julian day
4264 number of zero and the rest are since midnight prior to the start
4265 of the observation.
4267 An optional gap size can be specified to visually separate groups
4268 of interferometers with the same antenna1 index (handy for
4269 identifying antennas in an interferometer vs time display). The
4270 default is no gap.
4272 An optional increment can be specified to return data from every
4273 row matching the increment only.
4275 When the average flag is set, the data will be averaged over the
4276 time axis if the ifraxis is True or the row axis i.e., different
4277 interferometers and times may be averaged together. In the latter
4278 case, some of the coordinate information, like antenna_id, will
4279 no longer make sense. When all data to be averaged is unflagged,
4280 the result is the averaged value and the corresponding flag is
4281 False. When all data is flagged, the result is set to zero and the
4282 corresponding flag is True. When data to be averaged is mixed
4283 (unflagged and flagged), only the unflagged values are averaged and
4284 the flag is set to False.
4286 You need to call selectinitold before
4287 calling this function. If you haven't then selectinitold will be
4288 called for you with default arguments.
4290 Items prefixed with corrected, model, residual or obs_residual are
4291 not available unless your measurement set has been processed either
4292 with the imager or calibrator tools.
4295 Input Parameters:
4296 items Item names
4297 ifraxis Create interferometer axis if True
4298 ifraxisgap Gap size on ifr axis when antenna1 changes
4299 increment Row increment for data access
4300 average Average the data in time or over rows
4302 Example:
4304 ms.open('3C273XC1.MS')
4305 ms.selectinitold(datadescid=0)
4306 # Get amplitude and MJDseconds
4307 d = ms.getdataold(['amplitude','axis_info'],ifraxis=True)
4308 tstart = min(d['axis_info']['time_axis']['MJDseconds'])
4309 tstop = max(d['axis_info']['time_axis']['MJDseconds'])
4310 maxamp = max(max(d['amplitude'][:,0,0,0]),max(d['amplitude'][0,:,0,0]),
4311 max(d['amplitude'][0,0,:,0]),max(d['amplitude'][0,0,0,:]))
4312 print 'MJD start time (seconds) =', tstart
4313 # MJD start time (seconds) = 4121629400.0
4314 print 'MJD stop time (seconds) =', tstop
4315 # MJD stop time (seconds) = 4121642670.0
4316 # MJDseconds Correlation amplitude
4317 print 'Maximum correlation amplitude =', maxamp
4318 # Maximum correlation amplitude = 33.5794372559
4319 chan = 0
4320 corr = 0
4321 freqGHz = d['axis_info']['freq_axis']['chan_freq'][chan]/1.0E9
4322 baselineStr = d['axis_info']['ifr_axis']['ifr_name'][corr]
4323 corrStr = d['axis_info']['corr_axis'][corr]
4324 tcoord = d['axis_info']['time_axis']['MJDseconds']
4325 acoord = d['amplitude'][0,0,0,:]
4326 print 'Frequency', freqGHz, 'GHz', 'Baseline', baselineStr, '(', corrStr, ')'
4327 print 'MJDseconds', 'Correlation amplitude'
4328 for i in range(len(tcoord)):
4329 print tcoord[i], acoord[i]
4330 #
4331 # Frequency [ 8.085] GHz Baseline 1-2 ( RR )
4332 # MJDseconds Correlation amplitude
4333 # 4121629400.0 29.2170944214
4334 # 4121629410.0 29.1688995361
4335 # 4121629420.0 29.2497825623
4336 # 4121629430.0 29.2029647827
4337 # 4121629440.0 29.166015625
4338 # 4121629450.0 29.2417526245
4339 # 4121629460.0 29.2867794037
4340 # 4121638270.0 0.0
4341 # 4121638280.0 29.4539775848
4342 # 4121638290.0 29.472661972
4343 # 4121638300.0 29.4424362183
4344 # 4121638310.0 29.4234466553
4345 # 4121638320.0 29.4018745422
4346 # 4121638330.0 29.3326053619
4347 # 4121638340.0 29.3575496674
4348 # 4121642600.0 31.1411132812
4349 # 4121642610.0 31.0726108551
4350 # 4121642620.0 31.1242599487
4351 # 4121642630.0 31.0505466461
4352 # 4121642640.0 31.0448284149
4353 # 4121642650.0 30.9974422455
4354 # 4121642660.0 31.0648326874
4355 # 4121642670.0 31.0638961792
4358 This example selects all the data from the measurement set where
4359 the value in the DATA_DESC_ID column is zero. This corresponds to a
4360 particular spectral window and polarization setup. It then gets the
4361 correlated amplitude, and the axis information from this selected
4362 measurement set. This is returned in the casapy variable d. The
4363 remainder of the example prints a table of 'hour angle' and
4364 corresponding 'correlated amplitude' for the first channel,
4365 correlation and baseline.
4367 --------------------------------------------------------------------------------
4369 """
4370 return _ms.ms_getdataold(self, *args, **kwargs)
4373 def putdataold(self, *args, **kwargs):
4374 """
4375 putdataold(self, _items) -> bool
4379 Summary:
4380 Write new values into the measurement set
4382 Description:
4385 DEPRECATED: Please use the ms::putdata() function in place
4386 of ms::putdataold().
4388 This function allows you to write values from casapy variables back
4389 into the measurement set table. The main difference between this
4390 and directly accessing the table using the table tool is that this
4391 function writes data to the selected measurement set.
4393 Unlike the getdataold function you can only put items that
4394 correspond to actual table columns. You cannot change the data
4395 shape either so that the number of correlations, channels and rows
4396 (or intereferometers/time slots) must match the values in the
4397 selected measurement set. If the values were obtained using the
4398 getdataold function with ifraxis argument set to True, then any
4399 default values added to fill in missing intereferometer/timeslots
4400 pairs will be ignored when writing the modified values back using
4401 this function.
4403 Allowable items include: data, corrected_data, model_data, flag,
4404 flag_row, sigma, and weight.
4406 The measurement set has to be opened for read/write access to be
4407 able to use this function.
4409 You need to call selectinitold before
4410 calling this function. If you haven't then selectinitold will be
4411 called for you with default arguments.
4413 Items prefixed with corrected, model, residual or obs_residual are
4414 not available unless your measurement set has been processed either
4415 with the imager or calibrator tools.
4418 Input Parameters:
4419 items Record with items and their new values
4421 Example:
4423 ms.open('3C273XC1.MS', nomodify=False)
4424 ms.selectinitold(datadescid=0)
4425 rec = ms.getdataold(['weight','data'])
4426 rec['weight'][:,:] = 1
4427 import Numeric
4428 meanrec = Numeric.average(rec['data'],axis=None)
4429 print 'Mean data value = ', meanrec
4430 rec['data'][:,:,:] -= meanrec
4431 ms.putdataold(rec)
4433 This example selects all the data from the measurement set where
4434 the value in the DATA_DESC_ID column is zero. This corresponds to a
4435 particular spectral window and polarization setup. Note that the
4436 measurement set was opened for writing as well as reading. The
4437 third line reads all the weights and the data into the variable
4438 rec. The weights are set to one. The more obscure syntax is used as
4439 typing rec['weight'] = 1 will not preserve the shape of the weight
4440 array. The data then has its mean subtracted from it. The average
4441 function is defined in Numeric module. Finally the data is written
4442 back into the measurement set table. (NOTE: normally one should not
4443 modify the raw data column. Such adjustments are more appropriate
4444 for the corrected_data column, if it exists.)
4446 --------------------------------------------------------------------------------
4448 """
4449 return _ms.ms_putdataold(self, *args, **kwargs)
4452 def iterinitold(self, *args, **kwargs):
4453 """
4454 iterinitold(self, _columns, _interval, _maxrows, _adddefaultsortcolumns) -> bool
4458 Summary:
4459 Initialize for iteration over an ms
4461 Description:
4464 DEPRECATED: Please use the ms::iterinit() function in place
4465 of ms::iterinitold().
4467 Specify the columns to iterate over and the time interval to use
4468 for the TIME column iteration. The columns are specified by their
4469 MS column name and must contain scalar values.
4471 Note that the following columns are always added to the specified
4472 columns: array_id, field_id, data_desc_id and time. This is so that
4473 the iterator can keep track of the coordinates associated with the
4474 data (field direction, frequency, etc.). If you want to sort on
4475 these columns last instead of first, you need to include them in
4476 the columns specified. If you don't want to sort on these columns
4477 at all, you can set adddefaultsortcolumns to False.
4479 You may want to use iteration for a large dataset. After calling
4480 iterinitold, you must call iteroriginold before attempting to
4481 retrieve data with getdataold.
4483 You need to call selectinitold before calling this.
4486 Input Parameters:
4487 columns Vector of column names (case sensitive).
4488 interval Time interval in seconds (greater than 0), to group together in iteration
4489 maxrows Max number of rows (greater than 0) to return in iteration
4490 adddefaultsortcolumns Add the default sort columns
4492 Example:
4494 See the example for the iterendold function.
4496 --------------------------------------------------------------------------------
4498 """
4499 return _ms.ms_iterinitold(self, *args, **kwargs)
4502 def iteroriginold(self):
4503 """
4504 iteroriginold(self) -> bool
4508 Summary:
4509 Set the iterator to the start of the data.
4511 Description:
4514 DEPRECATED: Please use the ms::iterorigin() function in place
4515 of ms::iteroriginold().
4517 Set or reset the iterator to the start of the currently specified
4518 iteration. You need to call this after iterinitold, before
4519 attempting to retrieve data with getdataold. You may also use
4520 iteroriginold to set the iteration back to the start before you
4521 reach the end of the data.
4524 Example:
4526 See the example for the iterendold function.
4528 --------------------------------------------------------------------------------
4530 """
4531 return _ms.ms_iteroriginold(self)
4534 def iternextold(self):
4535 """
4536 iternextold(self) -> bool
4540 Summary:
4541 Advance the iterator to the next lot of data
4543 Description:
4546 DEPRECATED: Please use the ms::iternext() function in place
4547 of ms::iternextold().
4549 This sets the currently selected table (as accessed with
4550 getdataold) to the next iteration. If there is no more data, the
4551 function returns False and the selection is reset to that before
4552 the iteration started. You need to call iterinitold and
4553 iteroriginold before calling this.
4556 Example:
4558 See the example for the iterendold function.
4560 --------------------------------------------------------------------------------
4562 """
4563 return _ms.ms_iternextold(self)
4566 def iterendold(self):
4567 """
4568 iterendold(self) -> bool
4572 Summary:
4573 End the iteration and reset the selected table
4575 Description:
4578 DEPRECATED: Please use the ms::iterend() function in place
4579 of ms::iterendold().
4581 This sets the currently selected table (as accessed with
4582 getdataold) to the table that was selected
4583 before iteration started. Use this to end the iteration
4584 prematurely. There is no need to call this if you continue
4585 iterating until iternextold returns False.
4587 See the example below.
4590 Example:
4592 ms.open('3C273XC1.MS')
4593 ms.selectinitold(datadescid=0)
4594 ms.iterinitold(['ANTENNA1','ANTENNA2','TIME'],60.0)
4595 ms.iteroriginold()
4596 rec=ms.getdataold(['u','v','data'])
4597 ms.iternextold()
4598 ms.iterendold()
4600 We open the MS, select an array and spectral window and then
4601 specify an iteration over interferometer and time, with a 60s time
4602 interval. We then set the iterator to the start of the data and
4603 get out some data. Finally we advance the iterator to the next lot
4604 of data and then end the iteration.
4606 --------------------------------------------------------------------------------
4608 """
4609 return _ms.ms_iterendold(self)
4612 def continuumsubold(self, *args, **kwargs):
4613 """
4614 continuumsubold(self, _field, _fitspw, _spw, _solint, _fitorder, _mode) -> bool
4618 Summary:
4619 Continuum fitting and subtraction in uv plane
4621 Description:
4624 DEPRECATED: This function is deprecated and will be removed in an
4625 upcoming release.
4627 This function provides a means of continuum determination and
4628 subtraction by fitting a polynomial of desired order to a subset
4629 of channels in each time-averaged uv spectrum. The fit is used
4630 to model the continuum in all channels (not just those used in
4631 the fit), for subtraction, if desired. Use the fitspw parameter
4632 to limit the spectral windows processed and the range of channels
4633 used to estimate the continuum in each (avoid channels
4634 containing spectral lines). The default solution interval 'int'
4635 will result in per-integration continuum fits for each baseline.
4636 The mode parameter indicates how the continuum model (the result
4637 of the fit) should be used: 'subtract' will store the continuum
4638 model in the MODEL_DATA column and subtract it from the
4639 CORRECTED_DATA column; 'replace' will replace the CORRECTED_DATA
4640 column with the continuum model (useful if you want to image the
4641 continuum model result); and 'model' will only store the
4642 continuum model in the MODEL_DATA column (the CORRECTED_DATA is
4643 unaffected).
4645 It is important to open the dataset with nomodify=False so that
4646 changes will be allowed (see example below).
4648 For now, the only way to recover the un-subtracted CORRECTED_DATA
4649 column is to use calibrater.correct() again.
4651 Note that the MODEL_DATA and CORRECTED_DATA columns must be
4652 present for continuumsubold to work correctly. The function will
4653 warn the user if they are not present, and abort. To add these
4654 scratch columns, close the ms tool, then start a calibrater or an
4655 imager tool, which will add the scratch columns. Then restart
4656 the ms tool, and try continuumsubold again.
4659 Input Parameters:
4660 field Select fields to fit
4661 fitspw Spectral windows/channels to use for fitting the continuum; default all spectral windows in all channels
4662 spw Select spectral windows and channels from which to subtract a continuum estimate; default: all channels in all spectral windows for which the continuum was estimated
4663 solint Continuum fit timescale (units optional)
4664 fitorder Polynomial order for fit
4665 mode Desired use of fit model (see below)
4667 Example:
4669 ms.fromfits('ngc5921.ms','/aips++/data/demo/NGC5921.fits')
4670 ms.close()
4671 cb.open('ngc5921.ms') # add MODEL_DATA, CORRECTED_DATA columns
4672 cb.close()
4673 ms.open('ngc5921.ms',nomodify=False); # writable!
4674 ms.continuumsubold(field=2,fitspw='0:5~9;50~59',solint=0.0,
4675 fitorder=1,mode='subtract')
4676 ms.done()
4678 This example will fit a linear continuum to channels 5-9 and 50-59
4679 in spectral window 0 in each scan-averaged spectrum for field 2,
4680 and store the result in the MODEL_DATA column and subtract it from
4681 the CORRECTED_DATA column.
4683 --------------------------------------------------------------------------------
4685 """
4686 return _ms.ms_continuumsubold(self, *args, **kwargs)
4688 __swig_destroy__ = _ms.delete_ms
4689 __del__ = lambda self: None
4690ms_swigregister = _ms.ms_swigregister
4691ms_swigregister(ms)
4693# This file is compatible with both classic and new-style classes.