Plotbandpass
Return to Analysis Utilities
Note: plotbandpass will be available as an official CASA task in the 4.1 release.
This page documents the plotbandpass function of Python module analysisUtils.
The plotbandpass function provides extended capabilities beyond those of CASA's plotcal. It was written to facilitate rapid visualization of ALMA's bandpass and spectral Tsys measurements in Science Verification and Early Science data, but it can be used to plot EVLA bandpass solutions as well. It is distributed with the analysisUtils Python module which provides numerous other Python extensions callable from within CASA. plotbandpass has been tested on dual-polarization ALMA data, and single-, dual-, and full-polarization EVLA data. It supports both the old and new calibration table formats. Plotbandpass is being added as an official casa task in the casapy 4.1 to be released in May 2013. It has all of the functionality listed below (except for the platformingThreshold and resample options). In the analysisUtils version, a description of the input parameters can always be obtained by giving parameter: help=True.
# In CASA
import analysisUtils as au
au.plotbandpass(help=True)
This command will print to your screen a complete listing of available parameters and their meaning as shown below.
$Id: plotbandpass3.py,v 1.24 2013/02/15 17:58:50 thunter Exp $
Usage: plotbandpass(caltable='', antenna='', field='', spw='', yaxis='amp',
xaxis='chan', figfile='', plotrange=[0,0,0,0], help=False, caltable2='',
overlay='', showflagged=False, timeranges='', buildpdf=False, caltable3='',
markersize=3, density=108, interactive=True, showpoints='auto',
showlines='auto', subplot='22', zoom='', poln='', showatm=False, pwv='auto',
gs='gs', convert='convert', chanrange='', debug=False, vm='',
solutionTimeThresholdSeconds=60.0, phase='', ms='', showtsky=False,
showfdm=False, showatmfield='', lo1=None, showimage=False,
showatmPoints=False, parentms='', pdftk='pdftk', channeldiff=False, edge=8)
antenna: must be ID (int or string or list), or a single antenna name or list
atm: overlay the atmospheric transmission curve for the weather and elevation
buildpdf: True/False, if True and figfile is set, assemble pngs into a pdf
caltable: a bandpass table, of type B or BPOLY
caltable2: a second cal table, of type BPOLY or B, to overlay on a B table
caltable3: a third cal table, of type BPOLY, to overlay on the first two
chanrange: set xrange ('5~100') over which to autoscale y-axis for xaxis='freq'
channeldiff: set to value > 0 (sigma) to plot derivatives of amplitude
convert: full path for ImageMagick convert command (in case it's not found)
density: dpi to use in creating PNGs and PDFs (default=108)
edge: the number of edge channels to ignore in finding outliers (for channeldiff>0)
field: must be an ID, source name, or list thereof; can use trailing *: 'J*'
figfile: the base_name of the png files to save: base_name.antX.spwY.png
gs: full path for ghostscript command (in case it's not found)
help: print this message
interactive: if False, then figfile will run to completion automatically
lo1: specify the LO1 setting (in GHz) for the observation (used if showimage=T)
overlay: 'antenna' or 'time', make 1 plot with different items in colors
showflagged: show the values of data, even if flagged
markersize: size of points (default=3)
ms: name of the ms for this table, in case it does not match the string in the caltable
parentms: name of the parent ms, in case the ms has been previously split
pdftk: full path for pdftk command (in case it's not found)
phase: the y-axis limits to use for phase plots when yaxis='both'
plotrange: define axis limits: [x0,x1,y0,y1] where 0,0 means auto
poln: polarizations to plot (e.g. 'XX','YY','RR','LL' or '' for both)
pwv: define the pwv to use for the showatm option: 'auto' or value in mm
showatm: compute and overlay the atmospheric transmission curve
showatmfield: for overlay='time', use first observation of this fieldID or name
showatmPoints: draw atmospheric curve with points instead of a line
showfdm: when showing TDM spws with xaxis='freq', draw locations of FDM spws
showimage: also show the atmospheric curve for the image sideband (in black)
showtsky: compute and overlay the sky temperature curve instead of transmission
showlines: draw lines connecting the data (default=T for amp, F for phase)
showpoints: draw points for the data (default=F for amp, T for phase)
solutionTimeThresholdSeconds: consider 2 solutions simultaneous if within this interval (default=60)
spw: must be single ID or list or range (e.g. 0~4, not the original ID)
subplot: 11,22,32 or 42 for RowsxColumns (default=22), any 3rd digit is ignored
timeranges: show only these timeranges, the first timerange being 0
vm: the result from ValueMapping('my.ms'), or as returned from a previous call to plotbandpass
xaxis: 'chan' or 'freq'
yaxis: 'amp', 'tsys', 'phase', or 'both' amp&phase == 'ap'; append 'db' for dB
zoom: 'intersect' will zoom to overlap region of caltable with caltable2
If help is not True, the information printed to the screen at the conclusion of the function is the ValueMapping structure for the specified MS.
Regarding the showatm=True parameter, since some people reducing ALMA data do not load the ASDM_CALWVR table into the MS, the atmospheric transmission curve will be computed by default for 1.0 mm in this case, but you can set the PWV to any value using the pwv option. If you want the fully correct curve for ALMA, then copy the CalWVR.xml file from your ASDM to the present working directory and specify pwv='auto' (which is now the default).
Most of the regular CASA list syntax is accepted (commas, tildes, exclamation point) except channel selection within an spw and negation of spws is not supported. You are welcome to submit a ticket to the ALMA helpdesk if you find any problems or unexpected behavior. Please include the following information in your bug or enhancement request and send to helpdesk:
- the version number you are using, which is printed as the first line of output;
- the exact command; and
- a pointer to the dataset.
How to speed up the performance on large datasets
The analysisUtils version of the plotbandpass function first needs to call (Stuartt Corder's) ValueMapping to learn about the dataset and create a structure for future reference, which can be slow. (The version in casapy-test uses the new msmd tool which is faster.) If you plan to run the function many times on the same dataset, then you should store the return value of the structure from ValueMapping, like so:
# In CASA
vm = au.ValueMapping(your_ms)
Now, you can pass the result back to plotbandpass via the optional vm argument to avoid having to run ValueMapping inside of plotbandpass each time. It will do a sanity check to see if the MS name in the vm structure matches the MS name stored inside the caltable.
# All subsequent calls to plotbandpass will now run faster, as long as the vm=vm argument is passed.
au.plotbandpass(caltable='bandpass.bcal', vm=vm)
Display a simple bandpass solution
# In CASA
au.plotbandpass(caltable='bandpass.bcal',yaxis='both',antenna='DV07',figfile='bandpass')
Here we have specified a single antenna, but we could give a list, or leave it blank for all antennas. We have asked for both phase and amplitude which are shown in adjacent plots. Note how the ouput figfile name will be modified to include antenna number, spw, and timerange of the first panel for your convenience: bandpass.DV07.spw0.t1.png. The default style for amplitude is lines, and phase is points, but this can be changed with showpoints or showlines.
Maybe you prefer to see your phase plots on a common -180 to +180 degree scale. You can do that with plotrange and by limiting yourself to showing only the phase plots.
# In CASA
au.plotbandpass(caltable='bandpass.bcal',yaxis='phase',antenna='DV07',figfile='bandpass_phase',plotrange=[0,0,-180,180])
The first 3 plots are from the 3 different time ranges. The fourth plot is the first timerange on the second spw (spw=1). Notice how the upper half of the channels are missing. This is because they were flagged prior to the solution. The x-axis range reflects both flagged and unflagged data to visually remind you of this situation.
Display different (fixed) y-axis ranges for amplitude and phase
Alternatively, if you want to show both amplitude and phase plots on the same page, you can set a fixed amplitude range with the plotrange parameter, and a different fixed phase range with phase=[-180,180].
# In CASA
au.plotbandpass(caltable='bandpass.bcal',yaxis='both',antenna='DV07',figfile='bandpass_phase',plotrange=[0,0,0,5],phase=[-180,180])
Display a bandpass solution with a BPOLY solution overlaid
You can overlay a BPOLY solution on top of the regular B solution to see how well the polynomial reproduces the shape.
# In CASA
au.plotbandpass('bandpass_b_skipspw19high.bcal',overlay='',yaxis='phase',field='0',
xaxis='freq',caltable2='bandpass_bpoly_skipspw19high.bcal',
showpoints=True,spw=0,figfile='bpoly_overlay',antenna='4~7')
Note: You cannot overlay two BPOLY solutions, unless you overlay three solutions with the first caltable as a B solution (then caltable2 and 3 can be of either type).
Overlay a bandpass solution with a smoothed version created by smoothbandpass
# In CASA
au.plotbandpass(caltable='bandpass.bcal',caltable2='bandpass.bcal_smooth',xaxis='freq',
yaxis='both',overlay='',figfile='smooth',antenna='DV07')
The "c1" and "c2" labels in the legend correspond to caltable and caltable2:
Display a Tsys solution for individual times for one field
A Tsys table is simply a bandpass table with amplitude values set to the system temperature and phase set to zero. There is no inherent way in the header to differentiate a Tsys table from another bandpass table. Therefore, in order to decide whether to make the yaxis label "Amplitude" or "Tsys", we simply look for the letters "tsys" in the caltable name.
# In CASA
au.plotbandpass('X3c1.tsys',yaxis='amp',field='2',xaxis='chan',figfile='tsys_chan.png')
Overlay Tsys values for all antennas, one plot per timerange
A quick way to check whether any antenna shows an anomalous system temperature is to overlay all of them together.
# In CASA
au.plotbandpass('X3c1.tsys',overlay='antenna',yaxis='amp',field='2',xaxis='chan',
figfile='tsys_antenna_overlay.png',subplot=11)
Overlay Tsys values for all timeranges, one plot per antenna
# In CASA
au.plotbandpass('X3c1.tsys',overlay='time',yaxis='amp',field='2',xaxis='chan',
figfile='tsys_overlay.png',subplot=11)
Compute and overlay the atmospheric transmission cure
Sometimes it is instructive to compare the atmospheric transmission curve to the bandpass solution, for example to confirm that absorption features are due to ozone lines. Because Juan Pardo's atm program is contained in casa, the curve can be computed with showatm=True option. By default it will use 1.0 mm as the PWV, however you can change this by entering a different value with pwv='2.0' or by setting pwv='auto' , which will use the actual values of PWV as measured by the WVRs via TelCal and written into the ASDM_CALWVR table. In this case, the median value from all antennas is used. In all cases, the transmission curve uses the airmass of the source for the scan closest to the midpoint of the solution interval. The curve is drawn such that 0% is at the bottom and 100% is at the top of the y-axis, regardless of what plotrange is set for the amplitude.
# In CASA
au.plotbandpass('bandpass2_60m.bcal',showatm=True,xaxis='freq',figfile='showatm.png',
subplot=11,plotrange=[230.6,232.5,0,1.2])
For band 9, it is useful to also overlay the transmission curve from the image sideband, which affects the Tsys equally as the signal sideband. If you have imported the Receiver.xml file during importasdm, then it will automatically determine the LO1 frequency. If not, then you must specify it in GHz (for example, lo1=340.0). Here is an example call and plot:
# In CASA
au.plotbandpass('uid___A002_X41f8d2_X50f.ms.tsys_3.4',showatm=T,xaxis='chan',showimage=T,vm='',field='0',subplot=11)
Clipping off the edge channels
Sometimes the edge of the band shows extreme amplitude values. In this case, it is useful to limit the xrange of the display. If you are using xaxis='chan' , you can simply use plotrange=[8,120,0,0] to clip 8 channels off each edge. But if you are using xaxis='freq' , you must set chanrange='8~120' and leave plotrange at the default. Below is an example of the full display, and the display with chanrange set.
# In CASA
au.plotbandpass('bandpass2_20m.bcal',xaxis='freq',overlay='time',showatm=T,
antenna='',plotrange=[0,0,0,0],subplot=11,figfile='limitedrange',
chanrange='10~120')
