Last modified: 15 Dec 2015

URL: https://cxc.cfa.harvard.edu/chips/threads/chips_startup/

Starting ChIPS

ChIPS Threads (CIAO 4.11 ChIPS v1)


Overview

Synopsis:

This thread describes how to start ChIPS for the first time and how to access the help files for ChIPS commands in a variety of ways.

Last Update: 15 Dec 2015 - Updated for CIAO 4.8: added a note to the Starting ChIPS section about the IPython changes in this release.


Contents


Starting ChIPS for the First Time

The chips command starts the interactive ChIPS session, leaving you at a prompt at which you can enter any Python command (it is a customization of the ipython environment). The environment has both the ChIPS and Crates modules loaded. The program supports several command-line options, as described below; here we show several commands which plot up two columns from a file, change the properties of the plot, and then create a PDF version of the visualization:

First we start up ChIPS and then plot the data from a file (the make_figure routine is designed to quickly plot data from a file; it is also possible to use routines like add_curve):

unix% chips
-----------------------------------------
Welcome to ChIPS: CXC's Plotting Package
-----------------------------------------
CIAO 4.8 ChIPS version 1 Thursday, December 3, 2015

chips-1> make_figure("lc.fits[cols dt, count_rate]")
[NOTE]
Change in IPython directory in CIAO 4.8

The chips command runs IPython with a set of configurtion options - such as loading the ChIPS modules and changing the prompt. The location of these options has changed from $HOME/.ipyton-ciao45/ (used in versions 4.5, 4.6, and 4.7 of CIAO) to $HOME/.ipyton-ciao/. As this was the location used in CIAO 4.0 to 4.4, there may be some old configuration files in this directory. If any are found, a warning message will be displayed the first time that ChIPS is started and the old files moved to a different location.

At this point the display looks like Figure 1:

Figure 1: The make_figure command

[Thumbnail image: The columns have been plotted together, joined by lines and marked by points, and the plot title and axis labels have been set.]

[Version: full-size, PNG]

[Print media version: The columns have been plotted together, joined by lines and marked by points, and the plot title and axis labels have been set.]

Figure 1: The make_figure command

The make_figure call sets the plot title to the value of the OBJECT keyword in the file name, if it exists, and uses column metadata to label the axes (so here it can add in the units as well as the column labels).

The visualization can be manipulated, as shown below, to edit the existing properties or to add new items. The undo and redo commands are useful when editing your visualization!

chips-2> set_curve(["symbol.style", "none"])
chips-3> set_plot_title("Light curve")
chips-4> set_plot_xlabel(r"\Delta T (s)")
chips-5> set_plot_ylabel("Rate (count s^{-1})")
chips-6> log_scale(Y_AXIS)
chips-7> print_window("lc.pdf")
chips-8> show_gui()

The visualization created by these commands is shown in Figure 2, and the ChIPS GUI created by the show_gui() call is shown in Figure 3.

Figure 2: Plotting two columns from a file

[Thumbnail image: The light curve for the data shows a strong flare starting about 21 ks after the start of the observation.]

[Version: full-size, PNG, postscript, PDF]

[Print media version: The light curve for the data shows a strong flare starting about 21 ks after the start of the observation.]

Figure 2: Plotting two columns from a file

As each command is executed - e.g. set_curve(["symbol.style", "none"]) - the visualization is automatically updated. The other ChIPS threads show how the plot limits can be changed, new items - such as curves, histograms, contours, images, lines, labels and regions - can be added, and new plots created.

The Gallery page also provides a wide range of examples of the plotting capabilities of ChIPS.

Figure 3: The main ChIPS GUI window

[Thumbnail image: The default ChIPS GUI window contains areas for changing the limits and scaling of the axes, the properties of the objects, a small Pyton console, and a tool bar for common operations such as print and undo/redo.]

[Version: full-size]

[Print media version: The default ChIPS GUI window contains areas for changing the limits and scaling of the axes, the properties of the objects, a small Pyton console, and a tool bar for common operations such as print and undo/redo.]

Figure 3: The main ChIPS GUI window

The ChIPS GUI can be used to modify an existing plot, as described in the Using the ChIPS GUI section below. You can also add annotations - namely labels, points, lines, regions and color bars - directly from the GUI.

The print options - such as file name, format, and page size - can be set using a GUI by:

  1. using the "Print" option from the menu displayed by pressing the right-mouse button in the ChIPS window;

    [The right-mouse button brings up a list of options when used in the ChIPS window]
  2. using the print option from the ChIPS GUI;

  3. explicitly setting the printdialog attribute in the print_window call; for example

    chips-7> print_window(["printdialog", True])

Using ChIPS in other applications

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 *

The ChIPS GUI

The ChIPS GUI allows you to modify an existing visualization; for instance change the symbol style and line color of a curve, adjust the limits and scaling of an axis, and resize a plot.

For more information on the GUI, see the ahelp chipsgui page or try the Help/Reference Manual menu from the GUI.

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 GUI contains several areas: Coordinates; Info; Properties; Shell/Error]

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:

Menu Item Description
Undo Calls undo(1)
Redo Calls redo(1)
Edit <Object>

This option creates a window with the properties of the chosen object. You can use this window to modify the object; it must be closed before using the ChIPS window or main GUI.

Delete <Object>

The selected object will be deleted.

This option can also be selected by pressing the Delete or Backspace keys when the ChIPS window is active.

Shuffle Object

This item offers four options in a sub-menu: Shuffle Forward; Shuffle Backward; Shuffle Front; and Shuffle Back. They correspond to the shuffle_forward, shuffle_backward, shuffle_front, and shuffle_back commands.

Annotate

This item offers the following options in a sub-menu: Label; Point; Polyline; Horizontal Line; Vertical Line; Polygon; Ellipse; Box; and Colorbar.

These commands allow you to add annotations - labels, points, lines, regions and color bars - directly from the ChIPS window. You can also use the new "Annotate" menu item in the main ChIPS GUI.

Pan

Changes the interaction mode in the window to "Pan"; in this mode you can change the display limits of a plot by pressing down the left-mouse button and dragging the mouse.

If you have a wheel on your mouse then scrolling it will zoom into or out of the plot, as will pressing the + or - keys.

This mode can be chosen by pressing the p key when the ChIPS window is active.

Range

Changes the interaction mode in the window to "Range". Here you press down the left-mouse button at one corner and drag to the opposite corner; on release of the mouse button the limits will change to the selected region. This corresponds to the pick_limits command.

If you have a wheel on your mouse then scrolling it will zoom into or out of the plot, as will pressing the + or - keys.

This mode can be chosen by pressing the r key when the ChIPS window is active.

Select

Changes the interaction mode in the window to "Select". In this mode, objects are selected by clicking on them which will display a set of cyan handles at the bounding box of the object and change the properties frame of the main GUI - if displayed - to show this object. When an object is selected the Edit, Delete, and Shuffle options of the menu are selectable.

The Select mode acts like the Pan mode when you click on a part of a plot that does not contain an object; i.e. you can still drag around and zoom into or out of the plot.

This mode can be chosen by pressing the s key when the ChIPS window is active.

Print Calls print_window(["printdialog", True])
Show GUI Calls show_gui()

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:
[The plot title has been selected so is surrounded by cyan handles]

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:
[The axis has been selected, with three handles shown]

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:
[Handles are drawn at the corners and mid-points of 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:
[Handles are drawn at the bounding box of the 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:
[Handles are drawn at the corners and mid-points of the frame, in this case at the edges of the ChIPS window]

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:

[The options include 'Show Tooltips', 'Highlight on Selection', 'Selection Color' and 'Range Color']

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

[A box is shown in the plot which expands as you type into it.]
[Print media version: A box is shown in the plot which expands as you type into it.]

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:

[The menu contains items for adding Labels, Points, Lines (polylines, horizontal, or vertical), Regions (polygon, ellipse, or box), and a Color bar]
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 GUI contains a Tool Bar, Coordinate Frame, Information Frame, Propeties Frame, and a Shell/Error Frame]
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:

[The Tree mode shows the structure of the objects in the visualization]

Info mode:

[The Icon mode shows a list of icons, one for each object in the visualization]

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 window displays just the Curve properties from the main GUI]
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:

    [The left-hand column now contains the Properties and Coordinates frames, with the right column showing just the Information Frame]
  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


Getting Help on ChIPS commands

There are several ways to access the ChIPS help files, as described below.

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>

Finding a Command

Here are some tips on how to find the name of a command while working in ChIPS.

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   

Running CIAO and unix commands from the ChIPS Prompt

Any line beginning with "!" is passed from ChIPS to the shell. This allows you to run CIAO and shell commands from the ChIPS prompt.

For example:

chips> !pwd
/data/ciao_demo/threads/acis-s/1838/primary

chips> !ls
acisf01838_000N001_bpix1.fits  acisf01838N001_src2.fits
acisf01838N001_evt2.fits       pcadf084244404N001_asol1.fits

chips> !dmkeypar acisf01838N001_evt2.fits OBJECT echo+
G21.5-0.9

chips> !dmcopy "acisf01838N001_evt2.fits[energy=300:10000]" 1838_energy.fits

Undo and Redo

There is a history mechanism - accessed using the undo() and redo() routines - that allows you to easily recover from accidental or unwanted changes.

Refer to the help files for information about how ChIPS stores the undo and redo stacks.


Tracking down errors

When an error occurs, the default behavior of both ChIPS and Sherpa is to display the error itself but not to display the location of the error (the Python traceback), since this information is often not useful in an interactive environment.

To get this traceback information - e.g. when debugging a Python script - change the sys.tracebacklimit variable to a positive integer; this value controls the number of entries that are displayed (and defaults to 0). For example:

import sys
sys.tracebacklimit = 2

Saving and restoring a ChIPS session

The make_script Python command creates an editable Python script that, if used in another ChIPS session, will re-create the current visualization. The file created by make_script will re-create the current visualization but is not guaranteed to use the same set of commands that you used to create it.

This complements the save_state command, which saves a binary version of the ChIPS state; this file is not editable, but does retain the order of commands used to create the plot(s).

The ChIPS GUI provides access to both the make_script and save_state commands via the File/Save As menu item.


Exiting ChIPS

Type "quit" or use <CTRL>-D to exit ChIPS.


Command-line options for ChIPS

The command-line options for ChIPS can be listed by using the -h flag:

unix% chips -h
-- chips
  usage: chips [-x] [-n] [-b] [-rcfile file] <file>
     -x       launch chips shell in separate display terminal
     -n       do not print banner
     -b       batch mode
     -rcfile  load a user specifiable preference file
     <file>   Python command file to execute
-x

This will create a new Xterm and start ChIPS in it.

-n

This switch causes ChIPS to start without a banner:

unix% chips -n
chips-1>
-b

Setting this switch causes ChIPS to set the window.display to false for the session. This will mean that ChIPS windows will not be displayed unless the preference is explicitly changed to true before a window is created, or set_window is used to change the display attribute to True.

As the presence of the script causes ChIPS to exit once it has processed the command-line options it needs to be followed by a file name. Selecting -b automatically selects -n.

-rcfile <file>

Use the specified ChIPS resource file rather than $HOME/.chips.rc.

<file>

The contents of the file are executed before the user is prompted for further commands. So, if simple.py

unix% cat simple.py
add_curve([1,2,3,4,5], [1,4,9,16,25])
print("Created curve")

then we get a plot of y=x2 if ChIPS is started by saying:

unix% chips simple.py
-----------------------------------------
Welcome to ChIPS: CXC's Plotting Package
-----------------------------------------
CIAO 4.8 ChIPS version 1 Thursday, December 3, 2015

Created curve
chips-1> print(info())
Window [win1]
  Frame [frm1]
    Plot [plot1]   (0.15,0.15)  .. (0.90,0.90)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      Curve [crv1]
      X Axis [ax1]
      Y Axis [ay1]

chips-2>

If the -b flag is also given then no display will be created, no banner displayed, and the session will exit once the script has finished. So, if we edit the script to say

unix% cat simple.py
add_curve([1,2,3,4,5], [1,4,9,16,25])
print_window("simple.ps", ["clobber", True])

then we would see the following:

unix% chips -b simple.py
unix% ls simple.ps
simple.ps

History

22 Aug 2007 new for CIAO 4.0 [Beta 2]
15 Dec 2008 CIAO 4.1 - when ChIPS is started a banner is now displayed (by default); a number of command-line options are now available; some low-level commands have been moved to the "advanced" module
15 Dec 2009 Updated for CIAO 4.2; added a new section on Saving and restoring a ChIPS session.
15 Dec 2010 Updated for CIAO 4.3; removal of support for the S-Lang interface and improved support for the sys.tracebacklimit setting.
15 Dec 2011 Updated for CIAO 4.4; included a section on the new GUI; Using ChIPS from Python has been moved into a new Using ChIPS from applications section; and added ChIPS output to the Starting ChIPS section.
13 Dec 2012 Updated for CIAO 4.5: updated the GUI section to include the new Annotation support; the documentation and preferences have been updated to use "Frame" rather than "Pane".
03 Dec 2013 Updated for CIAO 4.6.
10 Dec 2014 Updated for CIAO 4.7: noted the change to the window.smoothing preference and the new form of the ahelp command.
15 Dec 2015 Updated for CIAO 4.8: added a note to the Starting ChIPS section about the IPython changes in this release.