Last modified: December 2022

AHELP for CIAO 4.15 Sherpa


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, NumPy, and Matplotlib modules in Python without using the "sherpa" startup script:

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

It is likely that you will want to include the numpy and matplotlib modules, so they are 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>

Differences between help and ahelp

For most terms, the ahelp pages are generated from the Python docstrings, and so contain the same information as the help version, but organised slightly differently.

Contributing to Sherpa

Sherpa is developed on 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.

Citing Sherpa

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

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

Changes in CIAO 4.15

Primini iterative method

The Primini iterative method has been removed, leaving only the "sigmarej" option for set_iter_method.


XSPEC has been updated from 12.12.0 in CIAO 4.14 to 12.12.1c in CIAO 4.15, although unfortunately Sherpa does not provide access to the polarimetry models added in XSPEC 12.12.1. A problem - introduced in CIAO 4.14 - with running conf, covar, or proj, on XSPEC model parameters has been fixed.

Noticing and ignoring data

The notice and ignore family of commands, such as notice, ignore, notice_id, and ignore2d, will now report the change in the filter. This is of most use for PHA data, where grouping can lead to somewhat-surprising filters being selected. As an example:

sherpa> load_pha("3c273.pi")
sherpa> ignore(hi=0.5)
dataset 1: 0.00146:14.9504 -> 0.5694:14.9504 Energy (keV)
sherpa> ignore(lo=7)
dataset 1: 0.5694:14.9504 -> 0.5694:6.57 Energy (keV)

If the output is distracting - such as with spatial filters to image data created with notice2d_image - then the SherpaVerbosity command can be used to temporarily hide the output.

sherpa> from sherpa.utils.logging import SherpaVerbosity
sherpa> with SherpaVerbosity("WARN"):
... ignore(hi=0.5)
... ignore(lo=7)


Sherpa now calculates the same error as XSPEC when using the chi2xspecvar variance, both source and background channels contain 0 counts, and the background is subtracted. Please note that it is strongly suggested that a Poisson statistic is used for low-count data, rather than one of the chi2 variants!

The contour command

A problem when switching the coordinate setting with set_coord could lead to errors when calling contour has been fixed.

Data validation

A number of checks have been added to internal routines to ensure that the arguments are sensible - e.g. if two arrays are given then they should have the same length - which has fixed a number of corner cases. For most users this should not change anything, since it is only intended to catch cases which would eventually lead to an error, but there are two places where the behavior has changed. Firstly, the independent axis - e.g. as returned by get_indep - is now marked as read-only so elements can not be changed. Secondly, data sets are now required to have the same sizes for the independent, dependent, error, and related fields (prior to CIAO 4.14 they could be set to different lengths, but it would cause problems).

Dataset identifiers

The code handling identifiers for datasets and plots has been re-worked to make them consistent. This means that a few names can no-longer be used as dataset identifiers: bkg_chiskr, bkg_delchi, bkg_fit, bkg_model, bkg_ratio, bkg_resid, and bkg_source.

Faking and creating PHA data

The fake_pha method can now support data with only a RSP file, such as XMM/RGS data (or where the ARF is not set). The FITS headers written out by save_pha have been improved, partiucularly for faked data, to better match OGIP standards.

Assorted fixes

The clean method now removes model instances, and a rare failure in delete_model_component has been addressed. The documentation for the calc_ftest and calc_mlr functions has been updated to note that they can return either a scalar or an array, depending on the input. Both histogram1d and histogram2d no-longer change the input arrays (they used to sort them as a side effect but they now copy the input data before sorting it).


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