Visualisation

Visualisation#

Plotting helpers for SONGS results.

This module provides small, focused plotting utilities that operate on the results list produced by generate_cubes(). Each public helper accepts the results container and an index selecting which generated cube to visualise. The functions are intentionally lightweight and return a Matplotlib (fig, ax) pair so callers (GUIs, scripts, tests) can further customise or save figures.

Dependencies#

  • matplotlib (this module sets the TkAgg backend by default)

  • astrodendro (used to compute a crude mask for visual guides)

Notes

  • These helpers call _prepare_cube() to extract cube / metadata and to

    compute a simple dendrogram-based mask used for moment maps. The dendrogram parameters are deliberately conservative and may be tuned for different signal-to-noise regimes.

  • The plotting functions attempt to save to figures/<shape>/ when

    save=True is passed; save failures are intentionally ignored to keep UI flows robust.

class songs.visualise.AnalysisViewer(master, data, idx: int = 0)[source]#

Bases: Toplevel

Combined analysis viewer: Moment 0, Moment 1, and integrated spectrum.

Source checkboxes (one per galaxy) and a Diffuse checkbox let the user select which components contribute to all three panels. The layout mirrors the nemo analysis viewer: two moment maps side-by-side on top, spectrum spanning the full width below.

class songs.visualise.SliceViewer(master, data, idx: int = 0)[source]#

Bases: Toplevel

Channel-by-channel IFU slice viewer matching nemo aesthetics.

Displays the full spectral cube with colormap / normalization controls, vmin/vmax sliders, and (when per-galaxy cubes are available) a sources sidebar with per-source contours, bounding boxes, and intensity-threshold masks whose threshold percentage is tunable via a dedicated slider.

songs.visualise.moment0(data, idx, save=False, fname_save=None, inline=False)[source]#

Plot the zeroth moment (integrated intensity) of a spectral cube.

Parameters:

  • data (sequence) – The results container produced by SONGS.generate_cubes.

  • idx (int) – Index selecting which cube to plot.

  • save (bool, optional) – If True, attempt to save the figure to figures/<shape>/moment0.pdf.

  • fname_save (str or None, optional) – Optional directory to save the figure. If None a path under the current working directory is chosen automatically.

Returns:

fig, ax – Matplotlib figure and axes objects containing the rendered moment map.

Return type:

(Figure, Axes)

songs.visualise.moment1(data, idx, save=False, fname_save=None)[source]#

Plot the first moment (intensity-weighted velocity) of a spectral cube.

Parameters:

  • data (sequence) – The results container produced by SONGS.generate_cubes.

  • idx (int) – Index selecting which cube to plot.

  • save (bool, optional) – If True, attempt to save the figure to figures/<shape>/moment1.pdf.

  • fname_save (str or None, optional) – Optional directory to save the figure. If None a path under the current working directory is chosen automatically.

Returns:

fig, ax – Matplotlib figure and axes objects containing the rendered moment map.

Return type:

(Figure, Axes)

songs.visualise.slice_view(data, idx=0, channel=None, cmap='viridis', parent=None)[source]#

Show a per-channel slice viewer embedded in a Tk window.

This viewer embeds the Matplotlib figure into a Tk Toplevel and uses a ttk-styled slider to step through spectral channels. The viewer keeps the lower colour limit fixed at 0 and computes an upper limit per slice so contrast adapts to the currently displayed channel.

Parameters:

  • data (sequence) – The results container produced by SONGS.generate_cubes.

  • idx (int, optional) – Index of the cube within data to display (default 0).

  • channel (int, optional) – Initial spectral channel index to show. If None (the default) the viewer will open on the central spectral channel (int(n/2)).

  • cmap (str, optional) – Matplotlib colormap to use for imshow.

  • parent (tkinter widget, optional) – If provided, the slice viewer will be a child Toplevel of this widget. Otherwise a new Toplevel (or root) is used.

Returns:

fig, ax – The Matplotlib figure and axes used by the embedded viewer.

Return type:

(Figure, Axes)

songs.visualise.spectrum(data, idx, save=False, fname_save=None)[source]#

Plot the integrated spectrum (total flux vs velocity) for a cube.

Parameters:

  • data (sequence) – The results container produced by SONGS.generate_cubes.

  • idx (int) – Index selecting which cube to plot.

  • save (bool, optional) – If True, save the figure as spectrum.pdf under figures/<shape>/ unless fname_save overrides the path.

  • fname_save (str or None, optional) – Optional directory to save the figure.

Returns:

fig, ax – The Matplotlib figure and axes containing the spectrum.

Return type:

(Figure, Axes)

Helper Functions#

The songs.visualise module provides lightweight wrappers around Matplotlib for the most common cube inspection tasks.

moment0#

from songs.visualise import moment0
moment0(cube, save=False, fname=None)

Computes and displays the moment-0 (integrated intensity) map by summing the cube along the spectral axis. Optionally saves the figure to fname as a PDF.

moment1#

from songs.visualise import moment1
moment1(cube, vels, beam_info=None, save=False, fname=None)

Computes the intensity-weighted velocity map:

\[M_1(x, y) = \frac{\sum_v v \cdot S(v, x, y)}{\sum_v S(v, x, y)}\]

An optional beam marker (ellipse) is overlaid when beam_info is provided.

spectrum#

from songs.visualise import spectrum
spectrum(cube, vels, save=False, fname=None)

Plots the spatially-integrated line-of-sight spectrum: flux summed over the spatial axes as a function of velocity channel.

SliceViewer Class#

SliceViewer provides an interactive channel-by-channel viewer launched either from the GUI or standalone:

from songs.visualise import SliceViewer
viewer = SliceViewer(cube, sources=sources_list, vels=vels)
viewer.show()

sources mode: when sources is a list of per-source component cubes, the viewer activates the per-source sidebar so that contours, bounding boxes and threshold masks are computed independently for each source component.

Key interactive controls:

  • Channel slider — step through spectral slices.

  • Source selector sidebar — toggle which source’s overlays are shown.

  • Contour level spinner — set contour threshold as a fraction of the channel peak.

  • Threshold slider — mask voxels below a chosen intensity fraction.

  • Bounding-box toggle — show/hide axis-aligned bounding boxes per source.