Last modified: December 2018

URL: http://cxc.harvard.edu/sherpa/ahelp/sherpa4.html
AHELP for CIAO 4.11 Sherpa v1

sherpa

Context: sherpa

Synopsis

Introduction to Sherpa, the CIAO modeling and fitting package

Description

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 ChIPS or 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, as well as the CRATES module, which handles file input and output ( "ahelp crates"), and the ChIPS module, used for customizing the plots ("ahelp chips").

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 ChIPS modules in Python without using the "sherpa" startup script:

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

For people who want to use Matplotlib rather than ChIPS, replace the pychips import with something like:

from matplotlib import pyplot as plt

You may also find it useful to load the numpy module

import numpy as np

Getting Help

There are several ways to access the Sherpa help files. Note that in the CIAO 4.11 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>

The ChIPS GUI

The ChIPS GUI can be used to modify any Sherpa plot if the ChIPS plotting backend is in use. It is launched by right clicking on an existing ChIPS window and selecting "Launch GUI" or by running the show_gui command from within a ChIPS session. A Python terminal is built into the GUI, allowing access to ChIPS and other Python commands.

Features include:

Futher information is available from the built-in help menu in the GUI and via "ahelp chipsgui".

Contributing to Sherpa

Development of Sherpa has moved to GitHub and can be found at https://github.com/sherpa/sherpa. 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.11

XSPEC models update

The XSPEC models have been updated to release 12.10.0e in CIAO 4.11. Support for the following models have been added to Sherpa: xsbrnei, xsbvrnei, xsbvvrnei, xsgrbcomp, xsjet, xsssa, and xszcutoffpl.

The Sherpa prompt

The IPython version packaged with CIAO has been updated to 6.5.0, which has meant that the configuration options we used to use to style the "Sherpa environment" have changed. To make it more obvious that the Sherpa command-line application is based on IPython, the prompt now more-closely matches the IPython one. This means that instead of seing 'sherpa-1>', 'sherpa-2>', ..., you will now see 'sherpa In [1]:', 'sherpa In[2]:', ... and output will be preceeded by 'Out[x]:'.

Plotting with matplotlib

The CIAO 4.11 release is the first release to include matplotlib. The default behavior is for Sherpa to still use ChIPS for plotting, but this can be changed by editing the .sherpa.rc file in your home directory (it is created the first time you run Sherpa if you do not already have a file), so that thet plot_pkg setting reads "pylab" rather than "chips"; that is

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

The '%matplotlib' IPython magic command should be used in a Sherpa interactive session to ensure that matplotlib plots are interactive (so that matplotib.pyplot.show() is not needed to display them).

Documentation

The ahelp files for the Sherpa models (XSPEC and Sherpa) have been updated to match the contents of the Python docstrings for these models.

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.


Bugs

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