Chandra X-Ray Observatory
	(CXC)
Skip to the navigation links
Last modified: April 2018

URL: http://cxc.harvard.edu/sherpa/ahelp/sherpa4.html
AHELP for CIAO 4.10 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 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, 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 *

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.10 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. 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:

  • the ability to edit the properties of an object, such as the symbol style of a curve or the font used for an axis label,
  • zoom, pan, and select objects in the plot,
  • update the plot ranges,
  • move plot areas and annotations,
  • resize plot areas, labels, and points,
  • and an object tree which describes existing plot objects.

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

Python 3.5

Changes have been made to fix problems Python 3.5 version of Sherpa. Use

% python --version

to check what version of Python is being used by CIAO, as CIAO 4.10 provides either Python 3.5.4 or 2.7.14.

Documentation

The Pyton 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.

XSPEC models update

The XSPEC models have been updated to release 12.9.1n in CIAO 4.10. Support for the following models have been added to Sherpa: xsbtapec, xsbvtapec, xsbvvtapec, xscarbatm, xshatm, xsismabs, xsnlapec, xsslimbh, xssnapec, xstapec, xstbfeo, xstbgas, xstbpcf, xstbrel, xsvoigt, xsvtapec, xsvvtapec, and xsxscat.

These models are only documented using Python docstrings, and not in ahelp. Use the help command on the model instance for information, as shown in the following example:

sherpa> set_source(xsphabs.gal * xsbvtapec.src)
sherpa> help(src)
...

Parameter names now match those of XSPEC

Over time the parameter names of some XSPEC models have changed - e.g. to support use in Python - so in CIAO 4.10 the Sherpa XSPEC interface has been updated to match the XSPEC names. The old names can still be used (they are aliased to the new name). As an example, the xsdisk model now uses the name 'CenMass' for the central mass parameter, but the old version ('NSmass') can still be used, as shown below:

sherpa> create_model_component('xsdisk', 'mdl')
<XSdisk model instance 'xsdisk.mdl'>
sherpa> mdl.cenmass.val
1.3999999999999999
sherpa> mdl.nsmass = 2
sherpa> mdl.cenmass.val
2.0

It is strongly suggested that code be updated to use the new names, as support for these aliases may be removed in a later release. The Python documentation for each model can be read to find out if a parameter contains an alias. The following table lists the parameters that have been changed.

Model name Old parameter name New parameter name
xsbmc loga log_A
xscompPS tauy tau_y
xscompPS hrcyl HovR_cyl
xscompth abhe Ab_met
xsdisk nsmass CenMass
xsdiskir lcld LcovrLd
xsdiskline rinm Rin_M
xsdiskline routm Rout_M
xseqpair l_hl_s l_hovl_s
xseqpair l_ntl_h l_ntol_h
xseqpair abhe Ab_met
xseqtherm l_hl_s l_hovl_s
xseqtherm l_ntl_h l_ntol_h
xseqtherm abhe Ab_met
xsgabs tau Strength
xsgnei kt_ave meankT
xsgrad tcltef TclovTef
xsgrbm temp tem
xsheilin redshift z
xskerrd tcolteff TcoloTeff
xskerrdisk r_brg r_br_g
xskerrdisk rinms Rin_ms
xskerrdisk routms Rout_ms
xslaor ring Rin_G
xslaor2 ring Rin_G
xslaor2 routg Rout_G
xslyman nhei n
xslyman redshift z
xsoptxagn loglledd logLoLEdd
xsoptxagnf loglledd logLoLEdd
xsredden ebv E_BmV
xssrcut breakfreq break_
xsswind1 logxi log_xi
xsuvred ebv E_BmV
xsvbremss heh HeovrH
xsvgnei kt_ave meankT
xsvvgnei kt_ave meankT
xsxion lxld lxovrld
xszbabs redshift z
xszdust ebv E_BmV
xszredden ebv E_BmV
xszsmdust ebv E_BmV
xszxipcf logxi log_xi

Note that the RoutG parameter for the xslaor model does not contain the alias, and so users of this model will need to replace 'RoutG' with 'Rout_G' (it is a case insensitive match).

New functions

The following routines have been added to the sherpa.astro.xspec module: get_xspath_manager, get_xspath_model, and set_xspath_manager.


Bugs

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


Last modified: April 2018
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email:   cxchelp@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2017. All rights reserved.