#
# stub function definition file for docstring parsing
#
[docs]def 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):
r"""
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)
.. raw:: html
<details><summary><i> mode = write_flags_back </i></summary>
- flagbackup_ (bool=False) - backup flags before saving flags when using write_flags_back
.. raw:: html
</details>
.. _Description:
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 <https://library.nrao.edu/public/memos/evla/EVLAM_198.pdf>`__, 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.
.. rubric:: 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 <../../notebooks/visibility_data_selection.ipynb>`__ or `CASAcore NOTE
199: Table Query
Language <https://casacore.github.io/casacore-notes/199.html>`__ 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:
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:
Development
No additional development details
.. _Details:
Parameter Details
Detailed descriptions of each function parameter
.. _vis:
| ``vis (string)`` - Name of input visibility file (MS)
| default: none;
.. _field:
| ``field (string='')`` - Field selection of input ms; use mssel syntax
.. _spw:
| ``spw (string='')`` - Spw selection; mssel syntax
.. _taql:
| ``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:
| ``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:
| ``phasecenter (string='')`` - phase center of uv grid; if empty it will default
| the first field selected in the input ms
.. _imsize:
| ``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:
| ``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:
| ``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:
| ``nchan (int=1)`` - Nunmber of spectral channels in the output grid
.. _start:
| ``start (string='')`` - Frequency of first channel of grid. If left empty, it will try to use the
| lowest frequency in the selected data
.. _width:
| ``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:
| ``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:
| ``memfrac (double=0.5)`` - Limit fraction of RAM available to use. Default is half.
.. _mode:
| ``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:
| ``flagbackup (bool=False)`` - Backup flags before saving flags when using write_flags_back
"""
pass