Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatasks/gaincal.py: 56%
27 statements
« prev ^ index » next coverage.py v7.6.4, created at 2024-10-31 18:48 +0000
1##################### generated by xml-casa (v2) from gaincal.xml ###################
2##################### 7c21c599f57fdbdddd203514dcc55c60 ##############################
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_gaincal import gaincal as _gaincal_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 _gaincal:
15 """
16 gaincal ---- Determine temporal gains from calibrator observations
19 The complex gains for each antenna/spwid are determined from the data
20 column (raw data) divided by the model column. The gains can be
21 obtained for a specified solution interval, spw combination and field
22 combination. The GSPLINE spline (smooth) option is still under
23 development.
25 Previous calibrations (egs, bandpass, opacity, parallactic angle) can
26 be applied on the fly. At present with dual-polarized data, both
27 polarizations must be unflagged for any solution to be obtained.
29 --------- parameter descriptions ---------------------------------------------
31 vis Name of input visibility file
32 Default: none
34 Example: vis='ngc5921.ms'
35 caltable Name of output gain calibration table
36 Default: none
38 Example: caltable='ngc5921.gcal'
39 field Select field using field id(s) or field name(s)
40 Default: '' (all fields)
42 Use 'go listobs' to obtain the list id's or
43 names. If field string is a non-negative integer,
44 it is assumed a field index, otherwise, it is
45 assumed a field name.
47 Examples:
48 field='0~2'; field ids 0,1,2
49 field='0,4,5~7'; field ids 0,4,5,6,7
50 field='3C286,3C295'; field named 3C286 and
51 3C295
52 field = '3,4C\*'; field id 3, all names
53 starting with 4C
54 spw Select spectral window/channels
55 Default: '' (all spectral windows and channels)
57 Examples:
58 spw='0~2,4'; spectral windows 0,1,2,4 (all
59 channels)
60 spw='<2'; spectral windows less than 2
61 (i.e. 0,1)
62 spw='0:5~61'; spw 0, channels 5 to 61,
63 INCLUSIVE
64 spw='\*:5~61'; all spw with channels 5 to 61
65 spw='0,10,3:3~45'; spw 0,10 all channels, spw
66 3, channels 3 to 45.
67 spw='0~2:2~6'; spw 0,1,2 with channels 2
68 through 6 in each.
69 spw='0:0~10;15~60'; spectral window 0 with
70 channels 0-10,15-60. (NOTE ';' to separate
71 channel selections)
72 spw='0:0~10^2,1:20~30^5'; spw 0, channels
73 0,2,4,6,8,10, spw 1, channels 20,25,30
74 intent Select observing intent
75 Default: '' (no selection by intent)
77 Example: intent='*BANDPASS*' (selects data
78 labelled with BANDPASS intent)
79 selectdata Other data selection parameters
80 Default: True
81 Options: True|False
82 timerange Select data based on time range
83 Subparameter of selectdata=True
84 Default = '' (all)
86 Examples:
87 timerange =
88 'YYYY/MM/DD/hh:mm:ss~YYYY/MM/DD/hh:mm:ss'
89 (Note: if YYYY/MM/DD is missing date defaults
90 to first day in data set.)
91 timerange='09:14:0~09:54:0' picks 40 min on
92 first day
93 timerange= '25:00:00~27:30:00' picks 1 hr to 3
94 hr 30min on NEXT day
95 timerange='09:44:00' pick data within one
96 integration of time
97 timerange='>10:24:00' data after this time
98 uvrange Select data by baseline length.
99 Default = '' (all)
101 Examples:
102 uvrange='0~1000klambda'; uvrange from 0-1000 kilo-lambda
103 uvrange='>4klambda';uvranges greater than 4 kilo-lambda
104 uvrange='0~1000km'; uvrange in kilometers
105 antenna Select data based on antenna/baseline
106 Subparameter of selectdata=True
107 Default: '' (all)
109 If antenna string is a non-negative integer, it
110 is assumed an antenna index, otherwise, it is
111 assumed as an antenna name
113 Examples:
114 antenna='5&6'; baseline between antenna
115 index 5 and index 6.
116 antenna='VA05&VA06'; baseline between VLA
117 antenna 5 and 6.
118 antenna='5&6;7&8'; baselines with
119 indices 5-6 and 7-8
120 antenna='5'; all baselines with antenna index
121 5
122 antenna='05'; all baselines with antenna
123 number 05 (VLA old name)
124 antenna='5,6,10'; all baselines with antennas
125 5,6,10 index numbers
126 scan Scan number range
127 Subparameter of selectdata=True
128 Default: '' = all
130 Check 'go listobs' to insure the scan numbers are
131 in order.
132 observation Select by observation ID(s)
133 Subparameter of selectdata=True
134 Default: '' = all
136 Example: observation='0~2,4'
137 msselect Optional complex data selection (ignore for now)
138 solint Solution interval
139 Default: 'inf' (infinite, up to boundaries
140 controlled by combine);
141 Options: 'inf' (~infinite), 'int' (per
142 integration), any float or integer value with or
143 without units
145 Examples:
146 solint='1min'; solint='60s', solint=60 (i.e.,
147 1 minute); solint='0s'; solint=0; solint='int'
148 (i.e., per integration); solint-'-1s';
149 solint='inf' (i.e., ~infinite, up to
150 boundaries enforced by combine)
151 combine Data axes which to combine for solve
152 Default: 'scan' (solutions will break at obs,
153 field, and spw boundaries)
154 Options: '','obs','scan','spw',field', or any
155 comma-separated combination in a single string
157 Example: combine='scan,spw' - Extend solutions
158 over scan boundaries (up to the solint), and
159 combine spws for solving
160 preavg Pre-averaging interval (sec)
161 Default: -1.0 (none)
163 Rarely needed. Will average data over periods
164 shorter than the solution interval first.
165 refant Reference antenna name(s); a prioritized list may be
166 specified
167 Default: '' (No refant applied)
169 Examples:
170 refant='4' (antenna with index 4)
171 refant='VA04' (VLA antenna #4)
172 refant='EA02,EA23,EA13' (EVLA antenna EA02,
173 use EA23 and EA13 as alternates if/when EA02
174 drops out)
176 Use taskname=listobs for antenna listing
177 refantmode Reference antenna mode
178 Default: 'flex'
180 - 'flex': If the preferred or current refant drops out, switch to another. Alternate reference antennas will be chosen from the refant parameter (if a nontrivial list of antennas is specified), or according to proximity to the last-used refant. If and when the preferred refant returns, the referencing will switch back to it.
181 - 'strict': If the preferred or current refant is absent for a solution, flag all antennas at that solution. This mode ensures that the effective cross-hand phase will be maintained constant and equal to that of the chosen refant, and not subject to variation due to finite SNR when switching among reference antennas. If a list of antennas is specified in refant, only the first is used.
182 minblperant Minimum number of baselines required per antenna for each
183 solve
184 Default: 4
186 Antennas with fewer baselines are excluded from
187 solutions.
189 Example: minblperant=10 --> Antennas
190 participating on 10 or more baselines are
191 included in the solve
193 minblperant = 1 will solve for all baseline
194 pairs, even if only one is present in the data
195 set. Unless closure errors are expected, use
196 taskname=gaincal rather than taskname=blcal to
197 obtain more options in data analysis.
198 minsnr Reject solutions below this SNR
199 Default: 3.0
200 solnorm Normalize (squared) solution amplitudes (G, T only)
201 Default: False (no normalization)
202 normtype Solution normalization calculation type: mean or median
203 Default: 'mean'
204 gaintype Type of gain solution (G,T,GSPLINE,K,KCROSS)
205 Default: 'G'
207 Example: gaintype='GSPLINE'
209 - 'G' means determine gains for each polarization and sp_wid
210 - 'T' obtains one solution for both polarizations;
211 Hence. their phase offset must be first removed
212 using a prior G.
213 - 'GSPLINE' makes a spline fit to the calibrator
214 data. It is useful for noisy data and fits a
215 smooth curve through the calibrated amplitude and
216 phase. However, at present GSPLINE is somewhat
217 experimental. Use with caution and check
218 solutions.
219 - 'K' solves for simple antenna-based delays via
220 FFTs of the spectra on baselines to the reference
221 antenna. (This is not global fringe-fitting.)
222 If combine includes 'spw', multi-band delays are
223 determined; otherwise, per-spw single-band delays
224 will be determined.
225 - 'KCROSS' solves for a global cross-hand delay.
226 Use parang=T and apply prior gain and bandpass
227 solutions. Multi-band delay solves
228 (combine='spw') not yet supported for KCROSS.
229 smodel Point source Stokes parameters for source model
230 (experimental).
231 Default: [] (use MODEL_DATA column)
233 Example: [1,0,0,0] (I=1, unpolarized)
234 calmode Type of solution" ('ap', 'p', 'a')
235 Default: 'ap' (amp and phase)
236 Options: 'p' (phase) ,'a' (amplitude), 'ap'
237 (amplitude and phase)
239 Example: calmode='p'
240 solmode Robust solving mode:
241 Options: '', 'L1', 'R', 'L1R'
242 rmsthresh RMS Threshold sequence
243 Subparameter of solmode='R' or 'L1R'
245 See CASA Docs for more information
246 (https://casa.nrao.edu/casadocs/)
247 corrdepflags f False (default), if any correlation is flagged, treat all correlations in
248 the visibility vector as flagged when solving (per channel, per baseline).
249 If True, use unflagged correlations in a visibility vector, even if one or more
250 other correlations are flagged.
252 Default: False (treat correlation vectors with one or more correlations flagged as entirely flagged)
254 Traditionally, CASA has observed a strict interpretation of
255 correlation-dependent flags: if one or more correlations
256 (for any baseline and channel) is flagged, then all available
257 correlations for the same baseline and channel are
258 treated as flagged. However, it is desirable in some
259 circumstances to relax this stricture, e.g., to preserve use
260 of data from antennas with only one good polarization (e.g., one polarization
261 is bad or entirely absent). Solutions for the bad or missing polarization
262 will be rendered as flagged.
263 append Append solutions to the (existing) table
264 Default: False (overwrite existing table or make
265 new table)
267 Appended solutions must be derived from the same
268 MS as the existing caltable, and solution spws
269 must have the same meta-info (according to spw
270 selection and solint) or be non-overlapping.
271 splinetime Spline timescale(sec); All spw\'s are first averaged.
272 Subparameter of gaintype='GSPLINE'
273 Default: 3600 (1 hour)
275 Example: splinetime=1000
277 Typical splinetime should cover about 3 to 5
278 calibrator scans.
279 npointaver Tune phase-unwrapping algorithm
280 Subparameter of gaintype='GSPLINE'
281 Default: 3; Keep at this value
282 phasewrap Wrap the phase for jumps greater than this value
283 (degrees)
284 Subparameter of gaintype='GSPLINE'
285 Default: 180; Keep at this value
286 docallib Control means of specifying the caltables
287 Default: False (Use gaintable, gainfield, interp,
288 spwmap, calwt)
289 Options: False|True
291 If True, specify a file containing cal library in
292 callib
293 callib Specify a file containing cal library directives
294 Subparameter of docallib=True
295 gaintable Gain calibration table(s) to apply on the fly
296 Default: '' (none)
297 Subparameter of docallib=False
298 Examples:
299 gaintable='ngc5921.gcal'
300 gaintable=['ngc5921.ampcal','ngc5921.phcal']
301 gainfield Select a subset of calibrators from gaintable(s)
302 Default: '' (all sources on the sky)
304 'nearest' ==> nearest (on sky) available field in
305 table otherwise, same syntax as field
307 Examples:
308 gainfield='0~2,5' means use fields 0,1,2,5
309 from gaintable
310 gainfield=['0~3','4~6'] means use field 0
311 through 3
312 interp Interpolation parmameters (in time[,freq]) for each gaintable, as a list of strings.
313 Default: '' --> 'linear,linear' for all gaintable(s)
314 Options: Time: 'nearest', 'linear'
315 Freq: 'nearest', 'linear', 'cubic',
316 'spline'
317 Specify a list of strings, aligned with the list of caltable specified
318 in gaintable, that contain the required interpolation parameters
319 for each caltable.
321 - When frequency interpolation is relevant (B, Df,
322 Xf), separate time-dependent and freq-dependent
323 interp types with a comma (freq after the
324 comma).
325 - Specifications for frequency are ignored when the
326 calibration table has no channel-dependence.
327 - Time-dependent interp options ending in 'PD'
328 enable a "phase delay" correction per spw for
329 non-channel-dependent calibration types.
330 - For multi-obsId datasets, 'perobs' can be
331 appended to the time-dependent interpolation
332 specification to enforce obsId boundaries when
333 interpolating in time.
334 - For multi-scan datasets, 'perscan' can be
335 appended to the time-dependent interpolation
336 specification to enforce scan boundaries when
337 interpolating in time.
338 - Freq-dependent interp options can have 'flag' appended
339 to enforce channel-dependent flagging, and/or 'rel'
340 appended to invoke relative frequency interpolation
342 Examples:
343 interp='nearest' (in time, freq-dep will be
344 linear, if relevant)
345 interp='linear,cubic' (linear in time, cubic
346 in freq)
347 interp='linearperobs,splineflag' (linear in
348 time per obsId, spline in freq with
349 channelized flagging)
350 interp='nearest,linearflagrel' (nearest in
351 time, linear in freq with with channelized
352 flagging and relative-frequency interpolation)
353 interp=',spline' (spline in freq; linear in
354 time by default)
355 interp=['nearest,spline','linear'] (for
356 multiple gaintables)
357 spwmap Spectral window mappings to form for gaintable(s)
358 Only used if callib=False
359 default: [] (apply solutions from each calibration spw to
360 the same MS spw only)
361 Any available calibration spw can be mechanically mapped to any
362 MS spw.
363 Examples:
364 spwmap=[0,0,1,1] means apply calibration
365 from cal spw = 0 to MS spw 0,1 and cal spw 1 to MS spws 2,3.
366 spwmap=[[0,0,1,1],[0,1,0,1]] (use a list of lists for multiple
367 gaintables)
368 parang Apply parallactic angle correction
369 Default: False
371 If True, apply the parallactic angle correction
372 (required for polarization calibration)
374 --------- examples -----------------------------------------------------------
378 For more information, see the task pages of gaincal in CASA Docs:
380 https://casa.nrao.edu/casadocs/
383 """
385 _info_group_ = """calibration"""
386 _info_desc_ = """Determine temporal gains from calibrator observations"""
388 def __call__( self, vis='', caltable='', field='', spw='', intent='', selectdata=True, timerange='', uvrange='', antenna='', scan='', observation='', msselect='', solint='inf', combine='', preavg=float(-1.0), refant='', refantmode='flex', minblperant=int(4), minsnr=float(3.0), solnorm=False, normtype='mean', gaintype='G', smodel=[ ], calmode='ap', solmode='', rmsthresh=[ ], corrdepflags=False, append=False, splinetime=float(3600.0), npointaver=int(3), phasewrap=float(180.0), docallib=False, callib='', gaintable=[ ], gainfield=[ ], interp=[ ], spwmap=[ ], parang=False ):
389 schema = {'vis': {'type': 'cReqPath', 'coerce': _coerce.expand_path}, 'caltable': {'type': 'cStr', 'coerce': _coerce.to_str}, 'field': {'type': 'cStr', 'coerce': _coerce.to_str}, 'spw': {'type': 'cStr', 'coerce': _coerce.to_str}, 'intent': {'type': 'cStr', 'coerce': _coerce.to_str}, 'selectdata': {'type': 'cBool'}, 'timerange': {'type': 'cStr', 'coerce': _coerce.to_str}, 'uvrange': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'antenna': {'type': 'cStr', 'coerce': _coerce.to_str}, 'scan': {'type': 'cStr', 'coerce': _coerce.to_str}, 'observation': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cInt'}]}, 'msselect': {'type': 'cStr', 'coerce': _coerce.to_str}, 'solint': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'combine': {'type': 'cStr', 'coerce': _coerce.to_str}, 'preavg': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'refant': {'type': 'cStr', 'coerce': _coerce.to_str}, 'refantmode': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'flex', 'strict' ]}, 'minblperant': {'type': 'cInt'}, 'minsnr': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'solnorm': {'type': 'cBool'}, 'normtype': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'mean', 'median' ]}, 'gaintype': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'XYf+QU', 'XY+QU', 'K', 'KCROSS', 'T', 'G', 'GSPLINE' ]}, 'smodel': {'type': 'cFloatVec', 'coerce': [_coerce.to_list,_coerce.to_floatvec]}, 'calmode': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'a', 'p', 'ap' ]}, 'solmode': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ '', 'L1', 'L1R', 'R' ]}, 'rmsthresh': {'type': 'cFloatVec', 'coerce': [_coerce.to_list,_coerce.to_floatvec]}, 'corrdepflags': {'type': 'cBool'}, 'append': {'type': 'cBool'}, 'splinetime': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'npointaver': {'type': 'cInt'}, 'phasewrap': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'docallib': {'type': 'cBool'}, 'callib': {'type': 'cStr', 'coerce': _coerce.to_str}, 'gaintable': {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, 'gainfield': {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, 'interp': {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, 'spwmap': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'parang': {'type': 'cBool'}}
390 doc = {'vis': vis, 'caltable': caltable, 'field': field, 'spw': spw, 'intent': intent, 'selectdata': selectdata, 'timerange': timerange, 'uvrange': uvrange, 'antenna': antenna, 'scan': scan, 'observation': observation, 'msselect': msselect, 'solint': solint, 'combine': combine, 'preavg': preavg, 'refant': refant, 'refantmode': refantmode, 'minblperant': minblperant, 'minsnr': minsnr, 'solnorm': solnorm, 'normtype': normtype, 'gaintype': gaintype, 'smodel': smodel, 'calmode': calmode, 'solmode': solmode, 'rmsthresh': rmsthresh, 'corrdepflags': corrdepflags, 'append': append, 'splinetime': splinetime, 'npointaver': npointaver, 'phasewrap': phasewrap, 'docallib': docallib, 'callib': callib, 'gaintable': gaintable, 'gainfield': gainfield, 'interp': interp, 'spwmap': spwmap, 'parang': parang}
391 assert _pc.validate(doc,schema), create_error_string(_pc.errors)
392 _logging_state_ = _start_log( 'gaincal', [ 'vis=' + repr(_pc.document['vis']), 'caltable=' + repr(_pc.document['caltable']), 'field=' + repr(_pc.document['field']), 'spw=' + repr(_pc.document['spw']), 'intent=' + repr(_pc.document['intent']), 'selectdata=' + repr(_pc.document['selectdata']), 'timerange=' + repr(_pc.document['timerange']), 'uvrange=' + repr(_pc.document['uvrange']), 'antenna=' + repr(_pc.document['antenna']), 'scan=' + repr(_pc.document['scan']), 'observation=' + repr(_pc.document['observation']), 'msselect=' + repr(_pc.document['msselect']), 'solint=' + repr(_pc.document['solint']), 'combine=' + repr(_pc.document['combine']), 'preavg=' + repr(_pc.document['preavg']), 'refant=' + repr(_pc.document['refant']), 'refantmode=' + repr(_pc.document['refantmode']), 'minblperant=' + repr(_pc.document['minblperant']), 'minsnr=' + repr(_pc.document['minsnr']), 'solnorm=' + repr(_pc.document['solnorm']), 'normtype=' + repr(_pc.document['normtype']), 'gaintype=' + repr(_pc.document['gaintype']), 'smodel=' + repr(_pc.document['smodel']), 'calmode=' + repr(_pc.document['calmode']), 'solmode=' + repr(_pc.document['solmode']), 'rmsthresh=' + repr(_pc.document['rmsthresh']), 'corrdepflags=' + repr(_pc.document['corrdepflags']), 'append=' + repr(_pc.document['append']), 'splinetime=' + repr(_pc.document['splinetime']), 'npointaver=' + repr(_pc.document['npointaver']), 'phasewrap=' + repr(_pc.document['phasewrap']), 'docallib=' + repr(_pc.document['docallib']), 'callib=' + repr(_pc.document['callib']), 'gaintable=' + repr(_pc.document['gaintable']), 'gainfield=' + repr(_pc.document['gainfield']), 'interp=' + repr(_pc.document['interp']), 'spwmap=' + repr(_pc.document['spwmap']), 'parang=' + repr(_pc.document['parang']) ] )
393 task_result = None
394 try:
395 task_result = _gaincal_t( _pc.document['vis'], _pc.document['caltable'], _pc.document['field'], _pc.document['spw'], _pc.document['intent'], _pc.document['selectdata'], _pc.document['timerange'], _pc.document['uvrange'], _pc.document['antenna'], _pc.document['scan'], _pc.document['observation'], _pc.document['msselect'], _pc.document['solint'], _pc.document['combine'], _pc.document['preavg'], _pc.document['refant'], _pc.document['refantmode'], _pc.document['minblperant'], _pc.document['minsnr'], _pc.document['solnorm'], _pc.document['normtype'], _pc.document['gaintype'], _pc.document['smodel'], _pc.document['calmode'], _pc.document['solmode'], _pc.document['rmsthresh'], _pc.document['corrdepflags'], _pc.document['append'], _pc.document['splinetime'], _pc.document['npointaver'], _pc.document['phasewrap'], _pc.document['docallib'], _pc.document['callib'], _pc.document['gaintable'], _pc.document['gainfield'], _pc.document['interp'], _pc.document['spwmap'], _pc.document['parang'] )
396 except Exception as exc:
397 _except_log('gaincal', exc)
398 raise
399 finally:
400 task_result = _end_log( _logging_state_, 'gaincal', task_result )
401 return task_result
403gaincal = _gaincal( )