Previous Up Next

Chapter 7  Visualization With The CASA Viewer

This chapter describes using the CASA Viewer to display data. The Viewer can be started as a stand-alone executable or by the viewer task inside a CASA shell. It can display both images and Measurement Sets. We are in the process of splitting the task-level access to the Viewer into two tasks: imview for images and msview for measurement sets. These tasks offer improved scriptability, giving command line access to many of the viewer features.

7.1  Starting the Viewer


Figure 7.1: The Viewer Display Panel (left) and the Data Manager (right) panel for a regular image or data cube.

Within the casa environment, the viewer task can be used to start the CASA Viewer, displaying an image or MS. The inputs are:

#  viewer :: View an image or visibility data set.

infile        =         ''   #   (Optional)  Name of file to visualize.
displaytype   =   'raster'   #   (Optional)  Type of visual rendering
                             #   (raster, contour, vector or marker).
                             #   lel  if an lel expression is given
                             #   for infile (advanced).

Examples of starting the CASA Viewer:

  CASA <1>: viewer()

  CASA <2>: viewer('ngc5921.demo.ms')

  CASA <3>: viewer('ngc5921.demo.cleanimg.image')

  CASA <4>: viewer('ngc5921.demo.cleanimg.image', 'contour')
  
  CASA <5>: viewer('"ngc5921.demo.cleanimg.image"^2', 'lel')

The first command creates an empty Viewer Display Panel (§ 7.2) and a Load Data window (§ 7.3.1) . The second starts the CASA Viewer and loads a Measurement Set. The third example starts the Viewer and opens an image data cube (see Figure 7.1).

Examples four and five make use of the second parameter (displaytype). Example four displays the image as a contour map rather than the default raster map. Example five uses ’Lattice (Image) Expression Language’ to display the square of the image data.

Note that the Viewer can open FITS files, CASA image files, Measurement Sets, and saved viewer states. The Viewer determines the type of file being opened automatically.

For additional scripting options when opening the Viewer, see the discussion of the imview and msview tasks at the end of this Chapter (§7.7 and 7.8).

7.1.1  Running the CASA Viewer outside casa

If you have CASA installed, then the CASA Viewer is available as a stand-alone application called casaviewer. From the operating system prompt, the following commands work the same as the casa task commands given in the previous Section:

  casaviewer &
  
  casaviewer ms_filename &
  
  casaviewer image_filename &
  
  casaviewer image_filename contour &
  
  casaviewer '"image_filename"^2' lel &

7.2  The Viewer Display Panel

The CASA Viewer consists of a number of graphical user interface (GUI) windows. The main Viewer Display Panel (§ 7.2) is used for both image and Measurement Set viewing. It is shown in the left panels of Figures 7.1 and 7.2 and appears the same whether an image or Measurement Set is being displayed.


Figure 7.2: The Viewer Display Panel (left) and Data Display Options (right) panels with a Measurement Set open.

At the top of the Viewer Display Panel are drop down menus:

7.2.1  The Main Toolbar


Figure 7.3: The display panel’s Main Toolbar appears directly below the menus and contains ’shortcut’ buttons for most of the frequently-used menu items.

Below the drop down menus is the Main Toolbar (Figure 7.3). This top row of icons offers fast access to these menu items:

7.2.2  The Mouse Toolbar


Figure 7.4: The ’Mouse Tool’ Bar allows you to assign how mouse buttons behave in the image display area. Initially, zooming, color adjustment, and rectangular regions are assigned to the left, middle and right mouse buttons. Click on a tool with a mouse button to assign that tool to that mouse button.

Below the Main Toolbar are eleven Mouse Tool buttons (Figure 7.4). These allow you to assign what behavior the three mouse buttons have when clicked in the display area. Clicking a mouse tool icon will [re-]assign the mouse button that was clicked to that tool. Black and white squares beneath the icons show which mouse button is currently assigned to which tool.

The mouse tools available from the toolbar are:

(Note that the ’escape’ key can be used to cancel any mouse tool operation that was begun but not completed, and to erase a region, point, or other tool showing in the display area.)

7.2.3  The Display Area

The main Display Area lies below the toolbars. This area shows the image or Measurement Set currently loaded. Clicking the mouse inside the display area allows region or position selection according to the settings in the mouse toolbar.

The Display Area may have up to three attached panels: the Animator panel, the Position Tracking panel, and the Regions panel. These may be displayed or hidden from the "View" dropdown menu in the main Viewer Display Panel. If one of these is missing from your viewer, check that it is checked "on" in that menu. The panels can also be turned off by clicked the "X" in the top right corner, in which case you will need to use the View menu to get them back.

By default, the three panels appear attached to the main Viewer Display Panel on the right side of the image. They may be dragged to new positions. Each of the three panels can be attached to the left, top, right, or bottom of the main Viewer Display Panel or they can be entirely undocked and left as free-floating panels.

NOTE: Depending on your window manager, windows without focus, including detached panels and tools like the Spectral Profile Browser may sometimes display odd behavior. As a general rule, giving the window focus by clicking on it will correct the issue. If you seem to "lose" a detached panel (like an Animator Panel), then click in the main window to get it back.

NOTE: With all three panels turned on (and especially with several images loaded), the main display panel can sometimes shrink to very small sizes as the panels grow. Try detaching the panels to get the main display panel back to a useful size.

A restart of the viewer will display all docks in the state of a previous viewer session, given that it was closed normally. In addition, the viewer docking can be changed under “Preferences” In the toolbar (Mac OS under the “CASA Viewer” tab on the toolbar, Linux: “Data”). Fig. 7.5 shows an example. Each item can be changed and the input box will only allow accepted input formats. A complete restart is required to apply the changes.


Figure 7.5: ”Preferences” dialog to manually change the docking and size of the viewer panel.

7.2.3.1  The Animator Panel


Figure 7.6: The animator panel, which allows one to scroll along the z axis of a data cube (using the Channels tape deck) or cycle among open Images. The panel can be undocked from the main display panel.

The Animator Panel allows you to scroll through the channels of a data cube and to rotate among loaded images. The main features of the panel are the two “tape decks,” one labeled "Channels" and one Labeled "Images" (note that you will only see the Images tape deck when multiple images are loaded.

The Channels tape deck scrolls between planes of an individual image. By default, the channel tape deck scrolls among frequency planes when R.A. and Declination are the displayed axes (in this case, frequency is the "z axis"). From outside to inside, the buttons cause the display to jump all the way to the beginning/end of the z axis, cause the viewer to step one plane forward or backward along the z axis, or start a movie. The limits on the z axis can be set manually using the windows at the end of the scroll bar. The scroll bar can also be dragged or the user can jump the display to a manually entered plane by entering the plane into the text bock.

When you have multiple images loaded, the Images tape deck cycles through which is image is being displayed. In the movie mode, it allows you continuously click between images. Functionally, the image tape deck works similarly to the channels tape deck, with the ability to step, jump, or continuously scroll through images.

NOTE: The check boxes next to the channel and images tabs enable or disable those panels. This doesn’t have much effect when the display has only a single panel, but with multiple panels (i.e., several maps at once in the main window) it changes the nature of the display. If the "Images" box is checked then interleaved maps from different cubes are display. Otherwise a series of maps from a single cube are shown.

7.2.3.2  The Position Tracking Panel


Figure 7.7: The position tracking panel, which gives information about the open data cube at the current location of the cursor. Freeze the position tracking panel using the SPACE bar.

The Position Tracking panel (below the images in Fig 7.1) shows the intensity, position (e.g., RA and Dec), Stokes, frequency (or velocity), and pixel location for the point currently under the cursor. A separate box appears for each registered image or Measurement Set and you can see the tracking information for each. Tracking can be ’frozen’ (and unfrozen again) by hitting the space bar when the viewer’s focus is on the main display area (to be sure that this is case first click on the main display area).

7.2.3.3  The Region Manager Panel

The Region Manager panel becomes active when regions are created. It has a large amount of functionality, from display region statistics and histograms to creating position-velocity cuts. We discuss these in §7.4.3. Like the Animator and Position Tracking panel, the Region Manager Panel can be moved relative to the main viewer display panel or entirely undocked.

7.2.4  Saving and Restoring the Display Panel State

You can save the display panel’s current state — meaning the panel settings and the data on display — or load a saved panel state from disk. To save the display panel state, select Save Panel State from the Display Panel drop-down menu or click the "Save Display Panel State to File" icon on the main toolbar (an arrow pointing from a picture to a page, see Figure 7.3). It is advisable but not required to retain the file’s ’.rstr’ ("Restore") extension.

You can restore the display panel to the saved state by loading the saved state from the Data Manager Panel, by selecting Restore Panel State from the Display Panel drop down menu, or by clicking the "Restore Display Panel State" icon (just to the right of the "Save Display Panel State" icon).

It is possible to restore panel states viewing Measurement Sets or image and panel states that have multiple layers, such as contour plots over raster images. You can also save LEL displays. You can also the save or restore the panel state with no data loaded, which is a convenient way to restore preferred initial settings such as overall panel size.

Data Locations: The viewer is fairly forgiving regarding data location when restore a saved panel state. It will find files located:

This means that you can generally restore a saved panel state if you move that file together with data files. The exception to this rule is that the process is less forgiving if you save the display of an LEL expression. In this case the files must be in the locations specified in the original LEL expression. If a data file is not found, restore will attempt to proceed but results may not be ideal.

Manually Editing Saved Display Panel States: The saved "Restore" files are in ascii (xml) format, and manual edits are possible. However, these files are long and complex. Use caution, and back up restore files before editing. If you make a mistake, the viewer may not even recognize the file as a restore file. It is easier and safer to make changes on the display panel and then save the display panel state again.

7.3  The Data Manager Panel — Saving and Loading Data


Figure 7.8: The load tab of the Data Manager panel. This appears if you open the viewer without any infile specified, if you use select Open from the Data drop down menu, or click the Open (Folder) icon. You can access the save image or save region tabs from this view or by selecting Save as... from the Data drop down menu. The load tab shows all files in the current directory that can be loaded into the viewer — images, MS, CASA region files, and Display Panel State files.

The Data Manager Panel is used to interactively load and save images, Measurement Sets, Display Panel States, and regions. An example of the loading tab in this panel is shown in Figure 7.8. This panel appears automatically if you open the viewer without specifying an input file or it can be accessed through the Data:Open menu or Open icon of the Viewer Display Panel.

7.3.1  Loading Data

The load tab of the Data Manager Panel allows you to interactively choose images or Measurement Sets to load into the viewer. The load tab automatically shows you the available images, Measurement Sets, and Display Panel States in the current directory that can be opened by the viewer. When you highlight an image in this view, the tab shows a brief summary of the image: pixel shape, extent of the image on the sky and in frequency/velocity, and restoring beam (if available).

Selecting a file will bring up information about that file in the panel on the right of the Data Manager Panel provide options for how to display the data. Images can be displayed as:

  1. raster image
  2. contour map
  3. vector map
  4. marker map

These options area each discussed in § 7.4.

slice: a subselection of a data cube can be loaded, the start and end pixel in each spatial, polarization, and spectral dimension can be selected.

LEL: Instead of only loading an image from disk, you may ask the viewer to evaluate a ’Lattice Expression Language’ (LEL) expression (§ 6.1.4). This can be entered in the box provided after you click the "LEL" box. The images used in the LEL expression should have the same coordinates and extents.

Measurement Sets: A Measurement Set can only be displayed as a raster. For measurement sets, the load tab offers options for data selection. This will reduce loading and processing times for visibility flagging.

Regridding Images on Load: Optionally, you may regrid the velocity axis of an image on load to match the current coordinates grid in the Display Panel. In this case, the viewer will interpolate (using the selected interpolation scheme) the cube on disk to share the same velocity gridding as the loaded coordinates. This can be used, e.g., to overlay contour maps of different spectral lines or to make synchronized movies of multiple cubes. Note that the regridding depends on the rest frequency in the image, which is used to calculate the velocities used in regridding.

7.3.2  Registered vs. Open Datasets

When you load data as described above, it is first opened, and then registered on all existing Display Panels.

An open dataset has been prepared in memory from disk. All open datasets will have a tab in the Data Display Options window, whether currently registered or not.

When a data set is registered to a Display Panel its coordinates are aligned to the master coordinate image in the panel and it is ready for drawing. If multiple Display Panels are open then a data set may be registered on one Display Panel and not on another. Only those data sets registered on a particular Display Panel show up in its Position Tracking panel.

Why Register More Than One Image? It is useful to have more than one image registered on a panel if you are displaying a contour image over a raster image (§ 7.4.2.1), to ’blink’ between images (see Animator in § 7.2), or to compare images using the position tracking panel.

Unregistering Images: A data set can be registered or unregistered using the Image Manager in the Data drop down menu or the Image Manager icon (third from left). It will open The Image Manager window and the checkboxes can be used to register or unregister an image.

Closing vs. Unregistering: You can close a data set that is no longer needed using the Close option in the Data drop-down menu, the "Close" icon (fourth from left), or right mouse button “Close” selection in the Image Manager (§ 7.3.3).

If you close a dataset, you must reload it from disk (or recreate it if it’s an LEL expression, regridded image, moment or something similar) to see it again. If you unregister a dataset, it will draw immediately if you re-register it, with its options as you have previously set them. In general, close unneeded datasets but unregister those that you intend to use again.

7.3.3  Image Manager

The Image Manager is used to define the master coordinate image, the sequence of images (e.g. for blinking), to register and unregister images, close images, change between raster, contour, vector, and marker displays, and to modify the properties of images. The panel can be invoked from the “Manage Images” tool, the third icon from the left (two overlapping squares).

An example is shown in Fig. 7.9. In this case, four images are loaded into the viewer. The sequence of images can be changed by dragging and dropping the images to new positions in the stack. The letter to the left indicates whether the image is a Raster, Contour, Vector, or Mmarker image. MC marks the coordinate master, in this case the second image. The checkboxes are to change the registration statuses. The Coordinate Master image can be defined by a right mouse click, and selection the corresponding option. The right mouse menu button also offers options for quick changes between contour and raster images and to close an image.

The Options button will open a drop down box (as shown in Fig. 7.9 for the first image), in which one can again change between image type, change to a different rest frequency (or “Reset” to the value in the image header), or open the “Display Options” panel for that specific image with all the adjustment options explained in (§7.4.1 or §7.4.2).


Figure 7.9: The Image Manager.

7.3.4  Saving Data or Regions


Figure 7.10: The Save Data panel that appears when selecting the ’Save as...’ (Figure 7.3).

The viewer can create new images by carrying out velocity regridding, evaluating an LEL expression, or collapsing a data cube. You can save these images to disk using the Data Manager Panel. Select Save as under the Data drop-down menu or click the Save as (disk) icon to bring up the Data Manager Panel set to the save tabs. This tab is shown in Figure 7.10.

From the Save Image tab of the Data Manager Panel, you can export images from the viewer to either a CASA image or FITS file on disk. Select the desired file name and click "save." The Data Manager also allows you to save your current regions to a file, either in the CASA or ds9 format. The left part lists all images that can be exported to disk. To save an image to a file, the use can either enter the new filename in the box labeled ’output name:’ followed by the save-button (alternatively the ’Enter’-key), or choose a file name from the right hand side.

7.4  Viewing Images

There are several options for viewing an image. These are seen at the right of the Load Data - Viewer panel described in § 7.3.1 and shown in Figure 7.1 after selecting an image. They are:

The raster image is the default image display, and is what you get if you invoke the Viewer with an image file and no other options. In this case, you will need to use the Open menu to bring up the Load Data panel to choose a different display.

7.4.1  Viewing a Raster Map

A raster map of an image shows pixel intensities in a two-dimensional cross-section of gridded data with colors selected a colormap according to a scaling that can be specified by the user.

Starting the casaviewer with an image as a raster map will look something like the example in Figure 7.1.

Once loaded, the data display can be adjusted by the user through the Data Display Options panel, which appears when you choose the Data:Adjust menu or use the wrench icon from the Main Toolbar.

The Data Display Options window is shown in the right panel of Figure 7.1. It consists of a tab for each image or MS loaded, under which are a cascading series of expandable categories. For an image, these are:

The basic settings category is expanded by default. To expand a category to show its options, click on it with the left mouse button.

7.4.1.1  Data Display Options — display and hidden axes

In this category the physical axes (i.e. Right Ascension, Declination, Velocity, Stokes) to be displayed can be selected and assigned to the x, y, and z axes of the display. The z axis will be the axis scrolled across by the channel bar in the Animator Panel.

If your image has a fourth axis (typically Stokes), then one of the axes will need to be hidden and not used in viewing. Which axis is hidden can be controlled by a slider within the hidden axes drop-down.

7.4.1.2  Data Display Options — basic settings

This roll-up is open by default showing some commonly-used parameters that alter the way the image is displayed. The most frequently used of these change how the intensity value of a pixel maps to a color on the screen. An example of this part of the panel is shown in Figure 7.11.


Figure 7.11: The basic settings category of the Data Display Options panel and the interactive tool for setting the mapping from intensity to color.

The options available are:

7.4.1.3  Graphical Specification of the Intensity Scale

A histogram icon next to the data range in the Data Display opens the Image Color Mapping window, which allows visualization and graphical manipulation of the mapping of intensity to color. The window at the left shows a histogram of the data with a gray range showing the data range. You can use this window to select the data range graphically (with the mouse), manually (by typing into the empty windows), or as a percentile of the data. On the right, you can select the scaling power cycles and see a visualization of the transfer function mapping intensity (x-axis) to color (y-axis).

The functionality here follows the other histogram tools, with the Display tab used to change the histogram plotting parameters. It will often be useful to use a logarithmic scaling of the y-axis and filled histograms when manipulating the color table.

7.4.1.4  Data Display Options — other settings

Many of the other settings on the Data Options panel for raster images are self-explanatory such as those which affect beam ellipse drawing (only available if your image provides beam data), or the form of the axis labeling and position tracking information. You can also give your image a color wedge, a key to the current mapping from data values to colors.

7.4.1.5  Viewer Canvas Manager — Panels, Margins, and Backgrounds


Figure 7.13: A multi-panel display set up through the Viewer Canvas Manager.

The display area can also be manipulated from the Viewer Canvas Manager window. Use the wrench icon with a ’P’ (or the ’Display Panel’ menu) to show this window, which allows you to manipulate the infrastructure of the main display panel. You can set:

Figure 7.13 illustrates a multi-panel display along with the Viewer Canvas Manager settings which created it.

7.4.2  Viewing a Contour Map

Viewing a contour image is similar to viewing a raster map. A contour map shows lines of equal data value for the selected plane of gridded data (Figure 7.14). Contour maps are particularly useful for overlaying on raster images so that two different measurements of the same part of the sky can be shown simultaneously (§ 7.4.2.1).

Several basic settings options control the contour levels used:

Additionally, you have the option to manipulate the thickness and color of the image and to have either positive or negative contours appear dashed.


Figure 7.14: The Viewer Display Panel (left) and Data Display Options panel (right) after choosing contour map from the Load Data panel. The image shown is for channel 11 of the NGC5921 cube, selected using the Animator tape deck, and zoomed in using the tool bar icon. Note the different options in the open basic settings category of the Data Display Options panel (as compared to raster image in Figure 7.1).

For example, the following settings:

   Relative Contour Levels = [0.2, 0.4, 0.6, 0.8]
   Base Contour Level = 0.0
   Unit Contour Level = <image max>

would map the maximum of the image to 1 in the relative contour levels and the base contour level to zero. So the contours will show 20%, 40%, 60%, and 80% of the peak.

Another approach is to set the unit contour to 1, so that the contours are given in intensity units (usually Jy/beam). So this setup:

   Relative Contour Levels = [0.010, 0.0.020, 0.040, 0.080, 0.160, 0.320]
   Base Contour Level = 0.0
   Unit Contour Level = 1.0

would create contours starting at 10 mJy/beam and doubling every contour.

Another useful approach is to set contours in units of the rms noise level of the image, which can be worked out from a signal free region. Then a setup like this:

   Relative Contour Levels = [-3,3,5,10,15,20]
   Base Contour Level = 0.0
   Unit Contour Level = <image rms>

Would indicate significance in the image. The first two contours show emission at ± 3-sigma and so on.

You can get the image rms using the imstat task (§ 6.10) or using the Viewer statistics tool on a region of the image (§ 7.4.3.3).

Not all images are of intensity, for example a moment-1 image (§ 6.8) has units of velocity. In this case, absolute contours (like the last two examples) will work fine, but by default the Viewer will set fractional contours but referred to the min and max of the image:

   Relative Contour Levels = [0.2, 0.4, 0.6, 0.8]
   Base Contour Level = <image min>
   Unit Contour Level = <image max>

Here we have contours spaced evenly from min to max, and this is what you get by default if you load a non-intensity image (like the moment-1 image). See Figure 7.15 for an example of this.

7.4.2.1  Overlay Contours on a Raster Map

Contours of either a second data set or the same data set can be used for comparison or to enhance visualization of the data. The Data Options Panel will have multiple tabs (switch between them at the top of the window) that allow you to adjust each overlay individually.

NOTE: axis labeling is controlled by the first-registered image overlay that has labeling turned on (whether raster or contour), so make label adjustments within that tab.

To add a Contour overlay, open the Load Data panel (Use the Data menu or click on the folder icon), select the data set and click on contour map. See Figure 7.15 for an example using NGC5921.


Figure 7.15: The Viewer Display Panel (left) and Data Display Options panel (right) after overlaying a Contour Map of velocity on a Raster Image of intensity. The image shown is for the moments of the NGC5921 cube, zoomed in using the tool bar icon. The tab for the contour plot is open in the Data Display Options panel.

7.4.3  Regions and the Region Manager


Figure 7.16: The Region Manager Panel, which becomes active once at least one region is created. Cycle through available regions using the slider bar at the bottom and use the various tabs to adjust, analyze, load, and save regions.

CASA regions are following the CASA ’crtf’ standard as described in § D. CASA regions can be used in all applications, including clean and image analysis tasks (§ 6).

NOTE: A leading ’ann’ (short for annotation) to a region definition indicates that it is for visual overlay purposes only.

NOTE: Whereas the region format is supported by all the data processing tasks, some aspects of the viewer implementation are still limited to rectangles, ellipses, and some markers. Full support for all region types is progressing with each CASA release.

Once one or more regions are created, the Region Manager Panel becomes active (see Figure 7.16). Like the Position Tracking and Animator Panels, this can be docked or detached from the main viewer display. It contains several tabs that can be used to adjust, analyze, and save or load regions.

NOTE: Moving the mouse into a region will bring it into focus for the Spectral Profile or Histogram tools.

7.4.3.1  Region Creation, Selection, and Deletion

Within the display area, you can draw regions or select positions using the mouse. Regions can be created with the buttons marked as ’R’ in the mouse tool bar (§ 7.2, § 7.4.3.2). The viewer currently supports creation of rectangles, ellipses, polygons, and the point. As usual, a mouse button can be assigned to each button as indicated by the small black square in each button (marking the left, middle, or right mouse button § 7.2, § 7.4.3.2). An example is shown in Fig. 7.17.

Regions can be selected by SHIFT+click, de-selected by pressing SHIFT+click again. The bottom of the Region Manager Panel features a slider to switch between regions in the image. Regions can be removed by hovering over and pressing ESC or by pressing the buttons to the right side of the slider where the first button deletes all regions and the far right button deletes the region that is currently displayed in the panel.


Figure 7.17: Selecting an image region (done with SHIFT+click). The region can be resized by dragging the handles or deleted by hitting ESCAPE.

Once regions are selected, they will feature little, skeletal squares in the corners of their boundary boxes. Selected regions can be moved by dragging with the mouse button and manually resize by grabbing the corners as handles. If more than one region is selected, all selected regions move together.

The Rectangle Region drawing tool currently enables the full functionality of the various Region Manager tabs (see below) as well as:

The Polygon Region and Ellipse Region drawing have the same uses, except that polygon region flagging of a Measurement Set is not supported.

7.4.3.2  Region Positioning


Figure 7.18: The positioning tab in the Region Manager. Use it to manually adjust the location, width, and display style of the selected region.

With at least one region drawn, the region manager becomes active. Using the Properties tab, one can manually adjust the position, annotation, and display style of the region. The frames boxes set which planes of the image cube the region persists through (regions can have a depth associated with them and will only appear in the frames listed in this range). One can manually adjust the width and height and the center of the box in the chosen units. The ’selection’ check box is an alternative way to the SHIFT+click to select a region. The ’annotation’ checkbox will place the ’ann’ string in front of the region ascii output – annotation regions are not be used for processing in, e.g. data analysis tasks. In the line and text tabs, one can set the style with which the region is displayed, the associated text, and the position and style of that text.

NOTE: Updating the position of a region will update the spectral profile shown if the Spectral Profile tool is open and the histogram if the Histogram tool is open. The views are linked. Dragging a region or adjusting it manually with the Position tab is a good way to explore an image.

7.4.3.3  Region Statistics


Figure 7.19: The statistics tab in the Region Manager.

One of the most useful features of defining a region is the ability to extract statistics characterizing the intensity distribution inside the region. You can see these in the Statistics tab of the of the Region Manager Panel (see Figure 7.19). This displays statistics for the current region in the current plane of the current image. When more than a single region is drawn, you can select them one by one and the region panel will update the statistics to reflect the currently selected region. All values are updated on the fly when the region is dragged across the image.

A similar functionality can be achieved by double clicking inside of a region. This will send statistics information for this region in all registered images to the terminal, looking something like this:

(IRC10216.36GHzcont.image) image
          Stokes         Velocity            Frame          Doppler        Frequency 
               I -2.99447e+11km/s             LSRK            RADIO      3.63499e+10 
  BrightnessUnit         BeamArea             Npts              Sum             Flux 
         Jy/beam          36.2521            27547     1.087686e-01     3.000336e-03 
            Mean              Rms          Std dev          Minimum          Maximum 
    3.948473e-06     3.723835e-04     3.723693e-04    -1.045624e-03     9.968892e-03 

Listed Parameters are Stokes, and the displayed channel Velocity with the associated Frame, Doppler and Frequency value. Sum, Mean, Rms, Std Deviation, Minimum, and Maximum value refer to those in the selected region and has the units as specified in BrightnessUnit. Npts is the number of pixels in the region, and BeamArea the beam size in pixels. FluxDensity is in Jy if the image is in Jy/beam.

This is an easy way to copy and paste the statistical data to a program outside of CASA for further use.

Taking the RMS of the signal-free portion of an image or cube is a good way to estimate the noise. Contrasting this number with the maximum of the image gives an estimate of the dynamic range of the image. The FluxDensity measurement gives a way to use the viewer to do very basic photometry.

7.4.3.4  Saving and Loading Regions


Figure 7.20: The save/load tab in the Region Manager.

The File tab in the Region Manager allows one to save or load selected regions, either individually or en masse. You can choose between CASA and ds9 region format. The default is a CASA region file (saved with a *.crtf suffix, see § D). The DS9 format does not offer the full flexibility and cannot capture stokes and spectral axes. DS9 regions will only be usable as annotations in the viewer, they cannot be used for data processing in other CASA tasks. When saving regions, one can choose to save only the current region, all regions that were selected with SHIFT+click, or all regions that are visible on the screen.

NOTE: The load functionality for this tab will only become available once at least one region exists. To load a region when no regions exist, use the Data Manager window (§ 7.3).

7.4.3.5  The Region Fit

NOTE: This functionality is still under development. Its robustness and functionality will be improved in future version of CASA.

The Viewer can attempt to fit a two dimensional Gaussian to the emission distribution inside the currently selected region. To attempt the fit, go to the Fit tab of the Region Manager and click the gaussfit button in the bottom left of the panel. You can choose whether or not to fit a sky level (e.g., to account for a finite background, either astronomical, sky, or instrumental). After fitting the distribution, the Fit panel shows the results of the fit, the center, major and minor axis, and position angle of the Gaussian fit in pixels (I) and in world coordinates (W, RA and Dec). The detailed results of the fit will also appear in the terminal window, including a flag showing whether the fit converged.

7.4.3.6  The Region Histogram


Figure 7.21: The histogram tab in the Region Manager. Right click to zoom. Hit SHIFT + Right Click to adjust the details of the histogram display.

The Viewer will automatically derive a histogram of the pixel values inside the selected region. This can be viewed using the Histogram tab of the of the Region Manager Panel. This is a pared down version of the full Histogram Tool. You can manipulate the details of the histogram plot by clicking:

  1. Use the Right Click to zoom - either to the full range, a selected percentile, or a range that you have graphically selected by dragging the mouse (may still be under development).
  2. Hit SHIFT + Right Click to open the histogram options. This lets you toggle between a logarithmic and linear y-axis, choose between a line, outline, or filled histogram, and adjust the number of bins.

The histogram will update as you change the plane of the cube or shift between region.

7.4.4  The Spectral Profile Tool


Figure 7.22: The Spectral Profile panel (right) that appears when pressing the button Open the Spectrum Profiler in the Main Toolbar and then use the tools to select a region in the image, such as the rectangular region on the left panel. The Spectral Profile tool shows the spectrum of the most recent region highlighted and updates to track movements of the region if moved by dragging with the mouse.

The Spectral Profile Tool allows you examine the intensity as a function frequency or velocity. To start a new Spectral Profile window, click the Spectral Profile option from the Tools drop-down menu or click the "Spectral Profile" (red line graph) icon from the Main Toolbar (see Fig. 7.3). A new Spectral Profile window will appear.

NOTE: Make Sure That You Use the Radio Version! This section describes the "Radio" version of the profiler. To be sure that you have the radio version of the tool selected (this may not be the default), click on the preferences icon (the gear fourth from the left) and make sure that the "Optical" option is not checked. If you use the viewer for the very first time, you will also be prompted for a selection that will subsequently be kept for all future calls unless the preference is being changed.

The Spectral Profile Tool consists of a toolbar (§7.4.4.1), a main display area (§7.4.4.2), and two associated tabs: Spectral-Line Fitting (§7.4.4.3) and Line Overlays (§7.4.4.4).

Interaction With the Main Display Panel: For the Spectral Profile tool to work, a region or point must be specified in the main Viewer Display window. Use the mouse tools to specify a point, rectangle, ellipse, or polygon region. Alternatively, load a region file. The Spectral Profile tool will show a spectrum extracted from the region most recently highlight by the mouse in the main Viewer Display Panel. The method of extraction can be specified by the user using a drop down menu below the spectrum in the Spectral Profile window; the method of extraction is mean by default).

The Spectral Profile tool can also feed back to the Main Display Panel. By holding CTRL and right clicking in the spectrum, you will cause the Main Display Panel to jump to display the frequency channel corresponding to the spectral (x) coordinate of the region clicked in the Spectral Profile tool. Holding CTRL and dragging out a spectral range while holding the right mouse button will queue a movie scrolling through images across that spectral range. You can achieve the same effect with the two-ended-arrow icon towards the right of the toolbar in the Spectral Profile window.

In both tabs, it will be useful to do select regions of frequency or velocity. You can do this with the parallel lines-and-arrow icon (see below) or by holding shift, left clicking, and dragging out the range of interest. A shaded gray region should appear indicating your selection.

7.4.4.1  Spectral Profile Toolbar


Figure 7.23: The toolbar for the Spectral Profile tool allows the user to save the spectrum, print or save the tool as an image, edit preferences (general, tool, legend), spectral smoothing, pan or zoom around the spectrum, select a range of interest, jump to a channel, or add a label.

Figure 7.23 shows the toolbar from the top portion of the Spectral Profile window. From left to right, the icons allow the user to:



Figure 7.24: Preferences options in the Spectral Profile Tool. From the toolbar, one can access dialogs to set overall viewer preferences, colors for plotting, how the plot legend is displayed, and spectral smoothing method and kernel width.

Figure 7.24 shows the setting dialogs accessible from the toolbar. This Preferences dialog opened by the gear icon allows the user to:

The Color Curve Preferences dialog opened by the color wheel icon allows the user to:

Two sets of preset colors, "Traditional" or "Alternative", are available and the user can define their own custom color palette.

The legend options opened by the signpost icon allow the user to toggle the plotting of a legend defining the curves shown in the main Spectral Profile window. Using a drop-down dialog, the legend can be placed in the top left corner of the plot, to the right of the plot, or below the plot. Toggling the color bar causes the color of the curve to be indicated either via a short bar or using the color of the text itself. Double click the names of the files or curves to edit the text shown for that curve by hand. A legend is only available if more than a single spectrum has been loaded.

The spectral smoothing option has two methods, Boxcar and Hanning with the selection of odd numbers for the smoothing kernel width in channels.

7.4.4.2  Main Spectral Profile Window


Figure 7.25: The main panel for the Spectral Profile tool. Buttons along the bottom row allow the axes to be set. Arrow keys pan and dragging out an area with the mouse zooms. Holding CTRL and right clicking in the spectrum will jump the main Viewer Display panel to display that frequency channel.

The main window shows the spectrum extracted from active region of the image in the main Display Panel. The spectra from the same region in any other registered images are also plotted if overlays are enabled. Menus along the bottom of the image allow the user to select how the spectrum is displayed. From left to right:

In addition to these drop-down menus, the main Spectral Profile window allows the user to do the following using keyboard and mouse inputs:

NOTE: If the mouse input to the Spectral Profile browser becomes confused hit the ESC key several times and it will reset.

7.4.4.3  Spectral-Line Fitting


Figure 7.26: The Spectral Line Fitting tab in the Spectral Profile Tool. The user can fit a combination of a polynomial and multiple Gaussian components, specifying the range to be fit (gray region) manually or with a shift+click+drag. Initial estimates for each component may be entered by hand or specified via an initial estimates GUI. The results are output to a dialog and text file with the fit overplotted (here in blue) on the spectrum (with the possibility to save it to disk).


Figure 7.27: The left panel shows the graphical specification of initial estimates for Gaussian fitting. Slider bars specify the center, FWHM, and peak intensity for the initial estimate. The right panel shows the verbose output of the fitting.

NOTE: Interactive spectral line fitting is still under development.

The Spectral-Line Fitting tab, shown in Figures 7.26 and 7.27, allows the user to interactively fit a combination of Gaussian and polynomial profiles to the data shown in the Spectral Line Profile tool. The tool includes a number of options, many of which remain under development:

NOTE: Currently the tool works well for specifying a single Gaussian. Fitting multiple components can become unstable and polynomial and multiple line-of-sight fitting are still under development. This is an area of active development and future releases will offer improved capabilities.

7.4.4.4  Line Overlays


Figure 7.28: Line Overlays in the Spectral Profile Tool. The Line Overlay tab, shown at the bottom, allows users to query the CASA copy of the Spaltalogue spectral line database. Enter the redshift of your source (right panel), select and Astronomical Filter from the drop down menu, and use shift+click+drag to select a frequency range (or do so manually). The "Search" button will bring up the dialog seen at the left top part of the image, which can in turn be used to graph the candidate lines in the main Spectral Profile window (here CO v=0).

CASA ships with a local version of the Splatalogue spectral line database (www.splatalogue.net) and this can be used to identify and overplot spectral transitions. This feature, shown in Figure 7.28, allows the user to search Splatalogue over the range of interest.

To overlay spectral lines:

  1. Select the Line Overlays tab in the Spectral Profiles tab.
  2. If you know it, enter the redshift or velocity of your source in the "Doppler Shift" panel. Otherwise, the lines will be overlaid assuming a redshift of 0.
  3. Specify a minimum and maximum frequency range to search, either by typing a range or by holding shift and left click and dragging out a range in the spectrum (you will see a gray box appear). If you don’t specify a range, the tool will search over the frequency range of spectrum.
  4. Optionally, you may select an astronomical filter from the list (for example, commonly used extragalactic lines or lines often found in hot cores, see Splatalogue for more information). This is usually a good idea because it pares the potentially very large list of candidate lines to a smaller set of reasonable candidates.
  5. Click "Search" and the Spectral Profile will search Splatalogue for a list of Spectral lines that that fit that Astronomical Filter in that frequency range for that redshift. A dialog will pop up showing the list of candidate lines.
  6. Highlight one or more of these transitions and click "Graph Selected Lines." A set of vertical markers will appear in the main Spectral Profile window at the appropriate (redshifted) frequencies for the line.

We emphasize that this feature remains under active development. Look for improved performance and an expanded feature set in the next release.

NOTE: You will want to click "Clear Lines" between searches, especially if you update the redshift.

7.4.5  The Brightness Profile Tool

The “line” tool can be used to display 1-dimensional brightness profiles of images. The viewer accepts even more than one line segments such as shown in Fig.7.29. The “region” dock will then display a preview of the slice in the “Slice Cut” tab and the full “1-D Slice Tool” can be launched from there. This panel allows one to select the interpolation method to connect the pixels, and a number count for the sampled pixels in between markers. “Automatic” will show all pixels. The x-axis of the display can be either the distance along the slice or the X and Y coordinate projections (e.g. along RA and DEC). All segments are also listed at the bottom with their start and end coordinates, the distance and the position angles of each slice segment. The color tool can be used to give each segment a separate color.


Figure 7.29: 1-dimensional slice of an image. The 1D slicer tool shows the brightness distribution along line segments.

7.4.6  The Collapse/Moments Tool


Figure 7.30: The Collapse/Moments tool, accessed from the Main Toolbar or the Tools drop down menu. The mean spectrum from the region in the Main Display Panel appears in the top part of the tool. After selecting a range, a moment to calculate, and optionally data to exclude click collapse to calculate a new image.

The CASA Viewer can collapse a data cube into an image, for instance allowing to look at the emission integrated along the z axis or the mean velocity of emission along the line of sight. You can access this functionality via the Collapse/Moments tool (accessed via the Tools menu or the four arrow icons), shown in Figure 7.30.

The tool uses the same format as the Spectral Profile tool and will show the integrated spectrum of whatever region or point is currently selected in the main Display Panel. To create a moment map:

  1. Select a range over which to integrate either manually using the left part of the window, by adding an interval and typing in the values into the box or by holding SHIFT + Left Click and dragging out the range of interest.
  2. Pick the set of algorithms that you will use to collapse the image along the z axis. Clicking toggles each moment method, and the collapse will create a new image for each selected moment. For details on the individual collapse method, see the immoments task for more details on each moment.
  3. The moment may optionally include or exclude pixels within a certain range (for example, you might include only values with signal-to-noise three or greater when calculating the velocity dispersion). You can enter the values to include or exclude manually in the Thresholding window on the right or you can open a histogram tool to specify this range graphically by clicking Specify Graphically (before this can work, you must click "Include" or "Exclude").
  4. The results of the collapse be saved to a file, which consists of a string specifying the specific moment tacked onto a root file name that you can specify using Select Root Output File.
  5. When you are satisfied with you chosen options, press Collapse.

NOTE: Even if you don’t save the results of the collapse to a file, you can still save the map later using the Save as... entry in the Data pull down menu from the main Viewer Display Panel.

NOTE: This area remains under active development and may still exhibit some stability issues in CASA 4.1.

7.4.7  The Histogram Tool


Figure 7.31: The Histogram tool, accessed from the Main Toolbar or the Tools drop down menu. Details of the display and included pixels can be manipulated via the menus along the top of the window. The right hand panel allows one to attempt to fit a distribution to the histogram.

CASA can calculate and visualize a histogram of pixel values inside a region of interest. To examine this histogram, select Histogram from the Tools drop-down menu or the Histogram icon (looks like a comb). This opens the full histogram tool; more limited versions are accessible from the Region Manager Panel, the graphical color table manipulation tool, and the Collapse/Moments tool.

The resulting Histogram Tool should look something like Figure 7.31. The menus along the top (or the corresponding mouse clicks) allow one to:

The Histogram Tool also allows you to fit the distribution using either a Gaussian or a Poisson distribution, for example to estimate the noise in the image (a Gaussian will be a good choice to describe the noise in most radio data cubes). You can specify initial estimates or let the program generate initial guesses. The fit is then overplotted on the histogram (colors can be adjusted by clicking the color wheel icon in the toolbar) and details of the fit are printed to the text window below the fit button.

7.4.8  The Two-D Fitting Tool


Figure 7.32: The interface to the two dimensional fitting tool (Tools:Fit... or the blue circles icon). The interface allows you to specify and automatically generate (Find Sources) initial estimates, to specify the range of pixel values to be included in the fit, and to specify the output (log file, residual image, and visualization). Click Fit to start the fit.

NOTE: This functionality is still under very active development. Not all features are functional at this point.

CASA can fit two dimensional Gaussians to an intensity distribution, and the Two-Dimensional Fitting tool in the Viewer exposes this functionality interactively. This tool, accessed by the blue circles icon or the Tools:Fit... menu item, has an interface like that shown in Figure 7.32. The interface exposes several options:

  1. You can select whether to fit only the selected region or the whole image plane and specify which channel of the cube you want to operate on. NOTE: The two dimensional fitter only operates on a single channel at a time.
  2. Initial Estimates: The box in the top left corner allows the user to specify initial estimates by feeding in a file. The easiest way to make an appropriate file is to edit an existing one. Even easier, you can use the Find Sources button to automatically generate a temporary file of initial estimates. NOTE: This functionality is still under development. When it is working, you click on Find Sources
  3. Pixel Range: You can choose to only include a certain range of pixel intensity values in the fit. For example, you might choose to only fit Gaussians to pixels above a few times the measured noise level. You can use the Specify Graphically button to bring up an interactive histogram of the region (a reduced functionality version of the full Histogram Tool).
  4. Output: You can choose to save the output of the fit as a file to the specified directory and to subtract the fit from the image and to subtract the fit from the original, creating a Residual Image that gets stored as a CASA image and automatically loaded into the viewer. This gives a way to tell how well your fit describes the total emission.
  5. Visualization: You can toggle whether the fit is displayed on the viewer or not and change the color of the marker.

Click Fit to start the fit. If the fit does not converge, try improving your initial estimates and fitting again.

7.4.9  Interactive Position-Velocity Diagram Creation


Figure 7.33: Interactive creation of position-velocity cuts in the viewer. Use the P/V tool from the Mouse Toolbar to define a cut, then use the pV tool from the Region Manager Panel to adjust the cut (including the width). Click Generate P/V to build the position velocity cut and open it in a new Viewer Display Panel (from which it can be saved to disk).

The route to create position-velocity cuts in the viewer is illustrated in Figure 7.33:

  1. Select the P/V cut tool from the Mouse Toolbar and use it to draw a line across a data cube along the axis you want to visualize.
  2. Open the Region Manager Panel and go to the pV tab. Highlight the cut you just drew. You should see the end point coordinates listed, along with information on the length and position angle of the cut. You can set the averaging width (in pixels) in a window at the bottom of the tab.
  3. When you are satisfied, hit Generate P/V. This will create a new Main Viewer Display Panel showing the position velocity cut. The axes should be Offset and velocity.

The new image can be saved to disk with the Data:Save as... option.

7.5  Viewing Measurement Sets


Figure 7.34: The Load Data - Viewer panel as it appears if you select an MS. The only option available is to load this as a Raster Image. In this example, clicking on the Raster Image button would bring up the displays shown in Figure 7.2.

Visibility data can also be displayed and flagged directly from the viewer. For Measurement Set files the only option for display is ’Raster’ (similar to AIPS task TVFLG). An example of MS display is shown in Figure 7.2; loading of an MS is shown in Figure 7.34.

Warning: Only one MS should be registered at a time on a Display Panel. Only one MS can be shown in any case. You do not have to close other images/MSs, but you should at least ’unregister’ them from the Display Panel used for viewing the MS. If you wish to see other images or MSs at the same time, create multiple Display Panel windows.

7.5.1  Data Display Options Panel for Measurement Sets

The Data Display Options panel provides adjustments for MSs similar to those for images, and also includes flagging options. As with images, this window appears when you choose the Data:Adjust menu or use the wrench icon from the Main Toolbar. It is also shown by default when an MS is loaded. The right panel of Figure 7.2 shows a Data Options window. It has a tab for each open MS, containing a set of categories. The options within each category can be either ’rolled up’ or expanded by clicking the category label.

For a Measurement Set, the categories are:

7.5.1.1  MS Options — Basic Settings

The Basic Settings roll-up is expanded by default. It contains entries similar to those for a raster image (§ 7.4.1.2). Together with the brightness/contrast and colormap adjustment icons on the Mouse Toolbar of the Display Panel, they are especially important for adjusting the color display of your MS.

The available Basic options are:

7.5.1.2  MS Options— MS and Visibility Selections

This roll-up provides choice boxes for Visibility Type (Observed, Corrected, Model, Residual) and Component (Amplitude, Phase, Real, or Imaginary).


Figure 7.35: The MS for NGC4826 BIMA observations has been loaded into the viewer. We see the first of the spw in the Display Panel, and have opened up MS and Visibility Selections in the Data Display Options panel. The display panel raster is not full of visibilities because spw 0 is continuum and was only observed for the first few scans. This is a case where the different spectral windows have different numbers of channels also.

Changes to Visibility Type or Component (changing from Phase to Amplitude, for example) require the data to be retrieved again from the disk into memory, which can be a lengthy process. When a large MS is first selected for viewing, the user must trigger this retrieval manually by pressing the Apply button (located below all the options), after selecting the data to be viewed (see Field IDs and Spectral Windows, below).

Tip: Changing visibility type between ’Observed’ and ’Corrected’ can also be used to assure that data and flags are reloaded from disk. You should do this if you’re using another flagging tool such as autoflag simultaneously, so that the viewer sees the other tool’s new edits and doesn’t overwrite them with obsolete flags. The Apply button alone won’t reload unless something within the viewer itself requires it; in the future, a button will be provided to reload flags from the disk unconditionally.

You can also choose to view the difference from a running mean or the local RMS deviation of either Phase or Amplitude. There is a slider for choosing the nominal number of time slots in the ’local neighborhood’ for these displays.

(Note: Insufficient Data is shown in the tracking area during these displays when there is no other unflagged data in the local neighborhood to compare to the point in question. The moving time windows will not extend across changes in either field ID or scan number boundaries, so you may see this message if your scan numbers change with every time stamp. An option will be added later to ignore scan boundaries).

You can retrieve and edit a selected portion of the MS data by entering the desired Spectral Window and Field ID numbers into these boxes. Important: Especially with large MSs, often the first thing you’ll want to do is to select spectral windows which all have the same number of channels and the same polarization setup. It also makes sense to edit only a few fields at a time. Doing this will also greatly reduce data retrieval times and memory requirements.

You can separate the ID numbers with spaces or commas; you do not need to enter enclosing brackets. Changes to either entry box will cause the selected MS data to be reloaded from disk.

If you select, say, spectral windows 7, 8, 23, and 24, the animator, slice position sliders, and axis labeling will show these as 0, 1, 2, and 3 (the ’slice positions’ or ’pixel coordinates’ of the chosen spectral windows). Looking at the position tracking display is the best way to avoid confusion in such cases. It will show something like: Sp Win 23 (s 2) when you are viewing spectral window 23 (plane 2 of the selected spectral windows).

Changes to MS selections will not be allowed until you have saved (or discarded) any previous edits you have made (see Flagging Options -- Save Edits, below). A warning is printed on the console (not the logger).

Initially, all fields and spectral windows are selected. To revert to this ’unselected’ state, choose ’Original’ under the wrench icons next to the entry boxes.

See Figure 7.35 for an example showing the use of the MS and Visibility Selections controls when viewing an MS.

7.5.1.3  MS Options — Display Axes

This roll-up is very similar to that for images: it allows the user to choose which axes (from Time, Baseline, Polarization, Channel, and Spectral Window) are on the display and the animator. There are also sliders here for choosing positions on the remaining axes. (It’s useful to note that the data is actually stored internally in memory as an array with these five axes).


Figure 7.36: The MS for NGC4826 from Figure 7.35, now with the Display Axes open in the Data Display Options panel. By default, channels are on the Animation Axis and thus in the tapedeck, while spectral window and polarization are on the Display Axes sliders.

For MSs, changing the choice of axis on one control will automatically swap axes, maintaining different axes on each control. Changing axes or slider/animator positions does not normally require pressing Apply — the new slice is shown immediately. However, the display may be partially or completely grey in areas if the required data is not currently in memory, either because no data has been loaded yet, or because not all the selected data will fit into the allowed memory. Press the Apply button in this case to load the data (see § 7.5.1.6 and Max. Visibility Memory at the end of § 7.5.1.5).


Figure 7.37: The MS for NGC4826, continuing from Figure 7.36. We have now put spectral window on the Animation Axis and used the tapedeck to step to spw 2, where we see the data from the rest of the scans. Now channels is on a Display Axes slider, which has been dragged to show Channel 33.

Within the Display Axes rollup you may also select whether to order the baseline axis by antenna1-antenna2 (the default) or by (unprojected) baseline length.

See Figures 7.367.37 showing the use of the Display Axes controls to change the axes on the animation and sliders.

7.5.1.4  MS Options — Flagging Options

These options allow you to edit (flag or unflag) MS data. The Point Tool and Rectangle Region Mouse Tools (§ 7.4.3.2) are used on the display to select the area to edit. When using the Rectangle Region tool, double-click inside the selected rectangle to confirm the edit.

The options below determine how edits will be applied.

7.5.1.5  MS Options— Advanced

These settings can help optimize your memory usage, especially for large MSs. A rule of thumb is that they can be increased until response becomes sluggish, when they should be backed down again.

You can run the unix ’top’ program and hit ’M’ in it (to sort by memory usage) in order to examine the effects of these settings. Look at the amount of RSS (main memory) and SWAP used by the X server and ’casaviewer’ processes. If that sounds familiar and easy, then fiddling with these settings is for you. Otherwise, the default settings should provide reasonable performance in most cases.

7.5.1.6  MS Options — Apply Button

When viewing large MSs the display may be partially or completely grey in areas where the required data is not currently in memory, either because no data has been loaded yet, or because not all the selected data will fit into the allowed memory (see Max. Visibility Memory above). When the cursor is over such an area, the following message shows in the position tracking area:

   press 'Apply' on Adjust panel to load data

Pressing the Apply button (which lies below all the options) will reload the memory buffer so that it includes the slice you are trying to view.

The message No Data has a different meaning; in that case, there simply is no data in the selected MS at the indicated position.

For large measurement sets, loading visibility data into memory is the most time-consuming step. Progress feedback is provided in the console window. Again, careful selection of the data to be viewed can greatly speed up retrieval.

7.6  Printing from the Viewer


Figure 7.38: Printing the display to a hardcopy of a file. From the Viewer Print Manager, located in top right here and accessed by the print icon or from the Data drop down menu, you can use the Save button to save an image or Print directly to a printer. To achieve the best results, it is often helpful to adjust the settings in the Data Display Options and Viewer Canvas Manager, shown at right.

You can select Data:Print from the drop down menu or click the Print icon to bring up the Viewer Print Manager. From this panel, you can Print the contents of Display Panel to a hardcopy or Save them as an image in a format selected from the drop-down menu at the bottom left of the window. Note that the save feature will overwrite the file in question without prompting.

The Viewer Print Manager allows you to adjust the DPI, orientation, and page format (Output Media) for Postscript or PDF files and to scale the image to a desired pixel size for other images.

To achieve the best output it is usually advisable to adjust the settings in the Viewer Print Manager, Data Display Options, and Viewer Canvas Manager . For PDF and Postscript output, turning the DPI up all the way yields the best-looking results. For other images, a white background often makes for better looking images than the default black. It is often necessary to increase the Line Width in the Axis Label Properties (in the Data Display Options panel) to ensure that the labels will be visible when printed. Increasing from the default of 1.4 to a value around 2 often works well.

Figure 7.38 shows an example of printing to a file while adjusting the Data Display Options and Viewer Canvas Manager to improve the appearance of the plot.

7.7  Image Viewer (imview)

The imview task offers scriptable access to many viewer options. This enables the production of customized plots without invoking the GUI and allows one to open the viewer to a carefully selected state.

imview has the following inputs:

#  imview :: View an image
raster              =         {}        #  (Optional)  Raster filename (string)
                                        #   or complete raster config
                                        #   dictionary. The allowed dictionary
                                        #   keys are file (string), scaling
                                        #   (numeric), range (2 element numeric
                                        #   vector), colormap (string), and
                                        #   colorwedge (bool).
contour             =         {}        #  (Optional)  Contour filename (string)
                                        #   or complete contour config
                                        #   dictionary. The allowed dictionary
                                        #   keys are file (string), levels
                                        #   (numeric vector), unit (float), and
                                        #   base (float).
zoom                =          1        #  (Optional)  zoom can specify
                                        #   intermental zoom (integer), zoom
                                        #   region read from a file (string) or
                                        #   dictionary specifying the zoom
                                        #   region. The dictionary can have two
                                        #   forms. It can be either a simple
                                        #   region specified with blc (2 element
                                        #   vector) and trc (2 element vector)
                                        #   [along with an optional coord key
                                        #   ("pixel" or "world"; pixel is the
                                        #   default) or a complete region
                                        #   rectangle e.g. loaded with
                                        #   "rg.fromfiletorecord( )". The
                                        #   dictionary can also contain a
                                        #   channel (integer) field which
                                        #   indicates which channel should be
                                        #   displayed.
axes                =         -1        #  (Optional)  this can either be a
                                        #   three element vector (string) where
                                        #   each element describes what should
                                        #   be found on each of the x, y, and z
                                        #   axes or a dictionary containing
                                        #   fields "x", "y" and "z" (string).
out                 =         ''        #  (Optional)  Output filename or
                                        #   complete output config dictionary.
                                        #   If a string is passed, the file
                                        #   extension is used to determine the
                                        #   output type (jpg, pdf, eps, ps, png,
                                        #   xbm, xpm, or ppm). If a dictionary
                                        #   is passed, it can contain the
                                        #   fields, file (string), scale
                                        #   (float), dpi (int), or orient
                                        #   (landscape or portrait). The scale
                                        #   field is used for the bitmap formats
                                        #   (i.e. not ps or pdf) and the dpi
                                        #   parameter is used for scalable
                                        #   formats (pdf or ps).

The raster and contour parameters specify which images to load and how these images should be displayed. These parameters take python dictionaries as inputs. The fields in these dictionaries specify how the image will be displayed.

An example call to imview looks like this:

imview(raster={'file': 'ngc5921.clean.image',
                       'range': [-0.01,0.03],
                       'colormap': 'Hot Metal 2',
                       'scaling': -1},
               contour={'file': 'ngc5921.clean.image'},
               axes={'x':'Declination'} ,
               zoom={'channel': 7, 'blc': [75,75], 'trc': [175,175],
                     'coord': 'pixel'},
               out='myout.png')

The argument to raster is enclosed in the curly braces { } . Within these braces are a number of "key":"value" pairs. Each sets an option in the viewer, with the GUI parameter to set defined by the "key" and the value to set it to defined by "value." In the example above, ’file’:’ngc5921.clean.image’ sets the file name of the raster image, ’range’: [-0.01,0.03] sets the range of pixel values used for the scaling.

contour works similar to ’raster’ but can accept multiple dictionaries in order to produce multiple contour overlays on a single image. To specify multiple contour overlays, simply pass multiple dictionaries (comma delimited) in to the contour argument:

 contour={'file': 'file1.image', 'levels': [1,2,3] },
         {'file': 'file2.image', 'levels': [0.006, 0.008, 0.010] }

zoom specifies the part of the image to be shown.

axes defines what axes are shown. By default, the viewer will show ’x’:’Right Ascension’, ’y’:’Declination’ but one may also view position-frequency images.

out defines the filename of the output, with the extension setting the file type.

Currently, the following parameters are supported with additional functionality planned for future releases:

raster  -- (string) image file to open
           (dict)   file (string)     => image file to open
                    scaling (float)   => scaling power cycles
                    range (float*2)   => data range
                    colormap (string) => name of colormap
                    colorwedge (bool) => show color wedge?
contour -- (string) file to load as a contour
           (dict)   file (string)     => file to load
                    levels (float*N)  => relative levels
                    base (numeric)    => zero in relative levels
                    unit (numeric)    => one in the relative levels
zoom    -- (int)    integral zoom level
           (string) region file to load as the zoom region
           (dict)   blc (numeric*2)   => bottom left corner
                    trc (numeric*2)   => top right corner
                    coord (string)    => pixel or world
                    channel (int)     => channel to display
           (dict)   <region record>   => record loaded
                                         e.g. rg.fromfiletorecord( )
axes    -- (string*3) dimension to display on the x, y, and z axes
           (dict)     x               => dimension for x-axes
                      y               => dimension for y-axes
                      z               => dimension for z-axes
out     -- (string) file with a supported extension
                    [jpg, pdf, eps, ps, png, xbm, xpm, ppm]
            (dict)    file (string)   => filename
                      format (string) => valid ext (filename ext overrides)
                      scale (numeric) => scale for non-eps, non-ps output
                      dpi (numeric)   => dpi for eps or ps output
                      orient (string) => portrait or landscape

Examples are also found in help imview.

7.8  Measurement Viewer (msview)

The Measurement Viewer msview is mostly a clone of the viewer at this stage. A difference is that msview allows the user to select data before it is loaded into the GUI and displayed. A screenshot is shown in Fig. 7.39 and selection parameters are field, spectral window, time range, uv range, antenna, corr, scan, array, ms selection expression in the usual CASA selection syntax (see Sect. 2.3).


Figure 7.39: Data selection in msview.


Previous Up Next