Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatools/calibrater.py: 91%
87 statements
« prev ^ index » next coverage.py v7.6.4, created at 2024-11-01 07:19 +0000
1##################### generated by xml-casa (v2) from calibrater.xml ################
2##################### ee9c1ac0f041f6fd47b9ac2de7b642f1 ##############################
3from __future__ import absolute_import
4from .__casac__.calibrater import calibrater as _calibrater
6from .errors import create_error_string
7from .typecheck import CasaValidator as _validator
8_pc = _validator( )
9from .coercetype import coerce as _coerce
12class calibrater:
13 _info_group_ = """calibrater"""
14 _info_desc_ = """Synthesis calibration (self- and cross-)"""
15 ### self
16 def __init__(self, *args, **kwargs):
17 """Create a {tt calibrater} tool. The casapy environment provides
18 a standard calibrater tool for general use (cb), but additional calibrater
19 tools may be created if needed. Calibrater tools created in this way
20 are independent of the standard calibrater tool.
21 """
22 self._swigobj = kwargs.get('swig_object',None)
23 if self._swigobj is None:
24 self._swigobj = _calibrater()
26 def open(self, filename, compress=False, addcorr=True, addmodel=True):
27 """Attaches a MeasurementSet to the {tt calibrater} tool for further processing with
28 other methods.
29 """
30 return self._swigobj.open(filename, compress, addcorr, addmodel)
32 def selectvis(self, time=[ ], spw=[ ], scan=[ ], field=[ ], intent=[ ], observation=[ ], baseline=[ ], uvrange=[ ], chanmode='none', nchan=int(1), start=int(0), step=int(1), mstart={'value': float(0.0), 'unit': 'km/s'}, mstep={'value': float(0.0), 'unit': 'km/s'}, msselect=''):
33 """This function provids for selection of the visibility data from the MS
34 which will be treated by subsequent execution of the {stfaf solve} and
35 {stfaf correct} functions. Note that data selection is not cumulative, i.e.,
36 any selection made in a previous call to {stfaf selectvis} will be overridden
37 by the the current call.
39 Most of the {stfaf selectvis} parameters use the standardized MS Selection
40 syntax.
42 The parameters are described below. The selected data will satisfy the
43 logical AND of all non-trivially specified parameters. Note that the
44 old-fashioned strided channel selection parameters are deprecated (and
45 will soon be removed); use spw instead. Running {stfaf selectvis} with
46 no specified parameters restores selection of the entire MS.
49 begin{description}
50 item[time] is used to specify time ranges in a stardard format
52 item[spw] is used to specify spectral window and channel selection. Currently,
53 only a single channel range can be specified per spw.
55 item[scan] is used to specify scan numbers and ranges
57 item[observation] is used to specify observation ID(s).
59 item[field] is used to specify field names or indices
61 item[baseline] is used to specify antenna and baseline combinations
63 item[uvrange] is used to specify baseline length ranges
65 item[chanmode] is deprecated (use spw)
66 item[nchan] is deprecated (use spw)
67 item[start] is deprecated (use spw)
68 item[step] is deprecated (use spw)
69 item[mstart] is deprecated (use spw)
70 item[mstep] is deprecated (use spw)
72 item[msselect] is used to specify a subselection of data according to
73 Measurement Set columns in conditional combinations not possible
74 with the standard parameters above. This parameter should be specified
75 as a valid htmladdnormallink{TaQL}{../../notes/199/199.html} expression.
76 If both msselect and the standard selection parameter are used together,
77 they are combined with a logical AND, i.e., the data must jointly satisfy
78 all {stfaf selectvis} parameters.
80 end{description}
81 """
82 return self._swigobj.selectvis(time, spw, scan, field, intent, observation, baseline, uvrange, chanmode, nchan, start, step, mstart, mstep, msselect)
84 def setmodel(self, modelimage):
85 """Name of the model image to be used as a sky model for model visibility
86 computations. For now, this is used only by EP-Jones solver.
87 """
88 return self._swigobj.setmodel(modelimage)
90 def setptmodel(self, stokes=[ float(0.0),float(0.0),float(0.0),float(0.0) ]):
91 """Set a global point source model Stokes parameters to use in solving operations.
92 """
93 return self._swigobj.setptmodel(stokes)
95 def setapply(self, type='', t=float(0.0), table='', field=[ ], interp='linear', select='', calwt=False, spwmap=[ int(-1) ], opacity=[ float(0.0) ]):
96 """This function is used to specify the calibration components which should be
97 applied during subsequent execution of the {stfaf solve} and
98 {stfaf correct} functions. This function should be executed as many
99 times as necessary to specify all desired calibration components.
101 Each calibration component represents a separate calibration matrix
102 correction included in the measurement equation. The different types
103 correspond to different instrumental and atmospheric effects.
104 Calibration components are available as calibration tables generated
105 by previous {stfaf solve} executions (types 'B','BPOLY','G','GSPLINE',
106 'D','DF','T','M','MF','X'), or are calculated analytically on
107 the fly (types 'P', 'TOPAC', 'GAINCURVE'). Upon execution
108 of {stfaf solve} or {stfaf correct}, the group of specified
109 calibration components will be applied in the order prescribed
110 by the Measurement Equation formalism.
112 The parameters are as follows:
114 begin{description}
116 item[type] The calibration type being specified. This is only required
117 for analytic types ('P','TOPAC','GAINCURVE'). When specifying an existing
118 pre-solved calibration table, it is not necessary to explicitly specify the
119 {stfaf type}; this will be discerned from the table. (Specifying the
120 {stfaf type} as well as the {stfaf table} will force a check that the
121 table contains solutions of the specified type.
123 For {stfaf type='GAINCURVE'}, an elevation-dependent correction
124 will be applied using parameters read from the data repository.
125 Currently, this is only supported for the VLA.
127 item[t] This parameter will be used in a future release to control
128 the range of applicability of the specified calibration. Currently,
129 it is ignored.
131 item[table] For pre-solved calibration, the file name of the table
132 to apply.
134 item[field] The fields to select from the specified table, using
135 MS Selection syntax (as in selectvis).
137 item[interp] The desired type of time-dependent interpolation. Use
138 {stfaf interp='nearest'} to calibrate each datum with the calibration
139 value nearest in time. Use {stfaf interp='linear'} to calibrate each
140 datum with calibration phases and amplitudes linearly interpolated
141 from neighboring (in time) values. In the case of phase, this mode
142 will assume that phase jumps greater than 180 degrees between neighboring
143 points indicate a cycle slip, and the interpolated value will follow
144 this change in cycle accordingly (i.e., the implied rate will always
145 be less than 180 degrees per sample). Use {stfaf interp='aipslin'}
146 to emulate the basic interpolation mode used in classic AIPS, i.e.,
147 linearly interpolated amplitudes, with phases derived from linear
148 interpolation of the complex calibration values. While this method
149 avoids having to track cycle slips (which is unstable for solutions
150 with very low SNR), it will yield a phase interpolation which becomes
151 increasingly non-linear as the spanned phase difference increases. The
152 non-linearity mimics the behavior of {stfaf interp='nearest'} as
153 the spanned phase difference approaches 180 degrees (the phase of the
154 interpolated complex calibration value initially changes very slowly,
155 then rapidly jumps to the second value at the midpoint of the interval).
156 If the uncalibrated phase is changing this rapidly, a 'nearest' interpolation
157 is not desirable. Usually, {stfaf interp='linear'} is the best choice.
158 The {stfaf interp} parameter is applicable to any calibration type,
159 as long as there are sufficient solutions available to perform the
160 interpolation. Note that calibration solutions which have been
161 determined for only one timestamp will default to 'nearest'. More
162 interpolation options (e.g., 'cubic') will be added in the future.
164 item[select] Used to specify general selection of a subset of
165 calibration measurements from the table to be applied to the
166 visibility data. Arbitrary cross-calibration is possible by combining
167 this function with the {stfaf setdata} function. The string
168 specified must be a valid htmladdnormallink{TaQL}{../../notes/199/199.html}
169 expression.
171 item[spwmap] This parameter is used to indicate how solutions
172 derived from different spectral windows should be applied to other
173 spectral windows. Nominally, data in each spectral window will be
174 corrected by solutions derived from the same spectral window. This is
175 the default behavior of {stfaf spwmap}, i.e., if {stfaf spwmap} is
176 not specified, calibrater will insist that data be corrected by
177 solutions from the same spw. Otherwise, {stfaf spwmap} takes a
178 vector of integers indicating which spectral window {em solutions} to
179 apply to which spectral window {em data}, such that {tt spwmap[j]=i}
180 causes solutions derived from the i-th spectral window to be used to
181 correct the j-th spectral window. For example, if (say) bandpass
182 solutions are available for spws 0 & 2, and it is desired that these
183 be applied to spws 1 & 3 (as well as 0 & 2), respectively, use
184 {stfaf spwmap=[0,0,2,2]}. Even if some spws do not require an
185 explicit {stfaf spwmap} setting, yet one or more does, it is safest
186 to specify it explicitly for all, e.g., {stfaf spwmap=[0,1,3,3]}
187 indicates that spw 2 will be corrected with solutions from spw 3, and
188 the others will behave nominally. Note that if no solutions exist
189 for any of the spws specified in {stfaf spwmap}, an error message
190 will result.
192 item[calwt] If set True, the data weights will be calibrated
193 along with the data. This is usually desirable.
195 item[opacity] For {stfaf type='TOPAC'}, an elevation-dependent
196 opacity correction will be applied according to the zenith opacity value
197 supplied in the {stfaf opacity} parameter. Currently, only one zenith
198 opacity value can be supplied, and it is used for all antennas.
200 end{description}
202 Use the {stfaf state} function to review the list of calibration
203 components that have been set for application.
205 Pending improvements:
207 begin{itemize}
208 item Enable variety of interpolation modes and timescales
209 item Allow for antenna- and time-dependent opacities
210 end{itemize}
211 """
212 return self._swigobj.setapply(type, t, table, field, interp, select, calwt, spwmap, opacity)
214 def setcallib(self, callib={ }):
215 """TBD
216 """
217 return self._swigobj.setcallib(callib)
219 def validatecallib(self, callib={ }):
220 """TBD
221 """
222 return self._swigobj.validatecallib(callib)
224 def setsolve(self, type='MF', t=[ ], table='', append=False, preavg=float(-1.0), phaseonly=False, apmode='AP', refant=[ ], refantmode='flex', minblperant=int(4), solnorm=False, normtype='mean', minsnr=float(0.0), combine='', fillgaps=int(0), cfcache='', painc=float(360.0), fitorder=int(0), fraction=float(0.1), numedge=int(-1), radius='', smooth=True, zerorates=False, globalsolve=True, niter=int(100), corrcomb='none', delaywindow=[ ], ratewindow=[ ], paramactive=[ ], concatspws=True, solmode='', rmsthresh=[ ]):
225 """This function specifies the calibration component that will be solved for
226 by the {stff solve} function. Currently, only one type can
227 be solved for at one time.
229 Each calibration component represents a separate calibration matrix
230 correction included in the measurement equation. The different types
231 correspond to different instrumental and atmospheric effects.
232 Currently, the solvable calibration components are types 'G','T','B', 'D'
233 and 'DF', which are antenna-based, and, 'M' and 'MF', which are
234 baseline-based. Arrange to pre-apply any existing calibration components (of
235 types other than the solved-for one) using the {stfaf setapply}
236 function.
238 The parameters are:
240 begin{description}
241 item[type] Specify the calibration type you want to solve for, from
242 'G','T','B','D','DF','M','MF'.
244 item[t] Specify the solution interval. This can be specified as an
245 integer (units of seconds assumed) or as a string containing a value
246 and units (e.g., '30s', '45min', '2h') or 'inf' (infinite) or 'int'
247 (per data integration). A solution interval of 0 (with or without
248 units) is the same as 'int' (per integration), and negative solution
249 intervals are treated as 'inf' (infinite).
251 item[table] Specify the output calibration table name in which to
252 store the calibration solve result. Existing tables will be
253 deleted and replaced.
255 item[append] Append the solutions to an existing table.
257 item[preavg] Specify the amount of pre-average (in time) within
258 the solution interval. By default, data are averaged up to
259 the solution interval (or up to 5 minutes for 'D' solving).
261 item[phaseonly] This parameter is deprecated, use apmode.
263 item[apmode] Control generation of amplitude-only ('a'),
264 phase-only ('p'), or amplitude-and-phase ('ap', the default) solutions.
266 item[refant] Specify an antenna (using data selection syntax)
267 for referencing the solutions.
269 item[solnorm] Normalize the solutions by their mean post-solve. For
270 'B', and 'MF', this is a complex normalization per solution spectrum.
271 For other types, this is a global (per-spw) normalization of the
272 amplitudes only.
274 item[minsnr] Specify the SNR below which solution are rejected.
276 item[combine] Specify which data axes (spw, field, scan, or some
277 combination) on which the data should be combined to generate
278 a single solution. E.g., combine='spw' will force combination
279 of many spws to form a single solution (per solution interval).
280 Similarly, combine='scan' with a long solution interval
281 will force the combination of scans to yield individual solutions
282 (per field and spw). Ordinarily, solutions are always broken
283 at scans boundaries. Separate multiple combine options with
284 commas.
286 item[fillgaps] For 'B' solutions, specify the largest solution
287 channel gap (which arise due to flagged data) that will be filled
288 post-solve via interpolation. Such solution gaps remain flagged
289 by default.
291 end{description}
293 Pending improvements:
295 begin{itemize}
296 item{Change t to solint?}
297 item{Permit flexible specification of preavg (as for t)}
298 end{itemize}
299 """
300 return self._swigobj.setsolve(type, t, table, append, preavg, phaseonly, apmode, refant, refantmode, minblperant, solnorm, normtype, minsnr, combine, fillgaps, cfcache, painc, fitorder, fraction, numedge, radius, smooth, zerorates, globalsolve, niter, corrcomb, delaywindow, ratewindow, paramactive, concatspws, solmode, rmsthresh)
302 def setsolvegainspline(self, table='', append=False, mode='PHAS', splinetime=float(10800), preavg=float(0.0), npointaver=int(10), phasewrap=float(250), refant=[ ]):
303 """This function is a specialization of the {stfaf setsolve} method which
304 should be used when cubic spline G solutions are desired, e.g., when
305 SNR on calibrators is very low. Currently, this solving mode treats
306 dual polarization data on a per-polarization basis. The option to
307 obtain a joint solution (a la 'T') will be provided in the future.
309 The visibility data are averaged in frequency (for multi-channel data)
310 prior to the solution.
312 This method uses many of the basic parameters as the generic
313 {stfaf setsolve}. Parameters unique to the spline solver are:
315 begin{description}
317 item[mode] For phase solutions only, use {stfaf mode='PHAS'}. For
318 amplitude solutions only, use {stfaf mode='AMP'}. If both are
319 desired, use {stfaf mode='PHASAMP'}, and both will be solved for
320 using the same spline timescale (this mode also assumes that all
321 calibrators have the correct relative flux densities). If solving for
322 phase and amplitude separately (usually in this order), it is usually
323 desirable to apply the first one when solving for the second
324 one. Spline solution so obtained will be stored in separate
325 calibration tables. In the near future, the {stfaf mode} parameter
326 will be consolidated with the generic {stfaf apmode} parameter.
328 item[splinetime] The spline timescale (time between knots) is
329 specified here. The default is 10800 seconds (3 hours). In future
330 this parameter will be consolidated with the generic {stfaf t}
331 parameter. The {stfaf preavg} parameter should be set to a value at
332 least 4X shorter than the spline time (an error will occur if there is
333 insufficient sampling within the {stfaf splinetime} timescale), and
334 consistent with the expected coherence. Consistent with these constraints,
335 use the largest possible value for {stfaf preavg} to optimize the SNR of
336 the pre-solve phase-tracking algorithm.
338 item[npointaver and phasewrap] These parameters tune the
339 phase-unwrapping algorithm when {stfaf mode $=$ 'PHAS'}. Cycle slips
340 are detected (and removed before the spline solve) when the median
341 phase a sequence of length {stfaf npointaver} (in integrations)
342 differs by more than {stfaf phasewrap} degrees from the previous
343 sequence.
345 end{description}
347 Pending improvements:
349 begin{itemize}
350 item Consolidate more parameters with the generic {stfaf setsolve}
351 item Introduce the generic combine options
352 item Improve phase-tracking algorithm
353 end{itemize}
354 """
355 return self._swigobj.setsolvegainspline(table, append, mode, splinetime, preavg, npointaver, phasewrap, refant)
357 def setsolvebandpoly(self, table='', append=False, t=[ ], combine='', degamp=int(3), degphase=int(3), visnorm=False, solnorm=True, maskcenter=int(0), maskedge=float(5.0), refant=[ ]):
358 """This function is a specialization of the {stfaf setsolve} method
359 which should be used to arrange for bandpass solving when polynomial
360 solutions for B are desired, e.g., when per-channel SNR on calibrators
361 is too low to obtain a useful sampled bandpass.
363 Prior to the solution, the visibility data are averaged in time,
364 and the solution is performed for both phase and amplitude.
366 This method uses most of the same parameters as the generic
367 {stfaf setsolve}, with a few unique additions:
369 begin{description}
371 item[degamp and degphase] The parameters permit specification
372 of the polynomial order to use in amp and phase. Specifying
373 0 (zero) yields constant solutions.
375 item[visnorm] This parameter is used to normalize the assembled
376 spectral data, in a per baseline manner. If set True, this will have
377 the effect of removing any non-frequency-dependent closure errors
378 (e.g., as caused by source structure, or introduced by the instrument)
379 from the data, and should be used with caution. The resulting
380 solutions will be effectively normalized as well. When {stfaf
381 visnorm=F} is used, closure errors in the data (as supplied to the
382 solver) may be visible in the form of offsets between the data and
383 solutions. For bandpass calibration, this is usually ok, as the {em
384 shape} of the bandpass is the most important aspect of the solution.
385 In future this parameter will be generalized and made available
386 for other solve types. (NB: Use of {stfaf solnorm=True} still
387 provides for post-solve normalization of the solutions.)
389 item[maskcenter and maskedge] These parameters control how many
390 channels are ignored on-the-fly, at the center and edges of each input
391 spectral window, respectively. To avoid edge channels, it is almost
392 always better to flag these channels directly, or select against them
393 in {stfaf setdata}. Aggressive use of maskedge (large values), will
394 yield polynomial solutions which will tend to diverge at the edges
395 (especially when the polynomial degree is also high), because maskedge
396 does not change the frequency domain of the solutions. Such solutions
397 should be used with caution in subsequent operations. (It is best to
398 avoid use of maskedge.)
399 end{description}
401 The BPOLY solution is performed for both phase and amplitude, and the
402 result will be stored in the same table. The frequency domain of the
403 solutions is limited to only the range of frequencies selected in
404 {stfaf selectvis}. When correcting data with these solutions (for
405 other solves or with {stfaf correct}), only data within this domain
406 will be corrected. Data outside (e.g., edge channels avoided in
407 {stfaf setdata} for the solve), will not be corrected. Therefore,
408 the same (or narrower) channel selection is recommended for all
409 operations using solutions produced by this function and {stfaf
410 solve()}.
412 Note that the {stfaf combine} parmaeter can be used meaningfully with
413 the BPOLY solver. When combine='spw', the data from multiple spws
414 will be combined on a common frequency axis, and a single polynomial
415 will be determined spanning them all. This is different than for
416 ordinary sampled 'B' solutions, for which combine='spw' causes the
417 bandpass to be combined on a common channel axis, effectively yielding
418 a mean bandpass for the set of spws.
419 """
420 return self._swigobj.setsolvebandpoly(table, append, t, combine, degamp, degphase, visnorm, solnorm, maskcenter, maskedge, refant)
422 def returndict(self):
423 """Return a dictionary containing information about the current calibrater tool state.
424 This dictionary contains the following keys: 'antennas', 'apply tables', 'field', 'intents', 'observation', 'scan', 'solve table', 'spw'.
426 Each of these keys will show which values for each of these parameters are selected. By default all of the MS is selected when opened by the calibrater tool.
428 The values of each of these keys is an array of either strings or integers.
430 """
431 return self._swigobj.returndict()
433 def state(self):
434 """Request the apply/solve state of the calibrater tool. A listing of
435 all calibration components that have been set for application or
436 solving is written to the logger.
437 """
438 return self._swigobj.state()
440 def reset(self, apply=True, solve=True):
441 """Resets the apply and/or solve components previously set by setapply and
442 setsolve.
443 """
444 return self._swigobj.reset(apply, solve)
446 def initcalset(self, calset=int(0)):
447 """This function re-initializes the calibration scratch columns:
448 MODEL_DATA to unity (in total intensity, and unpolarized), and
449 CORRECTED_DATA to (observed) DATA.
450 Optionally if calset is set to 1 any model saved in the MS header to for calibration
451 purposes is deleted
452 """
453 return self._swigobj.initcalset(calset)
455 def delmod(self, otf=False, field=[ ], spw=[ ], scr=False):
456 """This method can be used to delete the model visibility
457 data representations in the MS. The 'otf' representation is
458 the new (as of v3.4) 'scratch-less' model data, stored as
459 keywords in the MS header containing model data formation
460 instructions. It is generated by the im tool (setjy, ft, and clean
461 methods; usescratch=F in im.open), and if present, overrides the
462 old-fashioned MODEL_DATA column (if present). If a user
463 wishes to use the MODEL_DATA column _after_ having operated
464 with the 'otf' representation, this method can be used
465 to delete the 'otf' represenatation to make the MODEL_DATA
466 column visible. (Create the MODEL_DATA column by using
467 usescratch=T in the im tool, or by running the cb.open
468 with addmodel=T.)
470 If otf=T, the user may selectively remove only a selection of fields model from the MS by specifying the field parameter. Similarly if the field parameter is specified, selected spws model for those fields may be deleted by specifying the spw.
473 For convenience, this method also provides a means for
474 deleting the MODEL_DATA column by setting scr=T.
475 """
476 return self._swigobj.delmod(otf, field, spw, scr)
478 def solve(self):
479 """Execution of this function initiates a solve for the calibration component
480 specified in a previous {stfaf setsolve} execution. Existing calibration
481 components (as specified in one or more {stfaf setapply} executions) will
482 be appropriately applied to the observed and model data according to their
483 position in the Measurement Equation, and their commutation properties.
484 """
485 return self._swigobj.solve()
487 def correct(self, applymode=''):
488 """This function applies the calibration components specified via one or
489 more invocations of the {stff setapply} function to the observed
490 visibility data and writes the result to the CORRECTED_DATA column
491 of the Measurement Set.
492 """
493 return self._swigobj.correct(applymode)
495 def corrupt(self):
496 """This function applies the calibration components specified via one or
497 more invocations of the {stff setapply} function to the model
498 visibility data and (over-)writes the result to the MODEL_DATA column of the
499 Measurement Set.
500 """
501 return self._swigobj.corrupt()
503 def initweights(self, wtmode='nyq', dowtsp=False, tsystable='', gainfield='', interp='', spwmap=[ ]):
504 """This function initializes the MS weight info in various ways.
506 If wtmode='ones', SIGMA and WEIGHT will be initialized with 1.0,
507 globally.
509 If wtmode='nyq' (the default), SIGMA and WEIGHT will be initialized
510 according to bandwidth and integration time. This is the
511 theoretically correct mode for raw normalized visibilities.
513 If wtmode='sigma', WEIGHT will be initialized according to the
514 existing SIGMA column.
516 If mode='weight', WEIGHT_SPECTRUM will be initialized according to the
517 existing WEIGHT column; dowtspec=T must be specified in this case.
519 For the above wtmodes, if dowtspec=T (or if the WEIGHT_SPECTRUM column
520 already exists), the WEIGHT_SPECTRUM column will be initialized
521 (uniformly in channel), in a manner consistent with the WEIGHT column.
522 If the WEIGHT_SPECTRUM column does not exist, dowtsp=T will force its
523 creation.
525 The follow modes should be used with extreme care: If
526 wtmode='delwtsp', the WEIGHT_SPECTRUM column will be deleted (if it
527 exists). If wtmode='delsigsp', the SIGMA_SPECTRUM column will be
528 deleted (if it exists). Note that creation of SIGMA_SPECTRUM is not
529 supported via this method.
531 Note that this method does not support any prior selection.
532 Intialization of the weight information must currently be done
533 globally or not at all. This is to maintain consistency.
534 """
535 return self._swigobj.initweights(wtmode, dowtsp, tsystable, gainfield, interp, spwmap)
537 def fluxscale(self, tablein, reference=[ ], tableout='', transfer=[ ], listfile='', append=False, refspwmap=[ int(-1) ], gainthreshold=float(-1.0), antenna='', timerange='', scan='', incremental=False, fitorder=int(1), display=False):
538 """This function is used to bootstrap the amplitude scale the
539 calibration solutions according to specified reference calibrator(s)
540 of known flux density. This is necessary when the flux densities
541 of some of your calibrators were unknown (and thus were assumed
542 to be 1 Jy) during G solving.
544 The bootstrapping is achieved by comparing the median gain norm of the
545 calibration solutions derived for the calibrators specified in {stfaf
546 reference} (one or more sources with known flux densities at the time
547 of G solving) with that of the calibrators specified in {stfaf
548 transfer}, and enforcing the assumption that the antenna gains are
549 constant, on average. The gain solutions for the transfer sources are
550 then re-scaled accordingly. The {stfaf reference} and {stfaf transfer}
551 parameters may be specified using the general field selection syntax
552 (as in {stfaf field} in {stfaf selectvis}).
554 If no {tt transfer} fields are specified, then the solutions for
555 all non-reference fields in {tt tablein} will be re-scaled.
557 If no {tt tableout} is specified the input table will be overwritten
558 with the scaled solutions. Note that the resulting table will only
559 contain solutions for those fields implicit in the {tt reference} and
560 {tt transfer} specifications. Use {tt append=T} to append the scaled
561 solutions to an existing table.
563 Use the {stfaf refspwmap} parameter to indicate how data for
564 different spectral windows should be matched in calculating the flux
565 density scale factor for {stfaf transfer} fields. The default
566 behavior for {tt refspwmap} is to insist on precisely matching
567 spectral windows for {tt reference} and {tt transfer} fields. When
568 specified, the {stfaf refspwmap} parameter takes a vector of integers
569 indicating which spectral window solutions to use as the reference for
570 others, such that {tt refspwmap[j]=i} causes solutions (from reference
571 fields) observed in the i-th spectral window to be used to reference
572 solutions (from transfer fields) observed in the j-th spectral window.
573 For example, for the case of a total of 4 spectral windows: if the
574 {tt reference} fields were observed only in spw=2 & 4, and the {tt
575 transfer} fields were observed variously in all 4 spws, specify {tt
576 refspwmap=[2,2,4,4]}. This will ensure that {tt transfer} fields
577 observed in spws 1,2,3,4 will be referenced to {tt reference} field
578 data from spws 2,2,4,4, respectively. Note that if the {tt transfer}
579 fields were observed only in spws 1 & 3, the same specification would
580 work, but {tt refspwmap=[2,2,4]} would suffice. In this case,
581 nothing need be specified for the 4th spw (there are no transfer
582 fields there), and specifying 2 for the 2nd spw is actually
583 inconsequential (though required so that the specification of 4 for spw 3
584 is properly interpretted).
586 The gain values used in the flux scaling determination skewed by
587 outliers. The parameters, {tt gainthreshold} and {tt antenna} can be used
588 to limit the input gain solutions to be included in the flux scale determination.
589 Use the {tt gainthreshold} is a threshold in % from the median values of the
590 gain solutions to be used. Use the {tt antenna} to select or de-selesect (using the
591 MSSelection syntax) antenna(s). Futher refinements on the selection based on
592 timerange and scan are possible.
594 The derived flux densities for the transfer fields will be reported in
595 the logger, and returned to the Python dictionary specified in {tt
596 fluxd}. This will be an 2D array of shape [number-of-spectral-windows
597 X number-of-fields]. When mulitple spectral windows are involved the spectral
598 index will also be reported by fitting the determined flux densities across
599 the freuquencies. The order of a polynomcial to be fitted can be specified with
600 {tt fitorder}.
602 Note that elevation-dependent gain effects may render the basic
603 assumption used here invalid, and so should be corrected for prior to
604 solving for G, using types 'TOPAC' or 'GAINCURVE' in {tt setapply}.
606 Note that the visibility data itself is not used directly by this
607 function.
609 Pending improvements:
611 begin{itemize}
612 item Allow antenna and uv-distance selection to improve results for
613 resolved calibrators
614 item Set the visibility model according to the flux density results
615 item An option to use the data to derive the relative flux densities
616 end{itemize}
617 """
618 return self._swigobj.fluxscale(tablein, reference, tableout, transfer, listfile, append, refspwmap, gainthreshold, antenna, timerange, scan, incremental, fitorder, display)
620 def accumulate(self, tablein='', incrtable='', tableout='', field=[ ], calfield=[ ], interp='linear', t=float(-1.0), spwmap=[ int(-1) ]):
621 """This function enables cumulative calibration using {tt calibrater}.
622 It is the analog of the task ``CLCAL'' in classic AIPS.
624 The {tt accumulate} function is useful when:
626 begin{itemize}
627 item a calibration solution of a particular type already exists,
628 item an incremental calibration solution {em of the same type} is desired
629 (an incremental solution in this context means derived independently
630 from, or determined with respect to, the first)
631 item the first calibration cannot be implicitly recovered in the course
632 of obtaining the incremental solution
633 end{itemize}
635 For example, a phase-only ``G'' self-calibration on a target source
636 may be desired to tweak the full amplitude and phase ``G'' calibration
637 already obtained from a calibrator. The initial calibration (from the
638 calibrator) contains amplitude information, and so must be carried
639 forward, yet the phase-only solution itself cannot (by definition)
640 recover this information, as a full amplitude and phase
641 self-calibration would. In this case, the initial solution must be
642 applied while solving for the phase-only solution, then the two
643 solutions combined to form a {em cumulative} calibration embodying
644 the net effect of both. In terms of the Measaurement Equation, the net
645 calibration is the {em product} of the initial and incremental
646 solutions.
648 The analog of {tt accumulate} in classic AIPS is the use of CLCAL to
649 combine a series of (incremental) SN calibration tables to form
650 successive (cumulative) CL calibration tables.
652 Cumulative calibration tables also provide a means of generating
653 carefully interpolated calibration, on variable user-defined
654 timescales, that can be examined prior to application to the data with
655 {tt setapply} and {tt correct}. The solutions for different fields
656 and/or spectral windows can be interpolated in different ways, with
657 all solutions stored in the same table.
659 The only difference between incremental and cumulative calibration
660 tables is that incremental tables are generated directly from the data
661 via {tt solve} or (in the near future) from other ancilliary data
662 (e.g. weather information), and cumulative tables are generated from
663 other cumulative and incremental tables via {tt accumulate}. In all
664 other respects (internal format, application to data via {tt
665 setapply} and {tt correct}, plotting with {tt plotcal}, etc.), they
666 are the same, and therefore interchangable. Thus, {tt accumulate} and
667 cumulative calibration tables need only be used when circumstances
668 require it.
670 The {tt accumulate} function represents a generalization on the
671 classic AIPS CLCAL model of cumulative calibration in that its
672 application is not limited to accumulation of ``G'' solutions (SN/CL
673 tables classic AIPS are the analog of ``G'' (and, implicitly, ``T'')
674 in {tt aips++}). In principle, any basic calibration type can be
675 accumulated (onto itself), as long as the result of the accumulation
676 (matrix product) is of the same type. This is true of all the basic
677 types, except ``D''. Accumulation is currently supported for ``B'',
678 ``G'', and ``T'', and, in future, ``F'' (ionospheric Faraday
679 rotation), ``J'' (generic full-polarization calibration),
680 fringe-fitting, and perhaps others. Accumulation of certain
681 specialized types (e.g., ``GSPLINE'', ``TOPAC'', etc.) onto the basic
682 types will be supported in the near future. The treatment of various
683 calibration from ancilliary data (e.g., system temperatures, weather
684 data, WVR, etc.), as they become available, will also make use of {tt
685 accumulate} to achieve the net calibration.
687 Note that accumulation only makes sense if treatment of a uniquely
688 incremental solution is required (as described above), or if a careful
689 interpolation or sampling of a solution is desired. In all other
690 cases, re-solving for the type in question will suffice to form
691 the net calibration of that type. For example, the product of
692 an existing ``G'' solution and an amplitude and phase ``G'' self-cal
693 (solved with the existing solution applied), is equivalent to full
694 amplitude and phase ``G'' selfcal (with no prior solution applied),
695 as long as the timescale of this solution is at least as short as
696 that of the existing solution.
698 Use of {tt accumulate} is straightforward:
700 The {tt tablein} parameter is used to specify the existing cumulative
701 calibration table to which an incremental table is to be applied.
702 Initially, no such table exists, and {tt accumulate} will generate
703 one from scratch (on-the-fly), using the timescale (in seconds)
704 specified by the parameter {tt t}. These nominal solutions will
705 be unit-amplitude, zero-phase (i.e., unit matrix) calibration,
706 ready to be adjusted by accumulation. When {tt t} is negative (the
707 default), the table name specified in {tt tablein} must exist and
708 will be used.
710 The {tt incrtable} parameter is used to specify the incremental table
711 that should be applied to {tt tablein}. The calibration type of
712 {tt incrtable} sets the type assumed in the operation, so {tt
713 tablein} must be of the same type. If it is not, {tt accumulate}
714 will exit with an error message. (Certain combinations of types
715 and subtypes will be supported by accumulate in the future.)
717 The {tt tableout} parameter is used to specify the name of the output
718 table to write. If un-specified (or ``''), then {tt tablein} will be
719 overwritten. Use this feature with care, since an error here will
720 require building up the cumulative table from the most recent distinct
721 version (if any).
723 The {tt field} parameter specifies those field names (standard
724 selection syntax) in {tt tablein} to which the incremental solution
725 should be applied. The solutions for other fields will be passed to
726 {tt tableout} unaltered. If the cumulative table was created from
727 scratch in this run of {tt accumulate}, then these solutions will be
728 unit-amplitude, zero-phase, as described above.
730 The {tt calfield} parameter is used to specify the fields (standard
731 selection syntax) to select from {tt incrtable} to use when applying
732 to {tt tablein}. Together, use of {tt field} and {tt calfield}
733 permit completely flexible combinations of calibration accumulation
734 with respect to fields. Multiple runs of {tt accumulate} can be used
735 to generate a single table with many combinations. In future, a
736 ``self'' mode will be enabled that will simplify the accumulation of
737 field-specific solutions.
739 The {tt interp} parameter is used to specify the interpolation type
740 to use on the incremental solutions, as in {tt setapply}. The
741 currently available interpolation types are ``nearest'', ``linear'',
742 and ``aipslin''. See the {tt setapply} URM documentation for more
743 details.
745 The {tt spwmap} parameter enables accumulating solutions from
746 differing spectral windows. See {tt setapply} for details
747 on how spwmap works.
749 Pending improvements:
751 begin{itemize}
752 item Implement a ``self'' mode (independent of interpolation type),
753 to simplify or eliminate use of the {tt field} and {tt calfield}
754 parameters in some contexts (e.g., self-cal)
755 item More interpolation modes, e.g., ``cubic'', and interpolation
756 timescale (timerange to permit interpolation)
757 item Handle propogation (or not) of bad/flagged solutions
758 item Support of specialized types (e.g., TOPAC) onto the basic
759 types
760 item Smoothing (probably a separate function)
761 end{itemize}
762 """
763 return self._swigobj.accumulate(tablein, incrtable, tableout, field, calfield, interp, t, spwmap)
765 def activityrec(self):
766 """This funtion enables returning generic information about recent activity.
769 Pending improvements:
771 begin{itemize}
772 item ??
773 end{itemize}
774 """
775 return self._swigobj.activityrec()
777 def specifycal(self, caltable='', time='', spw='', antenna='', pol='', caltype='', parameter=[ float(1.0) ], infile='', uniform=True):
778 """This function enables specifying calibration parameters externally.
779 """
780 return self._swigobj.specifycal(caltable, time, spw, antenna, pol, caltype, parameter, infile, uniform)
782 def smooth(self, tablein, tableout, field=[ ], smoothtype='median', smoothtime=float(60.0)):
783 """This function provides for time-dependent smoothing of sampled
784 calibration solutions. Currently supported types are 'G', 'B', and 'T'.
785 (Smoothing on the frequency axis for 'B' will be supported in the near
786 future.)
788 Two (sliding) smoothing types are currenlty supported: 'median' or
789 'mean', one of these options should be specified in {stfaf
790 smoothtype}. The full width (in seconds) of the smoothing filter
791 should be specified in {stfaf smoothtime}. Amplitude and
792 (ambiguity-corrected) phase are smoothed separately.
794 Use {stfaf field} to limit the smoothing operation to a subset of the
795 fields (standard selection syntax) found in the calibration table
796 (other fields will pass to the output table unsmoothed). If {stfaf
797 field} is left blank, all fields in the table will be smoothed.
799 The smoothing is always done independently for each field, but
800 scan boundaries are not observed. Thus, if the {stfaf smoothtime}
801 is large enough, smoothing may occur over many boundaries.
803 Flagged solutions in the input table will not participate in the
804 smoothing calculation, but will be replaced with smoothed values
805 if the smoothing window covers one or more unflagged solutions when
806 centered on the flagged point.
808 Pending improvements:
810 begin{itemize}
811 item Add other smoothtypes?
812 item Add spw and other selection on input table
813 item Add A/P toggle
814 end{itemize}
815 """
816 return self._swigobj.smooth(tablein, tableout, field, smoothtype, smoothtime)
818 def rerefant(self, tablein, tableout, refantmode='flexible', refant=[ ]):
819 """TBD
821 Pending improvements:
823 begin{itemize}
824 item TBD
825 end{itemize}
826 """
827 return self._swigobj.rerefant(tablein, tableout, refantmode, refant)
829 def listcal(self, caltable, field=[ ], antenna=[ ], spw=[ ], listfile='', pagerows=int(50)):
830 """calibrater.listcal() lists antenna gain solutions in tabular
831 form. The table is organized as follows. Solutions are output by
832 begin{enumerate}
833 item Spectral window,
834 item Antenna,
835 item Time,
836 item Channel,
837 item and Polarization.
838 end{enumerate}
839 The inner-most loop is over polarization.
840 A ``Spw Header'' row is printed each time the spectral window changes.
841 In addition to listing the spectral window ID (SpwID), the Spw Header
842 also lists the date of observation (Date), the calibration table name (CalTable), and the measurement
843 set name (MS name). A lower-level ``antenna header'' is printed each time the antenna
844 names change or every `pagerows' of output, whichever comes first.
845 The antenna header column are described here:
847 begin{tabular}{ll}
848 hline hline
849 Column Name & Description
850 hline
851 Ant & Antenna name
852 Time & Visibility timestamp corresponding to gain solution
853 Field & Field name
854 Chn & Channel number
855 Amp & Complex solution amplitude
856 Phs & Complex solution phase
857 F & Flag
858 hline hline
859 end{tabular}
861 Elements of the ``F'' column contain an `F' when the datum is flagged,
862 and ` ' (whitespace) when the datum is not flagged.
864 Presently, the polarization mode names (for example: R, L)
865 are not given, but the ordering of the polrization modes (left-to-right) is
866 equivalent to the order output by task listobs (see ``Feeds'' in listobs output).
867 """
868 return self._swigobj.listcal(caltable, field, antenna, spw, listfile, pagerows)
870 def posangcal(self, posangcor, tablein, tableout=''):
871 """This function is used to apply position angle calibration for
872 observations made using circularly polarized feeds. According to the
873 Measurement Equation formalism, this correction should be applied to a
874 {tt D} (instrumental polarization) calibration table.
876 If no {tt D} calibration is performed (and thus no such table is
877 available), the correction can be applied to a {tt G} table, but it
878 should NEVER be applied to both, and always applied to a {tt D} table
879 if one is available. An input table must be specified. If no output
880 table is specified, then the input table will be modified in place.
882 Specify, as a vector of values, a position angle adjustment (in degrees)
883 for each spectral window. If only one value is specified, it will be
884 duplicated to all spectral windows; otherwise, the number of values
885 specified must match the number of spectral windows. The sign
886 convention for the position angle adjustment is such that the specified
887 value is the that which, when added to the position angle implied by the
888 data, will yield the correct position angle. For example, if {tt G-},
889 {tt D-}, and {tt P-}calibrated data for 3c286 suggests a position
890 angle of 45 degrees, the posangcor value should be -12 degrees as this
891 will yield the correct position angle of 33 degrees when added. In
892 general, posangcor equals correct position angle minus observed position
893 angle.
895 A future version of this function will have an option to recognize
896 standard position angle calibrators and determine the correction
897 automatically.
899 (NB: It may be desirable to use solutions for 'X' to handle
900 position angle calibration, rather than this method.)
901 """
902 return self._swigobj.posangcal(posangcor, tablein, tableout)
904 def linpolcor(self, tablein='', tableout='', fields=[ ]):
905 """THIS METHOD IS CURRENTLY DISABLED.
907 This function can be used to correct the gains derived from secondary
908 calibrators with unknown or variable polarization. It should only be
909 used for arrays with linear (X/Y) feeds and an Alt-Az mount for which
910 the observed polarization varies with feed position angle on the sky.
912 The function fits the gains with a sine and cosine term in feed position
913 angle and extracts the Q and U components of the secondary calibrator.
914 This is only possible if there is sufficient range in the position angle
915 (i.e., minimum of about 6 scans spanning at least 90 degrees in position
916 angle). Check the error of the fit to judge if the fit was succesfull,
917 it should generally be smaller than 0.5%.
919 Use the {stfaf fields} argument to select calibrator fields to be
920 fitted. The function takes a calibration table as input, and can write
921 the adjusted gain solutions to the same table on output, or create a new
922 table containing these results. The function also prints the derived
923 polarization for each field for each spectral window.
924 """
925 return self._swigobj.linpolcor(tablein, tableout, fields)
927 def plotcal(self, antennas, fields, spwids, plottype='AMP', tablename='', polarization=int(1), multiplot=False, nx=int(1), ny=int(1), psfile=''):
928 """This function plots a calibration table either to a plotter or
929 to a file.
931 The argument {stfaf plottype} can take the following values
932 for all types of solutions:
933 begin{description}
934 item[AMP] Gain Amplitude vs. Time
935 item[1/AMP] Inverse Gain Amplitude vs. Time (useful for
936 comparing with classic AIPS)
937 item[PHASE] Gain Phase vs. Time
938 item[RI] Gain Real vs. Imaginary
939 item[RLPHASE] Right/Left Gain phase difference (if polarizations are R,L)
940 item[XYPHASE] X/Y Gain phase difference (if polarizations are X,Y)
941 end{description}
943 The argument {stfaf plottype} can take the following values
944 for D tables
946 begin{description}
947 item[DAMP] Cross-polarized Gain Amplitude vs. Time
948 item[DPHASE] Cross-polarized Gain Phase vs. Time
949 item[DRI] Cross-polarized Gain Real vs. Imaginary
950 end{description}
952 The quality of the solutions can be examined with the following
953 {stfaf plottype} choices:
954 begin{description}
955 item[FIT] Fit per spectral window
956 item[FITWGT] Fit weight per spectral window
957 item[TOTALFIT] Total fit
958 end{description}
960 By default, all antennas (as specified in the antennas argument) will
961 appear on the same plot. Separate plots (all with the same scale)
962 for each antenna can be activated by setting multiplot=T. The multiplot
963 argument only separates plots by antenna (not, e.g., by the field_id(s)
964 specified in the fields argument). If multiplot=T, the nx and ny
965 arguments can be used to specify the number of plots per page.
967 At the moment, only one polarization can be plotted per execution.
968 This restriction will be relaxed in the near future.
970 For B solutions, the plotting will loop over timestamps (if more than
971 one).
973 A hardcopy plot can be created by specifying the texttt{psfile}
974 argument (which is especially useful for batch processing when a
975 display screen is not available). This will cause the plot to be
976 written to a PostScript file which can be subsequently sent to a
977 printer.
978 """
979 return self._swigobj.plotcal(antennas, fields, spwids, plottype, tablename, polarization, multiplot, nx, ny, psfile)
981 def modelfit(self, vary, niter=int(0), compshape='P', par=[ float(1.0),float(0.0),float(0.0) ], file=''):
982 """This method fits single-component models (points, elliptical Gaussians or elliptical Disks_
983 to the CORRECTED_DATA of the selected field. A first guess for the component
984 parameters may be specified in the {stfaf par} parameter.
985 """
986 return self._swigobj.modelfit(vary, niter, compshape, par, file)
988 def createcaltable(self, caltable, partype, caltype, singlechan):
989 """Creates an empty calibration table that can subsequently be filled
990 with by using the table tool.
991 """
992 return self._swigobj.createcaltable(caltable, partype, caltype, singlechan)
994 def updatecaltable(self, caltable):
995 """This method can be used to update a caltable (from v3.4 or later)
996 to the current version of CASA.
998 The following updates are currently supported.
1000 o At CASA v4.1.0, the OBSERVATION subtable and OBSERVATION_ID column
1001 were added to caltables. This method adds trivial versions of
1002 these elements to pre-v4.1 caltables.
1003 """
1004 return self._swigobj.updatecaltable(caltable)
1006 def close(self):
1007 """Close the {tt calibrater} tool, which is hardly ever necessary.
1008 """
1009 return self._swigobj.close()
1011 def done(self):
1012 """This function is redundant with the {stfaf close} method.
1013 """
1014 return self._swigobj.done()
1016 def parsecallibfile(self, filein):
1017 """TBD
1018 """
1019 return self._swigobj.parsecallibfile(filein)
1021 def setcorrdepflags(self, corrdepflags):
1022 """TBD
1023 """
1024 return self._swigobj.setcorrdepflags(corrdepflags)
1026 def setvi(self, old=False, quiet=False):
1027 """Use this method to control whether the modern (old=False) or old-style (old=True)
1028 VisibilityIterator is used by the calibration application. General users should
1029 avoid use of this function unless they understand what this means.
1031 This method will be removed from the calibrater tool in v5.1.
1032 """
1033 return self._swigobj.setvi(old, quiet)