Last modified: December 2020

AHELP for CIAO 4.13 Sherpa v1


Context: sherpa


Introduction to Sherpa, the CIAO modeling and fitting package


Welcome to 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.

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.13

Citing Sherpa

The sherpa module has gained a citation function which will display the Zenodo record for Sherpa:

sherpa> import sherpa
sherpa> sherpa.citation('latest')

Plotting improvements

Continuing the plotting improvements from CIAO 4.12 are:

Flux calculations

Extending the CIAO 4.12.1 changes to the calc_energy_flux and calc_photon_flux commands, there have been a number of improvements to the sample_energy_flux and sample_photon_flux commands. The main changes are the introduction of the model parameter, so you can now calculate the flux for a component (e.g. the unabsorbed flux), and the addition of the clip parameter to control how out-of-bounds parameter values are handled. The documentation has been improved and the support for the scales array no correctly handles both NumPy and list inputs.

Handling asymmetric errors

The resample_data routine, used to estimate the effect of asymmetric errors, has seen a number of improvements in behavior and the data that is returned.

PHA data handling

There have been a number of improvements and fixes to PHA data handling. In particular fitting a model to the background dataset has been re-worked and can result in different results if the source and background PHA datasets have different exposure times. A number of corner cases with filtering and grouping PHA datasets have also been addressed.

The load_pha command will now use the id argument when loading in a PHA2 file: it defines the first dataset which will be loaded whereas previously it always started at 1. The statistical error values for PHA files which store rate values, rather than counts, are now read in correctly.

The ungroup and unsubtract commands will no-longer error out if used on ungrouped or unsubtracted data.

Image filtering

A bug leading to a potential crash when applying multiple filters to an image has been addressed.

Numpy masked arrays

Numpy masked arrays can now be used to create a dataset with load_arrays or any of the Data classes.

Model combination

The dimensionality of models is now checked, so it is no longer to add a 1D model to a 2D model.

The voigt1d and pseudovoigt1d models

The absorbtionvoigt and emissionvoigt models were problematic and have been removed. They have been replaced by the more-generic voigt1d and pseudovoigt1d models.

XSPEC models

The XSPEC release has remained at version 12.10.1 (the patch release was version 'n' in CIAO 4.12 and is now 's'). If you want to use any of the new models in XSPEC 12.11.0 you will have to use the Standalone Sherpa release.

XSPEC convolution models

The XSPEC convolution models - such as xscflux, xszashift, and xsgsmooth - can now be used in Sherpa models.

Jupyter notebooks

Many of the objects created by Sherpa will now take advantage of Jupyter notebooks to display a HTML table or an actual plot. As an example, load a PHA file with load_pha() and then call get_data(), or call get_source() to display a model.


The Sherpa ahelp files have been updated to match the Python docstrings. Each command now has its own ahelp file, rather than combining multiple commands into a single file.


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