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 ticked

  • Height — 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 changes

  • Gear (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 problem

  • Flag / 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= with layout="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.

  1. 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.

  2. 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.

  3. 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.

  4. 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 plotms or 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:

  1. 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 plotms call for comparison:

    plotms(vis='twhya_selfcal_contsub_ms', xaxis='time', yaxis='amp',
           field='5', correlation='XX,YY')
    
  2. 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')
    
  3. Raster: amplitude over time × channel. Compare against msview’s 2-D raster display, or a plotms iteration 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, in uvcontsub, before this MS was written).

visplot amp vs time

TODO(screenshot): Amp vs. Time, both correlations, TW Hya field 5.

plotms amp vs time for comparison

TODO(screenshot): Equivalent plotms view, for side-by-side comparison.

visplot amp vs uvdist

TODO(screenshot): Amp vs. UVdist, both correlations.

visplot raster panel

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

Time

chan / channel

Channel

freq / frequency

Frequency

scatter X; a raster’s Channel axis reads frequency when several spectral windows are shown

amp / amplitude

Amplitude

phase

Phase

real / imag

Real, Imaginary

uvdist

UVdist

corr / correlation

Correlation (selection, not yet a plottable/colorize axis)

flag

Flag (raster quantity: the flagged fraction of each cell)

flagged data can also be shown (Flagging, Show flagged data)

coloraxis

Colorize (scatter, per layer)

continuous, categorical (e.g. by antenna, baseline, scan, field) or statistical (Z-Score)

elevation, hourangle, azimuth, parang

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 flagdata command 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.