The visplot window¶
Warning
This page is a working draft for the visplot test release. The
control-by-control description will be rewritten after the planned
reorganisation of the configuration panel; the sections a tester
needs first – A commissioning workflow, Reporting a problem and
Scope, explicitly – are current.
visplot is the cubevis replacement for CASA6’s
plotms (visibility scatter/line plots) and msview (2-D raster
display of visibility data). It unifies both plot styles into a single
tool that reads MSv2 measurement sets and MSv4 / Processing Set data
and renders them interactively, backed by Datashader for large-dataset
aggregation.
This page is aimed at astronomers testing the release. It assumes no
familiarity with the cubevis internals.
Status of this document¶
Updated 2026-11-17. Current: the Grid layout, Large selections, A commissioning
workflow, Reporting a problem and Scope, explicitly. Installing,
launching visplot and its arguments are in Starting visplot. The Layout tour still describes the controls in
outline only; every control explains itself in the status area at the
bottom of the window while the pointer is over it, and where there is
more to read (a ⓘ) pressing ? opens it, in visplot controls, in full:
see Help in the window.
Note
Jupyter notebooks are not yet supported. Run visplot from a
plain interactive Python or CASA6 session (ipython, or a casa
prompt). visplot.notebook() exists but raises
NotImplementedError saying so.
Layout tour¶
The preview window is divided into three regions:
┌──────────────────────────────────────────────────────────────┐
│ Toolbar: Plot, Reload, layout, height, presets, Export PNG │
├──────────────┬───────────────────────────────────────────────┤
│ Sidebar │ Panel A │ Panel B (One / Side by Side / │
│ (collapsible)│ │ Over / Under) │
│ │ each panel: a raster or a scatter │
├──────────────┴───────────────────────────────────────────────┤
│ Status line, and help for the control under the pointer │
└──────────────────────────────────────────────────────────────┘
Toolbar¶
Plot ▶ — run the query against the selected data and (re)render. It turns orange when something has been changed (a selection, an axis, a gear-tab setting) that is not drawn yet, and green again once the plot shows it
Reload ↺ — force re-read from disk (equivalent in spirit to
plotms’s Reload checkbox, used when the MS has changed on disk)⟨ Sidebar — collapse/expand the control sidebar
Presets — one button each; a preset sets both panels and plots:
vplot — Baseline vs Time amplitude raster, Amplitude vs Time scatter
radplot — the same raster, Amplitude vs UV Distance scatter
Waterfall — Time vs Channel amplitude, panels one above the other
All-BL — the same axes with every selected baseline in one image and each cell showing the largest amplitude among them (the AIPS FTFLG view), with Amplitude vs Channel below: a quick survey for interference
Z-Score — Baseline vs Time colored by Z-Score, to spot outliers
φrms·t, φrms·ν, φrms·uv — Phase RMS against time, against frequency (channel) and against UV distance. The raster shows which baseline and when (or at which channel); the scatter shows the same values for all baselines. These three also put the Phase slope and window controls back to their defaults
φ Wfall — Time vs Channel phase waterfall
Ant×Ant — the antenna × antenna matrix (AIPS LISTR’s): one cell per baseline, averaged over time and channels, mirrored so an antenna that is bad on every baseline shows as a whole row and column; the diagonal holds the autocorrelations when Autocorrelations is Include. Hover a cell for its baseline. Flag on Baseline × Time once the antenna is found (a flag box on the matrix is refused)
Spectrum — two scatter panels, Amplitude above Phase against frequency, each scan averaged (AIPS POSSM): the bandpass shape, edge channels and a phase slope across the band. Read one baseline at a time: tick one, or step with Baseline ◀ ▶ (which, like Antenna ◀ ▶, skips baselines with no data in the selected field and SPWs; the tables show those dimmed, marked “(no data)”)
Time series — the same pair against time, all channels averaged (AIPS VPLOT): phase drifts and jumps, amplitude dropouts. Read one baseline at a time, as for Spectrum
Layout — One, Side by Side, Over / Under, Grid (the first panel repeated for each baseline, antenna, SPW, field, scan or correlation, page by page;
layout="grid",iterate_by=). Each preset switches to the arrangement that suits it unless Pin layout (configuration panel, section Panels;pin_layout=True) is tickedHeight — the height of each row of plots: default (the layout’s), fit (share the window), or a size in pixels (
row_height). Applies at once and stays when the layout or preset changesGear (each panel’s toolbar) — opens that panel’s configuration tab in the sidebar; changes there apply when Plot ▶ is pressed. A successful Plot closes the tab unless its Pin checkbox (left of the tab’s ✕) is ticked, which keeps it open to try one setting after another
Help — holding the pointer over any toolbar or sidebar control shows what it does in the status area at the bottom; the ? Help button opens visplot controls, in full. See Help in the window, below
Pan / Zoom / Reset (shared across both panels when both are shown). Wheel (scroll) zoom is off until its toolbar button is clicked, so a trackpad or mouse-wheel scroll over a plot scrolls the page
Describe this plot (each figure’s toolbar, the page icon beside the gear) — opens a page describing that plot and the
visplot(...)call that reproduces it; see Reporting a problemFlag / Unflag boxes (each figure’s toolbar) — draw a box to propose flags; the Flagging section of the configuration panel holds the filters, reaches, undo / redo, the report and writing to the MS
Panels¶
The raster panel renders a 2-D image (e.g. amplitude as a function of time and channel) using Datashader aggregation, with pan/zoom that resamples the cached aggregate rather than re-querying the backend. The scatter panel renders point clouds (e.g. amplitude vs. UV distance), also Datashader-aggregated, with per-layer alpha blending when multiple quantities or correlations are overplotted.
When both panels share the same X quantity (e.g. both are plotted against time), their X ranges are linked, so panning one pans the other.
Grid¶
Grid (the fourth Layout button, layout="grid") draws one plot many
times over: once for each baseline, antenna, SPW, field, scan or
correlation in the selection, as small plots on a page, paged through –
plotms’s iteration (iteraxis, gridrows, gridcols), AIPS
VPLOT and POSSM, difmap’s vplot. The point is to compare: the one
baseline or antenna that looks unlike its neighbours.
What is drawn is the grid’s own panel, ⚙ Grid panel in the sidebar’s Grid section (or the gear in the grid’s toolbar): the same choices as a panel’s gear tab, raster or scatter. It starts as a copy of the first panel; a preset pressed in Grid sets it.
grid_panel=sets it from the start.Iterate by chooses the axis, and then a second one (Antenna, then SPW: each antenna’s SPWs in turn). The plots are of the current selection only: select five antennas and iterate by antenna for five plots. Rows and Cols set a page’s size; ⏮ ◀ ▶ ⏭ in the toolbar page through, and Play steps through the pages (Pages/s, Loop). When everything fits on one page, Play steps the sidebar’s stepper instead (the next antenna, say).
Scale: common (default) gives every plot the same axes, drawn once along the top row and down the left column, and a zoom in one plot zooms them all; per cell gives each plot its own axes and zoom. Color (rasters): one color range for the page (default), for the whole grid, or per plot. A scatter plot is shaded by its own density.
Hover gives that plot’s value under the cursor, as in a panel.
Tap a plot to open it in the One layout with the sidebar set to its selection. Flag there as usual. Grid again brings back the grid and its selection; flags added or written meanwhile show at once, with no need to press Plot. Flagging is not done in the grid’s plots themselves.
Export PNG in the toolbar writes the page shown;
plotfile=withlayout="grid"writes pages without a window (exprange).
The selection is read once for all the plots of a grid and held in memory, within the frame cache (see Large selections). A grid too big for that still works: each plot then reads its own rows, more slowly.
Help in the window¶
The status area at the bottom of the window shows what the last Plot or flagging step did, warnings, and – while the pointer is over a toolbar or sidebar control – a short description of that control.
ⓘ means there is more. A description or a warning that has a longer explanation in this documentation ends with a ⓘ (for a description cut off by the size of the area, at its bottom right). Text without a ⓘ is all there is.
? opens it. Pressing ? anywhere in the window opens the explanation of what the status area is showing, in a separate browser tab (the same one each time): the description of the control under the pointer, or a warning when the description has no ⓘ. Over text without a ⓘ the key does nothing.
Click a warning’s ⓘ to open its explanation. (For a control’s description use the key: moving the pointer onto the ⓘ leaves the control, and its description goes.)
In a text box (Scan, Time range, UV range, the antenna boxes) ? is typed into the box. Scroll the window or press Esc to leave the box, then press the key.
The explanations are the documentation of the installed version of
cubevis(the latest documentation for a development version). visplot controls, in full lists them all; the ? Help button opens it.
The window in more than one tab¶
One visplot session drives one browser tab at a time. Opening its
address in a second tab (or reloading) moves the session there: the
first tab dims under Open in another tab and stops updating, with its
plots left as they were. It does not take the session back by itself,
not even when the computer wakes from sleep; its Use this tab button
does, and the other tab then shows the same notice. A request that was
still running for the first tab finishes, but its result is not shown
in the new one: press Plot there.
This is unrelated to the remote-session indicator (“Reconnecting to host … 12 s”), which means the connection to a remote kernel is being restored.
When the window loses its connection (the computer slept, the network
dropped), it reconnects by itself when the connection returns; a step
that was in progress (a Plot, a flag) is completed once, not repeated.
After visplot has ended, the window says so: any request is answered
with “This visplot session is closed” instead of plotting.
Large selections¶
A scatter panel holds every selected sample while it draws. A selection
estimated to need more than 70 % of the memory available is loaded
anyway (it may be slow while the system swaps) and noted in the log.
Where swapping is not wanted – a shared cluster node, a machine without
swap – CUBEVIS_VISPLOT_MEMORY_GUARD=<MB>, set before visplot
starts, sets a limit: a scatter estimated to need more (about 110 bytes a
sample) is refused before anything is read, with a message saying what
to narrow. Plot reports it; a panel whose selection is too large when
the window opens stays empty, with the message in the status area. To
get under the limit, select less (fewer fields, scans, spectral windows,
antennas or correlations, a shorter time range), average over time or
channels (the scatter panel’s Averaging), or use a raster, whose size
does not grow with the data. off or no value means no limit. (CUBEVIS_VISPLOT_FRAME_CACHE_MB is a
different setting: how much read data is kept for redrawing.)
The Grid layout holds the rows of its selection in memory, counted in that
frame cache: while it holds them, the cache may run past its size by a
quarter, no more (CUBEVIS_VISPLOT_GRID_OVERFLOW=<percent> changes the
share; 0 keeps it within the size). A grid whose rows do not fit is
drawn plot by plot instead, reading each plot’s own rows.
A commissioning workflow¶
A first pass over a new observation, in the order the views are useful. Each step says what the view is for; the preset buttons set both panels at once.
Survey. Which antennas, baselines and times are wrong?
Ant×Ant – one cell per baseline, averaged over the selection. An antenna that is bad on every baseline is a whole row and column.
Z-Score – Baseline × Time colored by how unusual each sample is for its own baseline; isolated bright cells are outliers in time.
φrms·t / φrms·uv – phase stability per baseline over time, and against baseline length: a rise with length is the atmosphere, one high baseline is an antenna.
vplot – amplitude per baseline over time: dropouts, bad scans.
On circular-feed (RR / LL) or linear-feed data, a problem in one hand only shows when the raster shows that hand: set a raster’s Correlation shown to Parallel hands for a first look at both, or put RR and LL side by side.
On data that are not yet amplitude calibrated, keep Autocorrelations at Exclude (the default); otherwise they set the scale and every cross-correlation reads as zero.
Confirm on one baseline, stepping with Baseline ◀ ▶ (or Antenna ◀ ▶ for all baselines to one antenna):
Waterfall and φ Wfall – time × channel amplitude and phase. Narrow features in frequency or short ones in time are interference; in phase, stripes across frequency are a residual delay and stripes in time a rate.
Spectrum (scan-averaged, like AIPS POSSM) and Time series (channel-averaged, like VPLOT) – the bandpass, edge channels, phase slopes, jumps and drifts.
All-BL – every selected baseline in one waterfall (AIPS FTFLG), showing the largest amplitude: interference common to many baselines.
Narrow the data with Scan, Time range and UV range (Data section) to look closely at one stretch of time or baseline length; the status line lists whatever is in force.
Flag on the view that shows the problem best, with a box from the panel’s toolbar. Flag reaches (Flagging section) widen each box to all baselines of the antenna, all channels, all correlations, all spectral windows, the whole scan or all fields, as AIPS TVFLG’s scopes do; Preview each proposal shows what a box will flag before it is added. Undo, redo and Describe pending flags work on the list of pending operations.
Commit. Nothing is written until Write to MS, which first saves a backup of the flags it changes. Export the pending flags as JSON to keep a record or apply them elsewhere.
Times are UTC throughout (axes, readout, Time range box); the Time labels switch (Panels section) changes the axes to elapsed time.
Reporting a problem¶
Each plot’s toolbar has a Describe this plot button (a page icon,
beside the gear). It opens a page with everything that went into that
plot: the data set and how it was opened (local or remote kernel), the
selection in full, the axes and every setting that shaped the image, the
color scaling, the displayed range and zoom, the number of pending
flags, the versions of cubevis (with its git commit when run from a
checkout) and the main libraries, and the visplot(...) call that
reproduces the view, with a Copy button. The same page is available
from Python as VisibilityPlotter.describe(slot="A", html=True).
When reporting a problem, please include:
the summary page of the panel concerned (save it, or paste its text),
a screenshot, or a PNG from Export PNG,
what you expected to see, and – if you have it – the
plotmsor AIPS plot of the same data that shows it.
The summary lists what the call does not reproduce (zoom, pending flags, scatter color settings, theme), so say if any of those matter.
Checking against plotms¶
The goal here isn’t astronomical analysis — it’s confirming that
visplot is reading the MS correctly and rendering
something that resembles what plotms/msview would show for the
same selection. A reasonable sequence:
Amplitude vs. time, all correlations. This is
plotms’s default view (Amp vs. Time) and a good first sanity check — you should see the self-calibrated TW Hya continuum visibilities with no obvious dropouts or striping that would indicate a reader bug.Equivalent
plotmscall for comparison:plotms(vis='twhya_selfcal_contsub_ms', xaxis='time', yaxis='amp', field='5', correlation='XX,YY')
Amplitude vs. UV distance. Useful because the expected shape (a roughly declining amplitude envelope with baseline length, for a resolved but compact source like TW Hya) is easy to eyeball.
plotms(vis='twhya_selfcal_contsub_ms', xaxis='uvdist', yaxis='amp', field='5', correlation='XX,YY')
Raster: amplitude over time × channel. Compare against
msview’s 2-D raster display, or aplotmsiteration over channel. Flat, uniformly-colored channels with no residual line structure would be consistent with the continuum subtraction having worked (the line was removed upstream, inuvcontsub, before this MS was written).
TODO(screenshot): Amp vs. Time, both correlations, TW Hya field 5.¶
TODO(screenshot): Equivalent plotms view, for side-by-side
comparison.¶
TODO(screenshot): Amp vs. UVdist, both correlations.¶
TODO(screenshot): Raster panel, amplitude over time × channel.¶
Axis vocabulary: visplot vs. plotms¶
plotms axis names are the closest existing vocabulary an astronomer
will already know (see CASAdocs: Data Examination/Editing for the full
reference). visplot exposes fewer axes, chosen for commissioning; the
concepts line up as follows:
plotms axis |
visplot (preview) |
Notes |
|---|---|---|
|
Time |
|
|
Channel |
|
|
Frequency |
scatter X; a raster’s Channel axis reads frequency when several spectral windows are shown |
|
Amplitude |
|
|
Phase |
|
|
Real, Imaginary |
|
|
UVdist |
|
|
Correlation (selection, not yet a plottable/colorize axis) |
|
|
Flag (raster quantity: the flagged fraction of each cell) |
flagged data can also be shown (Flagging, Show flagged data) |
|
Colorize (scatter, per layer) |
continuous, categorical (e.g. by antenna, baseline, scan, field) or statistical (Z-Score) |
|
not available |
add if testers ask (computable from time, positions and field direction) |
Scope, explicitly¶
Updated 2026-10-11, before testing by astronomers.
Present and working:
Raster and scatter display, MSv2 and MSv4/Processing Set backends, local or in a remote kernel
vis=for either format, as in CASA tasks (ms=/ps=still work)Selection by data column, field (one, several, ranges, wildcards), spectral window, correlation, antenna and baseline (tables, or typed text); stepping through fields, spectral windows, antennas and baselines with ◀ ▶
Raster quantities including Phase RMS, Coherence, Z-Score and the phase / amplitude differences; vector or scalar averaging; how a cell covering several baselines is combined; which correlation each raster shows, including the parallel hands averaged
Scatter averaging over time and channels
Presets: vplot, radplot, waterfalls (one baseline, all baselines, phase), Z-Score, phase RMS views, antenna × antenna matrix, Spectrum, Time series
Colorize by axis, several correlations as layers
Flagging: boxes on either panel with filters, preview, reaches (antennas, all baselines, channels, correlations, spectral windows, scan, field), reason, undo / redo, a report, JSON export, and writing to the MS with a backup
Selection by scan, time range (UTC) and UV range, CASA syntax; autocorrelations excluded by default (Autocorrelations switch)
UTC time axes, readout and Time range box (or elapsed time)
The plot summary page and its reproducing call (Reporting a problem)
Export PNG from the toolbar, from Python without a browser (
VisibilityPlotter(..., headless=True)(plotfile=...)), and from the task (visplot(..., plotfile="out.png"))Shared pan/zoom/reset, linked X range when applicable; dark and light
The Grid layout: one plot per baseline, antenna, SPW, field, scan or correlation (or two of them), raster or scatter, paged, with drill-down to a full panel and PNG pages (Grid)
Not yet available:
Jupyter notebooks (
visplot.notebook()says so)Correlation as a raster axis (removed from the axis lists; each raster shows one correlation, or the parallel hands averaged, chosen in its gear tab and named in its title)
Flagging on the antenna × antenna matrix (refused, with the reason)
More than two panels (the Grid layout repeats one)
Flagging in the Grid layout’s plots (tap one and flag in the panel)
Locate; on-the-fly calibration; plotting calibration tables
A
flagdatacommand export (removed; JSON and writing to the MS replace it)
See also What visplot can do for a capability-by-capability
description of what visplot can do.
Feedback¶
If something looks wrong compared to plotms, msview or AIPS –
inverted axes, wrong amplitude scaling, missing correlations, channels
that don’t match the spectral window, times that don’t match the
observing log – that is exactly what testing is meant to catch. Report
it as described in Reporting a problem, with the plot summary page.