Interactive Channel/Baseline Flagging - PGFLAG

The pgflag exists because tvflag can only reliably run on screens that have an 8-bit colour depth, which is a limitation few users are able to stomach. In almost all other respects, pgflag can do the same things that tvflag can do, and it adds further features as well.

The pgflag display is that of a waterfall plot, with channel across the x-axis and time along the y-axis, and it uses greyscale colour to represent amplitude, with black being low amplitude, and white being high amplitude.

The only requirement for running pgflag is that the machine you are running it from (either locally or remotely) has the PGPLOT libraries installed, and has an interactive PGPLOT device, such as /XSERVE.

The input parameters to pgflag are straightforward, and only the most useful ones are described here:

• vis: The name of the visibility data-set to be flagged.
• device: The PGPLOT device to use as the plot window. pgflag will complain and exit if the device supplied is not interactive.
• select: The usual visibility data selection parameter.
• stokes: The usual Stokes polarization selection parameter. Task pgflag can deal with only a single polarization per run, so if this polarization is not specified here it will average all available polarizations together before display. While unusual, this is moderately useful. Assuming the data-set contains all four linear polarizations,

  	stokes=xx,yy
  

  will produce a Stokes-I display. On the other hand, no selection (i.e. allowing pgflag to average XX, YY, XY and YX) will produce a quantity which is not physically meaningful, but will still allow you to make a quick check for interference and outliers.
• line: The normal visibility linetype parameter. Unlike tvflag, pgflag does support spectral averaging.
• mode: This determines the quantity to be displayed. Possibilities are amplitude or phase.

Typical inputs are:

PGFLAG
vis=vela.line	Specify visibility dataset
device=/xs	Specify PGPLOT device
mode=amp	Display amplitude
stokes=xx	Select first linear polarisation, or
stokes=yy	Select second linear polarisation
line	Unset for all channels

After invoking pgflag a PGPLOT window will be created with the main screen. This screen has a title bar along the top with descriptions of some of the important keys, and an area that displays data information. In the centre is the main waterfall plot, that has channels along the x-direction and time along the y-direction. Gaps in time in the data are shown by dark gaps across this plot. A wedge is displayed both on the bottom of the plot and on the right edge, and these wedges show the data averaged over time (the bottom wedge) and over channels (the right wedge). A colour wedge is also displayed that shows the minimum and maximum values and how the colours represent the amplitudes.

You now work with pgflag by selecting data with the mouse or keyboard, and then performing actions on the selection. These actions are all initiated by key presses, and these will be described here.

Selection of data works as a two-corner model. The left mouse button controls the location of one corner of the selection box, and the right mouse button controls the location of the other corner. Once two corners have been defined, a green box will be shown that covers the data between those two corners. Further mouse clicks will move the appropriate corner and the box will be redrawn. The only other way to initially make a selection is to press M twice in succession; this will select an area centred on the sample with the highest amplitude.

Once a selection has been made, it can be manipulated using the keyboard. By pressing the c key, the selection box will be extended to encompass all the channels currently being displayed on the screen; hitting the c button again will extend the selection to encompass all channels present in the data - this is useful if you have zoomed in so not all channels are visible at once. Hitting the t key extends the selection box to encompass all the visible times, and pressing t again makes the box cover all available times. To clear the selection, press C.

Other keys act upon the display. The z key zooms the main display in so that only the visibilities within the current selection are displayed, while Z unzooms to display all available data. While zoomed in to a particular region, the visibilites shown can be changed by pressing h which moves the zoom window left (to a lower channel range) by half the range shown on the plot, while H moves the window left by the entire range. For example, if the x-axis is showing channels between 20 and 40, then pressing h will make the window show channels between 10 and 30, whereas pressing H will make the window show channels between 0 and 20. Similar functionality can be found by pressing the l and L keys to move the window right, the j and J keys to move the window down, and the k and K keys to move the window up. Old-school readers may recognise this as the cursor movement keys for the editor vi. While zoomed in, the display will indicate if there is further data in a particular direction by displaying a green arrow next to the main plot area for each possible scrolling direction. The plot can also be unzoomed in a specific direction: pressing s will unzoom to show all the available channels, and S will show all the available times.

The currently displayed baseline is changed with the n key - which displays the next available baseline - and the p key - which displays the previous available baseline. The selection and zoom region is preserved while changing baselines.

The display can also be changed to enable easier identification of bad data. Pressing the x key will subtract the average channel values (which are shown in the bottom wedge) from each visibility in the main plot, essentially correcting for any bandpass effects. While this subtracting is in effect, the bottom wedge will be outlined in red. To reset this behaviour press x again - the wedge will return to being outlined in white. The average time values (shown in the right wedge) can be subtracted by pressing the d key in the same manner.

The colour scaling can be changed in various ways. To select for yourself the range to use, press the , (comma) key, then press the left mouse button within the colour wedge to set the value to be assigned as white (the maximum value), or the right mouse button to set the value to be assigned as black (the minimum value). Regardless of whether the displayed is zoomed or not, the same colour scale will be used, and it is determined from all the available unflagged data on the currently displayed baseline. To use only the currently displayed data to set the colour scale, press the [ key, or to use only the currently selected data, press the ] key. Normally, changing baselines will cause the amplitude scale to be recomputed, however the current colour scaling can be locked by pressing the ; key. To reset the colour scale and allow pgflag to determine it automatically, press the . (full stop) key.

There are many flexible ways of flagging the data with pgflag, the simplest of which is by pressing the f key to flag as bad the visibilities within the current selection box on the current baseline only. Pressing the g key will flag the selected visibilites as good. Almost any flagging operation can be reversed by pressing the u key; no flagging is applied to the data itself until the task pgflag ends. Be aware though that pgflag only allows the very last flagging action to be undone with the u key, so successive presses of u will in fact undo the undo.

Pressing the F key will mark the selected visibilities as bad on all the baselines in the file, while G will mark them as good on all baselines. The currently displayed baseline is shown at the top of the plot in the form A-B where A and B are both antenna numbers. To flag the selected visibilities as bad for antenna A, press the 1 key (the ! key marks the selection as good), while to do it for antenna B, press the 2 key (or @ to mark as good).

It is also possible to remove all flagging actions performed by this session of pgflag on the currently displayed baseline by pressing rr. It is for safety that the r key must be pressed twice successively, as this operation cannot be undone. Pressing RR will remove all flagging actions on all baselines. Press ? to make pgflag print some information about how many flagging operations have been made during this session.

To exit pgflag and save all the flagging, press the q key. If you want to exit pgflag without applying any of the flagging, press the a key. You will be prompted to ensure that you don't exit the task accidentally.