Synopsis
Introduction to Sherpa, the CIAO modeling and fitting package
Description
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:
- -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.
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 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.
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
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)chi2xspecvar
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).
Bugs
See the bugs pages on the Sherpa website for an up-to-date listing of known bugs.