Chandra X-Ray Observatory
Skip to the navigation links
Last modified: 6 Dec 2015


Starting Sherpa

Sherpa Threads (CIAO 4.9 Sherpa v1)



This thread describes how to start Sherpa for the first time, how to access the help files for Sherpa commands in a variety of ways, as well as how to customize the Sherpa environment.

Last Update: 6 Dec 2015 - updated for CIAO 4.9


Starting Sherpa for the First Time

When Sherpa is started from within the CIAO environment, the user is informed of the CIAO version number, Sherpa package number, and date at which CIAO was installed on the user's system:

unix% ciao
CIAO configuration is complete... 
CIAO 4.9 Friday, December  2, 2016
  bindir      : /soft/ciao-4.9/bin

unix% sherpa
Welcome to Sherpa: CXC's Modeling and Fitting Package
CIAO 4.9 Sherpa version 1 Friday, December 2, 2016

The Sherpa package number is indicated by "version 1" in the above message. This means this is the first version of Sherpa released with CIAO 4.8—i.e., the major release version. If an intermediate patch of Sherpa is later released for CIAO 4.8, the package number will be incremented for that patch release, and the above text would change to "version 2".

The Sherpa script loads the Sherpa (Python) module, as well as the Crates module, 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.

The Sherpa and ChIPS applications use the $HOME/.ipython-ciao/ directory to store configuration information. The first time Sherpa or ChIPS is started you will see a message asking whether you want to update your ipythonrc-sherpa or ipythonrc-chips file.

unix% ciao
unix% sherpa

 ATTENTION: Out of date IPython profile for Sherpa found in:

           Local version (40201) vs latest (40301).
           Update to latest? [Y/N] :

Unless you have manually changed your $HOME/.ipython-ciao/ipythonrc-sherpa(or -chips) file, it is safe to answer "Y" here. The outdated file is renamed with a timestamp to preserve it. The new profile is installed read-only. If you would like to modify how Sherpa uses IPython functions, or call "exec"/"execfile" to load Python scripts when Sherpa starts, the customization file ~/.ipython-ciao/ipythonrc-sherpa-user should be used. If you would like IPython profiles to be somewhere other than ~/.ipython-ciao, you can set IPYTHONDIR to point to the desired directory.

A new IPython 0.13 Sherpa profile, first introduced with CIAO 4.5, is installed in ~/.ipython-ciao4.5 (profiles for CIAO 4.4 and earlier will remain unchanged in ~/.ipython-ciao). The Sherpa IPython 0.13 profile does not import Python code from the current working directory while Sherpa is being imported, to avoid Sherpa startup errors, but this capability is restored after Sherpa is finished importing.


IPython 0.13 profiles are incompatible with IPython 0.10, and vice-versa, which is why the IPython 0.13 profile is stored in a different directory. Users can switch back and forth between pre-CIAO 4.5 and later versions of Sherpa.

Sherpa runs in the Python scripting language. As of the release of Sherpa version 2 in CIAO 4.2, the Sherpa S-Lang interface is no longer supported; there is no longer any means of importing Sherpa as a S-Lang module. Therefore, the "-l" command-line option has been removed, and Sherpa no longer reads the environment variables CIAO_SCRIPT_LANG or SHERPA_SCRIPT_LANG. The following are the remaining command-line options which may be specified when Sherpa is started:

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

See the section Command-line Options for Sherpa for more details on these Sherpa startup options.

Getting Help

There are several ways to access the Sherpa help files.

From the CIAO command line

  • Python syntax, description and examples for a specific command:

    unix% ahelp <command>

From within Sherpa

From within Python, ahelp may be called in several ways:

  • Python:

    sherpa> ahelp "<command>"


    sherpa> !ahelp <command>


    sherpa> ,ahelp <command>

Finding a Command

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

In Python: ? and <TAB>

To search for a phrase, use the "?" system; the ? is placed after the string:

sherpa-6> *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

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

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

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

The Sherpa command-line options can be listed with the -h flag:

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

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


This switch causes Sherpa to start without a banner:

unix% sherpa -n

Executes Python command file as a non-interactive Sherpa session.


This option allows the user to specify a specific .sherpa.rc file to use; refer to "ahelp sherparc" for details.


This option specifies that a .sherpa.rc file should not be loaded; overrides "-rcfile" if both are set.


The contents of the file are executed before the user is prompted for further commands. The command must be in the same language as used at the interactive prompt. So, if contained

unix% cat
print "Loaded and plotted data"

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

unix% sherpa
Welcome to Sherpa: CXC's Modeling and Fitting Package
CIAO 4.9 Sherpa version 1 Friday, December 2, 2016

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]


Using Sherpa from Python

The Sherpa, ChIPS, and Crates modules which come packaged with CIAO can be loaded into Python as follows, enabling the user to access Sherpa functionality on the Python command line.

% ciao
CIAO configuration is complete... 
CIAO 4.8 Thursday, December  3, 2015
  bindir      : /soft/ciao-4.8/bin

% python
Python 2.7.10 (default, Nov 10 2015, 12:07:16) 
[GCC 4.4.7 20120313 (Red Hat 4.4.7-16)] on linux2
Type "help", "copyright", "credits" or "license" for more information.

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

Sherpa is also available for Python users as a standalone application, independent of CIAO; download instructions and user documentation are available at the Contributed CIAO Sherpa (Python) Extension Packages page.

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 matplotlib and would like Sherpa to plot with this program instead of the default CIAO plotting package (ChIPS), 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.


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"
15 Dec 2009 updated for CIAO 4.2
29 Jun 2010 updated for Sherpa v2 in CIAO 4.2: the Sherpa S-lang interface has been removed.
15 Dec 2010 updated with an explanation of the Sherpa start-up banner
15 Dec 2011 reviewed for CIAO 4.4: Sherpa start-up banner updated
10 Apr 2012 typo in executing python script
13 Dec 2012 new IPython 0.13 profile available in CIAO 4.5
03 Dec 2013 reviewed for CIAO 4.6: Sherpa start-up banner updated
02 Dec 2014 updated for CIAO 4.7
14 Dec 2015 updated for CIAO 4.8
06 Dec 2015 updated for CIAO 4.9

Last modified: 6 Dec 2015
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email: Smithsonian Institution, Copyright © 1998-2017. All rights reserved.