msuvbin

msuvbin(vis, field='', spw='', taql='', outputvis='', phasecenter='', imsize=[100], cell='1arcsec', ncorr=1, nchan=1, start='', width='', wproject=False, memfrac=0.5, mode='bin', flagbackup=False)[source]

grid the visibility data onto a defined uniform grid (in the form of an ms); multiple MS's can be done onto the same grid

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

Parameters

  • vis (string) - Name of input visibility

  • field (string=’’) - field(s) to select

  • spw (string=’’) - Spw selection

  • taql (string=’’) - TaQl string for data selection

  • outputvis (string=’’) - name of output uvgrid

  • phasecenter (string=’’) - phase center of uv grid

  • imsize ({int, intVec}=[100]) - Number of pixels

  • cell (string=’1arcsec’) - pixel cell size defined in sky dimension

  • ncorr (int=1) - number of correlations to store in grid

  • nchan (int=1) - Number of spectral channels in grid

  • start (string=’’) - Frequency of first spectral channel

  • width (string=’’) - spectral channel width

  • wproject (bool=False) - Do wprojection correction while gridding

  • memfrac (double=0.5) - Limit how much of memory to use

  • mode (string=’bin’) - when mode= “write_flags_back”Operation mode (bin/write_back_flags)

    mode = write_flags_back

    • flagbackup (bool=False) - backup flags before saving flags when using write_flags_back

Description

Warning

WARNING: This task is currently experimental.

msuvbin is a uv gridding task. It is primarily designed to be used for large volumes of data from multiple observing epochs that need to be imaged together in order to obtain a final image product for the target source or field of interest. One way of proceeding with such large multi-epoch data is to image each epoch separately and average the images afterward. Instead, msuvbin averages the visibilities on a common uv grid, then the resulting data product can be imaged using the task clean or tclean. Averaging such uv data into a common uv grid first has several conveniences and advantages, such as easily doing the proper weighted average. More details on this task can be found in the EVLA Memo 198, which explains the current implementation in msuvbin and its limitations. In particular, note the issue/limitation of creating a uv grid with wprojection and then using Cotton-Schwab major cycles to image it; see the EVLA Memo 198 for more details.

Parameter descriptions

vis

Name of input visibility file

field

Field name list; note that this position will define the phase center of the output uv grid

spw

Spectral window selection

taql

TaQl expression for data selection (see Data Selection in a Measurement Set or CASAcore NOTE 199: Table Query Language for more information)

outvis

Name of output grid

phasecenter

Phase center of the grid, to be used when the phase center of the selected field is not the desired output phase center. Example: phasecenter=’J2000 18h03m04 -20d00m45.1’

nx

Number of pixels along the x axis of the grid. Default: 1000

ny

Number of pixels along the y axis of the grid. Default: 1000

cell

Cellsize of the grid (given in sky units). Default: ‘1arcsec’

ncorr

Number of correlation/polarization plane in uv grid (allowed 1, 2, 4). For example, if the input data set has the correlations RR and LL, and ncorr =1, then the output uv grid will be written as Stokes I. If ncorr= 2, then the output grid will have both the RR and LL correlations. Default: 1

nchan

Number of spectral channels in the output uv grid. Default: 1

fstart

Frequency of the first channel. Default: ‘1GHz’ (the user needs to give a useful input here)

fstep

Width of spectral channel. Default: ‘1kHz’

wproject

Do wprojection correction while gridding. Default: False

memfrac

Controls how much of computer’s memory is available for gridding. Default=0.5

Examples

Let’s assume we have multi-epoch observations on a particular field of interest with measurement sets vis_1.ms, vis_2.ms, … vis_n.ms. The task msuvbin needs to be executed n times, one for each input data set with all the other parameters that define the output data set intact. For instance, for the 1st execution of msuvbin, one may set the following parameters:

vis = 'vis_1.ms'
 field = '0'
spw = ''
taql = ''
outvis = "uvgrid.ms'
phasecenter = ''
nx = 2048
ny = 2048
cell = '2.0arcsec'
ncorr = 2
nchan = 320
fstart = "1025.00MHz"
fstep = "62.5kHz"
wproject = False
memfrac = 0.9

Here we note the following:

  • Field ‘0’ was selected from the input data, and its position will define the phase center of the output uv grid. If another position is desired for the phase center, then the parameter phasecenter needs to be specified.

  • nx and ny define the number of the pixels along the x and y axes of the grid, respectively. The size of each pixel is defined by the parameter cell. These would be the same values that one would use in the task clean/tclean for imsize and cell to image the output uv grid, and therefore need to be set by taking into account the image that one will eventually be making.

  • ncorr defines the number of the correlations in the output uv grid. If the input data set has the correlations RR and LL, and ncorr is set to 1, then the output uv grid will be written as Stokes I. If ncorr is set to 2, then the output grid will have both the RR and LL correlations.

  • nchan determines the number of channels in the output uv grid with a frequency width per channel set by the parameter fstep. The lowest frequency of the output data is set by the parameter fstart. Note that msuvbin will perform on the fly Doppler correction; the resulting grid will be in the LSRK frame. The fstart value is the starting frequency in the LSRK frame. The above example will produce a uv grid with 320 channels starting at 1025 MHz in LSRK, with each channel having a width of 62.5 kHz.

  • memfrac may be used to set how much memory the task should use. In the above example 90% of the available memory will be utilized by the task.

After gridding the 1st data set, the task msuvbin will need to be executed on the other data sets one at a time by changing the vis parameter only (i.e., vis=’vis_2.ms’, then vis=’vis_3.ms’, etc…) and keeping the other parameters intact. The task msuvbin will perform the proper averaging when gridding the data sets on the same uv grid. The volume of the output data set stays the same regardless of how many measurement sets are added onto the same grid.

Development

No additional development details

Parameter Details

Detailed descriptions of each function parameter

vis (string) - Name of input visibility file (MS)
default: none;
field (string='') - Field selection of input ms; use mssel syntax
spw (string='') - Spw selection; mssel syntax
taql (string='') - TaQl string for data selection; the advance user can do
sophisticated data selection; see http://casacore.github.io/casacore-notes/199.html
outputvis (string='') - name of output uvgrid; if it existant the data will be binned additively into
that uvgrid (as long as the parameters match for the grid description). If the gridded ms
exists
and the gridding parameters do not match the ones with which the grid was made—
msuvbin will exit with an exception
phasecenter (string='') - phase center of uv grid; if empty it will default
the first field selected in the input ms
imsize ({int, intVec}=[100]) - Number of pixels
example:

imsize = [350,250]
imsize = 500 is equivalent to [500,500]

To take proper advantage of internal optimized FFT routines, the
number of pixels must be even and factorizable by 2,3,5 only.
To find the nearest optimal imsize to that desired by the user, please use the following tool method:

from casatools import synthesisutils
su = synthesisutils()
su.getOptimumSize(345)
Output : 360
cell (string='1arcsec') - pixel cell size defined in sky dimension
This should be in the units of sky angle. Usually you want to have a pixel size that
is smaller than the maximum resolution that can be expected from the data.
ncorr (int=1) - number of correlations to store in grid
if 1 is chosen and data have cross hands, then both XX and YY (or RR and LL)
will be gridded on the same correlation plane (XX or RR as MS V2.0 does not support
I as a correlation type).
if 2 is chosen the parallel hands will be stored on independent grids for each frequency channel
if 4 is chosen the all correlation type will be gridded independently.
nchan (int=1) - Nunmber of spectral channels in the output grid
start (string='') - Frequency of first channel of grid. If left empty, it will try to use the
lowest frequency in the selected data
width (string='') - Spectral channel width. If left empty the badwidth of the selected data will be divided by the nchan
selected to determine the width of an output channel. This happens only when not output grid already exists.
wproject (bool=False) - Do wprojection correction while gridding. This should be used with care as it is known to have issues like perfomance
and for Cotton-Schwab style cleaning.
memfrac (double=0.5) - Limit fraction of RAM available to use. Default is half.
mode (string='bin') - when mode will transfer back flag from grid to input ms
For this to work both the original ms and the gridded ms has to exist and the flags will be
transferred from the gridded ms back to original ms. This is provided as a utility to
msuvbinflagger task.
flagbackup (bool=False) - Backup flags before saving flags when using write_flags_back