phaseshift

phaseshift(vis, outputvis='', keepmms=True, field='', spw='', scan='', intent='', array='', observation='', datacolumn='all', phasecenter='')

Rotate a Measurement Set to a new phase-center

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

Parameters

• vis (path) - Name of input visibility file

• outputvis (string=’’) - Name of output visibility file

• keepmms (bool=True) - Create a Multi-MS as the output if the input is a Multi-MS.

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

• spw (string=’’) - Select spectral window/channels

• scan (string=’’) - Scan number range

• intent (string=’’) - Select observing intent

• array (string=’’) - Select (sub)array(s) by array ID number.

• observation (string=’’) - Select by observation ID(s)

• datacolumn (string=’all’) - Which data column(s) to process

• phasecenter (string=’’) - Direction coordinates of the desired center. MUST BE SPECIFIED

Description

This task changes the phase center of an MS by modifying the UVW coordinates and the specified data column(s) (via the datacolumn parameter) of the input MS and creating an output MS with these changes. The PHASE_DIR column of the FIELD subtable of the new MS is updated with the new phase center. Many MS selection parameters are supported (see Visibility Data Selections for details).

Danger

ALERT: Partial spectral window selection via the spw parameter (eg, spw=’1:20~25’) may cause errors. This issue is being investigated and will be fixed in a subsequent version of CASA. As a workaround, if you require such a selection, first specify it in and run split to create the desired selection and use the resulting MS as input to phaseshift.

Danger

ALERT: If you intend to move the phasecenter far enough away from the antenna pointing center, please be aware that the pointing table needs to exist in the MS, for the imaging tasks to know the world coordinates at which to center primary beams. If a pointing table does not already exist, please consider simply using tclean(phasecenter=’’) for on-the-fly phase rotation if the intention is to anyway run imaging soon after phaseshift, as this on-the-fly operation will still use the original (unmodified) phase/pointing center and primary beams will be correctly located.

The input MS is not modified, and so the outvis parameter must be specified; note that this behavior is different from that of task fixvis. The implementation assumes that the UVW coordinates are correct in the frame in which they are specified; these coordinates are transformed via rotation to the new phase center. No attempt is made to recompute the UVW values because of, eg, antenna position changes (please see the Development section for more details),

The new phase center is specified via the phasecenter parameter. The standard syntax for specifying astronomical world direction coordinates is supported (e.g. ‘J2000 19h45m20.56 -50d30m45.7’ or ‘J2000 19:45:20.56 -50.30.45.7’). Coordinate systems that are time dependent are not supported, such as topocentric or geodetic systems (e.g. azimuth-elevation). Ephemeris objects are likewise not supported.

The phaseshift application uses a similar algorithm as tclean (via its phasecenter parameter) for phase center shifting. However, these two applications use a signficantly different algorithm than plotms does for phase shifting, so results, particularly for larger shifts, are likely to diverge for plotms and phaseshift/tclean.

Examples

# shift the phase center to J2000 04:52:16 -02.04.55
# note that any valid direction syntax is supported, including
# FRAME XXhXXmXX.Xs YYdYYmYY.Ys
# FRAME XX.XXdeg YY.YYdeg
# FRAME XX.XXrad YY.YYrad
# the longitude-like and latitude-like coordinates can have different syntaxes, eg
# FRAME XXhXXmXX.Xs YY.YYrad
phaseshift(
    vis='unshifted.ms', outvis='shifted.ms',
    phasecenter='J2000 04:52:16 -02.04.55'
)

There is a Community Examples Notebook in CASA Docs describing in detail the numerical characterization of phaseshift, which provides a complete script and detailed results regarding the correctness of the results produced by phaseshift. In summary, in a 1.0 GHz VLA simulation in which the phase center and a source were initially separated by 2.7 degrees, using phaseshift to shift the phase center to be coincident with the source resulted in the source being located less than 30 marcsec (0.003 pixels) from the simulated position. In a 150 GHz ALMA simulation in which the phase center and a source were initially separated by 1.2 arcmin, using phaseshift to shift the phase center to be coincident with the source resulting in the source being located less than 90 μ arcsec (0.001 pixels) from the simulated position.

Development

• Support for time-dependent coordinate frames and ephemeris objects is planned for ngCASA only. However, if greatly desired, requests for such support will be considered prior to that. Please send us a request via the Help Desk should you have such a need.

• Specifying the new phase center in terms of an offset from the original phase center is currently not supported. However, if there is a need for such support, it can be added. Please send us a request via the Help Desk should you have such a need.

• There is currently no support for the possible use case of updating only the UVW values (eg, based on antenna position updates), but not the associated data values. The deprecated task fixvis has this functionality, so it may be used for this purpose. If such support will be needed after fixvis is removed, it can be added. Please send us a request via the Help Desk should you have such a need.

Parameter Details

Detailed descriptions of each function parameter

vis (path) - Name of input visibility file

Default: none, must be specified

Example: vis=’ngc5921.ms’

outputvis (string='') - Name of output visibility file

Default: None, must be specified

Example: outputvis=’ngc5921_out.ms’

keepmms (bool=True) - Create a Multi-MS as the output if the input is a

Multi-MS.

Default: True

Options: True|False

By default it will create a Multi-MS when the

input is a Multi-MS. The output Multi-MS will

have the same partition axis of the input

MMS. See CASA Docs for more information on

the MMS format.

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

Default: ‘’=all spectral windows and 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

spw=’0,10,3:3~45’; spw 0,10 all channels, spw

3 - chans 3 to 45.

spw=’0~2:2~6’; spw 0,1,2 with channels 2

through 6 in each.

spw = ‘*:3~64’ channels 3 through 64 for all sp id’s

spw = ‘ :3~64’ will NOT work.

scan (string='') - Scan number range

Default: ‘’ = all

intent (string='') - Select observing intent

Default: ‘’ (no selection by intent)

Example: intent=’BANDPASS’ (selects data

labelled with BANDPASS intent)

array (string='') - (Sub)array number range

Default: ‘’ (all)

observation (string='') - Select by observation ID(s)

Default: ‘’ = all

Example: observation=’0~2,4’

datacolumn (string='all') - Which data column(s) to process

(case-insensitive).

Default: ‘all’ (= whichever of the options that

are present)

Options: ‘data’, ‘model’, ‘corrected’,

‘all’,’float_data’, ‘lag_data’,

‘float_data,data’, ‘lag_data,data’

Example: datacolumn=’data’

phasecenter (string='') - Direction coordinates of new phase center, specified as absolute

world coordinates including frame, eg

phasecenter = ‘J2000 19h53m50 40d06m00’

phasecenter = ‘B1950 292.5deg -40.0deg’

phasecenter = ‘ICRS 13:05:27.2780 -049.28.04.458’

phasecenter = ‘GALACTIC 47.5rad -60.22rad’

Time dependent systems (eg, AZEL) are not supported, nor are ephemeris objects.

This will change the phase of the baseline visibilities so that the

final image is centered at the new location. Additionally the uvw

coordinates and the the PHASE_DIR column from the FIELD sub-table

will be changed accordingly.

This operation will be done for all selected fields, so all fields in the output

MS will have as center the new location. The new phase center is not constrained to

be located inside any images to be created.