# Appendix D. vis

Revision History
Revision 1.22016 Apr 21jbs
Describe the new rainbow command
Revision 1.12015 Oct 22klw
Revision 1.02014 Mar 20jbs
Initial Docbook revision

## D.1. VIS Commands

Commands can be concatenated together by delimiting them with semi–colons (;). The available commands and plotting input are summarised in the following two tables. More detailed explanations of each command are listed at the end of this appendix.

CommandFunction
arraySpecifies which antennas to use
bellsToggles the bells and whistles (border accessories)
cagetShow the ID number and time stamp of last datum received
concatConcatenates cycles together
cyclesRestricts the CAGET database (default/max=5000)
defineAssigns a monitor point to a user definable quantity
dumpSends a hardcopy of the display to the printer
expertMake assumptions about experience of the user
filterToggles data filtering (doesn't plot bad data)
forwardMoves 1 screen' forward in time
frequencyApply polarisation correction (use with stokes)
gridPlots a faint background grid
historyControls the amount of data (in time) that is displayed
helpAccesses the on-line help information
labelsShow data only (no axes). Only used for remote observing.
linesForces lines to be drawn between plotted points
listList all the sources on record
lockLock the left hand edge of a time based graph
measureMeasures the coordinates of a pixel
onsourceCauses data to be plotted, only when the array is on-source'
phaseToggles phase-tracking
printPrint a hard copy of the current page in CAMON
polcalUse with stokes command. Calibrate stokes data to be plotted.
quitExits the program gracefully
rainbowToggles the use of a rainbow colour map for the baselines, according to baseline length order.
recallRecalls a previously saved state
redrawClears and redraws the graph(s)
refSpecifies a reference baseline
resetResets the VIS display to the original state
rewindMoves 1 screen' back in time
saveSaves a graphics state
scaleSets the scale of a graph (to scale Time, use history)
sctypeOnly plot data of that scan type
selectSpecifies the baselines to be displayed
sortOrders the baselines into length order
sourceCauses only data from the specified source to be shown
squaredForces aspect ratio to 1
statusDisplays the current status of the VIS program
stokesEnable display of Stokes parameters (see polcal
suppressKills non-normal baselines
timeSets the time standard/zone used
uv:Plots a quantity on the uv plane
verboseMessage reports lengthen.
zoomUse mouse or cursor to scale a plot

InputAxis Label
aamplitude
bbaseline
cclosure phase
ddelay
eelevation
ffrequency
ggain (power)
hhour angle
iimaginary
j--
kparalactic angle
l1-way LO phase
m--
nCAGET cycles
o--
pphase
qtied array coherence
rreal
stied array amplitude
ttime
uu
v v
ww
xright ascension
ydeclination
zazimuth

array [1|2|3|4|5|6]

Specifies which antennas constitute a valid array. Subsequent use of the select command will automatically exclude the non-selected antennas. If no argument is specified, the default (all antennas) is restored. Related commands: onsource. Examples: VIS> array 1235 – excludes antennas 4 and 6. If select aa was issued, only baselines 12AA, 13AA, 15AA, 23AA, 25AA and 35AA would be selected. VIS> array – restore the setting to the default (all antennas). Note this is equivalent to VIS> array 123456.

bells [on|off]

bells puts additional information around the borders of the graphs. If no argument is specified, then the state will toggle.

caget

Displays a one line message about the current caget cycle. It may be used as a diagnostic and is of little use to the observer. It is useful when the underlying data acquisition process seems to have failed. The caget command provides a very quick means of examining the last recovered cycle, and you can watch for increments as a sign of a properly working system. Of course, if the Compact Array is not operating the cycles won't increment. The data the caget command presents is also shown in the output of the status command.

concat [on|off]

May be used for concatenating cycles together. Its primary use is to examine data from similar sources without interspersed spaces. concat only affects data in which integration cycles (option n') is one of the axes. concat requires suspend to be turned on. Example: use source to select only your calibrator, use suspend to halt updating, set the history to 12 hours and, using concat, display a tad graph.

cycles c

Allows the user to control how many cycles of history will be looked at. Primarily used for speed considerations or software diagnosis.

dump [b&w]

Creates a PostScript file of the current graph. It will be saved as ~/vis.ps. The file will automatically be spooled to a printer. Default is colour PostScript. You can also ask for black and white plots: use the argument b&w.

Related commands: print.

exit

Exit the program.

expert [on|off]

Enable (on) or disable (off) display of standard information. For example, polarisation visabilities are usually not displayed, but can be by enabling expert mode. Another expample is the aspect ratio of plots which will be 1:1 for a non-expert user

Related commands: stokes, select.

filter [on|off]

Suppresses inappropriate data from being plotted. The default is ON. Note that onsource will not work if filter is OFF. If no argument is specified the current state will toggle.

forward

Shifts the history forward in time by one screen-width'. It will not let you set the time scale into the future (giving an appropriate warning). See also history.

frequency [on|off]

Normalise the phases for the observing frequency. That is, it divides astronomical phase by frequency in GHz and plots result as round trip phase. Shows how much LO phase noise is leaking into the astronomical phase. If no argument is specified, the current state will toggle. Related commands: phase.

grid [on|off]

Plots a faint grid behind the graph (no argument toggles the grid on and off).

history HHhMMmSSs [HHhMMmSSs]

Allows the user control over the size of the horizontal axis (e.g., time or the time depth' of a graph which does not have time as one of its axes). VIS allows you to specify a second argument in the same format that represents the offset from the current plot time. If the lock command is activated, the first argument of the history command is ignored. The only acceptable formats are those with hms' or :' delimiters, using the latter, the first numeric field is hours. Related commands: forward, rewind, zoom. Examples: VIS> history 10m 1h30m – to look at 10 minutes of data that ended 1 and a half hours ago. VIS> history 25m or VIS> history 0:25 – the most recent 25 minutes of data displayed. You cannot use scale to adjust a time axis.

labels [on|off]

Turn on/off labels on the graph. No argument toggles the state on/off.

lines [on|off]

Ordinarily, points are only joined by lines if they have time specified as one of the axes. By turning lines on, you force connecting lines on non-time based plots. If no argument is specified, the state will toggle.

list

This command will cause VIS to search through all its available records and print a listing of the sources it can find. For surveys, this may be a lot!

lock [on|off]

This command locks the graphical display to a time. This will cause all subsequent plots to access data back to this time, regardless of the history command. This command is very useful in stopping data from rolling' off the end of a chronological display. By setting it at the start of a run, the incoming data will continue to squeeze in, so that at the completion, the display will have the entire run. To use this mode, it must be started when the telescope is off source. If no argument, the state will toggle.

measure [top|middle|bottom]

This enables you to get a precise measurement of any point on a graph. As there may be more than one graph on the screen at any given time, you must specify which one, using top, middle or bottom. If there are two graphs, middle is not valid, and if there is only one, then no arguments should be specified. Once entered, the program will instruct you to click at the appropriate point in the selected graph. This may be done with the mouse, or the cursor keys. To select a point, any mouse button or any non-cursor key may be used. The coordinates of the selected point will be displayed appropriately.

onsource [on|off]

When onsource is activated and filter is off, only data obtained while the antennas specified by the array command are on source will be plotted. That is, slew time, antenna drive failure, etc. will be blanked out. If no argument, the state will toggle.

phase [on|off]

Phase tracking. This prevents sudden 360 degree phase jumps caused by VIS trying to contain the astronomical phase within the -180^\circ to 180^\circ range. The algorithm works by comparing each datum with the datum immediately before it. If a jump of more than 270^\circ is detected, VIS will move (360-jump)^\circ in the other direction. If no argument is specified, then the phase tracking state will toggle.

polcal [on|off]

Apply the latest polarisation calibration (no argument will toggle the state). The calibration applied is in the file at\$log:leakage.log. If no argument, the state will toggle. Related commands: stokes.

quit

Exits the program gracefully.

rainbow [on|off]

vis sorts baselines into length order before plotting them, and assigns a colour to each rank, and this colour-rank mapping is always the same, regardless of the actual baseline length it represents. Normally, the colour-rank mapping is quasi-random, and there isn't an intuitive way to identify the comparitive rank of two different colours. Using the rainbow on command, you can make vis map the baseline length ranks to a more intuitive colour scheme. You can toggle this colour mapping by not giving an argument.

recall [name|list]

Recovers data from the time when a save command to the same name was entered. If the requested name is list, then all the saved states that are remembered are listed - BE WARNED: this may be a lot!

redraw

Replots the screen. Useful after resizing a window.

ref [##XX]

Sets a reference baseline. All data will have the corresponding point of the reference baseline subtracted from them. The reference baseline may be specified as the full 4 character designation (e.g., 34CC). To remove the reference baseline, enter ref without any arguments.

reset

Returns VIS to its default (startup) settings.

rewind

Causes the history offset to be increased by the history value. This effectively causes a move of one screen-width' back in time. Useful for use with the lock command. Not useful with non-chronological graphs. Related commands: forward.

save name

Remembers the setting of the current display. May be recalled using the recall command. name can be a maximum of 32 characters.

scale [qty] [min max]

The scale command lets you scale vertical axes manually. The program keeps track of which quantity has been manually set rather than the actual graph axis. Thus it is possible to scale the amplitudes, look at the uv coverage, and then return to the amplitudes with the old scaling remembered. To invoke this feature you need to specify the quantity to scale and the minimum and maximum values. It is possible to reverse the max. and min. but the graph will be inverted. To cancel manual scaling, enter scale without any arguments. This will not automatically redraw the screen (use redraw). To cancel the scaling for only one quantity, enter scale qty (the screen will be redrawn in this case). WARNING: Setting the scales can be a trap as you might not see data outside the scaled region that would otherwise concern you. Related commands: history. Examples: scale a 0 1 – set amplitude scale between 0 and 1. scale a – set amplitude to autoscale.

select[#][#][x][x] [,[-][#][#][x][x]]

Allows you to specify which baselines are displayed for the majority of quantities (where antenna based quantities are plotted the array command should be used). The arguments are full or partial baseline specifications. Baseline specifications can be negated with a minus (-) sign. There is a maximum of 15 baselines that can be plotted simultaneously. See also the array and suppress commands. Examples: VIS> select 25aa – select (plot) only the baseline 25AA. VIS> select bb,-4 – plot all the frequency 1, YY polarisation baselines, but exclude those baselines that involve antenna 4.

sort [on|off]

Allows traces to be sorted in logical (12,13,14,...) order – off, or baseline (shortest to longest) order – on. This may be useful on an amplitude vs baseline (a–b) plot. No argument will toggle the value.

source [name]

By specifying a name, VIS will only plot data obtained on a scan with a source of that name. The remainder will be left blank. It may be deactivated by typing source with no arguments.

squared on|off

For expert users only, this command gives the option of forcing both axes to use the same scale. It is not particularly suitable for graphs involving time or cycles. It may be useful for Real-Imaginary or uv plots. It has the potential of messing-up the display. Use with caution.

status

Shows you the current status of VIS. It indicates what options have been selected, any scaling information and how much data is being displayed.

stokes [on|off]

Enable the stokes parameters (I, Q, U and V) instead of conventional linear polarisations (AA, BB, AB, BA). Stokes parameters can then be selected using the select command. Related commands: select, polcal and expert.

suppress [on|off]

Suppresses non-standard phases such as 34AD or 11AA (no argument will toggle the value). If you turn the suppression off VIS expects that you are an expert user – the novice may cause it to crash!

suspend on|off

VIS typically updates the screen as new data comes in. It is possible to suspend these updates and thus is especially useful when looking back through the history.

time [AEST|UT|EDST|GMST|LST]

Change the time standard used to plot the labels on a time axis. (UTC & GMT are converted to UT)

uv:a

Plot the amplitude on a uv grid. The grid is then displayed as a grey-scale 2D plot. uv:a only works for a specific source (see source), with onsource tracking (onsource) and suspended updating (suspend). It will not work under AB,CD, etc. baselines. All AA or CC polarisations are suggested. It will conform to any scale commands, but the units of u and v are in grid pixels. Amplitude can also be scaled.

verbose [on|off]

Explanations of every command executed will be given if the state is on. If no argument is specified, the state will toggle.

zoom [top|middle|bottom] [x][y]

This enables you to use the mouse/cursor in order to scale a graph. As there may be more than one graph on the screen at any given time, you must specify which one, using top, middle or bottom. If there are only two graphs, middle is not valid, and if there is only one, then no arguments should be specified. The second set of arguments determines whether the zoom will be on the x-axis, y-axis or both (default).

The program will instruct you to click at the lower/left corner of the region to zoom in on, followed by a request for a second click at the upper/right corner. This may be done with the mouse, or the cursor keys. To select a point, any mouse button or any non-cursor key may be used. When the above sequence has been performed, the window will be scaled and redrawn appropriately.

Note that, if you intend to zoom on the time axis, the suspend command must be used first to prevent rapid screen updating. zoom will not work on the XDISP display.

To un-zoom' use the scale command. Examples: VIS> apd-t or tdpa – select three graphs (Amplitude, Phase and Delay) versus Time. To have a closer look at the phases: VIS> zoom m y gives mouse control over the middle (centre) graph – namely the phase' plot. It will allow the selection of a new vertical scale (specified by the y'). Then use VIS> scale p` (i.e., with no limits) to reinstate auto-scaling on the phase display.