Last modified: December 2021

URL: https://cxc.cfa.harvard.edu/sherpa/ahelp/sherpa4.html
AHELP for CIAO 4.14 Sherpa

sherpa

Context: sherpa

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:

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

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.

Citing Sherpa

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

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

Changes in CIAO 4.14

Filters, notice, and ignore

Data filtering with notice and ignore (and the *_id versions) has been improved to fix a number of edge cases in the code. There are occasions when a call to notice or ignore may select slightly-different bins (the first or last bin may differ) which would change the statistic slightly and hence the fit results or error analysis. This is mainly a change for "histogram" data - that is PHA data and Data1DInt datasets. For PHA data sets notice and ignore filters must, when using channel units, be integer values.

The filter expression returned by get_filter has been changed for PHA data, and Data1DInt datasets, to show the full selected range, rather than the mid-points of the first and last bins. This does not mean that the filter has changed the bins, or groups, that have been selected, just that the displayed range is now more consistent.

Image filters

In CIAO 4.13 the region expression returned by get_filter for image data as, for complex expressions - that is, those with multiple components - wrong. This would only be a problem for users using calc_data_sum2d, calc_model_sum2d, or calc_source_sum2d with the output of get_filter, or for users trying to re-create a Sherpa session with restore or the file created by save_all.

Flux calculations

The sample_flux command has seen a number of improvements - such as supporting the id argument, better handling of upper limits, and returning the correct statistic value - to match the functionality of the sample_energy_flux command added in CIAO 4.13.

Plot improvements

The plot_model_component command will now automatically add the PHA response, so that a sequence like the following will now produce sensible output:

sherpa> plot_fit(ylog=True)
sherpa> plot_model_component(src, alpha=0.6, overplot=True)
sherpa> plot_model_component(gal * src, alpha=0.6, overplot=True)

The plot will still display correctly if you have manually added the response, such as

sherpa> rsp = get_response()
sherpa> plot_model_component(rsp(src))

Model plots are now displayed correctly for XMM RGS data when wavelength units are used.

The plot_source command could ignore the clearwindow argument for certain data types.

XSPEC

XSPEC has been updated from 12.10.1s in CIAO 4.13 to 12.12.0 in CIAO 4.13, adding the following new models:

The load_xstable_model function can now be used with exponential (etable) models. Unfortunately there is no way to determine from the model file whether it is an etable or mtable model, so the etable argument has been added to distinguish between the two.

XSPEC parameter changes

The parameter limits - that is the "Min" and "Max" values reported by the print call - have been changed in CIAO 4.14 to use the XSPEC "hard-limit" range rather than the XSPEC "soft-limit" range which was used in earlier versions. This can lead to changes to fit results, and in routines like sample_energy_flux, for parameter values that are not well constrained.

For those rare models that require it, it is now possible to change the minimum and maximum range of XSPEC parameters by changing the hard_min or hard_max attribute of the parameter's set method.

The default chatter setting

In CIAO 4.14 the default chatter setting is now 10, matching the default behavior of XSPEC, rather than 0. This means that the first time a model is evaluated you may see extra output, but it should also help point out if your ~/.xspec/Xspec.init file needs updating (e.g. for the ATOMDB_VERSION and NEI_VERSION settings).

Simulating data

The fake_pha now supports simulating data from an instrument with multiple responses, such as HRC-S/LETG.

Utility routines

The sherpa.utils.logging.SherpaVerbosity context manager has been added to make it easy to temporarily quieten Sherpa routines. For example:

from shera.utils.logging import SherpaVerbosity

with SherpaVerbosity('ERROR'):
    load_pha(1, 'src1.pi')
    load_pha(2, 'src2.pi')
    load_pha(3, 'src3.pi')

will not display the normal screen messages about the response and background files that have bene automatically loaded.


Bugs

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