Starting ChIPS

ChIPS and Sherpa

Sherpa automatically loads ChIPS for you, so you have access to the ChIPS commands from the Sherpa shell. You can also use the ChIPS GUI from Sherpa just as you would from ChIPS. A number of Sherpa threads describe this, including the Plotting in Sherpa thread.

ChIPS and Prism

The Prism file browser uses ChIPS for plotting data. Information on how to use ChIPS in Prism, including the ChIPS GUI, is provided in the Introduction to Prism thread.

Using ChIPS from Python

The ChIPS and Crates modules can be loaded into Python with:

from pychips import *
from pychips.hlui import *
from pycrates import *

Advanced users may wish to use the low-level commands provided by the "advanced" ChIPS module. This module can be loaded by saying:

from pychips.advanced import *

or load in the "all" module (in which case you do not have to load in any of the other ChIPS modules):

from pychips.all import *

Displaying the GUI

The GUI can be started from the command line, by saying

chips> show_gui()

or by selecting the Show GUI option from the right-mouse button menu available in the ChIPS window. It looks like:

The ChIPS GUI can be opened and closed multiple times within a ChIPS session.

Using the Right-Mouse-Button Menu

As already mentioned, the right-mouse button in the ChIPS window will bring up a menu with the following options:

Interacting with the ChIPS window

As described in the previous section, a number of common options are provided in the right-mouse button menu of the ChIPS window. Other ways to interact with the visualization include:

• changing the mode from Pan to Range or Select,
• using the keyboard,
• and dragging, zooming, or selecting with the mouse.

The Pan, Range, and Select modes are described in the table above, and determine what a mouse click or drag does.

Selecting an object

An object can be selected by double clicking on it - which will also change the mode to Select - or from the Information Frame of the main GUI. A selected object will be surrounded by a set of handles, as shown in the following examples:

A label, including axes labels and plot titles:

Note that there is an extra handle above the bounding box; this is used to change the rotation of the label. Dragging on one of the other labels will change the label size, and dragging the whole label around will move it.

An axis:

Since an axis has no "width", there are only three handles drawn along the length of the axis. Note that the axis tick labels and label are not surrounded by the handles in this case. Axes can be moved but only in one dimension.

The plot:

Here handles are drawn at the corners and mid-points of the axes. To select the plot rather than an axis you need to choose one of the borders (in this case the top or right ones), or use the main GUI, since clicking on the left or bottom axes will just select that axis. The handles can be dragged to resize or move the plot.

A curve:

The handles are drawn around the full data range of the curve. If the curve extends outside of the plot area then the handles will be drawn at the plot boundary, and so will look similar to the plot-select case above. You can use the right-mouse button menu, or the main GUI, to check what has been selected.

The frame:

Selecting outside the plot area will select the underlying frame. In this case the frame fills the ChIPS window so the handles are drawn at the edges of the window. They can be dragged to re-size the frame.

As well as moving or re-sizing objects, several options are available from the right-mouse-button menu once an object has been selected: Edit <Object>, Delete <Object>, and Shuffle Object.

The keyboard can also be used to interact with a selected object:

• arrow keys will move an object around if there is a move_<object> command - essentially all objects but windows, curves, histograms, contours and images - and there is space for the object to move in,

• and the backspace or delete key will delete the object if possible.

Useful settings

The Edit/Gui Configuration menu option in the main GUI allows you to change the color used for the selection handles from the default value of cyan. If the Highlight on Selection setting is selected then objects will flash briefly when they are selected. Both values are available in the General tab, shown below:

Adding annotations to a plot

It is possible to add annotations to a visualization directly from the GUI, using either the RMB menu - mentioned above - or from the Annotate menu in the GUI.

Figure 4 shows the process of creating a label by selecting the Label entry from the Annotate menu.

Figure 4: Adding a label to a plot using the Annotate menu

Figure 4: Adding a label to a plot using the Annotate menu

The outlined box - containing the text "Variable background rate" - expands as you enter more text. It disappears, and the label is completed, by hitting the return key. At this point the label can be repositioned - e.g. by selecting it, so that handles appear around it, and then dragging - or its properties changed from the GUI or command line.

Due to the screen capture tool used to create this image the ChIPS cursor, which appears as a pencil when a label is being added, is not included in the image.

The Annotate menu item from the GUI looks like:

Label

When this option is selected, the cursor turns into a cross. Selecting a point starts the label at this position; a rectangle is drawn on the screen and any text that is entered will fill the box until either return or escape is entered. At this point the label is selected, so it can be moved around with the mouse/keyboard or its properties changed from the GUI or command line.

Point

When this option is selected, the cursor turns into a cross. Clicking on the plot places a symbol at this position (a ChIPS point), and selects it, so it can be moved around with the mouse/keyboard or its properties changed from the GUI or command line.

Polyline

When this option is selected, the cursor turns into a cross, and line segments are drawn between the vertices created by clicking with the left mouse button. A dotted magenta line indicates where the next line segment would lie if the left mouse button were pressed (this appears once at least one point has been selected). Press the Escape key to end the process, at which point the line will be selected. Unlike polygons, line segments are allowed to intersect.

Horizontal Line

A horizontal line is added at the position of the mouse click.

Vertical Line

A vertical line is added at the position of the mouse click.

Polygon

This is similar to creating a Polyline except that:

1. when Enter is pressed the region is closed,

2. and polygons can not contain intersecting line segments.

Ellipse

Select one corner that is to contain the ellipse and then drag the mouse to the opposite corner (a dotted representation of the ellipse will appear). Releasing the mouse will create the ellipse (which is represented as a ChIPS region).

Box

Select one corner and then drag the mouse to the opposite corner (a dotted representation of the rectangle will appear). Releasing the mouse will create the box (which is represented as a ChIPS region).

Colorbar

A colorbar is added at the position of the mouse click. Unless the preferences have been changed this will be aligned horizontally and fill the width of the plot. It can be moved with the mouse, by changing the coordinates in the GUI, or with the move_colorbar command.

Individual vertexes of regions and lines can not be edited

Note that the coordinates of the lines and regions created by these actions can not be edited, other than to move the whole shape. That is, if an ellipse has been created it can not then be selected and re-sized or rotated.

Changing the layout of the GUI

The default layout for the GUI contains several areas (also called frames in the documentation):

The Tool Bar

The tool bar has two sections: on the left are buttons that let you change the interaction mode when you use the mouse in the ChIPS window, and the right are common options like undo, redo, print, and clear plot. The display for the buttons can be changed from the default value of both to just labels or icons using the Edit/Gui Configuration menu option.

The Coordinates Frame

The coordinate frame lists the currently-selected plot and X/Y axis pair, which you can change using the drop-down menu. It also lets you change the axis limits, by entering in values or using the "auto" button to use the maximum data range of all the objects in the plot. The axis scale (logarithmic or linear) and direction can also be changed here by using the "log" and "flip" buttons respectively.

The top-right area of this frame contains a simple display showing the data range of the current plot as a black rectangle and the display range as the blue rectangle. Clicking and dragging within this area will scroll the data around, and using the scroll wheel on your mouse will zoom into or out of the plot.

The Information Frame

The Information Frame is used to show the current objects that have been created. The default appearance ("Tree") follows that used by the info command but this can be changed to an icon mode by using the right-mouse button within the area to select the "Icon" mode. Selecting an item in this area will display the object's properties in the Properties Frame. If the mode is set to "Select" then the object will also be highlighted in the ChIPS window (by displaying the cyan squares at the edges of the object).

Tree mode:

Info mode:

The above displays were created by turning off all but the "Show Property Frame" and "Show Info Frame" options in the View menu option of the GUI.

Arrow keys - up and down in Tree mode and left and right in Icon mode - can be used to change the selected object.

When in Tree mode, typing a phrase in the information frame will display a text box and jump to the first object that matches the text. This can be particularly helpful when a large number of objects have been created. The search is progressive so "ax" will take you to an Axis object and then you can add 1 to get to the axis called "ax1" or use the up and down arrow keys to jump between those items that match the current search term. The search is case insensitive.

The Properties Frame

This area is used to display the properties of the selected object (either by selecting an object in the Information Frame or by clicking on the object in the ChIPS window when the mode is set to Select). If the object has many attributes - such as a curve or axis - then the display will use a tabbed interface to display related components.

The contents of this frame are displayed in a separate window by the Edit <Object> option of the right-mouse-button menu. As an example we show the properties of a curve where the line color had been changed to "navy" and the style to "dotted", and the symbols to magenta diamonds:

The Shell/Error Frame

This area of the GUI contains an embedded ChIPS shell, which can be used to enter ChIPS or any other Python command, and an Errors tab which is used to display certain error messages from ChIPS commands.

Errors caught by the GUI - such as trying to delete an axis when it is displaying an object such as a curve or label - will be displayed in the Error tab. The label of the tab changes color to red to indicate the presence of an error; selecting the tab will display the error message and reset the label to its normal color.

There are two customizations that can be made:

1. Using the Alternate layout

   By selecting the View/Alternate Layout menu item, the layout of the frames is changed so that the Information Frame forms the right-hand column and the Properties and Coordinate frames the left-hand column:

   

2. Hiding certain frames

   The View menu also lets you select which frames should be displayed and which hidden. The default is to show all frames.

   The two views of the Information frame shown above were created by turning off all but the "Show Property Frame" and "Show Info Frame" option.

   These settings can also be changed using the "Edit/Gui Configuration" menu option using the options in the Frames tab.

Closing down the GUI

As mentioned earlier, the GUI can be closed down and re-opened multiple times from the same ChIPS session.

The ChIPS window (or windows) will exist as long as either the original program is running - e.g. ChIPS or Sherpa shells - or the GUI is displayed. This means that if you have a GUI running and then leave the original ChIPS process (e.g. use exit() or control-d) then the GUI and window will remain. Selecting File/Quit from the GUI - or using the Window Manager's close-window button - is required to close down the visualization.

The GUI preferences

The GUI contains menu items which let you customize its appearance and behavior (Edit/Gui Configuration and the View menu items). Some of the settings are also settable using the standard ChIPS preference values:

chips> print(get_preference("gui"))
gui.view.toolbar       : true
gui.view.propertyframe : true
gui.view.navframe      : true
gui.view.infoframe     : true
gui.view.shellframe    : true
gui.toolbar.mode       : pan
gui.toolbar.style      : both
gui.toolbar.zoom       : true
gui.tooltips           : true

From the command line

The ChIPS commands are provided with ahelp files, which can be viewed with the ahelp program; for instance

unix% ahelp <add_curve>

From within ChIPS

From within ChIPS ahelp may be called by saying one of the following:

chips> ahelp <command>
chips> ahelp "<command>"
chips> ,ahelp <command>

(where the "," starting the line means that the second argument should be treated as a string, so this is a short form for the previous version) or the ahelp tool can be run as a separate process using

chips> !ahelp <command>

The ? and tab completion

To search for a phrase, use the "?" system from ipython:

chips> *curve* ?
add_curve
chips_curve
current_curve
delete_curve
...
set_curve
shuffle_curve

Type the start of a command and hit <TAB> for all possible completions:

chips> move_
move_axis      move_frame     move_line      move_point     
move_colorbar  move_label     move_plot      move_region