#
# stub class definition file for docstring parsing
#
[docs]class calibrater:
r"""
Synthesis calibration (self- and cross-)
The ``calibrater`` tool (cb) provides for synthesis calibration operations within CASA.
"""
[docs] def calibrater(self):
r"""
Create a ``calibrater`` tool. The casapy environment provides a standard calibrater tool for general use (cb), but additional calibrater tools may be created if needed. Calibrater tools created in this way are independent of the standard calibrater tool.
"""
pass
[docs] def open(self, filename='', compress=False, addcorr=True, addmodel=True):
r"""
Attaches a MeasurementSet to the ``calibrater`` tool for further processing with other methods.
.. rubric:: Parameters
- ``filename (string='')`` - MeasurementSet file name. No default
- ``compress (bool=False)`` - Compress calibration columns?
- ``addcorr (bool=True)`` - Add scratch columns?
- ``addmodel (bool=True)`` - Add MODEL\_DATA column along with CORRECTED\_DATA ?
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
cb.open('ngc5921.ms');
"""
pass
[docs] def selectvis(self, time='', spw='', scan='', field='', intent='', observation='', baseline='', uvrange='', chanmode='channel', nchan=1, start=0, step=1, mstart=0.0, mstep=0.0, msselect=''):
r"""
This function provids for selection of the visibility data from the MS which will be treated by subsequent execution of the solve and correct functions. Note that data selection is not cumulative, i.e., any selection made in a previous call to selectvis will be overridden by the the current call.
Most of the selectvis parameters use the standardized MS Selection syntax.
The parameters are described below. The selected data will satisfy the logical AND of all non-trivially specified parameters. Note that the old-fashioned strided channel selection parameters are deprecated (and will soon be removed); use spw instead. Running selectvis with no specified parameters restores selection of the entire MS.
time
is used to specify time ranges in a stardard format
spw
is used to specify spectral window and channel selection. Currently, only a single channel range can be specified per spw.
scan
is used to specify scan numbers and ranges
observation
is used to specify observation ID(s).
field
is used to specify field names or indices
baseline
is used to specify antenna and baseline combinations
uvrange
is used to specify baseline length ranges
chanmode
is deprecated (use spw)
nchan
is deprecated (use spw)
start
is deprecated (use spw)
step
is deprecated (use spw)
mstart
is deprecated (use spw)
mstep
is deprecated (use spw)
msselect
is used to specify a subselection of data according to Measurement Set columns in conditional combinations not possible with the standard parameters above. This parameter should be specified as a valid expression. If both msselect and the standard selection parameter are used together, they are combined with a logical AND, i.e., the data must jointly satisfy all selectvis parameters.
.. rubric:: Parameters
- ``time (variant='')`` - Select on time
- ``spw (variant='')`` - Select on spectral window
- ``scan (variant='')`` - Select on scan
- ``field (variant='')`` - Select on field
- ``intent (variant='')`` - Select on intent or state
- ``observation (variant='')`` - Select by observation ID(s)
- ``baseline (variant='')`` - Select on antennas/baselines
- ``uvrange (variant='')`` - Select by uvrange
- ``chanmode (string='channel')`` - Type of data selection: channel or velocity
- ``nchan (int=1)`` - Number of channels to select (mode='channel')
- ``start (int=0)`` - Start channel (0-relative) (mode='channel')
- ``step (int=1)`` - Step in channel number (mode='channel')
- ``mstart (double=0.0)`` - Start velocity (e.g. '20Km/s')
- ``mstep (double=0.0)`` - Step in velocity (e.g. '100m/s')
- ``msselect (string='')`` - TAQL selection string. Default (empty) is no specific selection.
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
Open and select a field:
cb.open('ngc5921.ms');
cb.selectvis(field='N5921_2'); # by complete name
cb.selectvis(field='N5921*'); # with wildcard
cb.selectvis(field='2'); # by index
Select a field and a channel range:
cb.selectvis(spw='0:10~40',field='N5921*');
Select using all MS Selection parameters (these parameters are
over-specified somewhat, i.e., scan 6 contains only field N5921_2,
etc.):
cb.selectvis(time='>1995/04/13/10:40:00', # times greater than this
spw='0:20~40', # channels 20-40 in spw 0
scan='6', # scan 6 only
field='N59*', # fields matching N59*
baseline='1 \& *', # baselines to antenna 1
uvrange='>0.0klambda') # baselines greater than zero length
Reset selection to the entire dataset
cb.selectvis()
"""
pass
[docs] def setmodel(self, modelimage=''):
r"""
Name of the model image to be used as a sky model for model visibility computations. For now, this is used only by EP-Jones solver.
.. rubric:: Parameters
- ``modelimage (string='')`` - Name of the model image.
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
cb.setmodel("mymodel");
"""
pass
[docs] def setptmodel(self, stokes=[0.0, 0.0, 0.0, 0.0]):
r"""
Set a global point source model Stokes parameters to use in solving operations.
.. rubric:: Parameters
- ``stokes (doubleVec=[0.0, 0.0, 0.0, 0.0])`` - Vector of Stokes parameters.
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
cb.setmodel([1,1,0,0]);
"""
pass
[docs] def setapply(self, type='B', t=0.0, table='', field='', interp='aipslin', select='', calwt=False, spwmap=[-1], opacity=[0.0]):
r"""
This function is used to specify the calibration components which should be applied during subsequent execution of the solve and correct functions. This function should be executed as many times as necessary to specify all desired calibration components.
Each calibration component represents a separate calibration matrix correction included in the measurement equation. The different types correspond to different instrumental and atmospheric effects. Calibration components are available as calibration tables generated by previous solve executions (types ’B’,’BPOLY’,’G’,’GSPLINE’, ’D’,’DF’,’T’,’M’,’MF’,’X’), or are calculated analytically on the fly (types ’P’, ’TOPAC’, ’GAINCURVE’). Upon execution of solve or correct, the group of specified calibration components will be applied in the order prescribed by the Measurement Equation formalism.
The parameters are as follows:
type
The calibration type being specified. This is only required for analytic types (’P’,’TOPAC’,’GAINCURVE’). When specifying an existing pre-solved calibration table, it is not necessary to explicitly specify the type; this will be discerned from the table. (Specifying the type as well as the table will force a check that the table contains solutions of the specified type.
For type=’GAINCURVE’, an elevation-dependent correction will be applied using parameters read from the data repository. Currently, this is only supported for the VLA.
t
This parameter will be used in a future release to control the range of applicability of the specified calibration. Currently, it is ignored.
table
For pre-solved calibration, the file name of the table to apply.
field
The fields to select from the specified table, using MS Selection syntax (as in selectvis).
interp
The desired type of time-dependent interpolation. Use interp=’nearest’ to calibrate each datum with the calibration value nearest in time. Use interp=’linear’ to calibrate each datum with calibration phases and amplitudes linearly interpolated from neighboring (in time) values. In the case of phase, this mode will assume that phase jumps greater than 180 degrees between neighboring points indicate a cycle slip, and the interpolated value will follow this change in cycle accordingly (i.e., the implied rate will always be less than 180 degrees per sample). Use interp=’aipslin’ to emulate the basic interpolation mode used in classic AIPS, i.e., linearly interpolated amplitudes, with phases derived from linear interpolation of the complex calibration values. While this method avoids having to track cycle slips (which is unstable for solutions with very low SNR), it will yield a phase interpolation which becomes increasingly non-linear as the spanned phase difference increases. The non-linearity mimics the behavior of interp=’nearest’ as the spanned phase difference approaches 180 degrees (the phase of the interpolated complex calibration value initially changes very slowly, then rapidly jumps to the second value at the midpoint of the interval). If the uncalibrated phase is changing this rapidly, a ’nearest’ interpolation is not desirable. Usually, interp=’linear’ is the best choice. The interp parameter is applicable to any calibration type, as long as there are sufficient solutions available to perform the interpolation. Note that calibration solutions which have been determined for only one timestamp will default to ’nearest’. More interpolation options (e.g., ’cubic’) will be added in the future.
select
Used to specify general selection of a subset of calibration measurements from the table to be applied to the visibility data. Arbitrary cross-calibration is possible by combining this function with the setdata function. The string specified must be a valid expression.
spwmap
This parameter is used to indicate how solutions derived from different spectral windows should be applied to other spectral windows. Nominally, data in each spectral window will be corrected by solutions derived from the same spectral window. This is the default behavior of spwmap, i.e., if spwmap is not specified, calibrater will insist that data be corrected by solutions from the same spw. Otherwise, spwmap takes a vector of integers indicating which spectral window *solutions* to apply to which spectral window *data*, such that ``spwmap[j]=i`` causes solutions derived from the i-th spectral window to be used to correct the j-th spectral window. For example, if (say) bandpass solutions are available for spws 0 & 2, and it is desired that these be applied to spws 1 & 3 (as well as 0 & 2), respectively, use spwmap=[0,0,2,2]. Even if some spws do not require an explicit spwmap setting, yet one or more does, it is safest to specify it explicitly for all, e.g., spwmap=[0,1,3,3] indicates that spw 2 will be corrected with solutions from spw 3, and the others will behave nominally. Note that if no solutions exist for any of the spws specified in spwmap, an error message will result.
calwt
If set True, the data weights will be calibrated along with the data. This is usually desirable.
opacity
For type=’TOPAC’, an elevation-dependent opacity correction will be applied according to the zenith opacity value supplied in the opacity parameter. Currently, only one zenith opacity value can be supplied, and it is used for all antennas.
Use the state function to review the list of calibration components that have been set for application.
Pending improvements:
- Enable variety of interpolation modes and timescales
- Allow for antenna- and time-dependent opacities
.. rubric:: Parameters
- ``type (string='B')`` - Component type
- ``t (double=0.0)`` - Interpolation interval (seconds)
- ``table (string='')`` - Calibration table name
- ``field (variant='')`` - Select on field
- ``interp (string='aipslin')`` - Interpolation type (in time)
- ``select (string='')`` - TAQL selection string. Default is no selection.
- ``calwt (bool=False)`` - Calibrate weights?
- ``spwmap (intVec=[-1])`` - Spectral windows to apply
- ``opacity (doubleVec=[0.0])`` - Array-wide zenith opacity per antenna (for type='TOPAC')
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
cb.open('ngc5921.ms')
cb.selectvis(field='N5921*')
cb.setapply (type='G', table='gcal', field='1445*')
cb.setapply (type='P')
cb.correct();
cb.close();
In this example, we apply parallactic angle corrections and a gain
calibration derived from a field whose name matches '1445*' in a caltable
called 'gcal' to data for a field matching 'N5921*'
"""
pass
[docs] def setcallib(self, callib=''):
r"""
TBD
.. rubric:: Parameters
- ``callib (record='')`` - A calibration library record
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
TBD
"""
pass
[docs] def validatecallib(self, callib=''):
r"""
TBD
.. rubric:: Parameters
- ``callib (record='')`` - A calibration library record
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
TBD
"""
pass
[docs] def setsolve(self, type='G', t='', table='', append=False, preavg=-1.0, phaseonly=False, apmode='AP', refant='', refantmode='flex', minblperant=4, solnorm=False, normtype='median', minsnr=0.0, combine='', fillgaps=0, cfcache='', painc=360.0, fitorder=0, fraction=0.1, numedge=-1, radius='', smooth=True, zerorates=False, globalsolve=True, niter=100, corrcomb='none', delaywindow='', ratewindow='', paramactive='', concatspws=True, solmode='', rmsthresh=''):
r"""
This function specifies the calibration component that will be solved for by the solve function. Currently, only one type can be solved for at one time.
Each calibration component represents a separate calibration matrix correction included in the measurement equation. The different types correspond to different instrumental and atmospheric effects. Currently, the solvable calibration components are types ’G’,’T’,’B’, ’D’ and ’DF’, which are antenna-based, and, ’M’ and ’MF’, which are baseline-based. Arrange to pre-apply any existing calibration components (of types other than the solved-for one) using the setapply function.
The parameters are:
type
Specify the calibration type you want to solve for, from ’G’,’T’,’B’,’D’,’DF’,’M’,’MF’.
t
Specify the solution interval. This can be specified as an integer (units of seconds assumed) or as a string containing a value and units (e.g., ’30s’, ’45min’, ’2h’) or ’inf’ (infinite) or ’int’ (per data integration). A solution interval of 0 (with or without units) is the same as ’int’ (per integration), and negative solution intervals are treated as ’inf’ (infinite).
table
Specify the output calibration table name in which to store the calibration solve result. Existing tables will be deleted and replaced.
append
Append the solutions to an existing table.
preavg
Specify the amount of pre-average (in time) within the solution interval. By default, data are averaged up to the solution interval (or up to 5 minutes for ’D’ solving).
phaseonly
This parameter is deprecated, use apmode.
apmode
Control generation of amplitude-only (’a’), phase-only (’p’), or amplitude-and-phase (’ap’, the default) solutions.
refant
Specify an antenna (using data selection syntax) for referencing the solutions.
solnorm
Normalize the solutions by their mean post-solve. For ’B’, and ’MF’, this is a complex normalization per solution spectrum. For other types, this is a global (per-spw) normalization of the amplitudes only.
minsnr
Specify the SNR below which solution are rejected.
combine
Specify which data axes (spw, field, scan, or some combination) on which the data should be combined to generate a single solution. E.g., combine=’spw’ will force combination of many spws to form a single solution (per solution interval). Similarly, combine=’scan’ with a long solution interval will force the combination of scans to yield individual solutions (per field and spw). Ordinarily, solutions are always broken at scans boundaries. Separate multiple combine options with commas.
fillgaps
For ’B’ solutions, specify the largest solution channel gap (which arise due to flagged data) that will be filled post-solve via interpolation. Such solution gaps remain flagged by default.
Pending improvements:
- Change t to solint?
- Permit flexible specification of preavg (as for t)
.. rubric:: Parameters
- ``type (string='G')`` - Component type
- ``t (variant='')`` - Solution interval (units optional)
- ``table (string='')`` - Output calibration table name
- ``append (bool=False)`` - Append to existing table?
- ``preavg (double=-1.0)`` - Pre-averaging interval (in sec)
- ``phaseonly (bool=False)`` - Solve only for phase?
- ``apmode (string='AP')`` - Solve for 'AP', 'A' (amp-only) or 'P' (phase-only)
- ``refant (variant='')`` - Reference antenna. Default is none.
- ``refantmode (string='flex')`` - Reference antenna mode
- ``minblperant (int=4)`` - Minimum number of baselines per ant for solving
- ``solnorm (bool=False)`` - Normalize solution after solve
- ``normtype (string='median')`` - Solution normalization type
- ``minsnr (float=0.0)`` - SNR threshold for accepting solutions
- ``combine (string='')`` - Data axes on which to combine solving (scan, spw, and/or field)
- ``fillgaps (int=0)``
- ``cfcache (string='')`` - Name of the directory to be used for convolution function disk cache. This is used when type=EP.
- ``painc (float=360.0)`` - Parallactic Angle increment used to trigger computation of a new convolution function. This is used when type=EP. Default value implies that only one convolution function will be computed for the entire range of observation.
- ``fitorder (int=0)`` - Order of the polynomial fit, used when type='A'.
- ``fraction (float=0.1)`` - [SINGLE-DISH SPECIFIC] Edge detection parameter for otfraster/otf calibration. This is a number of edge points as a fraction of total number of points.
- ``numedge (int=-1)`` - [SINGLE-DISH SPECIFIC] Edge detection parameter for otfraster calibration. This is a number of edge points. The value specified here comes before fraction. Note that edge points will be detected from both side of each raster row so that number of edge points is effectively twice of the specified value in each raster row. Default (-1) is to use fraction.
- ``radius (string='')`` - [SINGLE-DISH SPECIFIC] Specifies radius of the central region of double circle gain calibration for fast scanning data. The value must be either empty or quantum string (numeric value with unit). Default ("") is to use a radius of primary beam.
- ``smooth (bool=True)`` - [SINGLE-DISH SPECIFIC] Whether or not applying smoothing during double circle gain calibration for fast scanning data. Default is True.
- ``zerorates (bool=False)`` - [FRINGE-FIT SPECIFIC] Zero delay-rates in fringe fitting solution tables.
- ``globalsolve (bool=True)`` - [FRINGE-FIT SPECIFIC] Use global least-squares solver to improve fringe-fitting parameter estimates
- ``niter (int=100)`` - [FRINGE-FIT SPECIFIC] Maximum number of iterations for global least-squares solver
- ``corrcomb (string='none')`` - [FRINGE-FIT SPECIFIC] Combine correlations (currently supported values are "none" and "all")
- ``delaywindow (doubleVec='')`` - [FRINGE-FIT SPECIFIC] Constrain FFT delay search to a window; a two-element list, units of nanoseconds
- ``ratewindow (doubleVec='')`` - [FRINGE-FIT SPECIFIC] Constrain FFT rate search to a window; a two-element list, units of seconds per second
- ``paramactive (boolVec='')`` - An array of three booleans to control whether to sove for delay, fringe-rate and dispersive delay
- ``concatspws (bool=True)`` - A flag to control multiband FFT behaviour in fringefit task.
- ``solmode (string='')`` - Solving mode: '', 'L1'; add 'R' for iterative outlier excision.
- ``rmsthresh (doubleVec='')`` - RMS threshold sequence.
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
cb.open('ngc5921.ms');
cb.setapply (type='P');
cb.setsolve (type='G',t='300s', refant=3, table='gcal');
cb.solve();
cb.close();
In this example, analytic (non-solvable) parallactic angle corrections
are pre-applied before G solutions are obtained on a timescale of 300
seconds. The resulting solutions are phase-referenced to antenna 3,
and stored in a calibration table called 'gcal'.
cb.reset();
cb.setapply (type='P',t=5.0);
cb.setapply (type='G',table='gcal');
cb.setsolve (type='D',t=86400.0, preavg=60.0, refant=3, table='dcal');
cb.solve();
cb.close();
In this example, the solve/apply state of the calibrater tool is reset
and then the P and G corrections (from above) are applied before
solving for D solutions on a diurnal timescale. Note that the data
will be averaged only to 60 seconds before the solution. The resulting
D solutions are stored in a table called 'dcal'.
"""
pass
[docs] def setsolvegainspline(self, table='', append=False, mode='AMP', splinetime=10800, preavg=0.0, npointaver=10, phasewrap=250, refant=''):
r"""
This function is a specialization of the setsolve method which should be used when cubic spline G solutions are desired, e.g., when SNR on calibrators is very low. Currently, this solving mode treats dual polarization data on a per-polarization basis. The option to obtain a joint solution (a la ’T’) will be provided in the future.
The visibility data are averaged in frequency (for multi-channel data) prior to the solution.
This method uses many of the basic parameters as the generic setsolve. Parameters unique to the spline solver are:
mode
For phase solutions only, use mode=’PHAS’. For amplitude solutions only, use mode=’AMP’. If both are desired, use mode=’PHASAMP’, and both will be solved for using the same spline timescale (this mode also assumes that all calibrators have the correct relative flux densities). If solving for phase and amplitude separately (usually in this order), it is usually desirable to apply the first one when solving for the second one. Spline solution so obtained will be stored in separate calibration tables. In the near future, the mode parameter will be consolidated with the generic apmode parameter.
splinetime
The spline timescale (time between knots) is specified here. The default is 10800 seconds (3 hours). In future this parameter will be consolidated with the generic t parameter. The preavg parameter should be set to a value at least 4X shorter than the spline time (an error will occur if there is insufficient sampling within the splinetime timescale), and consistent with the expected coherence. Consistent with these constraints, use the largest possible value for preavg to optimize the SNR of the pre-solve phase-tracking algorithm.
npointaver and phasewrap
These parameters tune the phase-unwrapping algorithm when mode :math:`=` ’PHAS’. Cycle slips are detected (and removed before the spline solve) when the median phase a sequence of length npointaver (in integrations) differs by more than phasewrap degrees from the previous sequence.
Pending improvements:
- Consolidate more parameters with the generic setsolve
- Introduce the generic combine options
- Improve phase-tracking algorithm
.. rubric:: Parameters
- ``table (string='')`` - Output calibration table name
- ``append (bool=False)`` - Append to existing table?
- ``mode (string='AMP')`` - Phase or Amplitude mode?
- ``splinetime (double=10800)`` - Spline timescale (sec)
- ``preavg (double=0.0)`` - Pre-averaging interval (in sec)
- ``npointaver (int=10)``
- ``phasewrap (double=250)``
- ``refant (variant='')`` - Reference antenna. Default is none.
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
cb.open('ngc5921.ms')
cb.selectvis(field='1445*')
cb.setsolvegainspline (table='gcalph',mode='PHAS',splinetime=3600.0,preavg=60.0)cb.solve()
cb.setsolvegainspline (table='gcalamp',mode='AMP',splinetime=10800.0);
cb.solve();
cb.close();
In this example, a spline solution is first found for phase on a hourly timescale, then for amplitude on a three-hour timescale.
"""
pass
[docs] def setsolvebandpoly(self, table='', append=False, t='', combine='', degamp=3, degphase=3, visnorm=False, solnorm=True, maskcenter=0, maskedge=5.0, refant=''):
r"""
This function is a specialization of the setsolve method which should be used to arrange for bandpass solving when polynomial solutions for B are desired, e.g., when per-channel SNR on calibrators is too low to obtain a useful sampled bandpass.
Prior to the solution, the visibility data are averaged in time, and the solution is performed for both phase and amplitude.
This method uses most of the same parameters as the generic setsolve, with a few unique additions:
degamp and degphase
The parameters permit specification of the polynomial order to use in amp and phase. Specifying 0 (zero) yields constant solutions.
visnorm
This parameter is used to normalize the assembled spectral data, in a per baseline manner. If set True, this will have the effect of removing any non-frequency-dependent closure errors (e.g., as caused by source structure, or introduced by the instrument) from the data, and should be used with caution. The resulting solutions will be effectively normalized as well. When visnorm=F is used, closure errors in the data (as supplied to the solver) may be visible in the form of offsets between the data and solutions. For bandpass calibration, this is usually ok, as the *shape* of the bandpass is the most important aspect of the solution. In future this parameter will be generalized and made available for other solve types. (NB: Use of solnorm=True still provides for post-solve normalization of the solutions.)
maskcenter and maskedge
These parameters control how many channels are ignored on-the-fly, at the center and edges of each input spectral window, respectively. To avoid edge channels, it is almost always better to flag these channels directly, or select against them in setdata. Aggressive use of maskedge (large values), will yield polynomial solutions which will tend to diverge at the edges (especially when the polynomial degree is also high), because maskedge does not change the frequency domain of the solutions. Such solutions should be used with caution in subsequent operations. (It is best to avoid use of maskedge.)
The BPOLY solution is performed for both phase and amplitude, and the result will be stored in the same table. The frequency domain of the solutions is limited to only the range of frequencies selected in selectvis. When correcting data with these solutions (for other solves or with correct), only data within this domain will be corrected. Data outside (e.g., edge channels avoided in setdata for the solve), will not be corrected. Therefore, the same (or narrower) channel selection is recommended for all operations using solutions produced by this function and solve().
Note that the combine parmaeter can be used meaningfully with the BPOLY solver. When combine=’spw’, the data from multiple spws will be combined on a common frequency axis, and a single polynomial will be determined spanning them all. This is different than for ordinary sampled ’B’ solutions, for which combine=’spw’ causes the bandpass to be combined on a common channel axis, effectively yielding a mean bandpass for the set of spws.
.. rubric:: Parameters
- ``table (string='')`` - Output calibration table name
- ``append (bool=False)`` - Append to existing table?
- ``t (variant='')`` - Solution interval (units optional)
- ``combine (string='')`` - Data axes on which to combine solving (scan, spw, and/or field)
- ``degamp (int=3)`` - Polynomial degree for amplitude solution
- ``degphase (int=3)`` - Polynomial degree for phase solution
- ``visnorm (bool=False)`` - Normalize data prior to solution
- ``solnorm (bool=True)`` - Normalize result?
- ``maskcenter (int=0)`` - Number of channels to avoid in center of each band
- ``maskedge (double=5.0)`` - Fraction of channels to avoid at each band edge (in \%)
- ``refant (variant='')`` - Reference antenna
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
cb.open('ngc5921.ms');
cb.selectvis(field='1331*')
cb.setsolvebandpoly(table='bpoly',degamp=5,degphase=7);
cb.solve();
cb.close();
In this example, amplitude (degree 5) and phase (degree 7) Chebychev
polynomial bandpasses are determined using the default parameters.
"""
pass
[docs] def returndict(self):
r"""
Return a dictionary containing information about the current calibrater tool state. This dictionary contains the following keys: ’antennas’, ’apply tables’, ’field’, ’intents’, ’observation’, ’scan’, ’solve table’, ’spw’.
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.
The values of each of these keys is an array of either strings or integers.
"""
pass
[docs] def state(self):
r"""
Request the apply/solve state of the calibrater tool. A listing of all calibration components that have been set for application or solving is written to the logger.
"""
pass
[docs] def reset(self, apply=True, solve=True):
r"""
Resets the apply and/or solve components previously set by setapply and setsolve.
.. rubric:: Parameters
- ``apply (bool=True)`` - If True, unset all apply settings
- ``solve (bool=True)`` - If True, unset all solve settings
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
cb.open('ngc5921.ms')
cb.setapply ('P', 5.0)
cb.setsolve ('G', 300.0, F, 3, 'gcal_1', T)
cb.state()
cb.reset(apply=T,solve=F);
cb.state()
cb.reset()
"""
pass
[docs] def initcalset(self, calset=0):
r"""
This function re-initializes the calibration scratch columns: MODEL_DATA to unity (in total intensity, and unpolarized), and CORRECTED_DATA to (observed) DATA. Optionally if calset is set to 1 any model saved in the MS header to for calibration purposes is deleted
.. rubric:: Parameters
- ``calset (int=0)`` - if it set to 1 the model saved in the header is removed
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
cb.open('ngc5921.ms');
cb.initcalset();
cb.solve();
"""
pass
[docs] def delmod(self, otf=False, field='', spw='', scr=False):
r"""
This method can be used to delete the model visibility data representations in the MS. The ’otf’ representation is the new (as of v3.4) ’scratch-less’ model data, stored as keywords in the MS header containing model data formation instructions. It is generated by the im tool (setjy, ft, and clean methods; usescratch=F in im.open), and if present, overrides the old-fashioned MODEL_DATA column (if present). If a user wishes to use the MODEL_DATA column \_after\_ having operated with the ’otf’ representation, this method can be used to delete the ’otf’ represenatation to make the MODEL_DATA column visible. (Create the MODEL_DATA column by using usescratch=T in the im tool, or by running the cb.open with addmodel=T.)
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.
For convenience, this method also provides a means for deleting the MODEL_DATA column by setting scr=T.
.. rubric:: Parameters
- ``otf (bool=False)`` - If T, delete the otf model data keywords
- ``field (variant='')`` - Select on field
- ``spw (variant='')`` - Select on spw only if field is defined
- ``scr (bool=False)`` - If T, delete the MODEL\_DATA column
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
cb.open('ngc5921.ms');
cb.delmod(otf=T,scr=F); # delete only the otf model for all fields
cb.solve();
cb.open('n4826.ms')
cb.delmod(otf=T, field='1')
#delete otf model of field 1 only, all other fields model are untouched
#if present
cb.open('n4826.ms')
cb.delmod(otf=T, field='1', spw='2')
#delete otf model of field 1 and spectralwindow 2 only.
####NOTE doing:
cb.delmod(otf=T, field='', spw='2')
#will delete all otf models and spw will be ignored
"""
pass
[docs] def solve(self):
r"""
Execution of this function initiates a solve for the calibration component specified in a previous setsolve execution. Existing calibration components (as specified in one or more setapply executions) will be appropriately applied to the observed and model data according to their position in the Measurement Equation, and their commutation properties.
"""
pass
[docs] def correct(self, applymode=''):
r"""
This function applies the calibration components specified via one or more invocations of the setapply function to the observed visibility data and writes the result to the CORRECTED_DATA column of the Measurement Set.
.. rubric:: Parameters
- ``applymode (string='')`` - Correction cal/flag mode: ''='calflag','cal','flag','trial'
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
cb.open('ngc5921.ms');
cb.selectvis(field='1445*')
cb.setapply ('G', 10.0, 'gcal_1')
cb.correct();
cb.close();
"""
pass
[docs] def corrupt(self):
r"""
This function applies the calibration components specified via one or more invocations of the setapply function to the model visibility data and (over-)writes the result to the MODEL_DATA column of the Measurement Set.
"""
pass
[docs] def initweights(self, wtmode='nyq', dowtsp=False, tsystable='', gainfield='', interp='', spwmap=''):
r"""
This function initializes the MS weight info in various ways.
If wtmode=’ones’, SIGMA and WEIGHT will be initialized with 1.0, globally.
If wtmode=’nyq’ (the default), SIGMA and WEIGHT will be initialized according to bandwidth and integration time. This is the theoretically correct mode for raw normalized visibilities.
If wtmode=’sigma’, WEIGHT will be initialized according to the existing SIGMA column.
If mode=’weight’, WEIGHT_SPECTRUM will be initialized according to the existing WEIGHT column; dowtspec=T must be specified in this case.
For the above wtmodes, if dowtspec=T (or if the WEIGHT_SPECTRUM column already exists), the WEIGHT_SPECTRUM column will be initialized (uniformly in channel), in a manner consistent with the WEIGHT column. If the WEIGHT_SPECTRUM column does not exist, dowtsp=T will force its creation.
The follow modes should be used with extreme care: If wtmode=’delwtsp’, the WEIGHT_SPECTRUM column will be deleted (if it exists). If wtmode=’delsigsp’, the SIGMA_SPECTRUM column will be deleted (if it exists). Note that creation of SIGMA_SPECTRUM is not supported via this method.
Note that this method does not support any prior selection. Intialization of the weight information must currently be done globally or not at all. This is to maintain consistency.
.. rubric:: Parameters
- ``wtmode (string='nyq')`` - Initialization mode
- ``dowtsp (bool=False)`` - Initialize WEIGHT_SPECTRUM column
- ``tsystable (string='')`` - Tsys calibration table to apply on the fly
- ``gainfield (string='')`` - Select a subset of calibrators from Tsys caltable
- ``interp (string='')`` - Interp type in time[,freq]. default==linear,linear
- ``spwmap (intVec='')`` - Spectral windows combinations to form for gaintables(s)
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
cb.open('ngc5921.ms')
cb.initweights()
cb.close()
"""
pass
[docs] def fluxscale(self, tablein='', reference='', tableout='', transfer='', listfile='', append=False, refspwmap=[-1], gainthreshold=-1.0, antenna='', timerange='', scan='', incremental=False, fitorder=1, display=False):
r"""
This function is used to bootstrap the amplitude scale the calibration solutions according to specified reference calibrator(s) of known flux density. This is necessary when the flux densities of some of your calibrators were unknown (and thus were assumed to be 1 Jy) during G solving.
The bootstrapping is achieved by comparing the median gain norm of the calibration solutions derived for the calibrators specified in reference (one or more sources with known flux densities at the time of G solving) with that of the calibrators specified in transfer, and enforcing the assumption that the antenna gains are constant, on average. The gain solutions for the transfer sources are then re-scaled accordingly. The reference and transfer parameters may be specified using the general field selection syntax (as in field in selectvis).
If no ``transfer`` fields are specified, then the solutions for all non-reference fields in ``tablein`` will be re-scaled.
If no ``tableout`` is specified the input table will be overwritten with the scaled solutions. Note that the resulting table will only contain solutions for those fields implicit in the ``reference`` and ``transfer`` specifications. Use ``append=T`` to append the scaled solutions to an existing table.
Use the refspwmap parameter to indicate how data for different spectral windows should be matched in calculating the flux density scale factor for transfer fields. The default behavior for ``refspwmap`` is to insist on precisely matching spectral windows for ``reference`` and ``transfer`` fields. When specified, the refspwmap parameter takes a vector of integers indicating which spectral window solutions to use as the reference for others, such that ``refspwmap[j]=i`` causes solutions (from reference fields) observed in the i-th spectral window to be used to reference solutions (from transfer fields) observed in the j-th spectral window. For example, for the case of a total of 4 spectral windows: if the ``reference`` fields were observed only in spw=2 & 4, and the ``transfer`` fields were observed variously in all 4 spws, specify ``refspwmap=[2,2,4,4]``. This will ensure that ``transfer`` fields observed in spws 1,2,3,4 will be referenced to ``reference`` field data from spws 2,2,4,4, respectively. Note that if the ``transfer`` fields were observed only in spws 1 & 3, the same specification would work, but ``refspwmap=[2,2,4]`` would suffice. In this case, nothing need be specified for the 4th spw (there are no transfer fields there), and specifying 2 for the 2nd spw is actually inconsequential (though required so that the specification of 4 for spw 3 is properly interpretted).
The gain values used in the flux scaling determination skewed by outliers. The parameters, ``gainthreshold`` and ``antenna`` can be used to limit the input gain solutions to be included in the flux scale determination. Use the ``gainthreshold`` is a threshold in % from the median values of the gain solutions to be used. Use the ``antenna`` to select or de-selesect (using the MSSelection syntax) antenna(s). Futher refinements on the selection based on timerange and scan are possible.
The derived flux densities for the transfer fields will be reported in the logger, and returned to the Python dictionary specified in ``fluxd``. This will be an 2D array of shape [number-of-spectral-windows X number-of-fields]. When mulitple spectral windows are involved the spectral index will also be reported by fitting the determined flux densities across the freuquencies. The order of a polynomcial to be fitted can be specified with ``fitorder``.
Note that elevation-dependent gain effects may render the basic assumption used here invalid, and so should be corrected for prior to solving for G, using types ’TOPAC’ or ’GAINCURVE’ in ``setapply``.
Note that the visibility data itself is not used directly by this function.
Pending improvements:
- Allow antenna and uv-distance selection to improve results for resolved calibrators
- Set the visibility model according to the flux density results
- An option to use the data to derive the relative flux densities
.. rubric:: Parameters
- ``tablein (string='')`` - Input calibration table name
- ``reference (variant='')`` - Reference calibrator field names (comma-separated)
- ``tableout (string='')`` - Output calibration table name. Default is input calibration table name.
- ``transfer (variant='')`` - Transfer source field names (comma-separated). Default is all other fields.
- ``listfile (string='')`` - Name of listfile that contains the fit information. Default is '' (no file).
- ``append (bool=False)`` - Append to existing table?
- ``refspwmap (intVec=[-1])`` - List of alternate spw for referencing
- ``gainthreshold (float=-1.0)`` - Threshold of gain amplitudes with respect to the median value to be used in flux scale calculation. Default: -1.0 (no threshold)
- ``antenna (string='')`` - antenna selection/de-selection in flux scale calculation. Default: ""(include all antennas)
- ``timerange (string='')`` - timerage sub-selection with antenna selection in flux scale calculation. Default: ""(include all)
- ``scan (string='')`` - scan sub-selection with antenna selection in flux scale calculation. Default: ""(include all)
- ``incremental (bool=False)`` - create a incremental caltable
- ``fitorder (int=1)`` - order for spectral fitting for multiple spws
- ``display (bool=False)`` - display statistics of the flux ratios
.. rubric:: Returns
``record``
.. rubric:: Examples
::
cb.open('ngc5921.ms')
cb.selectvis(field='1331*,1445*')
cb.setsolve(type='G',table='gcal',t='inf')
cb.solve()
cb.fluxscale (tablein='gcal', tableout='flxcal',
reference='1331*', transfer='1445*');
cb.close();
This example generates a calibration table containing {\tt G}
solutuions ('gcal') and then writes a re-scaled version, using
1335+305 as the reference calibrator, to derive properly scaled
amplitude calibration for the transfer source, 1445+099. We have
assumed that 1331+305 has already had its MODEL\_DATA set to
the correct flux density.
"""
pass
[docs] def accumulate(self, tablein='', incrtable='', tableout='', field='', calfield='', interp='linear', t=-1.0, spwmap=[-1]):
r"""
This function enables cumulative calibration using ``calibrater``. It is the analog of the task “CLCAL” in classic AIPS.
The ``accumulate`` function is useful when:
- a calibration solution of a particular type already exists,
- an incremental calibration solution *of the same type* is desired (an incremental solution in this context means derived independently from, or determined with respect to, the first)
- the first calibration cannot be implicitly recovered in the course of obtaining the incremental solution
For example, a phase-only “G” self-calibration on a target source may be desired to tweak the full amplitude and phase “G” calibration already obtained from a calibrator. The initial calibration (from the calibrator) contains amplitude information, and so must be carried forward, yet the phase-only solution itself cannot (by definition) recover this information, as a full amplitude and phase self-calibration would. In this case, the initial solution must be applied while solving for the phase-only solution, then the two solutions combined to form a *cumulative* calibration embodying the net effect of both. In terms of the Measaurement Equation, the net calibration is the *product* of the initial and incremental solutions.
The analog of ``accumulate`` in classic AIPS is the use of CLCAL to combine a series of (incremental) SN calibration tables to form successive (cumulative) CL calibration tables.
Cumulative calibration tables also provide a means of generating carefully interpolated calibration, on variable user-defined timescales, that can be examined prior to application to the data with ``setapply`` and ``correct``. The solutions for different fields and/or spectral windows can be interpolated in different ways, with all solutions stored in the same table.
The only difference between incremental and cumulative calibration tables is that incremental tables are generated directly from the data via ``solve`` or (in the near future) from other ancilliary data (e.g. weather information), and cumulative tables are generated from other cumulative and incremental tables via ``accumulate``. In all other respects (internal format, application to data via ``setapply`` and ``correct``, plotting with ``plotcal``, etc.), they are the same, and therefore interchangable. Thus, ``accumulate`` and cumulative calibration tables need only be used when circumstances require it.
The ``accumulate`` function represents a generalization on the classic AIPS CLCAL model of cumulative calibration in that its application is not limited to accumulation of “G” solutions (SN/CL tables classic AIPS are the analog of “G” (and, implicitly, “T”) in ``aips++``). In principle, any basic calibration type can be accumulated (onto itself), as long as the result of the accumulation (matrix product) is of the same type. This is True of all the basic types, except “D”. Accumulation is currently supported for “B”, “G”, and “T”, and, in future, “F” (ionospheric Faraday rotation), “J” (generic full-polarization calibration), fringe-fitting, and perhaps others. Accumulation of certain specialized types (e.g., “GSPLINE”, “TOPAC”, etc.) onto the basic types will be supported in the near future. The treatment of various calibration from ancilliary data (e.g., system temperatures, weather data, WVR, etc.), as they become available, will also make use of ``accumulate`` to achieve the net calibration.
Note that accumulation only makes sense if treatment of a uniquely incremental solution is required (as described above), or if a careful interpolation or sampling of a solution is desired. In all other cases, re-solving for the type in question will suffice to form the net calibration of that type. For example, the product of an existing “G” solution and an amplitude and phase “G” self-cal (solved with the existing solution applied), is equivalent to full amplitude and phase “G” selfcal (with no prior solution applied), as long as the timescale of this solution is at least as short as that of the existing solution.
Use of ``accumulate`` is straightforward:
The ``tablein`` parameter is used to specify the existing cumulative calibration table to which an incremental table is to be applied. Initially, no such table exists, and ``accumulate`` will generate one from scratch (on-the-fly), using the timescale (in seconds) specified by the parameter ``t``. These nominal solutions will be unit-amplitude, zero-phase (i.e., unit matrix) calibration, ready to be adjusted by accumulation. When ``t`` is negative (the default), the table name specified in ``tablein`` must exist and will be used.
The ``incrtable`` parameter is used to specify the incremental table that should be applied to ``tablein``. The calibration type of ``incrtable`` sets the type assumed in the operation, so ``tablein`` must be of the same type. If it is not, ``accumulate`` will exit with an error message. (Certain combinations of types and subtypes will be supported by accumulate in the future.)
The ``tableout`` parameter is used to specify the name of the output table to write. If un-specified (or ), then ``tablein`` will be overwritten. Use this feature with care, since an error here will require building up the cumulative table from the most recent distinct version (if any).
The ``field`` parameter specifies those field names (standard selection syntax) in ``tablein`` to which the incremental solution should be applied. The solutions for other fields will be passed to ``tableout`` unaltered. If the cumulative table was created from scratch in this run of ``accumulate``, then these solutions will be unit-amplitude, zero-phase, as described above.
The ``calfield`` parameter is used to specify the fields (standard selection syntax) to select from ``incrtable`` to use when applying to ``tablein``. Together, use of ``field`` and ``calfield`` permit completely flexible combinations of calibration accumulation with respect to fields. Multiple runs of ``accumulate`` can be used to generate a single table with many combinations. In future, a “self” mode will be enabled that will simplify the accumulation of field-specific solutions.
The ``interp`` parameter is used to specify the interpolation type to use on the incremental solutions, as in ``setapply``. The currently available interpolation types are “nearest”, “linear”, and “aipslin”. See the ``setapply`` URM documentation for more details.
The ``spwmap`` parameter enables accumulating solutions from differing spectral windows. See ``setapply`` for details on how spwmap works.
Pending improvements:
- Implement a “self” mode (independent of interpolation type), to simplify or eliminate use of the ``field`` and ``calfield`` parameters in some contexts (e.g., self-cal)
- More interpolation modes, e.g., “cubic”, and interpolation timescale (timerange to permit interpolation)
- Handle propogation (or not) of bad/flagged solutions
- Support of specialized types (e.g., TOPAC) onto the basic types
- Smoothing (probably a separate function)
.. rubric:: Parameters
- ``tablein (string='')`` - Input cumulative calibration table name
- ``incrtable (string='')`` - Input incremental calibration table name
- ``tableout (string='')`` - Output cumulative calibration table name. Default is input table name.
- ``field (variant='')`` - List of fields (names) to update in input cumulative table. Default is all.
- ``calfield (variant='')`` - List of fields (names) in incremental table to use. Default is use all.
- ``interp (string='linear')`` - Interpolation mode to use on incremental solutions
- ``t (double=-1.0)`` - Cumulative table timescale when creating from scratch
- ``spwmap (intVec=[-1])`` - Spectral windows to apply
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
cb.open('ap366.sim');
# obtain G solutions from calibrator
cb.selectvis(msselect='FIELD_ID IN [9,11]');
cb.setsolve(type='G',table='cal.G0',t=300);
cb.solve()
# obtain proper flux density scale
cb.fluxscale (tablein='cal.G0', tableout='cal.G1',
reference='1328+307', transfer="0917+624");
# generate cumulative table for target source on 20s timescale
cb.accumulate(tablein='',incrtable='cal.G1',tableout='cal.cG0',
field='0957+561',calfield='0917+624',
interp='linear',t=20);
# apply this calibration to target
cb.selectvis(msselect='FIELD_ID==10');
cb.setapply(type='G',table='cal.cG0',interp='linear')
cb.correct();
# (image target with imager tool)
# phase-selfcal target on 60s timescale
cb.selectvis(msselect='FIELD_ID==10');
cb.setapply(type='G',table='cal.cG0',interp='linear')
cb.setsolve(type='G',table='cal.G2',t=60,phaseonly=T);
cb.solve();
# accumulate new solution onto existing one
cb.accumulate(tablein='cal.cG0',incrtable='cal.G2',tableout='cal.cG1',
field='0957+561',calfield='0957+561',
interp='linear');
# apply new cumulative solution to data
cb.setapply(type='G',table='cal.cG1',interp='linear')
cb.correct();
# (another round of imaging, etc.)
cb.close();
"""
pass
[docs] def activityrec(self):
r"""
This funtion enables returning generic information about recent activity.
Pending improvements:
- ??
"""
pass
[docs] def specifycal(self, caltable='', time='', spw='', antenna='', pol='', caltype='', parameter=[1.0], infile='', uniform=True):
r"""
This function enables specifying calibration parameters externally.
.. rubric:: Parameters
- ``caltable (string='')`` - The calibration table name
- ``time (string='')`` - Calibration timestamp
- ``spw (string='')`` - Calibration spw(s)
- ``antenna (string='')`` - Calibration antenna(s)
- ``pol (string='')`` - Calibration polarization
- ``caltype (string='')`` - Calibration timestamp
- ``parameter (doubleVec=[1.0])`` - Calibration parameters
- ``infile (string='')`` - Ancillary input file
- ``uniform (bool=True)`` - Assume uniform calibration values across the array
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
cb.open('ap366.sim');
(TBD)
cb.close();
"""
pass
[docs] def smooth(self, tablein='', tableout='', field='', smoothtype='mean', smoothtime=60.0):
r"""
This function provides for time-dependent smoothing of sampled calibration solutions. Currently supported types are ’G’, ’B’, and ’T’. (Smoothing on the frequency axis for ’B’ will be supported in the near future.)
Two (sliding) smoothing types are currenlty supported: ’median’ or ’mean’, one of these options should be specified in smoothtype. The full width (in seconds) of the smoothing filter should be specified in smoothtime. Amplitude and (ambiguity-corrected) phase are smoothed separately.
Use field to limit the smoothing operation to a subset of the fields (standard selection syntax) found in the calibration table (other fields will pass to the output table unsmoothed). If field is left blank, all fields in the table will be smoothed.
The smoothing is always done independently for each field, but scan boundaries are not observed. Thus, if the smoothtime is large enough, smoothing may occur over many boundaries.
Flagged solutions in the input table will not participate in the smoothing calculation, but will be replaced with smoothed values if the smoothing window covers one or more unflagged solutions when centered on the flagged point.
Pending improvements:
- Add other smoothtypes?
- Add spw and other selection on input table
- Add A/P toggle
.. rubric:: Parameters
- ``tablein (string='')`` - Input calibration table
- ``tableout (string='')`` - Output calibration table
- ``field (variant='')`` - Limit smoothing to these fields (default is all fields)
- ``smoothtype (string='mean')`` - The smoothing type: 'mean' or 'median'
- ``smoothtime (double=60.0)`` - Smoothing filter time constant (sec)
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
cb.open('ngc5921.ms');
cb.smooth(tablein='in.gcal',tableout='out.gcal',
smoothtype='median',smoothtime=60);
cb.close();
In this example, 'G' solutions for all fields in the table 'in.gcal' are
smoothed using a median filter with a full-width of 60 seconds,
and the result written to 'out.gcal'.
"""
pass
[docs] def rerefant(self, tablein='', tableout='', refantmode='strict', refant=''):
r"""
TBD
Pending improvements:
- TBD
.. rubric:: Parameters
- ``tablein (string='')`` - Input calibration table
- ``tableout (string='')`` - Output calibration table
- ``refantmode (string='strict')`` - The refant application mode
- ``refant (variant='')`` - Reference antenna. Default is none.
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
cb.open('ngc5921.ms');
cb.rerefant(tablein='in.gcal',tableout='out.gcal',
refantmode='median',refant='4')
cb.close();
"""
pass
[docs] def listcal(self, caltable='', field='', antenna='', spw='', listfile='', pagerows=50):
r"""
calibrater.listcal() lists antenna gain solutions in tabular form. The table is organized as follows. Solutions are output by
#. Spectral window,
#. Antenna,
#. Time,
#. Channel,
#. and Polarization.
The inner-most loop is over polarization. A “Spw Header” row is printed each time the spectral window changes. In addition to listing the spectral window ID (SpwID), the Spw Header also lists the date of observation (Date), the calibration table name (CalTable), and the measurement set name (MS name). A lower-level “antenna header” is printed each time the antenna names change or every ‘pagerows’ of output, whichever comes first. The antenna header column are described here:
ll Column Name & Description Ant & Antenna name Time & Visibility timestamp corresponding to gain solution Field & Field name Chn & Channel number Amp & Complex solution amplitude Phs & Complex solution phase F & Flag
Elements of the “F” column contain an ‘F’ when the datum is flagged, and (whitespace) when the datum is not flagged.
Presently, the polarization mode names (for example: R, L) are not given, but the ordering of the polrization modes (left-to-right) is equivalent to the order output by task listobs (see “Feeds” in listobs output).
.. rubric:: Parameters
- ``caltable (string='')`` - Calibration table to list
- ``field (variant='')`` - Field names or indices to list: ''==\>all
- ``antenna (variant='')`` - Antenna/Baseline to list: ''==\>all
- ``spw (variant='')`` - Spectral windows and channels: ''==\>all, spw='10:8~20'
- ``listfile (string='')`` - Send output to file: ''==\>send to terminal)
- ``pagerows (int=50)`` - Rows per page
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
Input:
The following example imports a UVFITS file, performs a bandpass calibration,
and displays a subset of the resulting calibration table.
pathname=os.environ.get('CASAPATH').split()[0] # Get path to CASA home dir
fitsdata=pathname+'/data/demo/NGC5921.fits' # Select uv-data (FITS) file
msdata='NGC5921.ms' # MS name; write to current directory
importuvfits(fitsfile=fitsdata, vis=msdata) # import FITS data to MS
setjy(vis=msdata) # Create model data for flux calibrator
caldata=msdata+'.bcal' # Calibration table name
bandpass(vis=msdata, caltable=caldata) # Bandpass calibration
cb.open(msdata) # Open MS in cb
cb.listcal(caltable=caldata, field='N5921_2, 0, 1', antenna='1~5;10~13;20~22', spw='0:4~6', pagerows=0) # List a subset of calibration factors
Output:
SpwID = 0, Date = 1995/04/13, CalTable = NGC5921.ms.bcal (B Jones), MS name = /users/jcrossle/NRAO/casa/NGC5921.ms
-------------------------------------------------------------------------------------------------------------------------------------------------------
| Ant = 1 | Ant = 2 | Ant = 3 | Ant = 4 |
Time Field Chn| Amp Phs F Amp Phs F| Amp Phs F Amp Phs F| Amp Phs F Amp Phs F| Amp Phs F Amp Phs F|
----------|---------------|---|--------------|--------------|--------------|--------------|--------------|--------------|--------------|--------------|
09:21:46.0 1331+30500002_0 4|0.294 5.3 0.264 3.5 0.296 105.9 0.287 -111.9 0.276 -66.0 0.264 -24.5 0.269 165.8 0.281 -108.6
09:21:46.0 1331+30500002_0 5|0.303 5.3 0.279 0.6 0.305 107.0 0.298 -111.6 0.283 -64.2 0.274 -23.3 0.280 166.8 0.291 -108.9
09:21:46.0 1331+30500002_0 6|0.307 5.6 0.287 -1.6 0.309 107.5 0.303 -111.5 0.287 -63.2 0.280 -22.6 0.284 167.8 0.296 -108.8
10:05:27.9 1445+09900002_0 4|0.467 7.6 0.419 2.7 0.473 107.7 0.455 -112.3 0.437 -63.5 0.413 -24.8 0.427 168.2 0.446 -108.8
10:05:27.9 1445+09900002_0 5|0.472 7.3 0.440 0.0 0.486 109.1 0.471 -111.8 0.451 -62.6 0.436 -23.1 0.435 169.4 0.453 -108.5
10:05:27.9 1445+09900002_0 6|0.486 8.4 0.453 -2.4 0.482 110.0 0.478 -111.4 0.452 -60.7 0.443 -23.1 0.446 169.6 0.468 -108.6
10:09:05.3 N5921_2 4|0.082 50.0 0.074 34.7 0.097 -74.5 0.083 54.4 0.070 131.3 0.080 150.7 0.085 81.0 0.095 150.6
10:09:05.3 N5921_2 5|0.074 62.7 0.084 24.3 0.114 -73.1 0.093 47.3 0.066 119.9 0.069 154.9 0.099 81.2 0.085 147.4
10:09:05.3 N5921_2 6|0.079 44.4 0.081 21.7 0.092 -66.3 0.101 48.0 0.089 125.6 0.060 154.0 0.099 83.1 0.097 152.7
| Ant = 5 | Ant = 10 | Ant = 11 | Ant = 12 |
Time Field Chn| Amp Phs F Amp Phs F| Amp Phs F Amp Phs F| Amp Phs F Amp Phs F| Amp Phs F Amp Phs F|
----------|---------------|---|--------------|--------------|--------------|--------------|--------------|--------------|--------------|--------------|
09:21:46.0 1331+30500002_0 4|0.261 -26.0 0.285 -107.1 0.279 -149.5 0.263 2.9 0.274 -102.5 0.257 -7.0 0.289 174.3 0.309 -139.2
09:21:46.0 1331+30500002_0 5|0.269 -26.1 0.295 -107.2 0.288 -148.8 0.274 2.3 0.283 -100.9 0.271 -6.8 0.307 173.1 0.319 -138.2
09:21:46.0 1331+30500002_0 6|0.272 -26.1 0.300 -107.0 0.293 -148.7 0.281 2.0 0.287 -99.7 0.280 -6.7 0.312 171.2 0.326 -137.2
10:05:27.9 1445+09900002_0 4|0.416 -24.0 0.450 -106.4 0.437 -147.3 0.414 3.2 0.433 -99.6 0.412 -6.8 0.456 175.9 0.477 -140.0
10:05:27.9 1445+09900002_0 5|0.421 -22.6 0.478 -106.1 0.453 -147.4 0.433 2.0 0.453 -98.1 0.433 -6.7 0.481 174.4 0.491 -138.9
10:05:27.9 1445+09900002_0 6|0.436 -22.7 0.478 -106.7 0.459 -146.6 0.443 2.4 0.457 -97.1 0.450 -7.0 0.486 173.5 0.510 -137.7
10:09:05.3 N5921_2 4|0.074 95.0 0.085 -4.2 0.083 109.6 0.084 -116.6 0.081 63.2 0.071 131.2 0.050 -55.4 0.083 -27.4
10:09:05.3 N5921_2 5|0.071 96.8 0.084 -13.7 0.086 104.3 0.100 -116.4 0.099 61.7 0.084 145.1 0.091 -76.1 0.087 -33.6
10:09:05.3 N5921_2 6|0.082 84.9 0.078 -5.3 0.101 109.1 0.102 -109.9 0.087 60.1 0.107 130.4 0.085 -75.5 0.080 -31.2
| Ant = 13 | Ant = 20 | Ant = 21 | Ant = 22 |
Time Field Chn| Amp Phs F Amp Phs F| Amp Phs F Amp Phs F| Amp Phs F Amp Phs F| Amp Phs F Amp Phs F|
----------|---------------|---|--------------|--------------|--------------|--------------|--------------|--------------|--------------|--------------|
09:21:46.0 1331+30500002_0 4|0.285 -169.5 0.277 -90.4 0.254 -36.0 0.290 70.9 0.286 -97.8 0.305 108.8 0.273 -84.6 0.224 -124.2
09:21:46.0 1331+30500002_0 5|0.296 -168.9 0.287 -90.5 0.269 -38.6 0.300 71.0 0.296 -97.8 0.317 108.2 0.284 -85.8 0.243 -127.6
09:21:46.0 1331+30500002_0 6|0.301 -168.7 0.291 -90.3 0.278 -39.9 0.306 70.9 0.302 -97.8 0.326 107.2 0.289 -86.6 0.255 -129.7
10:05:27.9 1445+09900002_0 4|0.448 -167.2 0.434 -90.7 0.401 -34.4 0.456 70.8 0.457 -95.5 0.485 108.9 0.431 -82.1 0.361 -123.9
10:05:27.9 1445+09900002_0 5|0.466 -166.5 0.457 -91.1 0.423 -36.6 0.470 70.8 0.471 -96.6 0.506 108.1 0.448 -83.2 0.393 -126.7
10:05:27.9 1445+09900002_0 6|0.473 -166.9 0.464 -91.1 0.436 -37.8 0.485 70.2 0.476 -96.6 0.521 108.0 0.447 -83.2 0.410 -130.0
10:09:05.3 N5921_2 4|0.097 83.0 0.087 143.5 0.080 43.1 0.094 144.2 0.087 168.7 0.092 1.4 0.111 76.1 0.079 18.9
10:09:05.3 N5921_2 5|0.100 87.4 0.094 137.0 0.061 54.7 0.098 153.3 0.094 178.6 0.096 -3.7 0.101 64.6 0.091 9.5
10:09:05.3 N5921_2 6|0.099 93.3 0.122 140.5 0.077 51.3 0.090 151.7 0.083 -179.6 0.100 2.2 0.095 61.3 0.108 0.4
Listed 108 antenna solutions.
"""
pass
[docs] def posangcal(self, posangcor='', tablein='', tableout=''):
r"""
This function is used to apply position angle calibration for observations made using circularly polarized feeds. According to the Measurement Equation formalism, this correction should be applied to a ``D`` (instrumental polarization) calibration table.
If no ``D`` calibration is performed (and thus no such table is available), the correction can be applied to a ``G`` table, but it should NEVER be applied to both, and always applied to a ``D`` table if one is available. An input table must be specified. If no output table is specified, then the input table will be modified in place.
Specify, as a vector of values, a position angle adjustment (in degrees) for each spectral window. If only one value is specified, it will be duplicated to all spectral windows; otherwise, the number of values specified must match the number of spectral windows. The sign convention for the position angle adjustment is such that the specified value is the that which, when added to the position angle implied by the data, will yield the correct position angle. For example, if ``G-``, ``D-``, and ``P-``\ calibrated data for 3c286 suggests a position angle of 45 degrees, the posangcor value should be -12 degrees as this will yield the correct position angle of 33 degrees when added. In general, posangcor equals correct position angle minus observed position angle.
A future version of this function will have an option to recognize standard position angle calibrators and determine the correction automatically.
(NB: It may be desirable to use solutions for ’X’ to handle position angle calibration, rather than this method.)
.. rubric:: Parameters
- ``posangcor (doubleVec='')`` - Position angle corrections (degrees)
- ``tablein (string='')`` - Input calibration table name
- ``tableout (string='')`` - Output calibration table name. Default is input table name.
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
cb.open('polcal.ms');
cb.posangcal(tablein='3C286.dcal', tableout='3C286.dpacal',
posangcor=[-12.0, 54.0]);
cb.close();
This example takes an existing calibration table containing {\tt D}
Jones matrices, and applies a position angle calibration of 45 and 54
degrees to spectral windows 1 \& 2, respectively, writing the result
to a new table. The observed position angles for 3C286 must have been
45 and -21 degrees; the corrections specified yield the correct value
of 33 degrees when added to the observed values.
"""
pass
[docs] def linpolcor(self, tablein='', tableout='', fields=''):
r"""
THIS METHOD IS CURRENTLY DISABLED.
This function can be used to correct the gains derived from secondary calibrators with unknown or variable polarization. It should only be used for arrays with linear (X/Y) feeds and an Alt-Az mount for which the observed polarization varies with feed position angle on the sky.
The function fits the gains with a sine and cosine term in feed position angle and extracts the Q and U components of the secondary calibrator. This is only possible if there is sufficient range in the position angle (i.e., minimum of about 6 scans spanning at least 90 degrees in position angle). Check the error of the fit to judge if the fit was succesfull, it should generally be smaller than 0.5%.
Use the fields argument to select calibrator fields to be fitted. The function takes a calibration table as input, and can write the adjusted gain solutions to the same table on output, or create a new table containing these results. The function also prints the derived polarization for each field for each spectral window.
.. rubric:: Parameters
- ``tablein (string='')`` - Input calibration table name
- ``tableout (string='')`` - Output calibration table name
- ``fields (stringVec='')`` - Calibrator field names
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
cb.open('atca.ms');
cb.linpolcor(tablein='atca.gcal', tableout='atca.gcal2',
fields='2254-367');
cb.close();
This example takes an existing calibration table containing {\tt G}
Jones matrices, and writes a corrected output table, correcting only
gains derived from 2254-367 for linear polarization.
"""
pass
[docs] def plotcal(self, antennas='', fields='', spwids='', plottype='1/AMP', tablename='', polarization=1, multiplot=False, nx=1, ny=1, psfile=''):
r"""
This function plots a calibration table either to a plotter or to a file.
The argument plottype can take the following values for all types of solutions:
AMP
Gain Amplitude vs. Time
1/AMP
Inverse Gain Amplitude vs. Time (useful for comparing with classic AIPS)
PHASE
Gain Phase vs. Time
RI
Gain Real vs. Imaginary
RLPHASE
Right/Left Gain phase difference (if polarizations are R,L)
XYPHASE
X/Y Gain phase difference (if polarizations are X,Y)
The argument plottype can take the following values for D tables
DAMP
Cross-polarized Gain Amplitude vs. Time
DPHASE
Cross-polarized Gain Phase vs. Time
DRI
Cross-polarized Gain Real vs. Imaginary
The quality of the solutions can be examined with the following plottype choices:
FIT
Fit per spectral window
FITWGT
Fit weight per spectral window
TOTALFIT
Total fit
By default, all antennas (as specified in the antennas argument) will appear on the same plot. Separate plots (all with the same scale) for each antenna can be activated by setting multiplot=T. The multiplot argument only separates plots by antenna (not, e.g., by the field_id(s) specified in the fields argument). If multiplot=T, the nx and ny arguments can be used to specify the number of plots per page.
At the moment, only one polarization can be plotted per execution. This restriction will be relaxed in the near future.
For B solutions, the plotting will loop over timestamps (if more than one).
A hardcopy plot can be created by specifying the ``psfile`` argument (which is especially useful for batch processing when a display screen is not available). This will cause the plot to be written to a PostScript file which can be subsequently sent to a printer.
.. rubric:: Parameters
- ``antennas (intVec='')`` - Antennas to plot. Default is none.
- ``fields (intVec='')`` - Fields to plot. Default is none.
- ``spwids (intVec='')`` - Spectral windows id.'s to plot. Default is none.
- ``plottype (string='1/AMP')`` - Plot type
- ``tablename (string='')`` - Calibration table name
- ``polarization (int=1)`` - Polarization to plot
- ``multiplot (bool=False)`` - Turn on separate antenna plots
- ``nx (int=1)`` - If multiplot=T, number of plots on horizontal axis
- ``ny (int=1)`` - If multiplot=T, number of plots on vertical axis
- ``psfile (string='')`` - Name of output PostScript file to write plot to. Default is to send plot to the screen.
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
cb.open('ngc5921.ms');
cb.plotcal(plottype='PHASE', tablename="gcal", antennas=[1,3], polarization=2);
cb.close();
"""
pass
[docs] def modelfit(self, vary='', niter=0, compshape='P', par=[1.0, 0.0, 0.0], file=''):
r"""
This method fits single-component models (points, elliptical Gaussians or elliptical Disks\_ to the CORRECTED_DATA of the selected field. A first guess for the component parameters may be specified in the par parameter.
.. rubric:: Parameters
- ``vary (boolVec='')`` - If specified where T, let this parameter (in par) vary in fit
- ``niter (int=0)`` - Number of non-linear fitting iterations
- ``compshape (string='P')`` - Component shape, P=point G=gaussian
- ``par (doubleVec=[1.0, 0.0, 0.0])`` - Initial guess for fit parameters (default is for "P)"I flux, rel RA, rel Dec, 1,0, 0.0, 0.0 are defaults
- ``file (string='')`` - If specified, output componentslist file name, if empty don't write componentslist file
.. rubric:: Returns
``doubleVec``
.. rubric:: Examples
::
cb.open('ngc5921.ms');
cb.selectvis(field='1331*')
cb.modelfit(compshape='P',par=[15.0,0.0,0.0])
cb.close();
This example fits a point source mode using 15.0 Jy at the origin (phase center)
as a first guess.
cb.open('ngc5921.ms');
cb.selectvis(field='1331*')
cb.modelfit(compshape='G',par=[15.0,0.0,0.0,2.0,1.0,0.0])
cb.close();
This example fits a Guassian model with a starting
guess of 15 Jy at the phase center (0,0), with 2.0 arcsec major axis,
1.0 axial ratio, at position angle 0.0 deg.
"""
pass
[docs] def createcaltable(self, caltable='', partype='', caltype='', singlechan=''):
r"""
Creates an empty calibration table that can subsequently be filled with by using the table tool.
.. rubric:: Parameters
- ``caltable (string='')`` - Calibration table name
- ``partype (string='')`` - Parameter type name
- ``caltype (string='')`` - Calibration type name
- ``singlechan (bool='')`` - Create a calibration table with frequency-independent parameters?
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
cb.open('ngc5921.ms',F,F,F) # don't add MODEL_DATA, etc.
cb.createcaltable('ngc5921.gcal', 'Complex', 'G Jones', True)
cb.close()
"""
pass
[docs] def updatecaltable(self, caltable=''):
r"""
This method can be used to update a caltable (from v3.4 or later) to the current version of CASA.
The following updates are currently supported.
o At CASA v4.1.0, the OBSERVATION subtable and OBSERVATION_ID column were added to caltables. This method adds trivial versions of these elements to pre-v4.1 caltables.
.. rubric:: Parameters
- ``caltable (string='')`` - Name of the caltable.
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
cb.updatecaltable("mycaltable");
"""
pass
[docs] def close(self):
r"""
Close the ``calibrater`` tool, which is hardly ever necessary.
"""
pass
[docs] def done(self):
r"""
This function is redundant with the close method.
"""
pass
[docs] def parsecallibfile(self, filein=''):
r"""
TBD
.. rubric:: Parameters
- ``filein (string='')`` - Input cal library file name
.. rubric:: Returns
``record``
.. rubric:: Examples
::
TBD
"""
pass
[docs] def setcorrdepflags(self, corrdepflags=''):
r"""
TBD
.. rubric:: Parameters
- ``corrdepflags (bool='')`` - Turn correlation dependent flags on/off (True/False)
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
TBD
"""
pass
[docs] def setvi(self, old=False, quiet=False):
r"""
Use this method to control whether the modern (old=False) or old-style (old=True) VisibilityIterator is used by the calibration application. General users should avoid use of this function unless they understand what this means.
This method will be removed from the calibrater tool in v5.1.
.. rubric:: Parameters
- ``old (bool=False)`` - Use old-style VI, if old=True, else use new VI2
- ``quiet (bool=False)`` - Warn in logger, if quiet=False
.. rubric:: Returns
``bool``
.. rubric:: Examples
::
cb.setvi(True)
cb.open('ngc5921.ms')
"""
pass