Plotting

set_oiplot_defaults(; compact=oiplot_compact)

Apply consistent matplotlib style settings. When compact=true, all sizes are reduced for stacking multiple plots in a single figure. Calling without arguments preserves the current compact state.

The plotting functions install these once, on the first plot of a session. After that your own matplotlib.rcParams edits are left alone, so you can restyle freely:

using OITOOLS, PythonCall
plot_v2(data)                                        # style installed here
pyimport("matplotlib").rcParams["font.family"] = ["serif"]
plot_v2(data)                                        # serif is honoured

Call this function directly to reapply the OITOOLS style and discard such overrides.

uvplot(data; kwargs...)

Plot the UV coverage for one or more OIdata bins. Conjugate baselines (-u, -v) are always shown. Accepts a single OIdata, a vector, or the 2-D array returned by readoifits (flattened automatically).

Keyword arguments

• color — colouring scheme:
  • "baseline" (default) — one colour per baseline pair, labelled legend
  • "wav" / "wavelength" — coloured by λ (μm) with a horizontal colorbar
  • "mjd" / "time" — coloured by MJD with a horizontal colorbar
  • any other string — all points black
• figsize — figure size tuple. Default: (10, 10).
• minuv, maxuv — axis limits in Mλ when square=true.
• square — force equal axis limits. Default: true.
• legend_below — place the baseline legend below the plot. Default: true.
• figtitle — plot title string.
• cmap — matplotlib colormap for wav / mjd modes. Default: "Spectral_r".
• flipx — invert the x-axis (East to the right). Default: false.
• filename — save to file if non-empty.

plot_v2(data; kwargs...)

Plot squared visibilities V² vs baseline length (Mλ). Accepts a single OIdata, vector, or 2-D array.

Keyword arguments

• color — "baseline" (default), "wav", "mjd", or an explicit colour string.
• logplot — logarithmic y-axis. Default: false.
• figsize — figure size. Default: (12, 6).
• figtitle — prefix for the figure window title.
• markopt — use distinct marker shapes per baseline. Default: false.
• legend_below — place legend below the plot. Default: false.

plot_t3phi(data; kwargs...)

Plot closure phases T3φ (degrees) vs a representative baseline length (Mλ). Accepts a single OIdata, vector, or 2-D array.

Keyword arguments

• t3base — x-axis baseline: "geom" (default, geometric mean) or "max" (longest side).
• color — "baseline" (default), "wav", "mjd", or explicit colour string.
• figsize — figure size. Default: (12, 6).
• figtitle — prefix for the figure window title.
• markopt — use distinct marker shapes. Default: false.
• legend_below — place legend below the plot. Default: false.

plot_t3amp(data; kwargs...)

Plot triple amplitudes T3amp vs a representative baseline length (Mλ). Accepts a single OIdata, vector, or 2-D array.

Keyword arguments

• t3base — x-axis baseline: "geom" (default, geometric mean) or "max" (longest side).
• color — "baseline" (default), "wav", "mjd", or explicit colour string.
• logplot — use logarithmic y-axis. Default: false.
• figsize — figure size. Default: (12, 6).
• figtitle — prefix for the figure window title.
• markopt — use distinct marker shapes. Default: false.
• legend_below — place legend below the plot. Default: false.

plot_visamp(data; kwargs...)

Plot visibility amplitudes vs baseline length (Mλ). Accepts a single OIdata, vector, or 2-D array. The title and y-label adapt to the AMPTYP header stored in data.amptyp ("absolute", "differential", "correlated flux", or generic).

Keyword arguments

• color — "baseline" (default), "wav", "mjd", or explicit colour string.
• logplot — use logarithmic y-axis. Default: false.
• figsize — figure size. Default: (12, 6).
• figtitle — prefix for the figure window title.
• markopt — use distinct marker shapes. Default: false.
• legend_below — place legend below the plot. Default: false.

plot_visphi(data; kwargs...)

Plot visibility phases (degrees). The layout is chosen automatically from the PHITYP header stored in data.phityp:

• differential (phityp is "differential", matched case-insensitively) — one subplot per baseline with wavelength (nm) on the x-axis.
• absolute (default) — single panel with baseline (Mλ) on the x-axis, coloured by baseline, wavelength, or MJD.

Accepts a single OIdata, vector, or 2-D array.

Keyword arguments

• color — "baseline" (default), "wav", "mjd", or explicit colour string (ignored for differential layout).
• figsize — figure size. Default: (12, 6).
• figtitle — prefix for the figure window title.
• markopt — use distinct marker shapes. Default: false.
• legend_below — place legend below the plot. Default: false.

plot_diffphi(data; kwargs...)

Deprecated — use plot_visphi instead, which auto-detects differential phases from data.phityp.

plot_flux(data; kwargs...)

Plot flux spectra vs wavelength (μm). Accepts a single OIdata, vector, or 2-D array.

Keyword arguments

• color — colouring scheme:
  • "wav" (default) — coloured by wavelength with a horizontal colorbar.
  • "station" — one colour per station; OIFLUX entries with CALSTAT=C (i.e. `fluxsta_index == 0) are labelled"Calibrated"`.
  • "mjd" / "time" — scatter coloured by MJD with a horizontal colorbar.
  • any other string — treated as a matplotlib colour applied uniformly.
• figsize — figure size. Default: (12, 6).
• figtitle — prefix for the figure window title.
• markopt — use black markers with distinct shapes. Default: false.
• legend_below — place legend below the plot. Default: false.

plot_obs(data; obs=["V2","T3PHI","T3AMP"], color="baseline",
                 logplot=false, figsize=nothing, figtitle="", markopt=false)

Multi-panel figure with one subplot per observable, sharing the x-axis and a single legend. Panels are stacked vertically; only the bottom panel gets an x-axis label.

obs is a vector of spec keys from OBS_PLOT_SPECS (e.g. "V2", "T3PHI", "T3AMP", "VISAMP", "VISPHI", "FLUX"). Panels whose data is empty are skipped automatically.

When logplot=true, amplitude-like panels (V², T3amp, Visamp) use a log y-axis; phase panels are unaffected.

plot_residuals(data, obs; color="baseline", figsize=(14,10))

Plot data vs model and normalised residuals for all observable types present in data. obs is a NamedTuple from image_to_obs or model_to_obs.

Also accepts image-domain plot_residuals(x, ft, data) or model-domain plot_residuals(model, x, data) signatures.

imdisp(image; kwargs...)

Display a 2-D reconstructed image. The image is normalised to its maximum and oriented with East left / North up (Monnier convention). Accepts a flat vector (square image assumed) or a 2-D matrix.

Keyword arguments

• pixsize — pixel scale in mas. When -1 (default) the axes show pixel indices.
• colormap — matplotlib colormap. Default: "gist_heat".
• figtitle — figure window title. Default: "OITOOLS image".
• tickinterval — minor-tick spacing in mas. Default: 0.5; auto-scaled for large images.
• use_colorbar — show a right-side colorbar. Default: false.
• beamsize — if > 0, draw a filled white circle of this diameter (mas) to indicate the PSF.
• beamlocation — [fx, fy] fractional position of the beam circle. Default: [0.8, 0.8].

imdisp_multi(cube; kwargs...)

Display a 3-D stack of images (e.g. polychromatic channels or multi-temporal epochs) in a grid of subplots, one panel per slice. Each slice is normalised independently and rendered with the same formatting as imdisp.

cube is an (nx, nx, nslices) array.

Keyword arguments

• labels — vector of strings for subplot titles. Default: "1", "2", ….
• pixsize — pixel scale in mas (-1 = pixel indices).
• colormap — matplotlib colormap name. Default: "gist_heat".
• figtitle — figure window title. Default: "OITOOLS images".
• tickinterval — minor-tick spacing (auto-adjusted for large fields of view).
• use_colorbar — show a colour bar beside each panel.
• beamsize — if > 0, draw a beam circle on each panel.
• beamlocation — [x, y] fractional position for the beam circle.

uvplot_makie(data; color = :baseline, conjugate = true) -> PlotData

uv coverage in a fresh figure. Draws every uv point — V² baselines and closure-triangle legs alike — which is what uvplot shows and what the coverage actually is.

plot_observable_makie(data, which; color = nothing, logscale = false) -> PlotData

An observable against its natural x axis, in a fresh figure. which is any key of OBS_SPECS. color = nothing uses that observable's own oiplot default.

plot_v2_makie(data; kwargs...) -> PlotData

v2 against its natural x axis, in Makie — the counterpart of plot_v2.

A thin wrapper over plot_observable_makie, which takes any key of OBS_SPECS and is what to reach for when the observable is chosen at run time.

plot_t3phi_makie(data; kwargs...) -> PlotData

t3phi against its natural x axis, in Makie — the counterpart of plot_t3phi.

A thin wrapper over plot_observable_makie, which takes any key of OBS_SPECS and is what to reach for when the observable is chosen at run time.

plot_t3amp_makie(data; kwargs...) -> PlotData

t3amp against its natural x axis, in Makie — the counterpart of plot_t3amp.

A thin wrapper over plot_observable_makie, which takes any key of OBS_SPECS and is what to reach for when the observable is chosen at run time.

plot_visamp_makie(data; kwargs...) -> PlotData

visamp against its natural x axis, in Makie — the counterpart of plot_visamp.

A thin wrapper over plot_observable_makie, which takes any key of OBS_SPECS and is what to reach for when the observable is chosen at run time.

plot_visphi_makie(data; kwargs...) -> PlotData

visphi against its natural x axis, in Makie — the counterpart of plot_visphi.

A thin wrapper over plot_observable_makie, which takes any key of OBS_SPECS and is what to reach for when the observable is chosen at run time.

plot_flux_makie(data; kwargs...) -> PlotData

flux against its natural x axis, in Makie — the counterpart of plot_flux.

A thin wrapper over plot_observable_makie, which takes any key of OBS_SPECS and is what to reach for when the observable is chosen at run time.

plot_diffphi_makie(data; kwargs...) -> PlotData

diffphi against its natural x axis, in Makie — the counterpart of plot_diffphi.

A thin wrapper over plot_observable_makie, which takes any key of OBS_SPECS and is what to reach for when the observable is chosen at run time.

imdisp_makie(image; pixsize = -1, kwargs...) -> PlotData

One image, East left and North up, normalised to its own maximum.

image may be a matrix or a flat vector of nx² pixels. pixsize is in mas; -1 labels the axes in pixels instead.

Normalising to the maximum is imdisp's behaviour and is kept deliberately: it makes two reconstructions of the same target comparable by eye. An image whose maximum is below 1e-20 is drawn unnormalised, with a warning, rather than divided by roughly zero.

imdisp_multi_makie(cube; labels = nothing, kwargs...) -> PlotData

A stack of images as a grid of panels, one per slice of an (nx, ny, nslices) array.

Each panel is normalised to its own maximum, which is what imdisp_multi does and is worth knowing: it makes the faint channels readable and makes the panels non-comparable in brightness at the same time. Pass shared_scale = true for one normalisation across the cube when the comparison is the point.

Keywords otherwise as imdisp_makie; labels titles the panels and defaults to the slice number.

plot_residuals_makie(data, obs; color = :baseline, logscale = false) -> PlotData
plot_residuals_makie(model::FlatModel, x, data; kwargs...)
plot_residuals_makie(x, ft, data; kwargs...)

Data against model, with normalised residuals beneath, for every observable present.

obs is the NamedTuple model_to_obs or image_to_obs returns; the two convenience methods build it. Each observable gets a tall panel of data and model together and a short one of (model − data) / σ under it, sharing an x axis — the 3:1 split plot_residuals uses.

A phase residual is wrapped through mod360 BEFORE dividing by σ. Without that a model 359° from the data reads as a 359σ outlier rather than the 1° agreement it is.

color is :baseline, :wav or :mjd, as everywhere else.

plot_obs_makie(data; kinds = nothing, color = :baseline, logscale = false) -> PlotData

Several observables stacked in one figure on a shared x axis — the counterpart of plot_obs (and of plot_multi, which is an alias for it).

kinds defaults to every observable the data actually contains, in the order OBS_SPECS lists them. Only the bottom panel carries the x label and its tick labels; repeating them five times is what makes a stacked figure unreadable.

Each panel is drawn by draw! — the same implementation plot_observable_makie uses — so a panel here and a single-observable figure cannot disagree.

plot_v2_multifile_makie(datasets; logscale = false) -> PlotData

V² from several datasets on one axis — the counterpart of plot_v2_multifile.

One legend entry per baseline, not per file. A baseline that appears in five nights is one colour and one entry; the alternative is a legend longer than the plot, which is what makes the matplotlib version hard to read with more than a couple of files.

That also means the figure answers "does this baseline agree between nights", which is the question a multi-file V² plot is for. Colouring by file instead would answer a different one, and neither plot_v2_multifile nor this offers it.

plot_facility_makie(facility) -> PlotData

Telescope positions of a FacilityConfig, labelled and to scale — the counterpart of plot_facility.

Equal aspect, because an interferometric array plotted on unequal axes misreports the very thing the figure is for: which baselines are long and in which direction.

plot_corner_makie(posterior, names)

Corner plot of a posterior sample matrix, (n_samples, n_params), with one label per column.

Backend-agnostic on purpose: plot_ultranest_corner takes UltraNest's own result object and so can only ever serve that sampler, while this takes the samples any of them produce. Implemented by OITOOLSPairPlotsExt — using PairPlots — since drawing a good one is a package's worth of work and PairPlots.jl is already Makie-native.

plot_ultranest_corner(result; font_size = 8, histogram_color = "black",
                      contour_colors = ["#0072B2", "#56B4E9", "#009E73", "#F0E442"])

Draw UltraNest's corner plot for a completed nested-sampling result.

result is the raw Python object UltraNest returns, which is what fit_model_ultranest has while it still holds one: the plot needs the sampler's own structure – weights and cluster membership – not just the posterior matrix the UltraNestResult keeps.

This was inline in fit_model.jl until plotting moved out of the core package. It belongs here because it is matplotlib – it sets an rcParam and calls ultranest.plot – and leaving it in core would drag the whole plotting stack into every fit, including the ones that never draw anything. fit_model_ultranest(...; cornerplot = true) calls this when PythonPlot is loaded, and warns instead of failing when it is not.

The default contour colours are the Okabe-Ito palette, which stays legible in greyscale and to colour-blind readers.

PlotData(figure, axis, points, info)

A built figure plus what a click needs. points is the Makie plot object Makie.pick will return; info[i] describes point i of it.