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.
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:
- -x : launch Sherpa shell in separate display terminal.
- -n : prevents the Sherpa banner from being displayed on startup.
- -b : runs Sherpa in batch mode
- -rcfile : specify a specific .sherpa.rc file to use; refer to "ahelp sherparc" for details.
- -norcfile : do not load any .sherpa.rc file; overrides "-rcfile" if both are set.
- <file>: Python command file to execute
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.
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!
There are several ways to access the Sherpa help files.
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 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.13
The sherpa module has gained a citation function which will display the Zenodo record for Sherpa:
sherpa> import sherpa sherpa> sherpa.citation('latest')
Continuing the plotting improvements from CIAO 4.12 are:
- changes to the display of histogram and PHA data and models;
- the transparency of the data or model can be changed by setting the alpha argument to a value between 0 and 1;
- the plot function can now accept keyword arguments, with the settings applied to each plot;
- the overplot option now works for the plot_fit_xxx and plot_bkg_fit_xxx family of commands (e.g. plot_fit_ratio and plot_bkg_fit_resid).
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.
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.
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.
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.
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.