applycal

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)[source]

Apply calibrations solutions(s) to data

[Description] [Examples] [Development] [Details]

Parameters

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, int}=’’) - 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 (any=’’) - 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?

Description

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.

Examples

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

Development: No additional development details

Parameter Details: Detailed descriptions of each function parameter

vis (path) - Name of input visibility file

default: non

Example: vis=’ngc5921.ms’

field (string='') - Select field using field id(s) or field name(s)

default: ‘’ –> all fields

Use ‘go listobs’ to obtain the list id’s or
names. If field string is a non-negative integer,
it is assumed a field index,  otherwise, it is
assumed a field name.
Examples:
field=’0~2’; field ids 0,1,2
field=’0,4,5~7’; field ids 0,4,5,6,7
field=’3C286,3C295’; field named 3C286 and
3C295
field = ‘3,4C*’; field id 3, all names
starting with 4C

spw (string='') - Select spectral window/channels

Examples:
spw=’0~2,4’; spectral windows 0,1,2,4 (all
channels)
spw=’<2’;  spectral windows less than 2
(i.e. 0,1)
spw=’0:5~61’; spw 0, channels 5 to 61,
INCLUSIVE
spw=’*:5~61’; all spw with channels 5 to 61
spw=’0,10,3:3~45’; spw 0,10 all channels, spw
3, channels 3 to 45.
spw=’0~2:2~6’; spw 0,1,2 with channels 2
through 6 in each.
spw=’0:0~10;15~60’; spectral window 0 with
channels 0-10,15-60. (NOTE ‘;’ to separate
channel selections)
spw=’0:0~10^2,1:20~30^5’; spw 0, channels
0,2,4,6,8,10, spw 1, channels 20,25,30 
type ‘help par.selection’ for more examples.

intent (string='') - Select observing intent

default: ‘’ (no selection by intent)

Example: intent=’*BANDPASS*’ (selects data

labelled with BANDPASS intent)

selectdata (bool=True) - Other data selection parameters

default: True

timerange (string='') - Select data based on time range

Subparameter of selectdata=True

default = ‘’ (all)

Examples:
timerange =
‘YYYY/MM/DD/hh:mm:ss~YYYY/MM/DD/hh:mm:ss’
(Note: if YYYY/MM/DD is missing date defaults
to first day in data set.)
timerange=’09:14:0~09:54:0’ picks 40 min on
first day 
timerange= ‘25:00:00~27:30:00’ picks 1 hr to 3
hr 30min on NEXT day
timerange=’09:44:00’ pick data within one
integration of time
timerange=’>10:24:00’ data after this time

uvrange (variant='') - Select data within uvrange (default units meters)

Subparameter of selectdata=True

default: ‘’ (all)

Examples:
uvrange=’0~1000klambda’; uvrange from 0-1000
kilo-lambda
uvrange=’>4klambda’;uvranges greater than 4
kilolambda

antenna (string='') - Select data based on antenna/baseline

Subparameter of selectdata=True
default: ‘’ (all)
If antenna string is a non-negative integer, it
is assumed an antenna index, otherwise, it is
assumed as an antenna name

Examples: 
antenna=’5&6’; baseline between antenna
index 5 and index 6.
antenna=’VA05&VA06’; baseline between VLA
antenna 5 and 6.
antenna=’5&6;7&8’; baselines with
indices 5-6 and 7-8
antenna=’5’; all baselines with antenna index
5
antenna=’05’; all baselines with antenna
number 05 (VLA old name)
antenna=’5,6,10’; all baselines with antennas
5,6,10 index numbers

scan (string='') - Scan number range

Subparameter of selectdata=True

default: ‘’ = all

observation ({string, int}='') - Select by observation ID(s)

Subparameter of selectdata=True

default: ‘’ = all

Example: observation=’0~2,4’

msselect (string='') - Optional complex data selection (ignore for now)

docallib (bool=False) - Control means of specifying the caltables

default: False –> Use gaintable, gainfield,
interp, spwmap, calwt. 
If True, specify a file containing cal library in
callib

callib (string='') - Cal Library filename

Subparameter of callib=True
If docallib=True, specify a file containing cal
library directives

gaintable (pathVec='') - Gain calibration table(s) to apply on the fly

Subparameter of callib=False

default: ‘’ (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=False
default:’’ –> all sources in table

gaintable=’nearest’ –> nearest (on sky)
available field in table. Otherwise, same syntax
as field
Examples: 
gainfield=’0~2,5’ means use fields 0,1,2,5
from gaintable
gainfield=[‘0~3’,’4~6’] (for multiple
gaintables)

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 specified

in gaintable, that contain the required interpolation parameters

for each caltable.

- When frequency interpolation is relevant (B, Df,

Xf), separate time-dependent and freq-dependent
interp types with a comma (freq after the
comma). 

- Specifications for frequency are ignored when the

calibration table has no channel-dependence.

- Time-dependent interp options ending in ‘PD’

enable a “phase delay” correction per spw for

non-channel-dependent calibration types.

- For multi-obsId datasets, ‘perobs’ can be

appended to the time-dependent interpolation
specification to enforce obsId boundaries when
interpolating in time. 

- For multi-scan datasets, ‘perscan’ can be

appended to the time-dependent interpolation
specification to enforce scan boundaries when
interpolating in time. 

- Freq-dependent interp options can have ‘flag’ appended

to enforce channel-dependent flagging, and/or ‘rel’

appended to invoke relative frequency interpolation

Examples: 
interp=’nearest’ (in time, freq-dep will be
linear, if relevant)
interp=’linear,cubic’  (linear in time, cubic
in freq)
interp=’linearperobs,splineflag’ (linear in
time per obsId, spline in freq with
channelized flagging)
interp=’nearest,linearflagrel’ (nearest in
time, linear in freq with with channelized 
flagging and relative-frequency interpolation)
interp=’,spline’  (spline in freq; linear in
time by default)
interp=[‘nearest,spline’,’linear’]  (for
multiple gaintables)

spwmap (any='') - Spectral windows combinations to form for gaintables(s)

Subparameter of callib=False

default: [] (apply solutions from each spw to

that spw only)

Examples:
spwmap=[0,0,1,1] means apply the caltable
solutions from spw = 0 to the spw 0,1 and spw
1 to spw 2,3.
spwmap=[[0,0,1,1],[0,1,0,1]] (for multiple
gaintables)

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 per
gaintable)

parang (bool=False) - Apply parallactic angle correction

default: False
If True, apply the parallactic angle
correction. FOR ANY POLARIZATION CALIBRATION AND
IMAGING, parang = True

applymode (string='') - Calibration apply mode

default: ‘calflag’ 
Options: “calflag”, “calflagstrict”, “trial”,
“flagonly”, “flagonlystrict”, “calonly”
– applymode=’calflag’: calibrate data and apply
flags from solutions
– applymode=’trial’: report on flags from
solutions, dataset entirely unchanged
– applymode=’flagonly’: apply flags from
solutions only, data not calibrated
– applymode=’calonly’ calibrate data only, flags
from solutions NOT applied (use with extreme
caution!)
– applymode=’calflagstrict’ or ‘flagonlystrict’
same as above except flag spws for which
calibration is unavailable in one or more tables
(instead of allowing them to pass uncalibrated
and unflagged)

flagbackup (bool=True) - Automatically back up the state of flags before the run?

default: True