Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatasks/flagcmd.py: 100%
27 statements
« prev ^ index » next coverage.py v7.6.4, created at 2024-11-01 07:19 +0000
1##################### generated by xml-casa (v2) from flagcmd.xml ###################
2##################### b8a2611ec7c82cf7a20bc5e22bf736d2 ##############################
3from __future__ import absolute_import
4import numpy
5from casatools.typecheck import CasaValidator as _val_ctor
6_pc = _val_ctor( )
7from casatools.coercetype import coerce as _coerce
8from casatools.errors import create_error_string
9from .private.task_flagcmd import flagcmd as _flagcmd_t
10from casatasks.private.task_logging import start_log as _start_log
11from casatasks.private.task_logging import end_log as _end_log
12from casatasks.private.task_logging import except_log as _except_log
14class _flagcmd:
15 """
16 flagcmd ---- Flagging task based on batches of flag-commands
19 The flagcmd task will flag the visibility data or calibration
20 table based on several batch-operations using flag commands.
22 Flag commands follow the mode and parameter names from the
23 flagdata task.
25 The flagcmd task will flag data based on the commands input on
26 inpmode:
27 table = input from FLAG_CMD table in MS
28 list = input from text file or list of strings from inpfile
29 xml = input from Flag.xml in the MS given by vis
31 Batch operations include : apply/unapply/list/plot/clear/extract
33 IMPORTANT: If you use other ways to flag such as interactive
34 flagging in plotms, the FLAG_CMD will NOT be updated!
36 NOTE on flagging calibration tables.
37 -----------------------------------
38 We recommend using the flagdata task for flagging cal tabels. When
39 using flagcmd to flag cal tables, only the 'apply' and 'list'
40 actions are supported. Because cal tables do not have a FLAG_CMD
41 sub-table, the default inpmode='table' can only be used if an MS
42 is given in the 'inpfile' parameter so that flags from the MS are
43 applied to the cal table. Otherwise, the flag commands must be
44 given using inpmode='list', either from a file(s) or from a list
45 of strings. Data selection for calibration tables is limited to
46 field, scan, antenna, time, spw and observation.
50 --------- parameter descriptions ---------------------------------------------
52 vis Name of input visibility file or calibration table.
53 default: '' (none)
55 example: vis='uid___A002_X2a5c2f_X54.ms'
56 inpmode Input mode for flag commands(table/list/xml)
57 options: 'table','list','xml'
58 default: 'table' (the input commands from
59 FLAG_CMD table of the MS)
61 inpmode='xml' inputs online flags from Flag.xml
62 file in the MS. This mode has become largely
63 obsolete with the deprecation of the importevla
64 task (see the flagcmd task pages in CASA Docs for
65 more information). This mode will not work for
66 ALMA MS or cal tables.
68 NOTE: You can only apply the flags from a list or
69 xml; you will not be able to unapply
70 them. Transfer the flag commands to the FLAG_CMD
71 table if you want to unapply the flags (see
72 'inpfile' description below).
73 inpfile Source of flag commands. Subparameter of
74 inpmode='table/list'.
75 Path to MS containing FLAG_CMD (table), or name
76 of an ASCII file, list of files or a list of
77 Python strings to apply to MS or cal table
78 (list).
79 options: [] with flag commands or [] with
80 filenames or '' with a filename. (String values
81 must contain quotes around them or the parser
82 will not work.)
83 default: '' (read from FLAG_CMD table in the MS
84 specified via 'vis')
86 Main use is to read flags from internal FLAG_CMD,
87 but one use case is to read the flag commands
88 from an MS given in inpfile and apply them to
89 another MS or cal table given in vis.
90 tablerows List of rows of the FLAG_CMD table to read. Subparameter
91 of inpmode='table/list'.
92 default: [] (read all rows)
94 example: [0,1,2,10]
96 NOTE: currently only takes integer lists, not
97 parseable strings with ranges. Use the Python
98 range function to generate ranges, e.g. tablerows
99 = range(0,30) + range(50,55) instead of
100 '0~29,50~54' for now.
101 reason Select flag commands based on REASON(s). Subparameter of
102 inpmode.
103 default: 'any' (all flags regardless of reason)
105 Examples:
106 reason='FOCUS_ERROR'
107 reason=['FOCUS_ERROR','SUBREFLECTOR_ERROR']
109 If inpfile is a list of files, the reasons given
110 in this parameter will apply to all the files.
112 NOTE: what is within the string is literally
113 matched, e.g. reason='' matches only blank
114 reasons, and reason
115 ='FOCUS_ERROR,SUBREFLECTOR_ERROR' matches this
116 compound reason string only
117 useapplied Select commands whose rows have APPLIED column set to
118 True. Subparameter of inpmode='table'.
119 options: True,False
120 default: False
122 If useapplied=True it will read in both applied
123 and unapplied flags.
125 IMPORTANT: The APPLIED column is set to True
126 after a flag command is applied to the MS. In
127 order to re-apply the same flag command, this
128 parameter should be set to True.
129 tbuff Time buffer (sec) to pad flags. Subparameter of
130 inpmode='xml'.
131 default: 0.0
132 ants Allowed flag antenna names to select by. Subparameter of
133 inpmode='xml'.
134 action Action to perform in MS and/or in inpfile
135 options: apply/unapply/list/plot/clear/extract
136 default: 'apply'
138 Examples:
139 -- action='apply': This operation will apply
140 the commands chosen by inpmode. If
141 inpmode='table' and inpfile='' then the
142 APPLIED column in FLAG_CMD will be set to
143 True.
144 -- action='unapply': unapply flags in MS. (Not
145 available for cal tables). This operation will
146 unapply the commands chosen by inpmode='table'
147 ONLY. After unapplying the commands, the task
148 will update the APPLIED column to False.
149 -- action='list': list and/or save flag
150 commands. This operation will list the
151 commands chosen by inpmode on the screen and
152 save them to the MS or to a file without
153 applying. It will save the commands to outfile
154 if the parameter savepars is set to True. If
155 outfile is None, it will save the commands to
156 the MS given in 'vis'.
157 -- action='plot': plot flags (ant
158 vs. time). (Not available for cal
159 tables). This operation will plot the flags
160 chosen by inpmode to a matplotlib gui or to a
161 file. These will be sorted by antenna
162 vs. time. Most useful for showing the online
163 flags.
164 -- action='clear': clear flags from FLAG_CMD
165 in the MS. (Not available for cal tables) This
166 operation will delete the selected flag rows
167 from the internal FLAG_CMD table of the MS.
168 -- action='extract': extract internal flag
169 dictionary. (Not available for cal tables)
170 This option will return the internal flagging
171 dictionary to python. There is no extant
172 description of the format of this dictionary,
173 as it is an internal device used by the
174 flagcmd task. This action is provided for the
175 convenience of advanced users.
177 WARNING: choosing this action='clear' will
178 disregard anything you set in inpmode and will
179 always work on the FLAG_CMD table in vis. This can
180 be used to totally delete rows from the FLAG_CMD
181 table, when setting clearall=True.
182 flagbackup Automatically backup the FLAG column before
183 execution. Subparameter of action='apply/unapply'.
184 options: True,False
185 default: True
186 clearall Delete all rows from FLAG_CMD. Subparameter of
187 action='clear'.
188 default: False (will not clear)
189 rowlist FLAG_CMD rows to clear. Subparameter of action='clear'.
190 default: [] (all flags in table)
192 example: [0,1,2,10]
194 WARNING: this can be dangerous, and you must set
195 clearall=True to use this!!! This will delete
196 the specified rows from the internal FLAG_CMD
197 table for vis regardless of what mode is set to
198 (useful for when you import from xml or file),
199 and decide to redo it). This action will NOT
200 unapply the commands.
202 NOTE: currently only takes integer lists, not
203 parseable strings with ranges. Use the Python
204 range function to generate ranges, e.g. rowlist =
205 range(0,30) + range(50,55) instead of
206 '0~29,50~54' for now.
207 plotfile Name of output file to save plot
208 default: '' (plot to matplotlib window)
210 WARNING: will only reliably plot individual flags
211 per antenna and timerange (e.g. direct from xml)
212 savepars Save the flag commands to the FLAG_CMD table of the MS or
213 to an output text file.
214 options: True/False
215 default: False
216 outfile Name of output file to save commands. Subparameter of
217 savepars=True.
218 default: ' '; it will save the commands in the
219 FLAG_CMD table of the MS.
221 example: outfile='flags.txt' will save the
222 parameters in a text file.
223 overwrite Overwrite an existing file given in 'outfile' to save the
224 flag commands. Subparameter of savepars=True.
225 options: True/False
226 default: True; it will remove the existing file
227 given in 'outfile' and save the current flag
228 commands to a new file with the same name. When
229 set to False, the task will exit with an error
230 message if the file exist.
231 [1;42mRETURNS[1;m void
233 --------- examples -----------------------------------------------------------
237 For more information, see the task pages of flagcmd in CASA Docs:
239 https://casa.nrao.edu/casadocs/
242 """
244 _info_group_ = """flagging"""
245 _info_desc_ = """Flagging task based on batches of flag-commands"""
247 def __call__( self, vis='', inpmode='table', inpfile='', tablerows=[ ], reason='any', useapplied=False, tbuff=float(0.0), ants='', action='apply', flagbackup=True, clearall=False, rowlist=[ ], plotfile='', savepars=False, outfile='', overwrite=True ):
248 schema = {'vis': {'type': 'cReqPath', 'coerce': _coerce.expand_path}, 'inpmode': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'table', 'list', 'xml' ]}, 'inpfile': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}]}, 'tablerows': {'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}, 'reason': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}]}, 'useapplied': {'type': 'cBool'}, 'tbuff': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'ants': {'type': 'cStr', 'coerce': _coerce.to_str}, 'action': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'apply', 'clear', 'plot', 'list', 'extract', 'unapply' ]}, 'flagbackup': {'type': 'cBool'}, 'clearall': {'type': 'cBool'}, 'rowlist': {'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}, 'plotfile': {'type': 'cStr', 'coerce': _coerce.to_str}, 'savepars': {'type': 'cBool'}, 'outfile': {'type': 'cStr', 'coerce': _coerce.to_str}, 'overwrite': {'type': 'cBool'}}
249 doc = {'vis': vis, 'inpmode': inpmode, 'inpfile': inpfile, 'tablerows': tablerows, 'reason': reason, 'useapplied': useapplied, 'tbuff': tbuff, 'ants': ants, 'action': action, 'flagbackup': flagbackup, 'clearall': clearall, 'rowlist': rowlist, 'plotfile': plotfile, 'savepars': savepars, 'outfile': outfile, 'overwrite': overwrite}
250 assert _pc.validate(doc,schema), create_error_string(_pc.errors)
251 _logging_state_ = _start_log( 'flagcmd', [ 'vis=' + repr(_pc.document['vis']), 'inpmode=' + repr(_pc.document['inpmode']), 'inpfile=' + repr(_pc.document['inpfile']), 'tablerows=' + repr(_pc.document['tablerows']), 'reason=' + repr(_pc.document['reason']), 'useapplied=' + repr(_pc.document['useapplied']), 'tbuff=' + repr(_pc.document['tbuff']), 'ants=' + repr(_pc.document['ants']), 'action=' + repr(_pc.document['action']), 'flagbackup=' + repr(_pc.document['flagbackup']), 'clearall=' + repr(_pc.document['clearall']), 'rowlist=' + repr(_pc.document['rowlist']), 'plotfile=' + repr(_pc.document['plotfile']), 'savepars=' + repr(_pc.document['savepars']), 'outfile=' + repr(_pc.document['outfile']), 'overwrite=' + repr(_pc.document['overwrite']) ] )
252 task_result = None
253 try:
254 task_result = _flagcmd_t( _pc.document['vis'], _pc.document['inpmode'], _pc.document['inpfile'], _pc.document['tablerows'], _pc.document['reason'], _pc.document['useapplied'], _pc.document['tbuff'], _pc.document['ants'], _pc.document['action'], _pc.document['flagbackup'], _pc.document['clearall'], _pc.document['rowlist'], _pc.document['plotfile'], _pc.document['savepars'], _pc.document['outfile'], _pc.document['overwrite'] )
255 except Exception as exc:
256 _except_log('flagcmd', exc)
257 raise
258 finally:
259 task_result = _end_log( _logging_state_, 'flagcmd', task_result )
260 return task_result
262flagcmd = _flagcmd( )