Starting Sherpa

Sherpa Threads (CIAO 4.1)

Overview

Last Update: 31 Mar 2009 - added section "Customizing the Sherpa Environment"

Synopsis:

This thread describes how to start Sherpa for the first time, how to change the default scripting interface from Python to S-Lang, how to access the help files for Sherpa commands in a variety of ways, as well as how to customize the Sherpa environment.

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

Starting Sherpa for the First Time

The Sherpa script loads the Sherpa module, as well as the Crates module (S-Lang or Python help), which handles file input and output, and the ChIPS module, which provides the plotting capabilities. Default Sherpa settings are defined in the $HOME/.sherpa.rc file, which is processed when Sherpa is started; this file can be modified as described in the section "Customizing the Sherpa Environment."

Sherpa 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 Sherpa 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% sherpa -l python
-----------------------------------------------------
Welcome to Sherpa: CXC's Modeling and Fitting Package
-----------------------------------------------------
CIAO 4.1 Friday, December 5, 2008

sherpa-1>

To use S-Lang:

unix% sherpa -l slang
-----------------------------------------------------
Welcome to Sherpa: CXC's Modeling and Fitting Package
-----------------------------------------------------
CIAO 4.1 Friday, December 5, 2008

sherpa-1>

[New] The banner displayed by Sherpa 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% sherpa
-----------------------------------------------------
Welcome to Sherpa: CXC's Modeling and Fitting Package
-----------------------------------------------------
CIAO 4.1 Friday, December 5, 2008

sherpa-1>

and to use S-Lang:

unix% setenv CIAO_SCRIPT_LANG slang
unix% sherpa
-----------------------------------------------------
Welcome to Sherpa: CXC's Modeling and Fitting Package
-----------------------------------------------------
CIAO 4.1 Friday, December 5, 2008

sherpa-1>

Using the SHERPA_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 SHERPA_SCRIPT_LANG environment variable will be used, if set. So

unix% unsetenv CIAO_SCRIPT_LANG
unix% setenv SHERPA_SCRIPT_LANG python

will use Python and

unix% unsetenv CIAO_SCRIPT_LANG
unix% setenv SHERPA_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 SHERPA_SCRIPT_LANG environment variables set, and do not have a ~/.ciaorc file then the language to use defaults to Python.

Setting the Default Sherpa Language

[New] In CIAO 4.0 there was no way to specify the language to use for Sherpa. 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

[Updated] There are several ways to access the Sherpa help files. In CIAO 4.0 you had to include py.sherpa or sl.sherpa 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 Sherpa Python help files (in this case you still need to include py.sherpa):
```
unix% ahelp -c py.sherpa
```
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 Sherpa S-Lang help files (in this case you still need to include sl.sherpa):
```
unix% ahelp -c sl.sherpa
```

From within Sherpa

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

Python:

sherpa> ahelp "<command>"

sherpa> !ahelp <command>

sherpa> ,ahelp <command>
sherpa> ,ahelp py.crates <command>
sherpa> ,ahelp sl.crates <command>

S-Lang:

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

sherpa-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.sherpa or sl.sherpa to select the correct language: for example in the following case

unix% echo $CIAO_SCRIPT_LANG
python
unix% sherpa -l slang
-----------------------------------------------------
Welcome to Sherpa: CXC's Modeling and Fitting Package
-----------------------------------------------------
CIAO 4.1 Friday, December 5, 2008

sherpa-1> !ahelp sl.sherpa load_pha

Finding a Command

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

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:

sherpa-6> *arf* ?
get_arf
get_arf_plot
get_bkg_arf
is_arf
load_arf
load_bkg_arf
load_multi_arfs
plot_arf
read_arf
set_arf
unpack_arf
write_arf

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

sherpa-7> write_
write_arf    write_file   write_pha    write_rmf

In S-Lang: apropos and <TAB>

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

sherpa-6> apropos arf
 apropos arf ==>
  ARFCrate
  DataARF
  get_arf
  get_arf_plot
  get_bkg_arf
  is_arf
  load_arf
  load_bkg_arf
  load_multi_arfs
  plot_arf
  read_arf
  set_arf
  unpack_arf
  write_arf

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

sherpa-7> write_
write_arf  write_file write_pha  write_rmf

Running CIAO and unix commands from the Sherpa Prompt

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

For example:

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

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

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

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

Exiting Sherpa

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

Command-line options for Sherpa

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

unix% sherpa -h
-- sherpa
  usage: sherpa [-x] [-n] [-l python|slang] [-b] <file>
     -x       launch sherpa 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 Sherpa in it.

-n

This switch causes Sherpa to start without a banner:

unix% sherpa -n
sherpa-1>

-b

This flag does not work correctly in CIAO 4.1.

<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
load_pha("src.pi")
plot_data()
print "Loaded and plotted data"

unix% cat simple.sl
load_pha("src.pi");
plot_data;
message ("Loaded and plotted data");

then we will load and plot the data if Sherpa is started by saying either:

unix% sherpa -l python simple.py
-----------------------------------------------------
Welcome to Sherpa: CXC's Modeling and Fitting Package
-----------------------------------------------------
CIAO 4.1 Friday, December 5, 2008

read ARF file src.arf
read RMF file src.rmf
read background file bgnd.pi
Loaded and plotted data
sherpa-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]

sherpa-3>

unix% sherpa -l slang simple.sl
-----------------------------------------------------
Welcome to Sherpa: CXC's Modeling and Fitting Package
-----------------------------------------------------
CIAO 4.1 Friday, December 5, 2008

read ARF file src.arf
read RMF file src.rmf
read background file bgnd.pi
Loaded and plotted data
sherpa-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]

sherpa-2>

Using Sherpa from S-Lang and Python

The Sherpa, ChIPS, and Crates modules can be loaded into S-Lang and Python by saying

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

and

from sherpa.astro.ui import *
from pychips import *
from pychips.hlui import *
from pycrates import *

respectively.

Customizing the Sherpa Environment

When Sherpa is started, it processes the $HOME/.sherpa.rc resource file, which defines the default behavior for Sherpa commands. You can modify the settings in this file in any text editor to suit your preferences; see the .sherpa.rc ahelp file for detailed descriptions of the available settings.

For example, if you have installed the plotting package PyLab and would like Sherpa to plot with this program instead of the default CIAO plotting package (ChIPS), you would change the entry for the 'plot_pkg' option in the Sherpa resource file from 'chips' to 'pylab':

unix% grep plot_pkg ~/.sherpa.rc
plot_pkg   : pylab

If the plotting package is ChIPS, any preferences set in the $HOME/.chips.rc resource file will be available during plotting. There is an option to override the .chips.rc settings in .sherpa.rc; refer to the "[chips]" section of the .sherpa.rc ahelp file for details.

History

14 Nov 2007	new for CIAO 4.0 Beta 3
15 Dec 2008	CIAO 4.1 - when Sherpa is started a banner is now displayed (by default); Python or S-Lang mode for Sherpa can now be chosen using the `-l` flag; the `SHERPA_SCRIPT_LANG` environment variable has been superceded by the `CIAO_SCRIPT_LANG` variable; a number of command-line options are now available
31 Mar 2009	added section "Customizing the Sherpa Environment"