applycal(vis, field='', spw='', intent='', selectdata=True, timerange='', uvrange='', antenna='', scan='', observation='', msselect='', docallib=False, callib='', gaintable='', gainfield='', interp='', spwmap='', calwt=[True], parang=False, applymode='', flagbackup=True)¶
Apply calibrations solutions(s) to data
vis (path) - Name of input visibility file
field (string=’’) - Select field using field id(s) or field name(s)
spw (string=’’) - Select spectral window/channels
intent (string=’’) - Select observing intent
selectdata (bool=True) - Other data selection parameters
selectdata = True
timerange (string=’’) - Select data based on time range
uvrange (variant=’’) - Select data within uvrange (default units meters)
antenna (string=’’) - Select data based on antenna/baseline
scan (string=’’) - Scan number range
observation (string=’’) - Select by observation ID(s)
msselect (string=’’) - Optional complex data selection (ignore for now)
docallib (bool=False) - Use callib or traditional cal apply parameters
docallib = False
gaintable (pathVec=’’) - Gain calibration table(s) to apply on the fly
gainfield (stringVec=’’) - Select a subset of calibrators from gaintable(s)
interp (stringVec=’’) - Interpolation parameters for each gaintable, as a list
spwmap (intVec=’’) - Spectral windows combinations to form for gaintables(s)
calwt (boolVec=[True]) - Calibrate data weights per gaintable.
docallib = True
callib (string=’’) - Cal Library filename
parang (bool=False) - Apply parallactic angle correction
applymode (string=’’) - Calibration mode: “”=”calflag”,”calflagstrict”,”trial”,”flagonly”,”flagonlystrict”, or “calonly”
flagbackup (bool=True) - Automatically back up the state of flags before the run?
The applycal task reads the specified gain calibration tables, applies them to the (raw) MS DATA column (with the specified selection), and writes the calibrated data into the CORRECTED_DATA column, where imaging or other analysis can find it for further processing. All supplied calibration is applied in one step, according to the Measurement Equation. The existing contents of the CORRECTED_DATA (for the specified selection) will be overwritten.
The applycal task shares the input dataset (‘vis’), data selection and (prior) calibration parameters with the solving tasks; detailed information about setting these parameters can be found the section on “Solving for Calibration”. Several parameters unique to applycal are described below.
In the traditional interface (docallib=False), all calibration tables (both temporal, frequency, polarization calibrations) are specified in the gaintable parameter. The calibration values associated with a restricted list of fields can also be selected for each table in gainfield. As of CASA v4.2, docallib=True provides specification of an ensemble of calibration tables and directives via a cal library file.
After running applycal, the corrected data may be selected, partially (and optionally) averaged, and copied to a new MS using mstransform (formerly split). This may be desirable to reduce the size of the dataset for further processing, if circumstances (e.g., field-of-view) permit. Alternatively, the corrected data may be imaged directly from the original MS.
Calibrated data may be examined in plotms and visstat.
Weight calibration: calwt
Unlike the solving tasks, calibration of the weights is optional in applycal, and is controlled using the calwt parameter. If calwt=True, the weights will be calibrated by all specified caltables that change the data’s scale (phase-like caltables have no effect on the weights). The calwt parameter may also be specified as a list of Booleans, enabling control of which caltables calibrate the weights. In general, it is advisable to calibrate the weights, as this should ensure achieving the full natural sensitivity of the observation. Information about weight calibration conventions can be found here.
Calibration application modes: applymode
The applycal task supports different modes of application via the applymode parameter:
‘calflag’ will apply all flags from a calibration table to the MS and apply the calibration itself to the remaining visibilities (and weights, as per calwt). This is the default.
‘trial’ will only report on the calibration table flags but not manipulate the data or weights.
‘flagonly’ applies the flags but not the calibration itself, leaving the data and weights untouched.
‘calonly’ will apply the calibration to data and weights, but leave the flags untouched.
For the flag-aware options, if ‘strict’ is appended (e.g., ‘calflagstrict’ or ‘flagonlystrict’), applycal will flag all selected data for spws that have no solutions available in any one of the caltables, instead of allowing the to pass uncorrected and unflagged.
Flag control: flagbackup
Since the MS stores only one copy of the flags (in the FLAG column), saving flags prior to applycal is often desirable. Use flagbackup=True for this. The pre-applycal flags will be stored in a separate CASA table named for the MS, with a ‘.flagversions’ suffix. See the flagmanager task to recover old flag versions and otherwise manage the flag information.
Often, it is desirable to calibrate calibrators and science targets in separate runs of applycal, perhaps with different interpolation parameters. First we calibrate the calibrators (fields 0 and 1) using gainfield=’nearest’ for the gain caltable to ensure that each calibrator will be calibrated by solutions obtained from itself. (The bandpass calibration is typically solved from one field but applied to all fields.):
applycal(vis='n5921.ms', field='0,1', # calibrators spw='', # all channels gaintable=['n5921.gcal','n5921.bcal'] # gain and bandpass tables gainfield=['nearest',''], # nearest on sky for gcal interp=['nearest','nearest,linear'], # nearest in time for gcal calwt=True) # calibrate the weights
Next, calibrate the science target with explicit gainfield selection for the gain caltable, and linear interpolation in time:
applycal(vis='n5921.ms', field='2', # science field spw='', # all channels gaintable=['n5921.gcal','n5921.bcal'] # gain and bandpass tables gainfield=['1',''], # field 1 calibrates field 2 for gcal table interp=['linear','nearest,linear'], # linear in time for gcal calwt=True) # calibrate the weights
No additional development details
- Parameter Details
Detailed descriptions of each function parameter
vis (path)- Name of input visibility filedefault: nonExample: vis=’ngc5921.ms’
field (string='')- Select field using field id(s) or field name(s)default: ‘’ –> all fieldsUse ‘go listobs’ to obtain the list id’s ornames. If field string is a non-negative integer,it is assumed a field index, otherwise, it isassumed a field name.Examples:field=’0~2’; field ids 0,1,2field=’0,4,5~7’; field ids 0,4,5,6,7field=’3C286,3C295’; field named 3C286 and3C295field = ‘3,4C*’; field id 3, all namesstarting with 4C
spw (string='')- Select spectral window/channelsExamples:spw=’0~2,4’; spectral windows 0,1,2,4 (allchannels)spw=’<2’; spectral windows less than 2(i.e. 0,1)spw=’0:5~61’; spw 0, channels 5 to 61,INCLUSIVEspw=’*:5~61’; all spw with channels 5 to 61spw=’0,10,3:3~45’; spw 0,10 all channels, spw3, channels 3 to 45.spw=’0~2:2~6’; spw 0,1,2 with channels 2through 6 in each.spw=’0:0~10;15~60’; spectral window 0 withchannels 0-10,15-60. (NOTE ‘;’ to separatechannel selections)spw=’0:0~10^2,1:20~30^5’; spw 0, channels0,2,4,6,8,10, spw 1, channels 20,25,30type ‘help par.selection’ for more examples.
intent (string='')- Select observing intentdefault: ‘’ (no selection by intent)Example: intent=’*BANDPASS*’ (selects datalabelled with BANDPASS intent)
selectdata (bool=True)- Other data selection parametersdefault: True
timerange (string='')- Select data based on time rangeSubparameter of selectdata=Truedefault = ‘’ (all)Examples:timerange =‘YYYY/MM/DD/hh:mm:ss~YYYY/MM/DD/hh:mm:ss’(Note: if YYYY/MM/DD is missing date defaultsto first day in data set.)timerange=’09:14:0~09:54:0’ picks 40 min onfirst daytimerange= ‘25:00:00~27:30:00’ picks 1 hr to 3hr 30min on NEXT daytimerange=’09:44:00’ pick data within oneintegration of timetimerange=’>10:24:00’ data after this time
uvrange (variant='')- Select data within uvrange (default units meters)Subparameter of selectdata=Truedefault: ‘’ (all)Examples:uvrange=’0~1000klambda’; uvrange from 0-1000kilo-lambdauvrange=’>4klambda’;uvranges greater than 4kilolambda
antenna (string='')- Select data based on antenna/baselineSubparameter of selectdata=Truedefault: ‘’ (all)If antenna string is a non-negative integer, itis assumed an antenna index, otherwise, it isassumed as an antenna nameExamples:antenna=’5&6’; baseline between antennaindex 5 and index 6.antenna=’VA05&VA06’; baseline between VLAantenna 5 and 6.antenna=’5&6;7&8’; baselines withindices 5-6 and 7-8antenna=’5’; all baselines with antenna index5antenna=’05’; all baselines with antennanumber 05 (VLA old name)antenna=’5,6,10’; all baselines with antennas5,6,10 index numbers
scan (string='')- Scan number rangeSubparameter of selectdata=Truedefault: ‘’ = all
observation (string='')- Select by observation ID(s)Subparameter of selectdata=Truedefault: ‘’ = allExample: observation=’0~2,4’
msselect (string='')- Optional complex data selection (ignore for now)
docallib (bool=False)- Control means of specifying the caltablesdefault: False –> Use gaintable, gainfield,interp, spwmap, calwt.If True, specify a file containing cal library incallib
callib (string='')- Cal Library filenameSubparameter of callib=TrueIf docallib=True, specify a file containing callibrary directives
gaintable (pathVec='')- Gain calibration table(s) to apply on the flySubparameter of callib=Falsedefault: ‘’ (none)All gain table types: ‘G’, GSPLINE, ‘T’, ‘B’,‘BPOLY’, ‘D’s’ can be applied.Examples: gaintable=’ngc5921.gcal’gaintable=[‘ngc5921.ampcal’,’ngc5921.phcal’]
gainfield (stringVec='')- Select a subset of calibrators from gaintable(s)Subparameter of callib=Falsedefault:’’ –> all sources in tablegaintable=’nearest’ –> nearest (on sky)available field in table. Otherwise, same syntaxas fieldExamples:gainfield=’0~2,5’ means use fields 0,1,2,5from gaintablegainfield=[‘0~3’,’4~6’] (for multiplegaintables)
interp (stringVec='')- Interpolation parmameters (in time[,freq]) for each gaintable, as a list of strings.Default: ‘’ –> ‘linear,linear’ for all gaintable(s)Options: Time: ‘nearest’, ‘linear’Freq: ‘nearest’, ‘linear’, ‘cubic’,‘spline’Specify a list of strings, aligned with the list of caltable specifiedin gaintable, that contain the required interpolation parametersfor each caltable.- When frequency interpolation is relevant (B, Df,Xf), separate time-dependent and freq-dependentinterp types with a comma (freq after thecomma).- Specifications for frequency are ignored when thecalibration table has no channel-dependence.- Time-dependent interp options ending in ‘PD’enable a “phase delay” correction per spw fornon-channel-dependent calibration types.- For multi-obsId datasets, ‘perobs’ can beappended to the time-dependent interpolationspecification to enforce obsId boundaries wheninterpolating in time.- Freq-dependent interp options can have ‘flag’ appendedto enforce channel-dependent flagging, and/or ‘rel’appended to invoke relative frequency interpolationExamples:interp=’nearest’ (in time, freq-dep will belinear, if relevant)interp=’linear,cubic’ (linear in time, cubicin freq)interp=’linearperobs,splineflag’ (linear intime per obsId, spline in freq withchannelized flagging)interp=’nearest,linearflagrel’ (nearest intime, linear in freq with with channelizedflagging and relative-frequency interpolation)interp=’,spline’ (spline in freq; linear intime by default)interp=[‘nearest,spline’,’linear’] (formultiple gaintables)
spwmap (intVec='')- Spectral windows combinations to form for gaintables(s)Subparameter of callib=Falsedefault:  (apply solutions from each spw tothat spw only)Examples:spwmap=[0,0,1,1] means apply the caltablesolutions from spw = 0 to the spw 0,1 and spw1 to spw 2,3.spwmap=[[0,0,1,1],[0,1,0,1]] (for multiplegaintables)
calwt (boolVec=[True])- Calibrate data weights per gaintable.default: True (for all specified gaintables)Examples:calwt=False (for all specified gaintables)calwt=[True,False,True] (specified pergaintable)
parang (bool=False)- Apply parallactic angle correctiondefault: FalseIf True, apply the parallactic anglecorrection. FOR ANY POLARIZATION CALIBRATION ANDIMAGING, parang = True
applymode (string='')- Calibration apply modedefault: ‘calflag’Options: “calflag”, “calflagstrict”, “trial”,“flagonly”, “flagonlystrict”, “calonly”– applymode=’calflag’: calibrate data and applyflags from solutions– applymode=’trial’: report on flags fromsolutions, dataset entirely unchanged– applymode=’flagonly’: apply flags fromsolutions only, data not calibrated– applymode=’calonly’ calibrate data only, flagsfrom solutions NOT applied (use with extremecaution!)– applymode=’calflagstrict’ or ‘flagonlystrict’same as above except flag spws for whichcalibration is unavailable in one or more tables(instead of allowing them to pass uncalibratedand unflagged)
flagbackup (bool=True)- Automatically back up the state of flags before the run?default: True