Starting ChIPS

ChIPS Threads (CIAO 4.1)

Overview

Last Update: 15 Dec 2008 - CIAO 4.1 - when ChIPS is started a banner is now displayed (by default); Python or S-Lang mode for ChIPS can now be chosen using the -l flag; the CHIPS_SCRIPT_LANG environment variable has been superceeded by the CIAO_SCRIPT_LANG variable; a number of command-line options are now available; some low-level commands have been moved to the "advanced" module

Synopsis:

This thread describes how to start ChIPS for the first time, how to change the default from Python to S-Lang, and how to access the help files for ChIPS commands in a variety of ways.

Proceed to the HTML or hardcopy (PDF: A4 | letter) version of the thread.

Starting ChIPS for the First Time

The ChIPS script loads the ChIPS module, as well as the Crates module (S-Lang or Python help), which handles file input and output.

ChIPS can be run in two different languages: S-Lang and Python. There are several ways to tell CIAO which language to use:

Using the -l command-line flag

[New] The ChIPS script accepts a number of flags to control its behavior. This is new to CIAO 4.1. The -l flag determines what language to use (it over-rides all other methods).

To use Python:

unix% chips -l python
-----------------------------------------
Welcome to ChIPS: CXC's Plotting Package
-----------------------------------------
CIAO 4.1 Friday, December 5, 2008

chips-1>

To use S-Lang:

unix% chips -l slang
-----------------------------------------
Welcome to ChIPS: CXC's Plotting Package
-----------------------------------------
CIAO 4.1 Friday, December 5, 2008

chips-1>

[New] The banner displayed by ChIPS is new in CIAO 4.1. It replaces the S-Lang banner seen in CIAO 4.0 (and is the same for both Python and S-Lang modes).

Using the CIAO_SCRIPT_LANG environment variable

[New] If the -l flag is not given then the CIAO_SCRIPT_LANG environment variable is used to determine the language (this is also new to CIAO 4.1). The CIAO startup script sets this variable for you based on:

the value of the CIAO_SCRIPT_LANG line in your ~/.ciaorc file, if the file exists and the line is not commented out
otherwise python

So, to use Python:

unix% setenv CIAO_SCRIPT_LANG python
unix% chips
-----------------------------------------
Welcome to ChIPS: CXC's Plotting Package
-----------------------------------------
CIAO 4.1 Friday, December 5, 2008

chips-1>

and to use S-Lang:

unix% setenv CIAO_SCRIPT_LANG slang
unix% chips
-----------------------------------------
Welcome to ChIPS: CXC's Plotting Package
-----------------------------------------
CIAO 4.1 Friday, December 5, 2008

chips-1>

Using the CHIPS_SCRIPT_LANG environment variable

If the -l flag is not used and the CIAO_SCRIPT_LANG environment variable is not set then the contents of the CHIPS_SCRIPT_LANG environment variable will be used, if set. So

unix% unsetenv CIAO_SCRIPT_LANG
unix% setenv CHIPS_SCRIPT_LANG python

will use Python and

unix% unsetenv CIAO_SCRIPT_LANG
unix% setenv CHIPS_SCRIPT_LANG slang

will use S-Lang.

If none of the above are used

If you do not use the -l flag, do not have the CIAO_SCRIPT_LANG and CHIPS_SCRIPT_LANG environment variables set, and do not have a ~/.ciaorc file then the language to use defaults to Python.

Setting the Default ChIPS Language

[New] In CIAO 4.0 you had to edit the ChIPS preference file to specify the language to use. In CIAO 4.1 you edit your ~/.ciaorc file (which is a text file).

Choosing Python

If you wish to use Python then you do not need to do anything, since this is the default choice. However, you can edit ~/.ciaorc so that you get:

unix% grep CIAO_SCRIPT_LANG ~/.ciaorc
# CIAO_SCRIPT_LANG default is python. Other option is slang
CIAO_SCRIPT_LANG python

Choosing S-Lang

If you wish to use S-Lang then edit ~/.ciaorc so that you get:

unix% grep CIAO_SCRIPT_LANG ~/.ciaorc
# CIAO_SCRIPT_LANG default is python. Other option is slang
CIAO_SCRIPT_LANG slang

Getting Help on ChIPS commands

[Updated] There are several ways to access the ChIPS help files. In CIAO 4.0 you had to include py.chips or sl.chips as an argument to ahelp to select the Python or S-Lang version of the page; in CIAO 4.1 ahelp now uses the CIAO_SCRIPT_LANG environment variable to decide which language to display (in most cases).

From the CIAO command line

Python syntax, description and examples for a specific command, assuming that CIAO_SCRIPT_LANG is set to python:
```
unix% ahelp <command>
```
or to list all ChIPS Python help files (in this case you still need to include py.chips):
```
unix% ahelp -c py.chips
```
S-Lang syntax, description and examples for a specific command, assuming that CIAO_SCRIPT_LANG is set to slang:
```
unix% ahelp <command>
```
or to list all ChIPS S-Lang help files (in this case you still need to include sl.chips):
```
unix% ahelp -c sl.chips
```

From within ChIPS

From within Python or S-Lang, ahelp may be called two ways:

Python:

chips-3> ahelp "<command>"

chips-4> !ahelp <command>

S-Lang:

chips-3> ahelp("<command>");

chips-4> !ahelp <command>

If you have used the -l flag to override your default language choice then using the !ahelp form may need to include py.chips or sl.chips to select the correct language: for example in the following case

unix% echo $CIAO_SCRIPT_LANG
python
unix% chips -l slang
-----------------------------------------
Welcome to ChIPS: CXC's Plotting Package
-----------------------------------------
CIAO 4.1 Friday, December 5, 2008

chips-1> !ahelp sl.chips add_curve

Finding a Command

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

In Python: ? and <TAB>

[Updated] To search for a phrase, use the "?" system. This has changed from CIAO 4.0 in that you now place the ? after the string rather than before:

chips-6> *label* ?
ChipsAxisTicklabel
add_label
chips_label
current_label
...
shuffle_label

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

chips-7> move_
move_axis    move_label   move_plot    move_region
move_frame   move_line    move_point

In S-Lang: apropos and <TAB>

The apropos command returns a list of functions that contain that the given string:

chips-6> apropos label
 apropos label ==>
  ChipsAxisLabel
  ChipsAxisTicklabel
  ChipsLabel
  add_label
...
  shuffle_label

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

chips-7> move_
move_axis   move_frame  move_label  move_line   move_plot   move_point  
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-8> !pwd
/data/ciao_demo/threads/acis-s/1838/primary

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

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

chips-11> !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.

Exiting ChIPS

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

Command-line options for ChIPS

[New] CIAO 4.1 introduces a number of command-line options for the ChIPS script. They can be listed by using the -h flag:

unix% chips -h
-- chips
  usage: chips [-x] [-l python|slang] [-n] [-b] <file>
     -x       launch chips shell in separate display terminal
     -n       do not print banner
     -l       use python or slang shell
     -b       batch mode
     <file>   appropriate slang or python command file to execute

-l python|slang

This option allows you to select which language to use, as previously described.

-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 (S-Lang or Python help) is used to change the display attribute to 1 (or True in Python).

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.

<file>

The contents of the file are executed before the user is prompted for further commands. The commands must be in the same language - i.e. Python or S-Lang - as used at the interactive prompt. So, if simple.py and simple.sl contained

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

unix% cat simple.sl
add_curve ([1:5], [1:5]^2);
message ("Created curve");

then we get a plot of y=x² if ChIPS is started by saying either:

unix% chips -l python simple.py
-----------------------------------------
Welcome to ChIPS: CXC's Plotting Package
-----------------------------------------
CIAO 4.1 Friday, December 5, 2008

Created curve
chips-2> 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]
      X Axis [ax1]
      Y Axis [ay1]
      Curve [crv1]

chips-3>

unix% chips -l slang simple.sl
-----------------------------------------
Welcome to ChIPS: CXC's Plotting Package
-----------------------------------------
CIAO 4.1 Friday, December 5, 2008

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

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 scripts to

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

unix% cat simple.sl
add_curve ([1:5], [1:5]^2);
print_window ("simple-sl");

then we would see the following:

unix% chips -b -l python simple.py
unix% chips -b -l slang simple.sl
unix% ls simple-*ps
simple-py.ps    simple-sl.ps

Using ChIPS from S-Lang and Python

The ChIPS and Crates modules can be loaded into S-Lang and Python by using

require ("chips_hlui");
require ("crates");

and

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

respectively.

[Updated] In CIAO 4.1, some of the low-level commands have been moved into the "advanced" ChIPS module, so if you find that commands such as set_curve_linestyle are no-longer recognized, then either say

# Python
chips> from pychips.advanced import *

% S-Lang
chips> require ("chips_advanced");

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

# Python
from pychips.all import *

% S-Lang
require ("chips_all");

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); Python or S-Lang mode for ChIPS can now be chosen using the `-l` flag; the `CHIPS_SCRIPT_LANG` environment variable has been superceeded by the `CIAO_SCRIPT_LANG` variable; a number of command-line options are now available; some low-level commands have been moved to the "advanced" module