cvel2
- cvel2(vis, outputvis='', keepmms=True, passall=False, field='', spw='', scan='', antenna='', correlation='', timerange='', intent='', array='', uvrange='', observation='', feed='', datacolumn='all', mode='channel', nchan=-1, start='0', width='1', interpolation='linear', phasecenter='', restfreq='', outframe='', veltype='radio', hanning=False)[source]
Regrid an MS or MMS to a new spectral window, channel structure or frame
[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, stringVec, int, intVec}=’’) - Select field using field id(s) or field name(s)
spw ({string, stringVec, int, intVec}=’’) - Select spectral window/channels
scan ({string, stringVec, int, intVec}=’’) - Scan number range
antenna ({string, stringVec, int, intVec}=’’) - Select data based on antenna/baseline
correlation ({string, stringVec}=’’) - Select data based on correlation
timerange ({string, stringVec, int, intVec}=’’) - Select data based on time range
intent ({string, stringVec, int, intVec}=’’) - Select observing intent
array ({string, stringVec, int, intVec}=’’) - Select (sub)array(s) by array ID number.
uvrange ({string, stringVec, int, intVec}=’’) - Select data by baseline length.
observation ({string, stringVec, int, intVec}=’’) - Select by observation ID(s)
feed ({string, stringVec, int, intVec}=’’) - Multi-feed numbers: Not yet implemented.
datacolumn (string=’all’) - Data column(s) to process.
mode (string=’channel’) - Regridding mode (channel/velocity/frequency/channel_b).
mode = channel
nchan (int=-1) - Number of channels in the output spw
start (variant=’0’) - First input channel to use
width (variant=’1’) - Channel width of the output visibilities.
interpolation (string=’linear’) - Spectral interpolation method
mode = channel_b
nchan (int=-1) - Number of channels in the output spw
start (variant=’0’) - First input channel to use
width (variant=’1’) - Channel width of the output visibilities.
interpolation (string=’linear’) - Spectral interpolation method
mode = velocity
nchan (int=-1) - Number of channels in the output spw
start (variant=’0’) - First input channel to use
width (variant=’1’) - Channel width of the output visibilities.
interpolation (string=’linear’) - Spectral interpolation method
mode = frequency
nchan (int=-1) - Number of channels in the output spw
start (variant=’0’) - First input channel to use
width (variant=’1’) - Channel width of the output visibilities.
interpolation (string=’linear’) - Spectral interpolation method
phasecenter (variant=’’) - Phase center direction to be used for the spectral coordinate transformation: direction measure or field index
restfreq (string=’’) - Rest frequency to use for output.
outframe (string=’’) - Output reference frame.
veltype (string=’radio’) - Velocity definition.
hanning (bool=False) - Hanning smooth data to remove Gibbs ringing.
- Description
Warning
ALERT: cvel2 is currently an experimental task and will replace the current cvel in the near future. We will then remove current cvel and rename cvel2 to cvel.
The intent of cvel2 is to transform channel labels and the visibilities to a spectral reference frame which is appropriate for the science analysis, e.g. from TOPO to LSRK to correct for Doppler shifts throughout the time of the observation. cvel2 is based on mstransform.
VLA and ALMA datasets are observed in TOPOcentric velocity frames with fixed sky frequencies that are calculated from the observatory velocity at the start of the observation, and kept throughout (Doppler setting). The data will need to be regridded to a constant velocity grid to avoid a smearing of spectral features (e.g. to the LSRK or BARYcentric velocity frames). cvel2 can perform this operation. Naturally, the transformation of channel labels and visibilities into a different reference frame will change the shape of the spectral feature to some extent. According to the Nyquist theorem you should oversample a spectrum with twice the numbers of channels to retain the shape. We advise that for spectral regridding to a standard velocity system like LSRK or BARY the expected spectral features are oversampled at least by a factor of 3-4 of the linewidth to preserve the spectral shape and to minimize regridding artifacts.
cvel2 is in fact a more general tasks that transforms visibilities between spectral frames for visibilities. Doppler correction is also applied during imaging with tclean, which is recommended for most cases. cvel2 is still useful if the MS itself needs to be stored in a specific frame, e.g. for self-calibration on fixed velocity channels. An MS that was regridded using cvel2 can be imaged in channel mode in tclean (although tclean will perform some internal regridding anyways).
Gridding modes and parameters
cvel2 offers four gridding mode s: ‘channel’, ‘velocity’, ‘frequency’, and ‘channel_b’. All of the modes have the same four subparameters nchan, start, width, and interpolation. nchan is the number of channels for all modes. The meaning and units of the parameters start and width depend on the gridding mode used:
For the modes ‘channel’ and ‘channel_b’, start is the input starting channel, and width the number of input channels to be merged into a single output channel.
In velocity and frequency mode, start defines the first channel of the output grid and width the width of each channel in the output in velocity or frequency units, respectively.
Negative width numbers run the channel sequence in the opposite direction.
The difference between ‘channel’ and ‘channel_b’ is that ‘channel’ forces the output to be on an equidistant grid based on first selected channel, whereas ‘channel_b’ does not (which improves the speed of cvel2). Mode ‘velocity’ also requires the specification of a rest frequency (restfreq parameter, and definition type (’radio’ or ‘optical’) in the veltype parameter.
interpolation specifies the interpolation method between the spectral channels. The interpolation method ‘fftshift’ calculates the transformed visibilities by applying a FFT, then a phase ramp, and then an inverse FFT. It will also perform pre-averaging, if necessary for the output grid (this will also increase the S/N). Note that if you want to use this interpolation method, your frequency grid needs to be equidistant, i.e. it only works in mode velocity with veltype=’radio’, in mode ‘frequency’, and in mode ‘channel’ (in the latter only if the input grid is itself equidistant in frequency). Note also that, as opposed to all other interpolation methods, this method will apply a constant (frequency independent) shift in frequency which is not fully correct in the case of large fractional bandwidth of the given spectral window
The phasecenter parameter can be used to specify the field id or position that is used for the transformations. This can be useful for larger mosaics.
Hanning smoothing is optionally offered in cvel2, but tests have shown that already the regridding process itself, if it involved a transformation from TOPO to a non-terrestrial reference frame, implies some smoothing (due to channel interpolation) such that Hanning smoothing may not be necessary.
If cvel2 has already established the grid that is desired for the imaging, tclean should be run with exactly the same frequency/velocity parameters as used in cvel2 in order to avoid additional regridding in clean.
Multi-MS support
The option keepmms is set by default. This implies that unless the value of keepmms is explicitly changed to False, cvel2 will create a Multi-MS when the input is a Multi-MS. The output Multi-MS will keep the same partition axis of the input MMS. See the task partition for more information on the Multi-MS (MMS) format. NOTE: It is not possible to combine the spws if the input MMS was partitioned with separationaxis=’spw’. In this case, the task will abort with an error.
cvel and cvel2
cvel2 replicates the functionality of cvel, although the following differences should be noted:
The regridding calculations of cvel2 have been modified in order to better align it with the regridding calculations of tclean. Also, cvel2 will not perform a pre-average step automatically when the width of the output channels is more than twice the widtch of the input channels.
cvel2 also supports Multi-MS input, in which case it will create an output Multi-MS too.
The parameter passall is not supported in cvel2. The user may achieve the same results of passall=True by splitting out the data that will not be regridded with cvel2 and concatenate regridded and non-regridded sets at the end. In the case of Multi-MS input, the user should use virtualconcat to achieve a concatenated MMS.
cvel2 is based on and implemented in terms of the very general mstransform framework
- Examples
Example 1:
Regrid a MeasurementSet ‘myMS.ms’ to a new ‘myMSregridded.ms’, using velocity mode and a LSRK radio velocity definition. The output width is given in velocity units. The output data has a structure of 10 channels, starting at 123 km/s with a width of 0.1km/s. We use the HI rest frequency of 1.420405 GHz.
cvel2(vis='myMS.ms', outputvis='myMSregriddedVelMode.ms', outframe='LSRK', mode='velocity', veltype='radio', restfreq='1.420405GHz', nchan=10, start='123km/s', width='0.1km/s')
Example 2:
Regrid the same MS, but this time using channel mode. We start at channel 5, and create 10 new output channels, grouping 7 channels in the new bins. The output width is given in units of number of input channels. We also run the output MeasurementSet in reverse spectral order (note the negative value of width). This time we request a BARYcentric frame and use the interpolation method ‘fftshift’.
cvel2(vis='myMS.ms', outputvis='myMSregriddedChannelMode.ms', outframe='BARY', mode='channel', nchan=10, start=5, width=-7, interpolation='fftshift')
- Development
No additional development details
- Parameter Details
Detailed descriptions of each function parameter
vis (path)
- Name of input visibility fileDefault: noneExample: vis=’ngc5921.ms’outputvis (string='')
- Name of output visibility file or Multi-MSDefault: noneExample: vis=’ngc5921_out.ms’keepmms (bool=True)
- If the input is a Multi-MS the output will also be aMulti-MS.Default: TrueBy 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 ‘help partition’ for more information onthe MMS format.NOTE: It is not possible to combine the spws ifthe input MMS was partitioned withseparationaxis=’spw’. In this case, the task willabort with an error.passall (bool=False)
- HIDDEN parameter. Pass through (write to output MS) non-selected data with no changefield ({string, stringVec, int, intVec}='')
- 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 4Cspw ({string, stringVec, int, intVec}='')
- 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.NOTE: mstransform does not support multiplechannel ranges per spectral window.scan ({string, stringVec, int, intVec}='')
- Scan number rangeSubparameter of selectdata=Truedefault: ‘’ = allantenna ({string, stringVec, int, intVec}='')
- Select data based on antenna/baselineSubparameter of selectdata=Truedefault: ‘’ (all)If antenna string is a non-negative integer, itis assumed an antenna index, otherwise, it isassumed as an antenna nameExamples:antenna=’5&6’; baseline between antennaindex 5 and index 6.antenna=’VA05&VA06’; baseline between VLAantenna 5 and 6.antenna=’5&6;7&8’; baselines withindices 5-6 and 7-8antenna=’5’; all baselines with antenna index5antenna=’05’; all baselines with antennanumber 05 (VLA old name)antenna=’5,6,10’; all baselines with antennas5,6,10 index numbersantenna=’!ea03,ea12,ea17’: all baselinesexcept those that include EVLA antennas ea03,ea12, or ea17.correlation ({string, stringVec}='')
- Select data based on correlationDefault: ‘’ (all)Example: correlation=’XX,YY’.timerange ({string, stringVec, int, intVec}='')
- Select data based on time rangeSubparameter of selectdata=TrueDefault = ‘’ (all)Examples:timerange =‘YYYY/MM/DD/hh:mm:ss~YYYY/MM/DD/hh:mm:ss’(Note: if YYYY/MM/DD is missing date defaultsto first day in data set.)timerange=’09:14:0~09:54:0’ picks 40 min onfirst daytimerange= ‘25:00:00~27:30:00’ picks 1 hr to 3hr 30min on NEXT daytimerange=’09:44:00’ pick data within oneintegration of timetimerange=’>10:24:00’ data after this timeintent ({string, stringVec, int, intVec}='')
- Select observing intentDefault: ‘’ (no selection by intent)Example: intent=’BANDPASS’ (selects datalabelled with BANDPASS intent)array ({string, stringVec, int, intVec}='')
- Select (sub)array(s) by array ID number.Default = ‘’ (all)uvrange ({string, stringVec, int, intVec}='')
- Select data by baseline length.observation ({string, stringVec, int, intVec}='')
- Select by observation ID(s)Subparameter of selectdata=TrueDefault: ‘’ = allExample: observation=’0~2,4’feed ({string, stringVec, int, intVec}='')
- Multi-feed numbers: Not yet implemented.datacolumn (string='all')
- Which data column(s) to process.mode (string='channel')
- Regridding mode (channel/velocity/frequency/channel_b).Default: ‘channel’Options: ‘channel’, ‘velocity’, ‘frequency’,‘channel_b’* mode = ‘channel’; Use with nchan, start, width tospecify output spw. Produces equidistant gridbased on first selected channel.* mode = ‘velocity’, means channels are specifiedin velocity.* mode = ‘frequency’, means channels are specifiedin frequency.* mode = ‘channel_b’, alternative ‘channel’mode. Does not force an equidistant grid. Faster.Examples:spw = ‘0,1’; mode = ‘channel’ will produce asingle spw containing all channels in spw 0and 1spw=’0:5~28^2’; mode = ‘channel’ will producea single spw made with channels(5,7,9,…,25,27)spw = ‘0’; mode = ‘channel’: nchan=3; start=5;width=4 will produce an spw with 3 outputchannels- new channel 1 contains data from channels(5+6+7+8)- new channel 2 contains data from channels(9+10+11+12)- new channel 3 contains data from channels(13+14+15+16)spw = ‘0:0~63^3’; mode=’channel’; nchan=21;start = 0; width = 1 will produce an spw with21 channels- new channel 1 contains data from channel 0- new channel 2 contains data from channel 2- new channel 21 contains data from channel 61spw = ‘0:0~40^2’; mode = ‘channel’; nchan = 3;start = 5; width = 4 will produce an spw withthree output channels- new channel 1 contains channels (5,7)- new channel 2 contains channels (13,15)- new channel 3 contains channels (21,23)nchan (int=-1)
- Number of channels in the output spw (-1=all).Subparameter ofmode=’channel|velocity|frequency|channel_b’Default: -1 = all channelsUsed for regridding, together with ‘start’ and‘width’.Example: nchan=3start (variant='0')
- Start or end input channel (zero-based), depending on the sign of the width parameterSubparameter ofmode=’channel|velocity|frequency|channel_b’Used for regridding, together with ‘width’ and‘nchan’. It can be in different units, dependingon the regridding mode:- first input channel (mode=’channel’),- first velocity (mode=’velocity’), or- first frequency (mode=’frequency’).Example values: ‘5’, ‘0.0km/s’, ‘1.4GHz’, forchannel, velocity, and frequency modes,respectively.width (variant='1')
- Channel width of the output visibilities.Subparameter ofmode=’channel|velocity|frequency|channel_b’Used for regridding, together with ‘start’, and‘nchan’. It can be in different units, dependingon the regridding mode: number of input channels(mode=’channel’), velocity (mode=’velocity’), orfrequency (mode=’frequency’.Example values: ‘2’, ‘1.0km/s’, ‘1.0kHz’, forchannel, velocity, and frequency modes,respectively.Note: the sign indicates whether the startparameter is lower(+) or upper(-) end of therange.interpolation (string='linear')
- Spectral interpolation methodSubparameter ofmode=’channel|velocity|frequency|channel_b’Default = ‘linear’Options: linear, nearest, cubic, spline, fftshiftphasecenter (variant='')
- Phase center direction to be used for the spectralcoordinate transformation.Default: ‘’ (first selected field)Options: FIELD_ID (int) or center coordinate measure (str).Phase direction measure or fieldid. To be usedin mosaics to indicate the center direction to beused in the spectral coordinate transformation.Examples:phasecenter=6phasecenter=’J2000 19h30m00 -40d00m00’restfreq (string='')
- Rest frequency to use for output visibilities.Default=’’Occasionally it is necessary to set this (forexample some VLA spectral line data). Forexample for NH_3 (1,1) putrestfreq=’23.694496GHz’outframe (string='')
- Output reference frame (not case-sensitive).Default: ‘’ (keep original reference frame)Options: LSRK, LSRD, BARY, GALACTO, LGROUP, CMB,GEO, TOPO, or SOURCESOURCE is meant for solar system work andcorresponds to GEO + radial velocity correctionfor ephemeris objects.Example: outframe=’BARY’veltype (string='radio')
- Definition of velocity (in mode)Default = ‘radio’hanning (bool=False)
- Hanning smooth data to remove Gibbs ringing.Default: FalseOptions: False|True