Starting visplot

visplot displays visibility data as rasters and scatter plots and flags it interactively. It reads MSv2 measurement sets and MSv4 / Processing Sets, and replaces CASA6’s plotms and msview for this purpose.

visplot · from the Python source: VisibilityPlotter

Combined raster + scatter visibility inspection and flagging tool.

Before you start

  • An environment with cubevis[visplot]: see Installing.

  • An interactive Python or CASA6 session: ipython, or a casa prompt.

  • A measurement set (MSv2) or an MSv4 / Processing Set.

Note

Jupyter notebooks are not yet supported. visplot.notebook() exists but raises NotImplementedError saying so.

Opening a data set

visplot is called as a CASA-style task:

from cubevis import visplot

visplot(vis="twhya_selfcal_contsub_ms")

The call does everything: it opens the data, builds the window, shows it in your web browser and runs until the window is closed. Nothing is plotted until Plot ▶ is pressed, so the selection can be narrowed first.

Note

A screenshot of the window as it first opens will be added here when the layout is final.

The arguments that say which data to open:

visplot parameters · from the Python source: VisibilityPlotter

vis : str | None = None

Path to the data, MSv2 measurement set or MSv4 / Processing Set: the format is detected (on the kernel’s host when kernel_name is given). Exactly one of vis, ms or ps must be supplied.

ms : str | None = None

Path to an MSv2 measurement set.

ps : str | None = None

Path to an MSv4 / Processing Set Zarr store.

kernel_name : str | None = None

Kernelspec name (jupyter kernelspec list) to run the MSv2/MSv4 access and Datashader rendering on, via cubevis.remote. Required when backend="remote"; with backend="auto" (the default) giving it selects the remote backend. ms/ps is then a path on the kernel’s host. The same string you’d pass to AsyncKernelManager(kernel_name=...) directly — a local kernel ("python3") works for testing the remote path without an actual cluster. Construction blocks for the whole connect sequence: seconds against a local kernel, up to a couple of minutes on first connect to a real sshpyk-provisioned cluster kernel.

backend : str = 'auto'

Reduction backend: "auto", "casa6", "radps", "remote", or "null". Default "auto".

Data on another computer

When the data is on another computer, name a kernel that was set up there and give the path as it is on that computer:

visplot(vis="sis14_twhya_calibrated_flagged.ms", kernel_name="cvpost106-visplot")

The window runs on your computer and the data access on the other one. Setting up the kernel is described in Setting up remote execution.

Selecting data

The selection arguments use CASA’s selection syntax and set what the sidebar’s Data selection controls start with. Everything can be changed in the window afterwards.

visplot(
    vis         = "twhya_selfcal_contsub_ms",
    field       = "5",
    spw         = "0",
    correlation = "XX,YY",
    datacolumn  = "data",
)

Text that does not parse, or that matches nothing in the data, is refused with a message saying what is accepted.

visplot parameters · from the Python source: VisibilityPlotter

field : str = ''

Field name or integer index string. Default: first field.

spw : str = ''

Comma-separated SPW indices ("0,1,2,3"). Default: all.

antenna : str = ''

MSSelection antenna string (comma-separated names or IDs, !-prefixed for exclusion – see _parse_antenna_string’s own docstring for the exact supported subset). Wired to SelectionSpec.antenna_names (I-3, 2026-09); Prev/Next in the sidebar steps through meta.antennas in the dataset’s own order. NAME&NAME tokens select exact baselines instead ("DA44&DV19", several separated by ; or ,), in either order; they take precedence over antenna names. Sets what is initially ticked in the sidebar’s Antenna and Baseline tables.

scan : str = ''

Scans, CASA style: "1,3,7", "1~7", ">30", "!5". The sidebar’s Scan box starts with it. Text that matches no scan raises ValueError. Default: all.

timerange : str = ''

UTC time range, CASA style: "2012/11/19/07:37:00~2012/11/19/ 08:00:00", "07:37:00~08:00" (times of day, on the day of the data), ">08:00", "<08:30", "08:00:00+00:10:00" (start and length), "1/00:10:00" (day number / time, as the time axis labels data that cross midnight), or one time (the integration around it). One range. The Time range box starts with it. Default: all.

uvrange : str = ''

UV-distance ranges, CASA style: "0~50klambda", "100~300m", ">200m", "<1.5km", several with commas; units m, km, lambda, klambda, Mlambda, metres if none. Wavelengths are taken at each spectral window’s centre frequency, and whole rows (a baseline at one time) are in or out. The UV range box starts with it. Default: all.

autocorr : str = 'exclude'

Autocorrelations (baselines from an antenna to itself): "exclude" (default; cross-correlations only), "include" or "only". On VLBI data before amplitude calibration the autocorrelations are hundreds of times the cross-correlations and flatten every plot of all baselines. A baseline named in antenna ("BR&BR") is plotted whatever this says. Also the “Autocorrelations” switch in the Data section.

correlation : str = ''

Comma-separated correlation labels ("XX,YY"). Default: all.

datacolumn : str = 'data'

Visibility column: "data", "corrected", or "model".

time_range : tuple[float, float] | list[float] | None = None

(start, end) in UNIX seconds (UTC), the programmatic form of timerange; shown in the Time range box as text. Give one or the other.

freq_range : tuple[float, float] | list[float] | None = None

(start, end) in Hz.

uvdist_range : tuple[float, float] | list[float] | None = None

(min, max) UV distance in metres, the programmatic form of uvrange; shown in the UV range box as text. Give one or the other.

Choosing what is plotted

The window holds one or two panels, each a raster or a scatter plot, or a grid of plots: one plot repeated for each baseline, antenna, spectral window, field, scan or correlation in the selection, page by page, as plotms’s iteraxis does. A preset sets both panels at once to a view that is useful for one job; the same presets are buttons in the window’s toolbar.

visplot(vis="twhya_selfcal_contsub_ms", field="5", preset="radplot")
visplot(vis="twhya_selfcal_contsub_ms", field="5", layout="grid",
        iterate_by="baseline", gridrows=3, gridcols=4)

visplot parameters · from the Python source: VisibilityPlotter

preset : str | None = None

Named preset: "vplot", "radplot", "waterfall", "zscore", "phaserms-time", "phaserms-freq", "phaserms-uvdist", "phase-waterfall", "waterfall-all", "antmatrix", "spectrum", "timeseries", or None. "antmatrix" is the antenna x antenna matrix (raster Antenna 1 x Antenna 2: each baseline over time and channels). "spectrum" and "timeseries" show two scatter panels, Amplitude over Phase, against Frequency (each scan averaged) or Time (all channels averaged); they set layout to "over" and supply scatter_avg_time / scatter_avg_chan where those are left at "off".

layout : str = 'side'

Panel layout: "one" (single panel), "side" (both panels, side by side), "over" (both panels, one above the other), or "grid" (the first panel repeated once per baseline, antenna, SPW, field, scan or correlation – see iterate_by; a raster or a scatter). Default "side". "raster"/"scatter" are also accepted as shorthand for layout="one", kind="raster"/ "scatter" — see kind below. Combining the shortcut with an explicit, conflicting kind= raises ValueError.

kind : str | None = None

Which panel kind leads: "raster" (default when omitted) or "scatter". For layout="one" this is the single visible panel’s kind. For layout="side"/"over" both panels are always shown (one raster, one scatter, unchanged) — kind only decides which one starts in the primary/first screen position; the other always takes the complementary kind.

panels : list[dict] | None = None

Each panel’s configuration, in screen order: [{...}, {...}], one dict per panel, so that a two-panel view can be written as arguments (and the plot summary can print the call that reproduces what is on screen). Keys are the names of the per-panel arguments below – kind, raster_y, raster_x, raster_qty, averaging, raster_corr, baseline_order, baseline_combine, detrend, stat_time_window, stat_chan_window, scatter_x, scatter_y, scatter_avg_time, scatter_avg_chan – plus, for a raster, scaling ("linear", "log", "eq_hist", …), vmin and vmax (its color scale). A key left out takes the value the flat argument (or preset) gives that panel, so the flat arguments still describe the first panel; an unknown key raises. At most two panels for now. layout still decides how many are shown. Example (Spectrum written out):

panels=[dict(kind="scatter", scatter_x="FREQUENCY",
             scatter_y="AMPLITUDE", scatter_avg_time="scan"),
        dict(kind="scatter", scatter_x="FREQUENCY",
             scatter_y="PHASE", scatter_avg_time="scan")],
layout="over"
raster_y, raster_x : str | None = None

Explicit raster Y/X axis, e.g. "TIME", "BASELINE", "CHANNEL", "ANTENNA1" / "ANTENNA2" (together). Takes precedence over preset, which takes precedence over the default (Time vs. Channel). Validated against the same options the raster axis dropdowns expose in the GUI — an invalid value raises ValueError listing the valid options.

raster_qty : str | None = None

Explicit raster quantity (color axis), e.g. "AMPLITUDE", "PHASE", "REAL", "IMAGINARY", "FLAG". Same precedence and validation as raster_y/raster_x.

scatter_x, scatter_y : str | None = None

Explicit scatter X/Y axis, e.g. "UVDIST", "TIME", "FREQUENCY", "CHANNEL", "UVDIST_LAMBDA", "U", "V" for X; "AMPLITUDE", "PHASE", "REAL", "IMAGINARY", "U", "V" for Y. Same precedence and validation. E.g. scatter_x="U", scatter_y="V" launches directly into a U-vs-V UV-coverage scatter plot with no manual axis-picker step needed.

iterate_by : str = 'baseline'

What the Grid layout makes one plot of each: "baseline" (default), "antenna" (each antenna’s baselines), "spw", "field", "scan" or "correlation" – within the selection, as plotms’s iteraxis. Two axes, outer first, make one plot of each pair: "antenna,spw" is each antenna’s SPWs in turn (not both baseline and antenna). Every plot is drawn as the grid’s own panel is (grid_panel).

gridrows : int = 3

Rows of plots on a page of the Grid layout (1-8, default 3).

gridcols : int = 3

Columns of plots on a page of the Grid layout (1-8, default 3).

gridcolor : str = 'page'

The Grid layout’s color range: "page" (default), one range for the plots on a page; "grid", one for every plot in the grid, so that pages compare (found cell by cell in the background; until then a page is colored by its own range); "cell", each plot its own. With eq_hist the plots that share a range share its curve too.

grid_panel : dict | None = None

The Grid layout’s own panel: what every plot of the grid is drawn as, apart from the panels – so layout="grid" can start with both the grid and the panels set up. The keys of one panels entry; a key left out takes the first panel’s value. Without it the grid starts as a copy of the first panel, made the first time Grid is shown. In the GUI it is “Grid panel” in the Grid section; a tapped plot is shown in the first panel set up as this one. A raster or a scatter. Example:

layout="grid", iterate_by="antenna",
grid_panel=dict(raster_y="TIME", raster_x="BASELINE",
                raster_qty="PHASE")
pin_layout : bool = False

Start with “Pin layout” ticked: presets (this preset and the toolbar buttons) keep the current layout – layout – instead of switching to their own. Default False.

time_labels : str = 'utc'

How time axes and the cursor readout give time: "utc" (default; time of day, the date in the axis label, AIPS-style d/hh:mm:ss when the data cross a UTC midnight) or "elapsed" (minutes and seconds from the first sample). Also the “Time labels” switch in the configuration panel.

What each view is for, and the order in which they are useful on a new observation, is described in The visplot window. A list of everything visplot can do, one capability per page, is in What visplot can do.

Writing a plot to a file

With plotfile, visplot writes a PNG instead of opening the window and returns the file’s path:

path = visplot(vis="twhya_selfcal_contsub_ms", field="5",
               preset="radplot", plotfile="twhya_radplot.png")

visplot parameters · from the Python source: VisibilityPlotter

plotfile : str | None = None

Write a PNG of the plot to this path instead of opening the GUI (the visplot task then returns the path). Implies headless=True; theme and layout apply. A plotter built this way can be called again with other selections to write more files (see __call__).

exprange : str = 'current'

Which pages of the Grid layout plotfile= writes: "current" (default: the first page, as plotms), "all", or page numbers such as "2" or "1-3,5". Several pages are written to plotfile with _page01, _page02, … before the extension, unless the name contains {page}.

row_height : int, str or list = None

Height of each row of plots, in pixels: the plot with its axes, not the readout and color bars below it. None (default): 550 for One and Side by Side, 280 for Over / Under. "fit": the rows share the window’s height (never less than 250 px). A list gives one height per row (Over / Under has two). The GUI’s Row height menu changes it; it stays when the layout changes. With plotfile=, the height of each plot’s data area.

column_width : int, str or list = None

Width of each column of plots, in pixels. None or "fit" (default): follow the window. A number fixes the width; a list gives one width per column (Side by Side has two). With plotfile= there is no window: the default is 1020 for One and Over / Under, 500 per column for Side by Side.

theme : str = 'dark'

(not documented in the docstring)

From the CASA shell

visplot is also generated as a CASA task and for the CASA shell’s inp / go interface, with the same parameters and descriptions as above.

Note

Instructions for the inp / go interface will be added here.

All other parameters

The remaining parameters set the initial state of controls that are in the window: how raster cells are averaged, the statistics windows, color maps and flagging. They are listed here for reference; most sessions do not need them.

visplot parameters · from the Python source: VisibilityPlotter

averaging : str = 'vector'

How raster cells combine the samples they cover: "vector" (default; average the complex visibility, then take Amplitude / Phase – Amplitude drops where samples are incoherent) or "scalar" (Amplitude is the mean of the amplitudes, Phase the circular mean). Initial value for every raster panel, and for every scatter panel when it averages (scatter_avg_time / scatter_avg_chan); each panel’s own “Averaging” control changes it independently afterwards.

raster_corr : str = 'auto'

Which correlation a raster shows: "auto" (default; the first of correlation), "parallel" (the mean of the parallel hands, (XX+YY)/2 or (RR+LL)/2, valid where both are unflagged; a flag box on it flags both), or a product such as "LL" (read whether ticked or not). Initial value for every raster panel; each panel’s “Correlation shown” control changes it.

baseline_order : str = 'number'

How a raster orders its Baseline axis: "number" (default; by baseline number, as the sidebar’s Baseline table lists them) or "length" (shortest first, from the antenna positions; the ticks then read the length). Either way the baselines with data are drawn side by side with no holes. Initial value for every raster panel; each panel’s “Baseline order” control changes it afterwards.

baseline_combine : str = 'mean'

How a raster cell that covers several baselines combines them (only where Baseline is not a plot axis, e.g. Time x Channel with no single baseline ticked): "mean" (default; the mean of the baselines’ amplitudes), "median" (the middle one: what most baselines share, whatever a few bad ones do), "max" (the largest, so interference on a few baselines is not diluted by the rest) or "coherent" (the baselines’ visibilities are added before the amplitude is taken; for a calibrated point source). averaging applies to the samples within each baseline. Initial value for every raster panel; each panel’s “Baselines combined” control changes it afterwards.

detrend : bool = True

For the Phase RMS and Coherence raster quantities: remove a linear phase slope (residual delay along frequency, residual rate along time) before the statistic is taken (default True). False measures the data as they are, slope included. Initial value for every raster panel; each panel’s “Phase slope” control changes it afterwards.

stat_time_window : str or float = 'auto'

Time window the Phase RMS / Coherence statistic is taken within: "auto" (default), "off", "scan", or a number of seconds. Where Time is a plot axis every integration shows its window’s value; where it is not, the windows are pooled into each cell. "auto" is "off" in the first case and "scan" in the second. Windows never span a gap between scans. Initial value for every raster panel; each panel’s “Time window” control changes it afterwards.

stat_chan_window : str or int = 'off'

Channel window for the same statistic: "off" (default) or a number of channels. Same rules as stat_time_window.

scatter_avg_time : str or float = 'off'

Scatter points averaged over time, per baseline and correlation: "off" (default, every sample a point), "scan", or a number of seconds (windows from the start of each scan, never across a scan boundary). For a spectrum per scan (with X Frequency or Channel). Amplitude, Phase, Real and Imaginary only. Initial value for every scatter panel; each panel’s “Average over time” control changes it afterwards.

scatter_avg_chan : str or int = 'off'

Scatter points averaged over channels: "off" (default), a number of channels, or "all" (one point per spectral window). For a time series (with X Time). Same rules as scatter_avg_time.

compact_toolbar : bool = True

Whether each figure’s toolbar auto-hides until the mouse is over that plot. Defaults to True.

raster_cmap : Optional[str] = None

(not documented in the docstring)

scatter_cmap : Optional[str] = None

(not documented in the docstring)

flag_filters : dict | None = None

Extra flag filters, {name: callable | FlagFilter}; each callable is func(ds, **params) -> bool mask (see flag_filters.py). Selectable in the Flagging controls next to the built-in filters. Run only with local data; a remote session offers the built-ins.

flag_preview : bool = False

Review each flag proposal (counts, breakdown, highlighted samples) before it is added to the pending flags. Defaults to False.

flag_display : str = 'hide'

How pending flags are shown: "hide" (flagged points disappear, the default) or "color" (drawn in flag_color).

flag_color : str = '#ff00ff'

Color for pending flags when flag_display="color".

flag_show_flagged : bool = False

Also draw data that are currently flagged (on disk or pending) in flag_flagged_color, so an Unflag box can select them. Off by default; toggled in the Flagging controls.

flag_flagged_color : str = '#7f849c'

Color for flagged data when flag_show_flagged is on.

flag_reach : str = ''

How far a flag box reaches beyond what is drawn, as the “Flag reaches” controls start: a comma-separated list of shared-antenna (all baselines to the antenna the drawn baselines share), antennas (all baselines to every antenna of the drawn baselines), all-baselines, channels, spw (all selected spectral windows), scan (the whole scan), fields, correlations. Empty (the default): flags cover what is drawn.

flag_reason : str = ''

Text stored with each flag made from now on (why it was flagged); shown in the report, saved in the JSON, written as reason= in exported flagdata commands.

frame_cache_mb : float | None = None

Budget (MiB) of the cache of scatter frames – the decoded samples a scatter panel draws, flags and probes. When a selection’s frames do not fit, every redraw and flag operation re-reads them from the data (an INFO/WARNING line says so). None (default): the CUBEVIS_VISPLOT_FRAME_CACHE_MB environment variable if set, else by the host: a tenth of memory below 12 GiB; a quarter, at most half of what is free and 16 GiB, above; on a host with 48 GiB or more free (a compute node) 40 % of what is free, up to 64 GiB. The budget chosen is logged (INFO). Remote sessions apply it in the worker, where the frames live. The Grid layout’s rows held in memory count in it: while they are held, frames and rows may take it past the budget by CUBEVIS_VISPLOT_GRID_OVERFLOW percent (default 25), no more. Example: TW Hya with all fields (2 x 31 M samples, ~1.5 GiB per frame) needs about 3-4 GiB; on a 24 GB Mac the old 2.4 GiB default evicted frames and a flag box took 3.6 s instead of 0.5 s.