phaseshift(vis, outputvis='', keepmms=True, field='', spw='', scan='', intent='', array='', observation='', datacolumn='all', phasecenter='')¶
Rotate a Measurement Set to a new phase-center
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
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).
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.
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 -22.214.171.124’). 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.
# 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 Jupyter notebook in Google Colab (https://colab.research.google.com/github/casangi/casadocs/blob/master/docs/notebooks/phaseshift.ipynb#scrollTo=HjQnMfcFrqM-) 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.
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 fileDefault: none, must be specifiedExample: vis=’ngc5921.ms’
outputvis (string='')- Name of output visibility fileDefault: None, must be specifiedExample: outputvis=’ngc5921_out.ms’
keepmms (bool=True)- Create a Multi-MS as the output if the input is aMulti-MS.Default: TrueOptions: True|FalseBy default it will create a Multi-MS when theinput is a Multi-MS. The output Multi-MS willhave the same partition axis of the inputMMS. See CASA Docs for more information onthe 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 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/channelsDefault: ‘’=all spectral windows and channelsExamples: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 61spw=’0,10,3:3~45’; spw 0,10 all channels, spw3 - chans 3 to 45.spw=’0~2:2~6’; spw 0,1,2 with channels 2through 6 in each.spw = ‘*:3~64’ channels 3 through 64 for all sp id’sspw = ‘ :3~64’ will NOT work.
scan (string='')- Scan number rangeDefault: ‘’ = all
intent (string='')- Select observing intentDefault: ‘’ (no selection by intent)Example: intent=’BANDPASS’ (selects datalabelled with BANDPASS intent)
array (string='')- (Sub)array number rangeDefault: ‘’ (all)
observation (string='')- Select by observation ID(s)Default: ‘’ = allExample: observation=’0~2,4’
datacolumn (string='all')- Which data column(s) to process(case-insensitive).Default: ‘all’ (= whichever of the options thatare 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 absoluteworld coordinates including frame, egphasecenter = ‘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 thefinal image is centered at the new location. Additionally the uvwcoordinates and the the PHASE_DIR column from the FIELD sub-tablewill be changed accordingly.This operation will be done for all selected fields, so all fields in the outputMS will have as center the new location. The new phase center is not constrained tobe located inside any images to be created.