plotms is a GUI-style plotter, based on Qt, for creating X-Y plots of visibility data and calibration tables. It can either be started as a task within CASA or from outside CASA (type casaplotms on the command line).  This task also provides editing capability.

plotms was originally intended to plot MeasurementSets (the "ms" in "plotms"), but has been extended to include calibration tables.  Some options (axes, averaging) do not apply to calibration tables or have not been implemented yet.  Other options, such as calibration axes, do not apply to MeasurementSets. For simplicity, this document primarily addresses plotting MeasurementSets.

The current inputs and default values for plotms include:

Note that when some parameters are set or are True, their subparameters are displayed by inp( ).  By default, selectdata, averagedata, and showgui are True and their subparameters are shown above.  Other parameters with subparameters include:

Note that if the vis parameter is set to the name of a MeasurementSet here, when you start plotms the entire MeasurementSet will be plotted, which can be time consuming.  You may want to set selection or averaging parameters first.

To start a "blank" plotms window then enter your selections interactively in the GUI, use these commands:

Alternatively, they can be specified as task parameters in a plotms call, for scripting:

Note that subsequent plotms calls will return any unspecified parameters in that call to their default values.  See also the Examples tab in the plotms task for plotms calls using many of the parameters.

The plotms GUI will be described in the following sections, along with the corresponding parameters for the task interface or scripting.  For non-interactive scripting, set showgui=False and export the plot into an image specified by plotfile.

1. The Plot Tab

1.1 Loading, Selecting, and Averaging Data: the Plot Data Tab

1.1.1 File Selection

When plotms is first started, by default it will display the Plot tab (as chosen from the tabs at the top of the plotms window) and its Data subtab (as chosen from the tabs on the left side) as shown in Figure 1. First, a MeasurementSet or calibration table should be loaded by clicking on Browse in the File section and selecting a MeasurementSet directory (just select the directory itself; do not descend into it).

A plot can now be made of the MeasurementSet by clicking on the Plot button--but beware, this would plot the entire MeasurementSet, and could take quite some time! It is probably better to select a subset of the MeasurementSet in the Selection section or set averaging in the Averaging section before clicking Plot.

By default, plotms will plot Amplitude versus Time for a MeasurementSet; see this section on selecting axes for axis options.  The default axes change for calibration tables depending on the table type.  By default, plotms self-scales axes and the symbol size. For a very large range, this can hide points close to zero; see the sections below for information on setting axes ranges and symbol sizes.

The plotms task parameter for file selection is vis.

 1.1.2 Data Selection

The options for data selection are:

• field
• spw
• timerange
• uvrange
• antenna
• scan
• corr (correlated polarizations)
• array
• observation
• intent
• feed
• msselect

Note that, unlike when setting data selection parameters from the CASA command line, no quotation marks are needed around strings in the GUI.  For more information on data selection strings, see the documentation here.  To view information about your data in order to make your selection, see the Summary section below or use the listobs task.

The plotms parameter for data selection is selectdata (default is True, but no selection occurs unless one or more subparameters is set).  Its subparameters include field, spw, timerange. uvrange, antenna, scan, correlation, array, observation, intent, feed, and msselect.  These should be set to string values.

1.1.3 Averaging Data

plotms enables averaging of the data in order to increase signal-to-noise of the plotted points or to increase plotting speed. The options for averaging in the Plot > Data tab include:

• channel
• time (optionally over scans or fields)
  
• all baselines or per antenna
• all spectral windows
• vector (default) or scalar

The box next to a given averaging mode needs to be checked for that averaging to take effect.

When averaging, plotms will prefer unflagged data.  If an averaging bin contains any unflagged data at all, only the average of the unflagged will be shown. For averaging bins that contain only unflagged data, the average of that unflagged data will be shown. When flagging on a plot of averaged data, the flags will be applied to the unaveraged data in the MS.

The plotms task parameter for averaging is averagedata (default is True, but no averaging occurs unless one or more subparameters are set).  It subparameters include avgchannel and avgtime (set to a string value in channels or seconds, default ""), and boolean parameters avgscan, avgfield, avgbaseline, avgantenna, avgspw, and scalar (True/False, default False).  Invalid combinations of averaging will result in an error message (e.g. avgbaseline=True, avgantenna=True) or will be ignored (e.g. avgscan=True but avgtime has not been set).

Channel Averaging:

For example, to average n channels together, the user would click on the box next to Channel so that an “X” appears in it, and then type the number n in the empty box. When the user next clicks on Plot, every n channels will then be averaged together and plotted against the average channel numbers. The total number of channels plotted will be decreased by a factor of n.

Warning: If a complex channel selection is made e.g. of continuum in the presense of multiple lines, channel averaging is unlikely to produce a meaningful plot.

Time Averaging:

Time averaging is a little trickier, as it is controlled by three fields. If the checkbox next to Time is checked, a blank box with units of seconds will become active, along with two additional checkboxes: Scan and Field. If averaging is desired over a relatively short interval (say, 30 seconds, shorter than the scan length), a number can simply be entered into the blank box and, when the data are replotted, the data will be time averaged. Clicking on the Scan or Field checkbox in this case will have no impact on the time averaging.  These checkboxes become relevant if averaging over a relatively long time—say the entire observation, which consists of multiple scans—is desired. Regardless of how large a number is set in the Time averaging box, only data within individual scans will be averaged together. In order to average data across scan boundaries, the Scan checkbox must be checked and the data replotted. Finally, clicking on the Field checkbox enables the averaging of multiple fields together in time.

Averaging All Baselines/Per Antenna:

Clicking on the All Baselines checkbox will average all baselines in the array together. Alternatively, the Per Antenna box may be checked, which will average all baselines for a given antenna together. In this case, all baselines are represented twice; baseline 3-24 will contribute to the averages for both antenna 3 and antenna 24. This can produce some rather strange-looking plots if the user also selects on antenna—say, if the user requests to plot only antenna 0 and then averages Per Antenna, In this case, an average of all baselines including antenna 0 will be plotted, but each individual baseline including antenna 0 will also be plotted (because the presence of baselines 0-1, 0-2, 0-3, etc. trigger Per Antenna averaging to compute averages for antennae 1, 2, 3, etc. Therefore, baseline 0-1 will contribute to the average for antenna 0, but it will also singlehandedly be the average for antenna 1.)

Averaging All Spectral Windows:

Spectral windows can be averaged together by checking the box next to All Spectral Windows. This will result in, for a given channel n, all channels n from the individual spectral windows being averaged together.

Vector/Scalar Averaging:

Finally, the default mode is vector averaging, where the complex average is formed by averaging the real and imaginary parts of the relevant visibilities. If Scalar is chosen, then the amplitude of the average is formed by a scalar average of the individual visibility amplitudes.

1.1.4 A Brief Note Regarding plotms Memory Usage

In order to provide a wide range of flexible interactive plotting options while minimizing the I/O burden and speeding up the plotting, plotms caches the data values for the plot (along with a subset of relevant meta-info) in as efficient a manner as possible.  Sometimes, however, the data changes on disk, for example when other data processing tasks are applied. To force plotms to reload the data, check the Reload box next to the Plot button or press the SHIFT key while clicking the Plot button.

For plots of large numbers of points, the total memory requirement can be quite large. plotms attempts to predict the memory it will require (typically 5 or 6 bytes per plotted point when only one axis is a data axis, depending upon the data shapes involved), and will complain if it believes there is insufficient memory to support the requested plot. For most practical interactive purposes (plots that load and draw in less than a few or a few 10s of minutes), there is usually not a problem on typical modern workstations.  Attempts to plot large datasets on small laptops might be more likely to encounter problems here.

The absolute upper limit on the number of simultaneously plotted points is currently set by the ability to index the points in the cache. For modern 64 bit machines, this is about 4.29 billion points (requiring around 25GB of memory). Such plots are not especially useful interactively, since the I/O and draw become prohibitive.

In general, it is usually most efficient to plot data in modest chunks of no more than a few hundred million points or less, either using selection or averaging. Note that all iterations are (currently) cached simultaneously for iterated plots, so iteration is not a way to manage memory use. A few hundred million points tends to be the practical limit of interactive plotms use with respect to information content and utility in the resulting plots, especially when you consider the number of available pixels on your screen.

1.2 On-The-Fly Calibration: the Plot Calibration Tab

One can apply calibration tables to the uncalibrated data on the fly, i.e. without a run of applycal beforehand, by specifying a calibration library and selecting the corrected Data Column for the plotted axes.  See the Cal Library Syntax documentation for more information on specifying calibration in a string or file.

The Calibration tab on the left hand side contains a field to specify a calibration library file, or use Browse to open a file selection dialog.  You can also specify the calibration library commands directly in a string.  There is a switch to apply the calibration library to produce the corrected data (Calibration On) or to show an existing CORRECTED_DATA column (Calibration Off).  If the corrected Data Column is requested but the column is not present in the MS and the calibration library is not set or enabled, plotms issues a warning and plots the DATA column instead.

The plotms task parameter ’callib’ can be used to provide a calibration library file or a string containing the cal library commands.  It is enabled by default when the parameter is set.

1.3 Selecting Plot Axes: The Plot Axes Tab

1.3.1 Selecting Axes

The X and Y axes of a plot are selected by clicking on the Plot > Axes tab and choosing an entry from the drop-down menus below X Axis and Y Axis. The axes are grouped by type and listed in this order:

• MeasurementSet metadata:
  • Scan — The scan number, as listed by listobs or the plotms summary
  • Field — The field number, as listed by listobs or the plotms summary
  • Time —The time at which the visibility was observed, given in terms of calendar year (yyyy/mm/dd/hh:mm:ss.s).
  • Interval — The integration time in seconds.
  • Spw — The spectral window number. The characteristics of each spectral window are listed in listobs or the plotms summary.
  • Channel — The spectral channel number.
  • Frequency — Frequency in units of GHz. The frame for the frequency (e.g., topocentric, barycentric, LSRK) can be set in the Plots > Transform tab.
  • Velocity — Velocity in units of km s−1, as defined by the Frame, Velocity Defn, and Rest Freq parameters in the Plots > Transform tab.
  • Corr — Correlations which have been assigned integer IDs, including RR (5), RL (6), LR (7), LL (8), XX (9), XY (10), YX (11), and YY (12).  The axis values are these IDs, as listed by listobs or the plotms summary.
    
  • Antenna1 — The first antenna in a baseline pair; for example, for baseline 2-4, Antenna1= 2. Antennae are numbered according to the antenna IDs listed in listobs or the plotms summary.
  • Antenna2 — The second antenna in a baseline pair; for baseline 2-4, Antenna2 = 4. Antennae are numbered according to the antenna IDs listed in listobs or the plotms summary.
  • Antenna — Antenna ID for plotting antenna-based quantities. Antennae are numbered according to the antenna IDs listed in listobs or the plotms summary.
  • Baseline — The baseline number.
  • Row — The MS data row number. A row number corresponds to a unique timestamp, baseline, and spectral window in the MeasurementSet.
  • Observation — The observation ID (index)
  • Intent — The intent ID (index)
  • Feed1 — The first feed number, most useful for single-dish data.
    
  • Feed2 — The second feed number, most useful for single-dish data.
• Visibility values and flags:
  • Amp — Data amplitudes in units which are proportional to Jansky (for data which are fully calibrated, the units should be in Jy).
  • Phase — Data phases in units of degrees.
  • Real and Imag — The real and imaginary parts of the visibility in units which are proportional to Jansky (for data which are fully calibrated, the units should be Jy).
  • Wt and Wt*Amp — the weight of the visibility and the product of the weight and the amplitude.
  • WtSp — WEIGHT_SPECTRUM column, i.e. a weight per channel.
  • Sigma — the SIGMA column of the visibilities
  • SigmaSp — SIGMA_SPECTRUM column, i.e. a sigma per channel
  • Flag — Data which are flagged have Flag = 1, whereas unflagged data are set to Flag = 0.  Note that, to display flagged data, you will have to click on the Plots > Display tab and choose a Flagged Points Symbol.
  • FlagRow — In some tasks, if a whole data row is flagged, then FlagRow will be set to 1 for that row. Unflagged rows have FlagRow = 0. However, note that some tasks (like plotms) may flag a row, but not set FlagRow = 1. It is probably better to plot Flag than FlagRow for most applications.
• Observational geometry:
  • UVdist — Projected baseline separations in units of meters. Note that UVDist is not a function of frequency.
  • UVwave — Projected baseline separations in units of the observing wavelength (lambda, not kilolambda). UVwave is a function of frequency, and therefore, there will be a different data point for each frequency channel.
  • U, V, and W — u, v, and w in units of meters.
  • Uwave, Vwave, and Wwave — u, v, and w in units of wavelengths lambda.
  • Azimuth and Ant-Azimuth — Azimuth in units of degrees. Azimuth plots a fiducial value for the entire array, while Ant-Azimuth plots the azimuth for each individual antenna (their azimuths will differ depending on each antenna's longitude, latitude, and elevation).
  • Elevation and Ant-Elevation — Elevation in units of degrees. Elevation is a representative value for the entire array, while Ant-Elevation is the elevation for each individual antenna (their elevations will differ depending on each antenna's longitude, latitude, and elevation).
  • HourAngle — Hour angle in units of hours. This is a fiducial value for the entire array.
  • ParAngle and Ant-ParAng — Parallactic angle in units of degrees. ParAngle is the fiducial parallactic angle for all antennae in the array, while Ant-ParAng plots the parallactic angle for each individual antenna (their parallactic angles will differ depending on each antenna's longitude, latitude, and elevation).
• Calibration:
  • GainAmp, GainPhase, GainReal, GainImag — the amplitude, phase, real and imaginary part of the calibration tables for regular complex gain tables.
  • Delay — The delay of a delay calibration table.
  • SwPower — Switched Power values for VLA switched power calibration tables.
  • Tsys — Tsys for Tsys calibration tables.
  • Opac — Opacity values of a Opacity calibration table.
  • SNR — Signal-to-Noise Ratio of a calibration table.
  • TEC — Total Electron Content of an ionosphere correction calibration table.

If the data axis selected from the drop-down menu is already stored in the cache (therefore implying that plotting will proceed relatively quickly), an “X” will appear in the checkbox next to Cached.   To reload the data from disk, the Reload checkmark should be set at the bottom of this display.

The plotms task parameters used to select the axes are xaxis and yaxis.  Valid options include 'scan', 'field', 'time', 'interval', 'spw', 'chan' (or 'channel'), 'freq' (or 'frequency'), 'vel' (or 'velocity'), 'corr' (or 'correlation), 'ant1' (or 'antenna1'), 'ant2' (or 'antenna2'), 'baseline', 'row', 'observation', 'intent', 'feed1', 'feed2', 'amp' (or 'amplitude'), 'phase', 'real', 'imag', 'wt' (or 'weight'), 'wtsp' (or 'weightspectrum'), 'flag', 'flagrow', 'uvdist', 'uvwave' (or 'uvdistl'), 'u', 'v', 'w', 'uwave', 'vwave', 'wwave', 'azimuth', 'elevation', 'hourang' (or 'hourangle'), 'parang' (or 'parangle'), 'ant' (or 'antenna'), 'ant-azimuth', 'ant-elevation', 'ant-parang' (or 'ant-parangle'), 'gainamp' (or 'gamp'), 'gainphase' (or 'gphase'), 'gainreal' (or 'greal'), 'gainimag' (or 'gimag'), 'delay' (or 'del'), 'opacity' (or 'opac'), 'swpower' (or 'swp' or 'spgain').

When left as the default empty strings (""), the axes for a MeasurementSet will be Amp vs. Time.  The default axes for a calibration table depend on the type.

1.3.2 Data Columns

For relevant data axes like Amp and Phase, the user will be presented with the option to plot raw data or calibrated data. This can be selected via a Data Column drop-down menu, located directly under the drop-down menu for X Axis or Y Axis selection. To plot raw data, select “data”; to plot calibrated data, select “corrected”. Note that this choice will only have an impact on a plot if a calibration table has been applied to the MeasurementSet or a calibration library is set and enabled.

If a data model is present in the MeasurementSet (e.g., created by setjy, clean, or ft), it can be plotted by selecting “model” from the Data Column menu. Residuals can be plotted via “corrected-model”, “data-model”, “data/model”, and “corrected/model”.  Note that when the residuals are selected, vector (complex) subtraction or division occurs before the operation for the requested axis (amp, phase, real, imag) is performed.

The plotms task parameters used to select the data columns are xdatacolumn and ydatacolumn.  Valid options include 'data', corrected', 'model', 'corrected-model', 'data-model', 'data/model', 'corrected/model', and 'float'.  Default data columns for x and y are both 'data'.

1.3.3 Axis Locations

The location of the x-axis and y-axis can be set using the radio buttons in the GUI, where the x-axis can be located at the Bottom (default) or Top, and the y-axis can be located at the Left (default) or Right.

The plotms task parameter to set the y-axis location is yaxislocation.  There is no parameter to set the x-axis location.  Valid values for this parameter include 'left' and 'right' (default "" == 'left').

1.3.4 Axes Ranges

The X and Y ranges of the plot can be set manually or automatically. By default, the circle next to Automatic will be checked, and the ranges will be auto-scaled. To define the range, click on the circle below Automatic and enter a minimum and maximum value in the blank boxes. Note that if identical values are placed in the blank boxes (xmin=xmax and/or ymin=ymax), then the values will be ignored and a best guess will be made to auto-range that axis.

The plotms task parameter used to set the axes ranges is plotrange, and its value is a list of numbers in the format [xmin, xmax, ymin, ymax] (default [ ], automatic range).

1.3.5 Plotting Multiple Y-Axes

Different values of the same dataset can be shown at the same time. To add a second y-axis, press the Add Y Axis Data button at the bottom of the Axes tab. Then select the parameters for the newly created axis by selecting from the new “Y Axis Data” drop-down menu. If the two y-axes have the same units, they can be displayed both on the same axis. If they are different (or their ranges are dissimilar), e.g. Amplitude and Elevation (both versus Time; see Figure 4 below), one axis should be attached to the left and the other to the right hand side of the plot. Using more than a single y-axis data is also reflected in the Display tab where a drop-down menu appears in order to select multiple y-axis options; here you may colorize each axis differently.  See the section below to learn more about symbol properties. To remove the additional y-axis, click Delete Y Axis Data at the bottom of the Axes tab.

The plotms task parameters used to plot multiple y-axes are the same as for a single y-axis: yaxis and yaxislocation; multiple y-axes can be specified as a list of strings if you are specifying the plotms command in the terminal. The values for yaxis and yaxislocation should be set to lists of the same length:

1.4 Iteration: The Plot Page Tab

In many cases, it is desirable to iterate through the data that were selected in the Data tab. A typical example is to display a single baseline in an amplitude vs. time plot and then proceed to the next baselines step by step. This can be done via the Plot > Page tab.  A drop-down menu allows you to select the axis to be iterated on, with options None, Scan, Field, Spw, Baseline, Antenna, Time, and Corr.  Press the Plot button after changing your selection.  Each plot will be autoscaled according to its iteration value range unless a Range is specified in the Axis tab.

The current iteration is indicated in the plot title of the displayed plot. To proceed to the next plot use the green arrow buttons below the main panel. The different button symbols let you to proceed panel by panel (single arrow symbols) or to jump to the first or last panel directly (double arrow symbols).

The number of plots per page can be selected under Options > Grid, the last of the top row of tabs, as described in the section on plotting on a grid.  There are two scaling options for the iterated axes in a grid, set in this tab: Global and Shared. Global will use a common axis range based on data loaded with the selection criteria specified in the Data tab. Shared displays one set of x-axes and y-axes for the page rather than per-plot.  When left unchecked, Global and Shared results in plots with axes scaling to the data for each individual panel of the iteration.

The plotms task parameter used to select an iteration axis is iteraxis.  The options include 'scan', 'field', 'spw', 'baseline', 'antenna', 'time', and 'corr'.

1.5 Transforming the Velocity Frame or Phase Center: The Plot Transform Tab

1.5.1 Frequency Frame

If the user plans to plot frequency, the reference frame must be defined. By default, plotms selects the frame keyword (if any) present in the data, usually the frame observed at the telescope unless modified during previous processing. However, transformations can be made by choosing a Frame from the drop-down menu in the Plot > Transform tab. Frequency reference frames can be chosen to be:

• LSRK — local standard of rest (kinematic)
• LSRD — local standard of rest (dynamic)
• BARY — barycentric
• GEO — geocentric
• TOPO — topocentric
• GALACTO — galactocentric
• LGROUP — local group
• CMB — cosmic microwave background dipole

The plotms task parameter used to select frequency frame is freqframe.  Valid options include those listed above (strings with all caps).  The default empty string "" results in no frame transformation.

1.5.2 Velocity

If Velocity is selected as an axis, by default the transformation from frequency uses the parameters in the MS metadata, or, if absent, using the central frequency and TOPO frame. The user can change this by using the Frame, Velocity Defn, and Rest Freq options in the Transform tab.  The velocity definition is chosen from the Velocity Defn drop-down menu, offering selections of Radio, True (Relativistic), or Optical.

For more information on frequency frames and spectral coordinate systems, see the paper by Greisen et al. (A&A, 446, 747, 2006) (Also at http://www.aoc.nrao.edu/~egreisen/scs.ps)

Finally, the spectral line’s rest frequency in units of MHz should be typed into the Rest Freq input box next. You can use the slsearch task to search a spectral line table, or the me.spectralline tool method to turn transition names into frequencies:

For a list of known lines in the CASA measures system, use the toolkit command me.linelist(). For example:

The plotms task parameters used to set velocity definition and rest frequency are veldef and restfreq.  Valid options for veldef are 'RADIO', 'TRUE', or 'OPTICAL' (default is 'RADIO').  restfreq should be in a string in MHz, for example '22235.08MHz'.

1.5.3 Shifting the Phase Center

The plot’s phase center can be shifted in the Plot > Transform tab. This will allow coherent vector averaging of visibility amplitudes far from the phase tracking center.  Enter the X and Y shifts in units of arcseconds in the dX and dY boxes under Phase center shift.

The plotms task parameter used to shift the phase center is shift.  Its value should be a list in the format [dx,dy] in arcsec (default [0.0, 0.0]).

1.6 Display Options for Plots: The Plot Display Tab

1.6.1 Colorizing Your Data

Data points can be given informative symbol colors using the Colorize option in the Plot > Display tab. By checking the box next to Colorize and selecting a data axis from the drop-down menu, the data will be plotted with colors that vary along that axis. For example, if “corr” is chosen from the Colorize menu, “RR”, “LL”, “RL”, and “LR” data will each be plotted with a different color. Note that Colorize while plotting flagged data will override the default flagged red symbol color.

The plotms task parameter used to colorize data is coloraxis.  Options include 'scan', 'field', 'spw', 'antenna1', 'antenna2', 'baseline', 'channel', 'corr', 'time', 'observation', and 'intent'.

1.6.2 Customizing Your Symbols

Unflagged and flagged plot symbols can be customized in the Plot > Display tab. Most fundamentally, the user can choose to plot unflagged data and/or flagged data. By default, unflagged data is plotted (the circle next to Default is checked under Unflagged Points Symbol), and flagged data is not plotted (the circle next to None is checked under Flagged Points Symbol). We note here that plotting flagged data on an averaged plot is undertaken at the user’s own risk, as the distinction between flagged points and unflagged points becomes blurred if data are averaged over a dimension that is partially flagged. Take, for example, a plot of Amplitude vs. Time where all channels are averaged together, but some channels have been flagged due to RFI spikes. In creating the average, plotms will skip over the flagged channels and only use the unflagged ones. The averaged points will be considered unflagged, and the flagged data will not appear on the plot at all.

Symbol options include:

• None — no data points
• Default — data points which are small circles (blue for unflagged data and red for flagged data)
• Custom — allows the user to define a plot symbol

If Custom plot symbols are chosen, the user can determine:

1. Size, by typing a number in the blank box next to px or by clicking on the adjacent up or down arrows.
2. Shape, chosen from the drop-down menu; options include circle, square, diamond, pixel, or autoscaling.  Note that pixel only has one possible size.  autoscaling attempts to adjust the size of the points from dots to circles of different sizes, depending on how many points are plotted.
   
3. Color, chosen by typing a hex color code in the Fill input box or by clicking on the ... button and selecting a color from the pop-up GUI.
4. Fill, using the adjacent drop-down menu for how heavily the plot symbol is shaded with this color, from heaviest to lightest; options include fill, mesh1, mesh2, mesh3, and no fill.
5. Outline, by selecting None (no outline) or Default (outlined in black)

Note that if “no fill” and Outline: None are selected, the plot symbols will be invisible.

The plotms task parameter and subparameters used to customize unflagged symbols include:

• customsymbol (True/False, default False) - must be True for subparameters to take effect
  
• symbolshape ('autoscaling', 'circle', 'square', 'diamond', 'pixel', 'nosymbol', default 'autoscaling')
• symbolsize (in number of pixels, default 2)
• symbolcolor (RGB hex code e.g. 'aa55ff' or string color name e.g. 'purple', default '0000ff' blue)
• symbolfill ('fill', 'mesh1', 'mesh2', 'mesh3', 'no fill', default 'fill')
  
• symboloutline (True/False, default False)

The plotms task parameters used to customize flagged symbols include customflaggedsymbol (default False) with subparameters flaggedsymbolshape (default 'nosymbol'), flaggedsymbolsize (default 2), flaggedsymbolcolor (default 'ff0000' red), flaggedsymbolfill (default 'fill'), and flaggedsymboloutline (default False).  Supported values are the same as for unflagged symbols.

1.6.3 Symbols for Multiple Y-Axes

If you have added an additional y-axis in the Plot > Axes tab, you may customize each y-axis individually by selecting the axis in the Y Axis Data pull-down menu at the top of the Plot > Display tab and then customizing the symbols for that axis.

To set multiple symbols in the plotms task, set the symbol parameters as a list:

In this plot, the 'amp' axis will be purple, and the 'elevation' axis will be green.

1.7 Plot Labels: The Plot Canvas Tab

1.7.1 Plot Title

Options to change the plot title include None (no title), Default, and a user-input string.  To set the plot title, under Title, click on the circle next to the input box and enter the desired text. This text box shows the grayed-out default string, "%%yaxis%% vs. %%xaxis%%" (to substitute the axis names for "yaxis" and "xaxis").  The user can also choose the size of the title font by checking the Title Font checkbox and entering the font size or using the arrows to increase or decrease the value.  The default is to scale the title font depending on the plot size.

The plotms task parameters used to set the title and its font are title (default "" for yaxis vs. xaxis string) and titlefont (default is 0 to autoscale).  Set title='"" for the default title (Y vs. X) or " " (space) for no title.

1.7.2 Legend

A plot symbol legend can be added to the plot by clicking on the checkbox next to Legend. For a simple plot, a symbol legend simply echoes the plot axes (e.g. "Amp vs Time") but is useful when overplotting data with custom colors so that you can identify the data (e.g. "Amp vs Time" in blue and "Phase vs Time" in green on the same plot).

When enabled, a drop-down menu next to Legend allows the user to select the legend location either within the plot (Upper Right, Lower Right, Upper Left, Lower Left) or outside the plot (Out Right, Out Left, Out Top, Out Bottom).

The plotms task parameter used to enable the legend is showlegend (default is False).  To select the legend location subparameter, set legendposition to 'upperRight', 'upperLeft', 'lowerRight', 'lowerLeft', 'exteriorRight', 'exteriorLeft', 'exteriorTop', or 'exteriorBottom' (default is "" == upperRight).

1.7.3 Axis Labels

To enable the X- and Y-axis labels, check the Show Label checkboxes under X Axis and Y Axis (default is checked).  As with the plot title, the user may set the label to None (no label), Default (axis name with units),  or type the desired text in the blank box.  The font size of labels can also be customized by enabling then setting the font size for each axis.  The location of axis labels is determined by the axis location as set in the Plot > Axes tab, as shown in the section above.

The plotms task parameters used to set the label text and font are xlabel and ylabel (default "" is axis name with units, set to ' ' space to disable label) and xaxisfont and yaxisfont (default 0 == autoscale).

1.7.4 Grid Lines

A grid of lines can be superimposed on the plot using Grid Lines in the Plot > Canvas tab. “Major” grid lines are drawn at the locations of major tick marks, while “minor” grid lines are drawn at minor tick marks.

Grid line colors, thicknesses, and styles are selected independently for the “major” and “minor” grid lines. Desired line thickness should be typed into the blank boxes just to the right of the Major and Minor labels. Colors are set by clicking on the ... buttons. The blank boxes to the left of the ... buttons will then contain the hex codes for the selected colors (e.g., “808080”). Line styles can also be selected from the drop-down menus to the right of ... buttons; style options include solid, dash, dot, and none.

The plotms task parameter used to add and customize major grid lines include showmajorgrid (default is False) with subparameters majorwidth (default is 1), majorstyle ('solid', 'dash', 'dot', 'none'; default is 'solid'), and majorcolor (RGB hex code or color name; default is 'b0b0b0' dark gray).

Parameters for minor grid lines include showminorgrid (default is False) with subparameters minorwidth (default is 0), minorstyle (default is 'solid'), and minorcolor (default is 'd0d0d0' light gray).

2. Flag Extensions: The Flag Tab

See the section below on interactive flagging in plotms.  The options in this tab allows the user to have flagging extend to other data points besides what is marked on the plot.

When enabled with the Extend flags checkbox, the user may choose to extend flags based on correlation or channel by checking the corresponding checkboxes.  Future options for flag extensions are planned.

By checking the boxes next to Extend Flags and Correlation, flags will be extended beyond the correlations displayed. Currently the only option is to extend to All correlations as noted by the radio button, implying that all correlations will be flagged.  For example, with RR displayed, the correlations RR, RL, LR, and LL will all be flagged when this option is enabled.

By checking the boxes next to Extend Flags and Channel, flagging will be extended to other channels in the same spw as the displayed point. For example, if spw=’0:0’ and channel 0 is displayed, then flagging will extend to all channels in spw 0.

The plotms task parameter used to extend flags is extendflag (True/False, default is False) with subparameters extcorr (True/False), and extchannel (True/False).  These parameters will enable flag extensions when interactively flagging the plot.

3. Interactive Tools: The Tools Tab, Annotate Tab, and Tool Icons

Various interactive GUI tools are selectable with the radio buttons in the Hand Tools section of the Tools tab at the top of the plotms window.  They are also available as icon buttons at the bottom of the plotms window.  These tools can be used to zoom, pan, annotate, flag/unflag, and locate data.  Described below are the bottom icon buttons in order.

• Zoom — The “magnifying glass” button (1st on left) lets you draw a box around a region of the plot (left-click on one corner of the box, and drag the mouse to the opposite corner of the desired box), and then zooms in on this box.
• Pan — The “four-arrow” button (2nd from left) lets you pan around a zoomed plot.
• Annotate — The 3rd button from the left is chosen from a drop-down menu to either Annotate Text (“T with a green diamond” button) or Annotate Rectangle (“pencil” button). With Annotate Text activated, click on a location in the plot where text is desired; a window will pop up, allowing you to type text in it. When you click the OK button, this text will appear on the plot. Annotate Rectangle simply lets you draw a box on the plot by left-clicking and dragging the mouse. By clicking on the Annotate tab near the top of the plotms window, different fonts, colors, line styles, etc. can be selected for annotations.
• Stack Base — The “house” button (5th from left) returns to the original zoom level.
• Stack Back and Stack Forward — The left and right arrow buttons (4th and 6th from left) step through the zoom settings you’ve visited.
• Mark Regions — The “box with a green diamond” button (7th from left) lets you mark a region for flagging, unflagging, or locating. Left-click on one corner of the desired region, and then drag the mouse to set the opposite corner of the region. You can mark multiple boxes before performing an operation on them.  The selected regions will appear on the plot as shaded rectangles.
  
• Subtract Regions — The “box with a minus sign” button (8th from left) lets you de-select marked regions (draw around a marked region and the shaded area will disappear).  To de-select all marked regions, use the next button.
  
• Clear Regions — Clicking on the “box with a red circle” button (9th from left) will clear all regions which have been marked using Mark Regions.
• Locate — The “magnifying glass on a sheet of paper” button (10th from left) will print out information about points in the marked regions.  This information is printed to the shell terminal when plotms was started with casaplotms, or to the casa logger/logfile when plotms was started in a casa python session.  The header of the output indicates the plotted X and Y axes and the range of values in the selected region.  The output for each point includes scan, field, time, baseline, spw, channel, frequency, correlation, X, Y, and observation ID.  By copying this list to a text file, or setting a new logfile with casalog.setlogfile as described in the CASA logger documentation, the Locate information can be edited to provide input for flagdata.  To list an entire column, e.g. all visibilities for a source, use the listvis task or the table tools.
  
• Flag — Click on the “flag” button (11th from left) to flag all points in the marked regions.  See the section below on Interactive Flagging.
  
• Unflag — Click on the “crossed-out flag” button (12th from left) to unflag any flagged points in the marked regions (even if not displayed).
• Iteration — The next four green arrow buttons (13th through 16th from left) control iteration, with the first and last "double arrow" buttons used to display the first and last iteration, and the center two "single arrow" button to display the previous or next iteration.  If the plots are on a grid, these arrows navigate through the pages of plots which contain multiple iterations.
• Hold Drawing — If the Hold Drawing button (rightmost, or 17th from left) is clicked to activate it, when new plot axes are selected from the Plot > Axes tab, the new data will be cached but not plotted. When the button is clicked again (de-activated), it will automatically plot the data that was last requested. This can be particularly useful when changing the size of the plotms window.

The Tools tab also contains Tracker tools including Hover and Display.  When Hover is selected and the mouse is moved over the plot, the pointer's position is displayed on the plot in (X, Y) format.  When Display is selected, the (X, Y) position is displayed in the text box under the Display checkbox.

To record various tracked positions, enable Display then click on the plot to activate it.  As usual, moving the pointer displays the position in the small display text box.  Pressing the SPACE bar will copy the displayed line into the larger white box below it. This can be repeated many times and a log of positions and values will be created. The content in the box can then be easily copied and pasted into any other application that is used for data analysis. The Clear button wipes out the content of the box for a fresh start into new scientific adventures.

4. Miscellaneous Options: The Options Tab

A few miscellaneous per-page plot options and GUI options are available in the Options tab, the last tab at the top of the plotms window.

4.1 Plotting on a Grid

The layout of the page is set on the plotms Options tab. For multiple plots per page, set the grid layout, the number of rows and columns that determine the number of sub-plots.  Currently the plot updates after each grid change.

4.1.1 Plotting Iterations on a Grid

If iteration is enabled in the Plot > Page tab, the grid will be filled automatically with each iterated plot.  The Plot > Page tab is also where common axis scales and shared axes will be set; they are enabled for the plot in Figure 7.  These axis options are only available for iterated plots in a grid.

The plotms task parameters used to create a grid with iteration include gridrows and gridcols (default is 1). To create the plot shown in Figure 7, the plotms command would be:

4.1.1 Plotting Multiple Data on a Grid

We note here that plotting multiple datasets or axes on a grid is possible in plotms but covered separately in the section below, as this involves many settings in the GUI or multiple plotms task commands.  Since the grid affects all of the plots, its settings are in the Options tab rather than the Plot tab.

4.2 Tool Button Style

The Tool Button Style drop-down menu determines the format of the tool buttons at the bottom of the plotms window. The options include Icon Only, Text Only, Text Beside Icon, and Text Under Icon.  In Icon Only mode (default), hovering the cursor over each icon will give a text description of the icon.

To hide the bottom icons, see the description of the View menu. The tools can also be accessed in the Tools tab.

4.3 Log Events

This drop-down menu shows a checklist of events and plotms functions so that you can customize how verbose plotms is in documenting its actions.

4.4 Clear Regions and Annotations

The When changing plot axes, clear any existing regions or annotations checkbox determines when regions and annotation are deleted from the plot. By default, this is enabled.

4.5 Cached Images

A useful option is the Use fixed size for cached image checkbox. It determines how large the dots in the panel are with respect to the screen resolution. The values influence how the data is redrawn on the panel. When Screen resolution is selected, the plotms window can be resized without redrawing on the canvas – a considerable speedup for large data sets. The penalty is that the dots of the data points are the size of a pixel on the screen, which may be very small for high resolution monitors.  By default, this feature is not enabled.

4.6 File Chooser History Limit

This setting allows the user to limit how many remembered filepaths are displayed in file chooser dialogs produced by clicking Browse in the Plot > Data tab to select a MeasurementSet or calibration table and in the Plot > Calibration tab to select a calibration library.

5. The plotms Menus

5.1 File Menu: Quit

The File menu in the top menu bar allows you to Quit plotms, or you can click the X in the upper right corner of the window.

5.2 Export Menu: Saving Your Plot

You can save a copy of a plot to file with the Export menu, which produces an Export Plots dialog box with many settings.

• Filename: Click the Browse button for a GUI-based selection of the directory and filename to which the plot will be saved, or click the Insert MS Name button to minimize typing. You may also just type in a file name. The file format can be determined in this GUI by the suffix given to the filename: .png, .jpg, .ps, .pdf, and txt.  Warning: if a file already exists with the given filename, it will be overwritten without warning!
  
• Format: Alternatively, the file format can be selected from the Format drop-down menu, with these options: [by file extension], PNG, JPG, PS, PDF, and TEXT. For the first option, if your filename is "test.jpg" the plot will be exported in JPG format.  For the other formats, plotms will use the filename as given and not add a suffix to indicate its format. See below for an example of TEXT format.
  
• Range: When iteration is chosen, producing multiple plots, you may select to export only the Current Page or All Pages.  Each saved plot will have the name of the iteration appended to the given filename before the extension.  For example, with filename "ngc5921_ut.jpg" and iteration on antenna, the first plot will be named "ngc5921_ut_Antenna1@VLA:N7.jpg".  This is so the exported plots can be identified without viewing them.  Be warned that if you are plotting iterations on a grid, the filenames will have all of the iterations on the page appended, which can lead to a very long filename. Filenames exceeding 255 characters in length will be automatically shortened upon export. 
  
• High Resolution: Exporting to images in screen resolution is currently not working, so plot exports are always high resolution.  A notice is issued in the console/log.
• DPI, Size: Use the text boxes or up/down arrows to set the output DPI or size (in pixels) of the exported plot.
• Export: When settings are complete, click Export to create your plotfile.

Note: The plot files produced by the PS and PDF options can be large and time-consuming to export. The JPG is the smallest.

The TEXT format will not save an image but all of the data points themselves. This allows one to dump the current plot into a file that is used in other programs for further processing.

The reported data is the same as when using the Locate button in plotms, with the following format:

where x and y are the two plotted axes and the other columns contain additional information such as the baselines and frequencies.  These axes are not labeled in the text file, so you may want to include that information in the filename.

The plotms task parameter used to export plots is plotfile.  Its subparameters include:

• expformat ('jpg', 'png', 'pdf', 'ps', 'txt') - select the format if no extension is included in the plotfile. If there is no plotfile extension and no expformat set, the plot will be exported as a PNG.
  
• exprange ('current', 'all'; defaults to current)
  
• highres (True/False, default is False)
  
• dpi
• width (in pixels)
• height (in pixels)
• overwrite (True/False, default is False) - in this case you will get a warning if the file already exists.

5.3 Summary Menu: Information About Your Dataset

Information about the MeasurementSet can be obtained from within plotms by clicking on the Summary menu in the top menu bar. If All is chosen from the pull-down menu next to Type, listobs-style output about scans, correlator configurations, and antennae will be written to the console or log. Other options for a subset of the data include Where, What, How, Main, Tables, Antenna, Feed, Field, Observation, History, Polarization, Source, Spectral Window, Spectral Window and Polarization, SysCal, and Weather.  For more detail, click on the Verbose checkbox.

5.4 View Menu: Hide or Display Tool Icons

This menu controls the display of tool icons.  Use the View > Toolbars menu to de-select and hide the Tools, Iteration (green arrows), or Display (Hold Drawing) icons.  By default these icons are all selected and displayed at the bottom of the plotms window.

5.4 Help Menu: About plotms

This menu's About option describes plotms and the versions of CASA, Qt, and Qwt it uses, along with links.  Qt is the software framework that plotms uses for its GUI, and Qwt is a library that provides plotting functionality on top of the Qt framework.

Click About Qt  for more detail about this software package and its licensing.

6. Plotting Multiple Data

6.1 Overplotting Multiple Datasets or Axes on the Same Plot

It is possible to overplot two datasets on the same plot, or the same dataset with different y-axes in each plot.  To do this, set up the first plot as usual.  Then press the Add Plot button at the bottom left of the plotms window. This will bring up an additional data input panel in the Plot > Data tab where you can specify the plot parameters as you did for the first one, which is automatically minimized.  Use the slider to scroll vertically through the panels.  Use right-click options or the Minimize, Maximize, or Close buttons to keep a better overview on the individual datasets.

When overplotting, you may want to set different custom colors for each dataset in its Display tab.  If you are plotting different axes or the axes ranges are a significantly different range of values, you may want to set different axes locations for each plot in the Axes tab.  When you are done, click the Plot button to see the overplot.

Use the Close button in each data panel to close the panel and remove that plot.

In the plotms task interface, you can overplot by invoking plotms more than once with clearplots=False. Each plotms command corresponds to a plot to go on top of previous ones, and each must have its own plotindex (0-based, default is 0).  Otherwise, with the same plotindex, the second plot will overwrite the first.  In the following example, we are plotting Scan vs. Time for MeasurementSet test1.ms with plotindex 0, and Field vs. Time for MeasurementSet test2.ms on the same  plot with plotindex 1.  The test2 data is a different color and its yaxis is on the right.

6.2 Plotting Multiple Datasets or Axes on a Grid

plotms allows you to plot more than one dataset or axes on the same page by specifying a grid size then a grid location for each plot as described below. Here is an example of two plots with different datasets:

The process is similar to the one above, except that you specify the grid  and each plot's location:

1. Set up your first plot as described above.
2. Use the Options tab to set up a grid by incrementing the number of rows and/or columns.  By default the plot you set up in step 1 will be in row 0, column 0.
3. Use the Add Plot button to set up the second plot's parameters. Pay particular attention to the new dataset's Page tab, where you can set the Grid Location (row and column number) of the new plot.  This section appears only when a grid is set up.
4. Unlike iteration, you cannot share axes among the plots.
5. Add as many plots as you desire to fill your grid, then click Plot.

Several plotms task parameters are used to create a grid and specify a plot location.

• gridcols and gridrows define the number of plots on the screen.
• colindex and rowindex (0-based) set the location of an individual plot
• plotindex (0-based) must be incremented for each plotms call
• clearplots is set to False to keep previous plots

Here is an example of multiple plotms calls to set up two plots on a grid and export the plot page; note the defaults on the first call are rowindex=0, colindex=0, plotindex=0 so just set up the grid.  On each subsequent plotms call set clearplots=False and increment the plotindex.  To save the gridded plot, set a plotfile on the final plot.

7. Interactive Flagging

Interactive flagging, on the principle of “see it — flag it”, is possible on the X-Y display of the data plotted by plotms. Use the cursor to mark one or more regions, and then flag, unflag, or list (Locate) the data that falls in these regions of the display.

For plotting, plotms opens the MeasurementSet read-only, so there should be no problem if another task accesses the same dataset, unless the other task locks the file.  When this happens, you can wait for the lock to be released, cancel cache-loading in the plotms dialog box, type go clearstat at the prompt, or exit plotms. Do not attempt to flag data in plotms while another task is accessing the same data set, as in this case plotms must open the MeasurementSet with a file lock for writing.

Using the row of icons at the bottom of the plotms window, click on the Mark Regions button, then mark a region by left-clicking and dragging the mouse.  Each click and drag will mark an additional region. You can remove all of your marked regions by clicking on the Clear Regions button. Once regions are marked, you can then click on one of the other buttons to take action:

1. Flag — flag all of the points in the region(s),
2. Unflag — unflag flagged points in the region(s),
3. Locate — list information (X and Y value, scan, field, baseline, frequency, etc.) about the points in the region(s) to the command line or log (Warning: this could be a long list!).

Note that if you mark a region with flagged and unflagged values and Flag it, using Unflag will not return the data to its original state but will unflag all of the data in the region.

The following figure shows an example of marking regions and then clicking the Flag button. Whenever you click on a button, that action occurs without requiring an explicit disk-write. If you quit plotms and re-enter, you will see your previous edits because your flag changes were written to the MeasurementSet on disk.

plotms does not automatically create flag backups in the .flagversions file. It is thus recommended to save the initial flags with the flagmanager task before starting plotms interactive flagging. Important intermediate flagging stages may also be saved during plotms flagging in the same fashion.  Flagging can also be performed using the interactive msview task or scripted with the flagdata or flagcmd tasks.

Flags can also be extended with options in the Flag tab; see this section for a more detailed description of these options. Flag extension enables the user to plot a subset of the data and extend the flagging to a wider set. In this release, the only functional extensions are over correlation and channel.

8. Scripting With No GUI

When scripting to produce exported plotfiles, you may want to set the plotms parameter showgui=False to suppress the GUI and pop-up dialog boxes.  The default is True.

9. Exiting plotms

To exit the plotms GUI, select Quit from the File menu at the top of the plotms window. You can also dismiss the window by killing it with the “X” on the frame.

Alternatively, you can just leave it alone, and plotms will keep running in the background and update with each subsequent plotms call. If the data file changes in the background while you are using other tasks, you can force reloading the data via the Reload checkbox next to the Plot button, or press SHIFT while clicking on Plot for the same purpose.

If started in a casa session, plotms will automatically quit when the session is ended.