Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatasks/polcal.py: 56%
27 statements
« prev ^ index » next coverage.py v7.6.4, created at 2024-10-31 19:10 +0000
1##################### generated by xml-casa (v2) from polcal.xml ####################
2##################### fc3d1d4a07231908b23e215ee75e4bbe ##############################
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_polcal import polcal as _polcal_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 _polcal:
15 """
16 polcal ---- Determine instrumental polarization calibrations
19 The complex instrumental polarization factors (D-terms) for each antenna/spwid
20 are determined from the data for the specified calibrator sources. Previous
21 calibrations can be applied on the fly.
23 --------- parameter descriptions ---------------------------------------------
25 vis Name of input visibility file
26 caltable Name of output gain calibration table
27 field Select field using field id(s) or field name(s)
28 spw Select spectral window/channels
29 intent Select observing intent
30 selectdata Other data selection parameters
31 timerange Select data based on time range
32 uvrange Select data within uvrange (default units meters)
33 antenna Select data based on antenna/baseline
34 scan Scan number range
35 observation Select by observation ID(s)
36 msselect Optional complex data selection (ignore for now)
37 solint Solution interval
38 combine Data axes which to combine for solve (obs, scan, spw, and/or field)
39 preavg Pre-averaging interval (sec)
40 refant Reference antenna name(s)
41 minblperant Minimum baselines _per antenna_ required for solve
42 minsnr Reject solutions below this SNR
43 poltype Type of instrumental polarization solution (see help)
44 smodel Point source Stokes parameters for source model.
45 append Append solutions to the (existing) table
46 docallib Use callib or traditional cal apply parameters
47 callib Cal Library filename
48 gaintable Gain calibration table(s) to apply
49 gainfield Select a subset of calibrators from gaintable(s)
50 interp Interpolation mode (in time) to use for each gaintable
51 spwmap Spectral window mappings to form for gaintable(s)
52 Only used if callib=False
53 default: [] (apply solutions from each calibration spw to
54 the same MS spw only)
55 Any available calibration spw can be mechanically mapped to any
56 MS spw.
57 Examples:
58 spwmap=[0,0,1,1] means apply calibration
59 from cal spw = 0 to MS spw 0,1 and cal spw 1 to MS spws 2,3.
60 spwmap=[[0,0,1,1],[0,1,0,1]] (use a list of lists for multiple
61 gaintables)
63 --------- examples -----------------------------------------------------------
67 The instrumental polarization factors (D-terms), the calibrator polarization,
68 and the R-L polarization angle can be determined using polcal. The solutions
69 can be obtained for each antenna/spwid and even individual channels, if desired.
70 Previous calibrations of the total intensity data should be applied on the fly
71 when running polcal, since polcal uses the 'data' column, not the 'corrected'
72 column.
74 After calibrating the gain, bandpass, and (if relevant, for channelized data)
75 cross-hand delay, the simplest way to calibrate the polarization data is:
77 a) Run polcal with poltype = 'D+QU' on the main 'calibrator' source. The D terms
78 and polarization (QU) of the calibrator will be determined. Relatively good
79 parallactic angle coverage is needed.
81 b) If there is little parallactic angle coverage, place the known polarization of
82 the main calibrator (or 0) using setjy with the appropriate fluxdensity. Then
83 run polcal with poltype = 'D'. Run plotcal with xaxis = 'real'; yaxis ='imag'
84 to view solutions. It is best to use an unpolarized calibrator in this
85 instance; large systematic offsets from zero indicate significant source
86 polarization that will bias the polarization calibration. A mechanism
87 to constrain this bias will be made available in the near future.
89 c) To determine R-L polarization angle, use setjy to put the fluxdensity of the
90 polarization calibrator [I,Q,U,0.0] in the model column. For resolved sources
91 put in values associated with an appropriate u-v range. Polarized models are
92 not yet available for the major polarization standard sources, so very
93 resolved polarized sources should not be used.
95 d) Run polcal with poltype = 'X' and include polarization standard. Make sure to
96 include all previous calibrations, especially the D results. Run plotxy with
97 correlation = 'RL LR' and make sure polarization angles are as expected.
99 e) Run applycal with all calibration table, include the D and X tables. Make sure
100 that parang = T
102 NOTE: For very high dynamic range, use poltype='Df' or 'Df+QU' to determine
103 D terms for each channel. Similarly, poltype='Xf' can
104 be used to determine a channel-dependent R-L phase
105 "bandpass".
106 NOTE: Rather than use setjy in b and c above, the new smodel
107 parameter may be used in polcal to specify a simple
108 point source Stokes model.
110 Keyword arguments:
111 vis -- Name of input visibility file
112 default: none; example: vis='ngc5921.ms'
113 caltable -- Name of output gain calibration table
114 default: none; example: caltable='ngc5921.dcal'
116 --- Data Selection (see help par.selectdata for more detailed information)
118 field -- Select field using field id(s) or field name(s).
119 [run listobs to obtain the list id's or names]
120 default: ''=all fields.
121 Most likely, the main calibrator source should be picked.
122 If field string is a non-negative integer, it is assumed a field index
123 otherwise, it is assumed a field name
124 field='0~2'; field ids 0,1,2
125 field='0,4,5~7'; field ids 0,4,5,6,7
126 field='3C286,3C295'; field named 3C286 adn 3C295
127 field = '3,4C*'; field id 3, all names starting with 4C
128 spw -- Select spectral window/channels
129 type 'help par.selection' for more examples.
130 spw='0~2,4'; spectral windows 0,1,2,4 (all channels)
131 spw='<2'; spectral windows less than 2 (i.e. 0,1)
132 spw='0:5~61'; spw 0, channels 5 to 61, INCLUSIVE
133 spw='*:5~61'; all spw with channels 5 to 62
134 spw='0,10,3:3~45'; spw 0,10 all channels, spw 3, channels 3 to 45.
135 spw='0~2:2~6'; spw 0,1,2 with channels 2 through 6 in each.
136 spw='0:0~10;15~60'; spectral window 0 with channels 0-10,15-60
137 NOTE ';' to separate channel selections
138 spw='0:0~10^2,1:20~30^5'; spw 0, channels 0,2,4,6,8,10,
139 spw 1, channels 20,25,30
140 intent -- Select observing intent
141 default: '' (no selection by intent)
142 intent='*BANDPASS*' (selects data labelled with
143 BANDPASS intent)
144 selectdata -- Other data selection parameters
145 default: True
146 timerange -- Select data based on time range:
147 default = '' (all); examples,
148 timerange = 'YYYY/MM/DD/hh:mm:ss~YYYY/MM/DD/hh:mm:ss'
149 Note: if YYYY/MM/DD is missing dat defaults to first day in data set
150 timerange='09:14:0~09:54:0' picks 40 min on first day
151 timerange= '25:00:00~27:30:00' picks 1 hr to 3 hr 30min on next day
152 timerange='09:44:00' data within one integration of time
153 timerange='>10:24:00' data after this time
154 uvrange -- Select data within uvrange (default units meters)
155 default: '' (all); example:
156 uvrange='0~1000klambda'; uvrange from 0-1000 kilo-lambda
157 uvrange='>4klambda';uvranges greater than 4 kilo-lambda
158 antenna -- Select data based on antenna/baseline
159 default: '' (all)
160 If antenna string is a non-negative integer, it is assumed an antenna index
161 otherwise, it is assumed as an antenna name
162 antenna='5&6'; baseline between antenna index 5 and index 6.
163 antenna='VA05&VA06'; baseline between VLA antenna 5 and 6.
164 antenna='5&6;7&8'; baseline 5-6 and 7-8
165 antenna='5'; all baselines with antenna index 5
166 antenna='05'; all baselines with antenna name 05, i.e. VLA ant 5
167 antenna='5,6,10'; all baselines with antennas 5, 6 and 10
168 scan -- Scan number range
169 observation -- Observation ID(s).
170 default: '' = all
171 example: '0~2,4'
172 msselect -- Optional complex data selection (ignore for now)
174 --- Solution parameters
175 poltype -- Type of instrumental polarization solution
176 'D+QU' (or 'Df+QU') solve also for apparent source polarization (channelized D)
177 Need relatively good parallactic angle coverage for this
178 'D' (or 'Df') solve only for instrumental polarization (channelized). The
179 I, Q, U flux density of the source can be placed in the model column using
180 setjy. Use for poor parallactic angle coverage.
181 'X' (or 'Xf') = solve only for position angle correction (channelized).
182 The source must have its I, Q, U flux density in the model column
183 or specified in smodel. If the source is resolved, use a limited
184 uvrange that is appropriate.
185 'D+X' (or 'Df+X') = solve also for position angle offset (channelized D) as
186 well as the D-term. Not normally done.
187 default: 'D+QU'
188 The solution used the traditional linear approximation. Non-linearized options
189 will be avaible soon.
190 smodel -- Point source Stokes parameters for source model (experimental)
191 default: [] (use MODEL_DATA column)
192 examples: [1,0,0,0] (I=1, unpolarized)
193 [5.2,0.2,0.3,0.0] (I=5.2, Q=0.2, U=0.3, V=0.0)
194 solint -- Solution interval (units optional)
195 default: 'inf' (~infinite, up to boundaries controlled by combine);
196 Options: 'inf' (~infinite), 'int' (per integration), any float
197 or integer value with or without units
198 examples: solint='1min'; solint='60s', solint=60 --> 1 minute
199 solint='0s'; solint=0; solint='int' --> per integration
200 solint-'-1s'; solint='inf' --> ~infinite, up to boundaries
201 enforced by combine
202 combine -- Data axes to combine for solving
203 default: 'obs,scan' --> solutions will break at field and spw
204 boundaries but may extend over multiple obs and scans
205 (per field and spw) up to solint.
206 Options: '','obs','scan','spw',field', or any comma-separated
207 combination in a single string
208 example: combine='scan,spw' --> extend solutions over scan boundaries
209 (up to the solint), and combine spws for solving
210 preavg -- Pre-averaging interval (sec)
211 default=300
212 Interval to apply parallactic angle.
213 refant -- Reference antenna name
214 default: '' => refant = '0'
215 example: refant='13' (antenna with index 13)
216 refant='VA04' (VLA antenna #4)
217 refant='EA02,EA23,EA13' (EVLA antenna EA02, use
218 EA23 and EA13 as alternates if/when EA02
219 drops out)
220 Use 'go listobs' for antenna listing.
221 USE SAME REFERENCE ANTENNA AS USED FOR I CALIBRATION.
222 minblperant -- Minimum number of baselines required per antenna for each solve
223 Antennas with fewer baaselines are excluded from solutions. Amplitude
224 solutions with fewer than 4 baselines, and phase solutions with fewer
225 than 3 baselines are only trivially constrained, and are no better
226 than baseline-based solutions.
227 default: 4
228 example: minblperant=10 => Antennas participating on 10 or more
229 baselines are included in the solve
230 minsnr -- Reject solutions below this SNR
231 default: 3.0
232 append -- Append solutions to the (existing) table. Appended solutions
233 must be derived from the same MS as the existing
234 caltable, and solution spws must have the same
235 meta-info (according to spw selection and solint)
236 or be non-overlapping.
237 default: False; overwrite existing table or make new table
239 --- Other calibrations to apply on the fly before determining polcal solution
241 docallib -- Control means of specifying the caltables:
242 default: False ==> Use gaintable,gainfield,interp,spwmap,calwt
243 If True, specify a file containing cal library in callib
244 callib -- If docallib=True, specify a file containing cal
245 library directives
247 gaintable -- Gain calibration table(s) to apply
248 default: '' (none); BUT I CALIBRATION TABLES SHOULD GENERALLY BE INCLUDED
249 examples: gaintable='ngc5921.gcal'
250 gaintable=['ngc5921.ampcal','ngc5921.phcal']
251 gainfield -- Select a subset of calibrators from gaintable(s)
252 default:'' ==> all sources in table;
253 'nearest' ==> nearest (on sky) available field in table
254 otherwise, same syntax as field
255 example: gainfield='0~3'
256 gainfield=['0~3','4~6'] means use field 0 through 3
257 from first gain file, field 4 through 6 for second.
258 interp -- Interpolation type (in time[,freq]) to use for each gaintable.
259 When frequency interpolation is relevant (B, Df, Xf),
260 separate time-dependent and freq-dependent interp
261 types with a comma (freq _after_ the comma).
262 Specifications for frequency are ignored when the
263 calibration table has no channel-dependence.
264 Time-dependent interp options ending in 'PD' enable a
265 "phase delay" correction per spw for non-channel-dependent
266 calibration types.
267 For multi-obsId datasets, 'perobs' can be appended to
268 the time-dependent interpolation specification to
269 enforce obsId boundaries when interpolating in time.
270 For multi-scan datasets, 'perscan' can be appended to
271 the time-dependent interpolation specification to
272 enforce scan boundaries when interpolating in time.
273 default: '' --> 'linear,linear' for all gaintable(s)
274 example: interp='nearest' (in time, freq-dep will be
275 linear, if relevant)
276 interp='linear,cubic' (linear in time, cubic
277 in freq)
278 interp='linearperobs,spline' (linear in time
279 per obsId,
280 spline in freq)
281 interp=',spline' (spline in freq; linear in
282 time by default)
283 interp=['nearest,spline','linear'] (for multiple gaintables)
284 Options: Time: 'nearest', 'linear'
285 Freq: 'nearest', 'linear', 'cubic', 'spline'
286 spwmap -- Spectral windows combinations to form for gaintable(s)
287 default: [] (apply solutions from each spw to that spw only)
288 Example: spwmap=[0,0,1,1] means apply the caltable solutions
289 from spw = 0 to the spw 0,1 and spw 1 to spw 2,3.
290 spwmap=[[0,0,1,1],[0,1,0,1]]
293 """
295 _info_group_ = """calibration"""
296 _info_desc_ = """Determine instrumental polarization calibrations"""
298 def __call__( self, vis='', caltable='', field='', spw='', intent='', selectdata=True, timerange='', uvrange='', antenna='', scan='', observation='', msselect='', solint='inf', combine='obs,scan', preavg=float(300.0), refant='', minblperant=int(4), minsnr=float(3.0), poltype='D+QU', smodel=[ ], append=False, docallib=False, callib='', gaintable=[ ], gainfield=[ ], interp=[ ], spwmap=[ ] ):
299 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}, 'minblperant': {'type': 'cInt'}, 'minsnr': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'poltype': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'Dflls', 'D', 'Dlls', 'D+QU', 'D+X', 'PosAng', 'X', 'Dfgen', 'Dfgen+X', 'Df+X', 'Df', 'Dgen+X', 'Dgen+QU', 'Df+QU', 'Dgen', 'Xfparang+QU', 'Xf', 'Dfgen+QU', 'Xj', 'Xparang+QU' ]}, 'smodel': {'type': 'cFloatVec', 'coerce': [_coerce.to_list,_coerce.to_floatvec]}, 'append': {'type': 'cBool'}, '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]}}
300 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, 'minblperant': minblperant, 'minsnr': minsnr, 'poltype': poltype, 'smodel': smodel, 'append': append, 'docallib': docallib, 'callib': callib, 'gaintable': gaintable, 'gainfield': gainfield, 'interp': interp, 'spwmap': spwmap}
301 assert _pc.validate(doc,schema), create_error_string(_pc.errors)
302 _logging_state_ = _start_log( 'polcal', [ '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']), 'minblperant=' + repr(_pc.document['minblperant']), 'minsnr=' + repr(_pc.document['minsnr']), 'poltype=' + repr(_pc.document['poltype']), 'smodel=' + repr(_pc.document['smodel']), 'append=' + repr(_pc.document['append']), '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']) ] )
303 task_result = None
304 try:
305 task_result = _polcal_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['minblperant'], _pc.document['minsnr'], _pc.document['poltype'], _pc.document['smodel'], _pc.document['append'], _pc.document['docallib'], _pc.document['callib'], _pc.document['gaintable'], _pc.document['gainfield'], _pc.document['interp'], _pc.document['spwmap'] )
306 except Exception as exc:
307 _except_log('polcal', exc)
308 raise
309 finally:
310 task_result = _end_log( _logging_state_, 'polcal', task_result )
311 return task_result
313polcal = _polcal( )