Last modified: December 2019

AHELP for CIAO 4.12 Sherpa v1


Context: sherpa


Introduction to Sherpa, the CIAO modeling and fitting package


The CIAO 4 release includes a new, more powerful version of Sherpa, the CIAO modeling and fitting package. Sherpa enables the user to construct complex models from simple definitions and fit those models to data, using a variety of statistics and optimization methods.

This document provides an introduction to Sherpa; more information is available on the Sherpa website.

Sherpa is designed for use in a variety of modes: as a user-interactive application and in batch mode. The Sherpa command launches an interactive Python session (using the IPython interpreter), in which Sherpa commands (which are Python functions) can be used, as well as Matplotlib commands (to create and modify plots); Crates commands for reading and writing files; as well as other Python functions. It is possible to write Python scripts that import the relevant Sherpa modules, and so run non-interactively.

The Sherpa session can be saved into a platform-independent state file. The session can then be restored at any time.

Starting Sherpa

From the CIAO command line, type:

unix% sherpa [-x|-n|-b|-rcfile|-norcfile] <file>

Any or all of the following options which may be supplied when Sherpa is started:

The startup script loads the Sherpa module and the CRATES module, which handles file input and output ( "ahelp crates").

The "Starting Sherpa" thread has more details.

The Sherpa Resource File: .sherpa.rc

When Sherpa is started, it processes the $HOME/.sherpa.rc resource file. The resource file defines default behavior for the Sherpa commands and can be customized to the user's preferences; refer to "ahelp sherparc" for details.

Loading Modules

To import the Sherpa, CRATES, and Matplotlib modules in Python without using the "sherpa" startup script:

from sherpa.astro.ui import *
from pychips.hlui import *
from matplotlib import pyplot as plt
import numpy as np

It is likely that you will want to include the numpy module, so this is included in the example above too!

Getting Help

There are several ways to access the Sherpa help files. Note that in the CIAO 4.12 release the Pyton docstrings are the preferred option, and that the ahelp pages for Sherpa commands are not guaranteed to be kept up to date.

Within Sherpa

Within the Sherpa application, the native Python help system can be used:

sherpa> help <command>

It is also possible to do a wildcard search for commands, by taking advantage of the native IPython support:

sherpa> plot* ?
sherpa> *psf ?

Alternatively, the ahelp system can be used either directly:

sherpa> ahelp("<command>")
sherpa> ,ahelp <command>

or by running the ahelp command-line program:

sherpa> !ahelp <command>

From the CIAO command line

Syntax, description and examples for a specific command:

unix% ahelp <command>

Contributing to Sherpa

Development of Sherpa has moved to GitHub and can be found at Please consider contributing to Sherpa development - whether it is reporting bugs, providing documentation updates, fixing bugs, or adding new functionality. Using this repository, Sherpa can be installed outside of CIAO, and so used with Python packages that can not be installed into the CIAO environment.

Changes in CIAO 4.12

XSPEC models update

The XSPEC models have been updated to release 12.10.1n in CIAO 4.12. Support for the following models have been added to Sherpa: xsagnsed, xscph, xskyrline, xsqsosed, xsvcph, xszbknpower, and xszlogpar.

Default abundance and cross-section tables

The default setting for the photo-ionization table is now "vern" (in CIAO 4.11 and earlier it was "bcmc").

% python -c 'from sherpa.astro import xspec;

Note that both the abundance and cross-section tables will now be read from your XSPEC settings file, if it exists (this is due to a change in XSPEC 12.10.1). So, changing your ~/.xspec/Xspec.init file will change the default setting used by Sherpa. For example:

% egrep 'ABUND|XSECT' ~/.xspec/Xspec.init
XSECT: vern
ABUND: angr

ChIPS is no longer supported

As of CIAO 4.12, ChIPS is no-longer included in CIAO. Sherpa will automatically switch you to using matplotlib if your ~/.sherpa.rc file still asks for ChIPS, but please convert it so that it uses matplotlib (to avoid excess screen output):

unix% egrep '^plot_pkg' ~/.sherpa.rc
plot_pkg : pylab

One easy way to do this - if you have not changed anything in this file - is to delte ~/.sherpa.rc since it will be re-created the next time you start Sherpa.

%matplotlib is no longer needed

It is no-longer necessary to use the IPython magic command "%matplotlib" in a sherpa session. If you are using IPython then it is suggested that you use the --matplotlib option when starting it, to make sure Sherpa plots appear automatically:

% ipython --matplotlib

Plotting improvements

The plot_xxx family of routines - e.g. plot_data and plot_fit - can now accept plot settings as keyword arguments. The allowable keywords are the same as those returned by the get_xxx_plot_prefs routines - e.g. xlog, ylog, and color. This allows you to say

sherpa> plot_fit(ylog=True)
sherpa> plot_model(2, overplot=True, color='gray')

New routines have been added - plot_fit_ratio and plot_bkg_fit_ratio - that display the ratio of the model to data along with the "fit" plot.

Warnings about displaying error bars in plots, when error bars have been "turned off" - by setting the yerrorbars preference to False - have been removed from most plots (but will still occur for the combined fit and residual plot commands).

The plot_pvalue routine has seen improvements when fitting PHA spectra.

Paging and the show_xxx commands

The paging performed by the show_xxx commands - such as show_data and show_source - no longer uses an external command (controlled by the PAGER environment variable). It is now handled directly by Python, which means that the output will now appear in Jupyter notebooks.


The Python docstrings are the preferred means for documenting Sherpa's behavior. The ahelp files are still provided but are not guaranteed to be kept up to date. This means that the recommended command to use for help is now the Python help command, rather than ahelp, for Sherpa functions and model instances.


See the bugs pages on the Sherpa website for an up-to-date listing of known bugs.