Last modified: December 2018

AHELP for CIAO 4.11 Sherpa v1


Context: sherpa


The .sherpa.rc file provides user-configuration options for Sherpa


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.

The .sherpa.rc file may be edited in any text editor to change the settings.

Since Sherpa defaults to using ChIPS, any preferences set in the .chips.rc resource file will be available during plotting as well. There is an option to override the .chips.rc settings in .sherpa.rc; refer to the "[chips]" section, below.

Contents of default .sherpa.rc file

The default .sherpa.rc file contains the following entries:

# Plotting packages available- pylab, chips
plot_pkg   : chips

# IO packages available- pyfits, crates
io_pkg     : crates

# If true, use truncation value in Cash, C-stat
truncate   : True

# Truncation value for Cash, C-stat (ignored if
# truncate option is False)
trunc_value: 1.0e-25

# The value used to replace energy bin edges (the ENERG_LO column) in
# ARF and RMF files which are set to 0? The field can either be "None" -
# in which case no replacement is made but an error is raised - or replaced
# by this value, which must be a float greater than 0 (and is in keV).
minimum_energy: 1.0e-10

# Sherpa Chatter level
# a non-zero value will
# display full error traceback
level      : 0
# NumPy arrays have a threshold size print option, such that when an
# array greater than that size is converted to a string, for printing,
# only the first few and last few elements are shown.  If the array is
# smaller than the threshold size, all the elements are printed out.
# (This setting makes no change to the actual array, but merely
# governs how the array is represented when a copy of the array is
# converted to a string.)  
# The default threshold size is 1000.  Here, the threshold size is
# changed to a much larger value as Sherpa often deals with large
# arrays.
arraylength: 1000000

# Integral number of cores to use for all parallel operations
# 'None' indicates that all available cores will be used.
# Fewer than 2 will turn off parallel processing.
numcores : None

# If the plotting package is chips, set Sherpa-specific
# preferences here.  If plotting package is anything else,
# this section is completely ignored.  These preferences
# go into effect the first time a Sherpa plot function
# is called (*not* when Sherpa is started; chips is not
# imported until the first plot is made).

window.height          : 6
window.width           : 8
window.units           : inches



The plot_pkg defines whether chips (the default) or pylab is used for Sherpa plotting. Both ChIPS and matplotlib are distributed with CIAO, so either setting - chips or pylab - can be used.


The io_pkg defines whether crates (the default) or AstroPy (pyfits) will be used to handle reading and writing of files. CRATES is a software package developed by the CXC and distributed in CIAO; see "ahelp crates" for details. The AstroPy package can be installed into CIAO using the 'pip3' command provided with CIAO - e.g.

unix% pip3 install astropy

although note that the choice of pyfits for I/O will mean that CIAO Data Model syntax (such as on the fly filtering, column selection, and binning) can not be used.


truncate and trunc_value

The Cash and C-stat statistic functions evaluate the logarithm of each data point. If the number of counts is zero or negative, it's not possible to take the log of that number.

If truncate is set to True (the default), then log(<trunc_value>) is substituted into the equation, and the statistics calculation proceeds. The default trunc_value is 1.0e-25.

If truncate is set to False, C-stat or Cash returns an error and stops the calculation when the number of counts in a bin is zero or negative. The trunc_value setting is not used.



The value used to replace the minimum energy value of ARF and RMF values that are invalid (i.e. are set to 0).



When a NumPy array is converted to a string for printing to the screen, only the first few and last few elements are shown. The arraylength value determines only how the array is displayed; it does not affect the the actual array. The default value is 1000000, as Sherpa often deals with large arrays.


This option is no-longer used by Sherpa and is only kept for backwards compatibility.


This section of the file contains ChIPS preferences to override the settings in the .chips.rc file; see "ahelp chipsrc" for details. Note that these preferences and the .chips.rc file are read when a plot function is called and ChIPS is launched, not at the beginning of the Sherpa session.

The [chips] section can be left blank, in which case none of the values defined in .chips.rc are overridden.

If a plotting package (plot_pkg option) other than ChIPS is used, this section of the file is ignored.


The 'numcores' switch in the [parallel] section is available for setting the number of cores on the user's system which should be used in the execution of the Sherpa parallelized commands, such as the computationally intensive conf() and proj() functions. The default value for 'numcores' is None, which indicates that all available cores will be used for concurrent functions.

Changes in CIAO 4.11


The CIAO 4.11 release is the first to include matplotlib, which means that the plot_pkg setting can be changed to pylab for CIAO users. The default option remains chips.


The level option within the verbosity section is no longer used. It is kept in the file so that Sherpa versions prior to CIAO 4.11 can still be used.


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