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 acasaprompt.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= NonePath to the data, MSv2 measurement set or MSv4 / Processing Set: the format is detected (on the kernel’s host when
kernel_nameis given). Exactly one ofvis,msorpsmust be supplied.ms: str | None= NonePath to an MSv2 measurement set.
ps: str | None= NonePath to an MSv4 / Processing Set Zarr store.
kernel_name: str | None= NoneKernelspec name (
jupyter kernelspec list) to run the MSv2/MSv4 access and Datashader rendering on, viacubevis.remote. Required whenbackend="remote"; withbackend="auto"(the default) giving it selects the remote backend.ms/psis then a path on the kernel’s host. The same string you’d pass toAsyncKernelManager(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 realsshpyk-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 toSelectionSpec.antenna_names(I-3, 2026-09); Prev/Next in the sidebar steps throughmeta.antennasin the dataset’s own order.NAME&NAMEtokens 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 raisesValueError. 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 inantenna("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 oftimerange; 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 ofuvrange; 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= NoneNamed preset:
"vplot","radplot","waterfall","zscore","phaserms-time","phaserms-freq","phaserms-uvdist","phase-waterfall","waterfall-all","antmatrix","spectrum","timeseries", orNone."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 setlayoutto"over"and supplyscatter_avg_time/scatter_avg_chanwhere 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 – seeiterate_by; a raster or a scatter). Default"side"."raster"/"scatter"are also accepted as shorthand forlayout="one", kind="raster"/"scatter"— seekindbelow. Combining the shortcut with an explicit, conflictingkind=raisesValueError.kind: str | None= NoneWhich panel kind leads:
"raster"(default when omitted) or"scatter". Forlayout="one"this is the single visible panel’s kind. Forlayout="side"/"over"both panels are always shown (one raster, one scatter, unchanged) —kindonly decides which one starts in the primary/first screen position; the other always takes the complementary kind.panels: list[dict] | None= NoneEach 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", …),vminandvmax(its color scale). A key left out takes the value the flat argument (orpreset) gives that panel, so the flat arguments still describe the first panel; an unknown key raises. At most two panels for now.layoutstill 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= NoneExplicit raster Y/X axis, e.g.
"TIME","BASELINE","CHANNEL","ANTENNA1"/"ANTENNA2"(together). Takes precedence overpreset, 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 raisesValueErrorlisting the valid options.raster_qty: str | None= NoneExplicit raster quantity (color axis), e.g.
"AMPLITUDE","PHASE","REAL","IMAGINARY","FLAG". Same precedence and validation asraster_y/raster_x.scatter_x,scatter_y: str | None= NoneExplicit 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’siteraxis. 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= 3Rows of plots on a page of the Grid layout (1-8, default 3).
gridcols: int= 3Columns 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. Witheq_histthe plots that share a range share its curve too.grid_panel: dict | None= NoneThe 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 onepanelsentry; 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= FalseStart with “Pin layout” ticked: presets (this
presetand the toolbar buttons) keep the current layout –layout– instead of switching to their own. DefaultFalse.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-styled/hh:mm:sswhen 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= NoneWrite a PNG of the plot to this path instead of opening the GUI (the
visplottask then returns the path). Impliesheadless=True;themeandlayoutapply. 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 toplotfilewith_page01,_page02, … before the extension, unless the name contains{page}.row_height: int, str or list= NoneHeight 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. Withplotfile=, the height of each plot’s data area.column_width: int, str or list= NoneWidth of each column of plots, in pixels.
Noneor"fit"(default): follow the window. A number fixes the width; a list gives one width per column (Side by Side has two). Withplotfile=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 ofcorrelation),"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).averagingapplies to the samples within each baseline. Initial value for every raster panel; each panel’s “Baselines combined” control changes it afterwards.detrend: bool= TrueFor 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).Falsemeasures 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 asstat_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 asscatter_avg_time.compact_toolbar: bool= TrueWhether 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= NoneExtra flag filters,
{name: callable | FlagFilter}; each callable isfunc(ds, **params) -> bool mask(seeflag_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= FalseReview 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 inflag_color).flag_color: str= '#ff00ff'Color for pending flags when
flag_display="color".flag_show_flagged: bool= FalseAlso 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_flaggedis 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= NoneBudget (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): theCUBEVIS_VISPLOT_FRAME_CACHE_MBenvironment 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 byCUBEVIS_VISPLOT_GRID_OVERFLOWpercent (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.