Interactive Clean
Create a new interactive GUI for image reconstruction, to replace the current CASA6 viewer. Design a standalone front-end package that is usable with a backend application that implements the building blocks of image reconstruction, to allow usage with current CASA6, future ngCASA, or any experimental set of methods that can implement the backend (as per the API specified by the front-end).
| Release | Date | Focus Features |
|---|---|---|
| Beta 2 | Summer 2024 | GUI usability,performance tests/optimization, automask+multifield features, remote operation usage mode |
| Beta 1 | Feb 2024 | Iteration control and feedback about covergence, mask edits, imaging and deconvolution options, interpretability of convergence health, improved GUI layout and usability. |
| Alpha | Mar 2023 | Basic iteration control, convergence plots, mask-editing and interactive controls. |
| First-Look | Nov 2022 | Technology prototype using casa6 methods in the backend and bokeh in a browser as a front end. |
Download the 6.6.4-3 monolithic CASA pre-release appropriate for your OS:
- RH7: https://casa.nrao.edu/download/distro/casa/releaseprep/casa-6.6.4-3-py3.8.el7.tar.xz
- RH8: https://casa.nrao.edu/download/distro/casa/releaseprep/casa-6.6.4-3-py3.8.el8.tar.xz
- Mac: https://casa.nrao.edu/download/distro/casa/releaseprep/casa-6.6.4.3-12.0-py38.dmg
Launch the pre-release version of CASA that you downloaded (on Mac, install first then launch)
In CASA, run the following to add the test version of the casagui package and its dependencies:
!pip3 install casagui==0.3.70
Import the run_iclean function:
from casagui.apps import run_iclean
Call the run_iclean function, providing your desired imaging and deconvolution parameters. See help(run_iclean) for more details. Monitor the console and CASA log for progress. The GUI should open as a new tab in your default web browser after running one execution of the tclean and deconvolve tasks.
Example :
run_iclean( vis='test.ms', imagename='try1', imsize=512, cell='12.0arcsec', specmode='cube', interpolation='nearest', nchan=5, start='1.0GHz', width='0.2GHz', pblimit=-1e-05, deconvolver='hogbom', threshold='0.001Jy', niter=50, cycleniter=10, cyclefactor=3 )
- On OSX, if you have installed the CASA pre-release to /Applications and are getting an error from pip, ensure your terminal application has 'Full Disk Access' enabled under System Settings → Privacy & Security
- 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 browser application prior to calling the run_iclean function.
- Errors about .residual/mask0 occasionally appear on the terminal (and in the status message) and sometimes require a restart of your python session (CAS-14100). Please watch out for this for now.
- List of MS inputs are not yet supported via run_iclean. Please test with only a single MS.
- calcres/calcres=False mode is not yet supported.
- Are you able to control deconvolution iterations predictably (with masks), for all the supported imaging modes ?
- Are status and error messages easy to interpret ?
- How well do the convergence plots replace information from the logs ?
Please add your feedback to this document. Feedback includes bug reports, areas that are not easy to interpret, feature requests, and suggestions for the GUI (and its usability) that are not already listed below.
The following are features intended to be supported by the new Interactive Clean GUI. Items not yet implemented are indicated with
The required feature list is derived/updated from CASR-681 and periodically updated based on testing feedback. Casagui docs contain information about the design of the front-end and back-end applications.
- Gridding and Imaging options (those available with task_tclean) : gridders = standard, mosaic, wproject, awproject,
${\textsf{\color{red}awp2,awphpg}}$ . - Deconvolution options (those available with task_deconvolve) : deconvolvers = hogbom, clark, multiscale, mtmfs,
${\textsf{\color{red}asp}}$ - Imaging modes : Spectral Cubes, Multiple Stokes Planes, Single Images and
$\textsf{\color{red}Images with outlier fields}$ . specmodes = cube, mfs, cubesource, cubedata,${\textsf{\color{red}mtmfsviacube}}$ .
- Synchronous interaction options made available in-between major and minor cycle boundaries. At the end of each major cycle, pause and display the .residual image with a contour/shade overlay of the current .mask - image. This would allow a user to interactively draw/edit a mask and edit iteration control parameters before continuing. Offer controls for proceeding for one set of minor/major cycle, continue until the end, or stop/restore/exit. If 'continue until convergence', allow a 'stop' option to pause at the next major-minor cycle boundary. This would allow a user to watch the convergence profile evolve for a few major cycles, but choose to intervene after some time.
- Display current values of iteration control parameters, allow the user to edit them, and send the edited values to the backend when the user presses one of the “controls” options above. Basic GUI controls include niter, nmajor, cycleniter, threshold, cyclefactor, gain, nsigma. Some parameters are auto-updated at the end of each set of minor cycle iterations, and this is to be updated on the GUI as well.
Iteration control rules
- Global stopping criteria include the following subset of tclean stopping criteria (listed in order of precedence)
| stopcode | stop description |
|---|---|
| 7 | Zero mask |
| 1 | Reached the iteration limit |
| 2 | Reached global stopping threshold (within mask) |
| 9 | Reached the major cycle limit |
The remaining tclean stopcodes (e.g., stopcode 4, no change in peak residual across consecutive major cycles) are not implemented as they can cause unexpected hard stops to the interactive clean use-cases.
- Controls supplied to the minor cycle are
cycleniterandcyclethreshold.cyclethresholdis calculated as follows :
image_threshold = psf_fraction * peak_residual
cyclethreshold = max(image_threshold, user_threshold)
where user_threshold is the user input threshold, and image_threshold is internally calculated based on the PSF sidelobe level and the peak residual. psf_fraction in the above equation is calculated as :
psf_fraction = max_psf_sidelobe * cyclefactor
psf_fraction = max(psf_fraction, min_psf_fraction)
psf_fraction = min(psf_fraction, max_psf_fraction)
where cyclefactor is input by the user, max_psf_sidelobe, max_psf_fraction, and min_psf_fraction are the peak value of the PSF sidelobe, and the maximum and minimum fraction of the PSF peak that can be reliably used during minor cycles.
- Drawing masks by hand (shapes, lasso, etc) separately per channel/stokes/$\textsf{\color{red} image field}$, extending them across channel/stokes/$\textsf{\color{red} image field}$ and the ability to copy and paste masks from one plane to another.
- Be able to start from an existing tclean mask on disk (image with ones and zeroes)
- Include automasking to grow a mask across major cycles, both with parameters used at startup,
$\textsf{\color{red}and by allowing automask-parameter editing via the GUI.}$
- Illustrate convergence history via plots of peak residual (within the deconvolution mask) and model flux against iteration count, separately per channel/stokes/image_field plane, and with the ability to navigate between channel/stokes/image_field planes. It is intended to replace the very verbose text that currently goes to the casa logger, especially for many-channel cubes.
- On the convergence plot, display useful diagnostic information per minorcycle set : cyclethreshold, minor-cycle exit criterion.
- Show a spectrum plot at the cursor location.
- Show statistics for the currently displayed image plane : rms, peak (within mask), number of pixels in the mask, etc. Mask-based statistics should update when the mask on the current plane is edited.
- Saving & playback : A way to record/save the iteration control history of the interactive run. A way to recreate an interactive run, in a script
$\textsf{\color{red}, including a record of interactive mask edits, and the final restore step}$ . -
$\textsf{\color{red}Final return dictionary : A single consolidated return dictionary containing information used to make the combined convergence plots}$ .
Expected call sequence of tclean/deconvolve in the log
At startup :
-- tclean(niter=0) to make the .residual,.psf images
-- deconvolve(niter=0,usemask=<inputs>,mask=<inputs>) to make the initial .mask
For each set of iterations :
-- deconvolve(niter>0,usemask='user',mask='') for minor cycle iterations that use the existing imagename.mask
-- tclean(niter=0) to update the .residual in a major cycle
-- (if not converged) deconvolve(niter=0,usemask=<inputs>,mask=<inputs>) to update the automask
At the end
-- deconvolve(niter=0,restoration=True) for restoration.
The user is allowed to edit the mask before each set of iterations.
- Start InteractiveClean in a local python session and connect to a GUI in a browser.
$\textsf{\color{red}Run InteractiveClean in a Jupyter notebook.}$ $\textsf{\color{red}Start the InteractiveClean backend in a remote process, but connect to it from a local GUI (local browser or notebook).}$ $\textsf{\color{red}A standalone application (electron?).}$
$\textsf{\color{red}Test and enable real-time usability is important for image sizes up to ~16k pixels on a side.}$ - Full image cubes may have 1000s of channels, but interactive mask drawing might be restricted to only a subset. Include a spectral summary plot to help identify useful channel ranges, and be able to navigate quickly to them.
- Where possible, preserve similarity with CARTA look-and-feel, as users will interact with both GUIs interchangeably during data analysis. GUI elements that would benefit from such similarity include colormap and colorscale adjusters, spectrum display, statistics display, pan/zoom, common icons).
-
$\textsf{\color{red}Meet basic accessibility standards (font size up to 2x, keyboard navigation, compatibility with color controls, etc)}$ . Possible Reference : https://aally.app/en/blog/test-the-accessibility-of-your-website-color-and-contrast
Additional feature requests are noted below, along with improvements based on testing feedback. These are currently not included in the product definition or github issues. Then can be added to the product list and/or as github issues after some design analysis and decisions of whether or not they are to be supported.
Features
- Mask drawing application : Automasking or interactive/comparative mask drawing should also be usable as part of a separate “makemask” application that is not tied to interactive clean.
- Guide for mask drawing : The ability to load a comparison image in world coordinates, as a guide for drawing a mask.
- Another automask algorithm : A level-based mask drawing where a mouse-move event is linked with a contour drawn at the level of the pixel intensity at the location of the mouse.
- Calculate moment maps for cube (useful to compress a lot of scientifically relevant information in a cube).
- Convergence plots and statistics : Be responsive to hand-drawn region-based statistics to aid in mask drawing ? Stats 'within the deconvolution mask' ? This topic needs more definition.
- Convergence plots : Toggle for linear vs log y-scale. Allow different y-scales for peak residual and model flux (L and R vertical axes?)
- A 'tape-deck' style channel selector is easier to use than (and preferred over) a slider. Place channel and stokes switching controls close together.
- Mask drawing for some basic shapes - circle or freehand, in addition to the lasso.
- Layout scaling options : Set a min width for the display, with scroll bars ?
- Convention choice for ‘peak res within or outside mask’ needs to be clarified/cleaned-up. Maybe display both, or allow a user to configure what they want to display ?
- Ability to navigate and explore images while next is running : Ask if this is a significant usage mode.
- Consider usability without a keyboard (e.g. from a touchscreen only) especially for remote use via a browser.
- Consider ease of use of keyboard+mouse controls (e.g. all keyboard controls to be on the left (or right) side of the keyboard, so that the other hand can only operate the mouse).
- Allow additional parameters to be changed between major and minor cycles (e.g. deconvolver, some deconvolver parameters, loopgain, etc).
- Improve intuitiveness of controls (e.g. keyboard shortcuts)
- Allow users to customize the application, and save preferences. Set a default.
- A way to restore the full convergence history from the previous session if cleaning is resumed.
- Verbose logging of some gclean internal calculations, e.g. the deconvolve threshold.
Fixes These items need to be converted to github issues or CAS tickets, and removed from here.
- Allow calcres/calcpsf=False to skip the initial major cycle when asked for in the run_iclean input.
- Add 'savemodel' option at the end as part of the last "restore" step ?
- Display units of quantities listed in the cursor display and convergence plots.
- GUI colormap : minmax autoscaling vs global user-set values. Proposal is to match CARTA convention.
- A few more parameters need to flow through (cutthreshold, smoothfactor, pbmask).
- Add indication (print to terminal) that the first major cycle is being run, before the GUI starts up.
- Recheck which parameters from tclean should or should not be made available through run_iclean.
- Modify default region drawing tools.
- Improve behavior when pressing CTRL-C, or when closing the browser tab.
- Add list-of-MS support.
- Enable mask= option at run_iclean startup
- ? Add the restore step to the interactive clean log ?
- Fix a one pixel offset in the drawn mask vs saved mask ?