# 2-D Visualization and Flagging of Visibility Data (viewer/msview)

2-dimensional visualization and editing of visibilities with the viewer/msview GUI.

# Viewing MeasurementSets

Visibility data can also be displayed and flagged directly from the viewer or the more tailored task msview. A difference is that msview allows the user to select data before it is loaded into the GUI and displayed. A screenshot is shown in Data Selection in msview.   Selection parameters are field, spectral window, time range, uv range, antenna, corr, scan, array, and ms selection expression in the usual CASA selection syntax (see Data Selection).

For MeasurementSet files the only option for display is ’Raster’ (similar to AIPS task TVFLG). An example of MS display is shown in Data Display Options; loading of an MS is shown in Loading a MeasurementSet.

Warning: Only one MS should be registered at a time on a Display Panel. Only one MS can be shown in any case. You do not have to close other images/MSs, but you should at least ’unregister’ them from the Display Panel used for viewing the MS. If you wish to see other images or MSs at the same time, create multiple Display Panel windows.

## Data Display Options Panel for MeasurementSets

The Data Display Options panel provides adjustments for MSs similar to those for images, and also includes flagging options. As with images, this window appears when you choose the Data:Adjust menu or use the wrench icon from the Main Toolbar. It is also shown by default when an MS is loaded. The right panel of Data Display Options shows a Data Options window. It has a tab for each open MS, containing a set of categories. The options within each category can be either ’rolled up’ or expanded by clicking the category label.

For a MeasurementSet, the categories are:

• MS and Visibility Selection
• Display Axes
• Flagging Options
• Basic Settings
• Axis Drawing and Labels
• Color Wedge

### MS Options — Basic Settings

The Basic Settings roll-up is expanded by default. It contains entries similar to those for a raster image, Data Display Options - Basic Settings). Together with the brightness/contrast and colormap adjustment icons on the Mouse Toolbar of the Display Panel, they are especially important for adjusting the color display of your MS.

The available Basic options are:

• Data minimum/maximum

This has the same usage as for raster images. Lowering the data maximum will help brighten weaker data values.

• Scaling power cycles

This has exactly the same usage as for raster images (see Data Display Options - Basic Settings). Again, lowering this value often helps make weaker data visible. If you want to view several fields with very different amplitudes simultaneously, this is typically one of the best adjustments to make early, together with the Colormap fiddling mouse tool, which is on the middle mouse button by default.

• Colormap

Greyscale or Hot Metal colormaps are generally good choices for MS data.

### MS Options— MS and Visibility Selections

• Visibility Type
• Visibility Component
• Moving Average Size

This roll-up provides choice boxes for Visibility Type (Observed, Corrected, Model, Residual) and Component (Amplitude, Phase, Real, or Imaginary).

Changes to Visibility Type or Component (changing from Phase to Amplitude, for example) require the data to be retrieved again from the disk into memory, which can be a lengthy process. When a large MS is first selected for viewing, the user must trigger this retrieval manually by pressing the Apply button (located below all the options), after selecting the data to be viewed (see Field IDs and Spectral Windows, below).

Tip: Changing visibility type between ’Observed’ and ’Corrected’ can also be used to assure that data and flags are reloaded from disk. You should do this if you’re using another flagging tool such as autoflag simultaneously, so that the viewer sees the other tool’s new edits and doesn’t overwrite them with obsolete flags. The Apply button alone won’t reload unless something within the viewer itself requires it; in the future, a button will be provided to reload flags from the disk unconditionally.

You can also choose to view the difference from a running mean or the local RMS deviation of either Phase or Amplitude. There is a slider for choosing the nominal number of time slots in the ’local neighborhood’ for these displays.

(Note: Insufficient Data is shown in the tracking area during these displays when there is no other unflagged data in the local neighborhood to compare to the point in question. The moving time windows will not extend across changes in either field ID or scan number boundaries, so you may see this message if your scan numbers change with every time stamp. An option will be added later to ignore scan boundaries).

• Field IDs
• Spectral Windows

You can retrieve and edit a selected portion of the MS data by entering the desired Spectral Window and Field ID numbers into these boxes.

Important: Especially with large MSs, often the first thing you’ll want to do is to select spectral windows which all have the same number of channels and the same polarization setup. It also makes sense to edit only a few fields at a time. Doing this will also greatly reduce data retrieval times and memory requirements.

You can separate the ID numbers with spaces or commas; you do not need to enter enclosing brackets. Changes to either entry box will cause the selected MS data to be reloaded from disk.

If you select, say, spectral windows 7, 8, 23, and 24, the animator, slice position sliders, and axis labeling will show these as 0, 1, 2, and 3 (the ’slice positions’ or ’pixel coordinates’ of the chosen spectral windows). Looking at the position tracking display is the best way to avoid confusion in such cases. It will show something like: Sp Win 23 (s 2) when you are viewing spectral window 23 (plane 2 of the selected spectral windows).

Changes to MS selections will not be allowed until you have saved (or discarded) any previous edits you have made (see Flagging Options -- Save Edits, below). A warning is printed on the console (not the logger).

Initially, all fields and spectral windows are selected. To revert to this ’unselected’ state, choose ’Original’ under the wrench icons next to the entry boxes.

See MeasurementSet Visibility Selections for an example showing the use of the MS and Visibility Selections controls when viewing an MS.

### MS Options — Display Axes

This roll-up is very similar to that for images: it allows the user to choose which axes (from Time, Baseline, Polarization, Channel, and Spectral Window) are on the display and the animator. There are also sliders here for choosing positions on the remaining axes. (It’s useful to note that the data is actually stored internally in memory as an array with these five axes).

Within the Display Axes rollup you may also select whether to order the baseline axis by antenna1-antenna2 (the default) or by (unprojected) baseline length.

See MeasurementSet Display AxesChanging the Axis of a MeasurementSet showing the use of the Display Axes controls to change the axes on the animation and sliders.

### MS Options — Flagging Options

These options allow you to edit (flag or unflag) MS data. The Point Tool and Rectangle Region Mouse Tools ( see Viewer Region Positioning) are used on the display to select the area to edit. When using the Rectangle Region tool, double-click inside the selected rectangle to confirm the edit.

The options below determine how edits will be applied.

• Show Flagged Regions...

You have the option to display flagged regions in the background color (as in TVFLG) or to highlight them with color. In the former case, flagged regions look just like regions of no data. With the (default) color option, flags are shown in shades of blue: darker blue for flags already saved to disk, lighter blue for new flags not yet saved; regions with no data will be shown in black.

• Flag or Unflag

This setting determines whether selected regions will be flagged or unflagged. This does not affect previous edits; it only determines the effect which later edits will have. Both flagging and unflagging edits can be accumulated and then saved in one pass through the MS.

• Flag/Unflag All...

These flagging extent checkboxes allow you to extend your edit over any of the five data axes. For example, to flag all the data in a given time range, you would check all the axes except Time, and then select the desired time range with the Rectangle Region mouse tool. Such edits will extend along the corresponding axes over the entire selected MS (whether loaded into memory or not) and optionally over unselected portions of the MS as well (Use Entire MS, below). Use care in selecting edit extents to assure that you’re editing all the data you wish to edit.

• Flag/Unflag Entire Antenna?

This control can be used to extend subsequent edits to all baselines which include the desired antenna[s]. For example, if you set this item to ’Yes’ and then click the point tool on a visibility position with baseline 3-19, the edit would extend over baselines 0-3, 1-3, 2-3, 3-3, 3-4, ... 3-nAntennas-1. Note that the second antenna of the selection (19) is irrelevant here – you can click anywhere within the ’Antenna 3 block’, i.e., where the first antenna number is 3, to select all baselines which include antenna 3.

This item controls the edit extent only along the baseline axis. If you wish to flag all the data for a given antenna, you must still check the boxes to flag all Times, Channels, Polarizations and Spectral Windows. There would be no point, however, in activating both this item and the ’Flag All Baselines’ checkbox. You can flag an antenna in a limited range of times, etc., by using the appropriate checkboxes and selecting a rectangular region of visibilities with the mouse.

Note: You do not need to include the entire ’antenna block’ in your rectangle (and you may stray into the next antenna if you try). Anywhere within the block will work. To flag higher-numbered antennas, it often helps to zoom in.
• Undo Last Edit
• Undo All Edits

The ’Undo’ buttons do the expected thing: completely undo the effect of the last edit (or all unsaved edits). Please note, however, that only unsaved edits can be undone here; there is no ability to revert to the flagging state at the start of the session once flags have been saved to disk (unless you have previously saved a ’flag version’. The flag version tool is not available through the viewer directly).

• Use Entire MS When Saving Edits?

"Yes" means that saving the edits will flag/unflag over the entire MS, including fields (and possibly spectral windows) which are not currently selected for viewing. Specifically, data within time range(s) you swept out with the mouse (even for unselected fields) will be edited.

In addition, if "Flag/Unflag All..." boxes were checked, such edits will extend throughout the MS. Note that only unselected times (fields) can be edited without checking extent boxes for the edits as well. Unselected spectral windows, e.g., will not be edited unless the edit also has "Flag/Unflag All Spectral Windows" checked.

Warning: Beware of checking “All Spectral Windows” unless you have also checked "All Channels" or turned “Entire MS” off; channel edits appropriate to the selected spectral windows may not be appropriate to unselected ones. Set "Use Entire MS" to “No” if your edits need to apply only to the portion of the MS you have selected for viewing. Edits can often be saved significantly faster this way as well.

Also note that checkboxes apply to individual edits, and must be checked before making the edit with the mouse. “Use Entire MS”, on the other hand, applies to all the edits saved at one time, and must be set as desired before pressing "Save Edits".

• Save Edits

MS editing works like a text editor in that you see all of your edits immediately, but nothing is committed to disk until you press “Save Edits”. Feel free to experiment with all the other controls; nothing but ’Save Edits’ will alter your MS on disk. As mentioned previously, however, there is no way to undo your edits once they are saved, except by manually entering the reverse edits (or restoring a previously-saved ’flag version’).

Also, you must save (or discard) your edits before changing the MS selections. If edits are pending, the selection change will not be allowed, and a warning will appear on the console.

If you close the MS in the viewer, unsaved edits are simply discarded, without prior warning. It’s important, therefore, to remember to save them yourself. You can distinguish unsaved flags (when using the ’Flags In Color’ option), because they are in a lighter shade of blue.

The program must make a pass through the MS on disk to save the edits. This can take a little time; progress is shown in the console window.

These settings can help optimize your memory usage, especially for large MSs. A rule of thumb is that they can be increased until response becomes sluggish, when they should be backed down again.

You can run the unix ’top’ program and hit ’M’ in it (to sort by memory usage) in order to examine the effects of these settings. Look at the amount of RSS (main memory) and SWAP used by the X server and ’casaviewer’ processes. If that sounds familiar and easy, then fiddling with these settings is for you. Otherwise, the default settings should provide reasonable performance in most cases.

• Cache size

The value of this option specifies the maximum number of different views of the data to save so that they can be redrawn quickly. If you run an animation or scroll around zoomed data, you will notice that the data displays noticeably faster the second time through because of this feature. Often, setting this value to the number of animation frames is ideal Note, however, that on multi-panel displays, each panel counts as one cached image.

Large images naturally take more room than small ones. The memory used for these images will show up in the X server process. If you need more Visibility Memory (below) for a really large ms, it is usually better to forgo caching a large number of views.

• Max. Visibility Memory

This option specifies how many megabytes of memory may be used to store visibility data from the MeasurementSet internally. Even if you do not adjust this entry, it is useful to look at it to see how many megabytes are required to store your entire (selected) MS in memory. If the slider setting is above this, the whole selected MS will fit into the memory buffer. Otherwise, some data planes will be ’grayed out’ (see MS Options - Apply Button), and the selected data will have to be viewed one buffer at a time, which is somewhat less convenient. In most cases, this means you should select fewer fields or spectral windows – see MS Options - MS and Visibility Selections. The ’casaviewer’ process contains this buffer memory (it contains the entire viewer, but the memory buffer can take most of the space).

### MS Options — Apply Button

When viewing large MSs the display may be partially or completely grey in areas where the required data is not currently in memory, either because no data has been loaded yet, or because not all the selected data will fit into the allowed memory (see Max. Visibility Memory above). When the cursor is over such an area, the following message shows in the position tracking area:

   press 'Apply' on Adjust panel to load data


Pressing the Apply button (which lies below all the options) will reload the memory buffer so that it includes the slice you are trying to view.

The message No Data has a different meaning; in that case, there simply is no data in the selected MS at the indicated position.

For large MeasurementSets, loading visibility data into memory is the most time-consuming step. Progress feedback is provided in the console window. Again, careful selection of the data to be viewed can greatly speed up retrieval.