Open in Colab: https://colab.research.google.com/github/casangi/casadocs/blob/20cf5f0/docs/notebooks/interactive_clean.ipynb

Interactive Clean

The new iclean task uses the cubevis package (formerly casagui) to display the interactive clean graphical interface in a web browser. The cubevis package and its dependencies (e.g. bokeh, astropy), together with a new task iclean, is available in CASA versions >= 6.7.2. This page describes the features of the interactive clean graphical user interface (GUI). For a description of the interactive clean (iclean) task interface please refer to the iclean API.

The iclean task was developed as a replacement for the interactive cleaning capabilities present in the current casaviewer, and as such only contains the functionality necessary for interactive deconvolution. It is not meant as a replacement for an image viewer such as CARTA.

iclean GUI

The iclean GUI is designed to support interactive image viewing, mask drawing and iteration control.

Usage

  • Masking : To add or modify the mask, select a drawing tool, draw a region, and then add or subtract the region from the image mask (using the toolbar buttons or keyboard shortcuts).

  • Deconvolution : Setup the deconvolution parameters using the input text boxes in the default iteration control tab. Then click the “Run a single major cycle” button (single circular arrow) or “run multiple major cycles” button (double looping arrows).

    • The “run multiple major cycles” button will continuously execute the deconvolution loop until a user interrupt, or until a convergence criterion is reached.

Known Issues

  • Outlier fields : All outlier fields must currently use the same specmode as the main field.

  • Default web browser : On some systems, the GUI will be unable to open a new browser tab if no instances of the browser are already running. If you encounter this, manually launch your default browser application prior to calling the iclean task. Iclean will use your default web browser as configured by your system settings. The $BROWSER environment variable can be set before launching CASA to specify your desired web browser.

  • Temporary HTML file : The iclean task will write a HTML file to a temporary location (typically /tmp or /private/tmp) for use during the interactive session. Users wishing to specify a different path can set this with the $TMPDIR envirionment variable before starting casa. This file should open automatically when executing the iclean task, following the initial computation of PSF and residual images. Users should not attempt to open this file manually in another web browser or refresh their browser tab, as doing so may break communication with the active interactive clean session.

  • Restarting iclean : The iclean task can be re-started without changing the image name in order to resume cleaning. However, the setting of calcres or calcpsf to False is not yet supported.

  • Mask warnings : Warnings or errors about .residual/mask0 may sometimes appear in the terminal and/or CASA log. The warnings can generally be ignored but CASA may need to be restarted if an error of this nature is preventing the iclean task from running.

GUI Main Page

Key features of the GUI are summarized below:

  • Raster image : shows a visualization of the residual image and mask for the currently selected image, channel and stokes.

  • Content area : a large section of the GUI where different content is loaded depending on the selected tab

  • Tab selection : these tabs change the contents of the GUI area above. Currently the options are: Iteration, Spectrum, Colormap, Statistics and Automask

  • Help button : shows keyboard shortcuts

  • Log button : shows the list of tclean and deconvolve commands that iclean has run

  • Stokes selection : select which Stokes plane to display

  • Coordinates selection : select between world and pixel coordinates

  • Mask display : controls the color of the mask and if the area is a contour or filled

  • Cursor location : displays the pixel or world coordinates at the cursor location and the corresponding value of the displayed image and mask. The keyboard shortcut ‘f’ can be used to freeze the locator at the current cursor position.

  • Image toolbar : these tools control how the mouse is used to interact with the image raster. The toolbar includes selection of different region drawing tools and buttons to add or subtract from the mask.

  • Status message : prints the major cycle exit criteria

  • Run / stop buttons : click to run a single major cycle (single arrow) or multiple cycles (two arrows). When running multiple cycles, click stop to stop after the current major cycle ends.

  • Channel controls : select the displayed channel by dragging the slider, typing in the channel index or clicking on the arrow buttons. The channel controls are only visible when running on cube image types.

  • Field selection : use these tabs to select between the primary image and outlier fields

iclean_gui.

GUI Tabbed Content

Examples of the tabbed content and a description of their key features is provided below:

  • Colormap tab : Provides adjustments for the display of the raster image. A histogram is shown for the active channel, Stokes plane and field. There are dropdown menus for the color map and scaling function. Min and Max clipping levels can be set using the text fields or by dragging the red vertical lines. The toolbar near the histogram provides tools to pan, zoom and reset the histogram display.

  • Iteration tab : The top section of this window allows for adjustment of the iteration controls. The bottom section shows the convergence plot, which tracks changes in the peak residual, model flux and stopping threshold for the active channel, Stokes plane and field.

  • Spectrum tab : Shows a plot of image intensity versus channel number at the location of the mouse cursor. The location can be frozen with ‘f’ and resets when the mouse exits and re-enters the raster area. This tab is only available when iclean is running on cube image types.

  • Automask tab : This window provides adjustments for the automasking parameters. This tab is only available if usemask='auto-multithresh' was set when first running the iclean task.

  • Statistics tab : This window provides image statistics for the active channel, Stokes plane and field. The dropdown menu controls whether the statistics are only calculated within the mask or calculated over the entire image.

iclean_panel1

iclean_panel2