Synopsis
The .sherpa.rc file provides user-configuration options for Sherpa
Description
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.
Contents of default .sherpa.rc file
The default .sherpa.rc file contains the following entries:
# SHERPA_VERSION 4.14.2 [options] # Plotting backends (space separated list) # will be tried in order, the first one that imports is set as default # plotting backend. If no listed backend can be imported, Sherpa sets # a dummy backend as default. # The backend can be changed in a running sherpa session. # The following line would try all available backends until it finds one that imports correctly # (i.e. all dependencies are available): # plot_pkg : pylab dummy plot_pkg : pylab # IO packages (space separated list) in the order they will be tried # The first backend that imports successfully is set as default I/O backend. # If no listed backend can be imported, Sherpa sets # a dummy backend as default. # The backend can be changed in a running sherpa session. # The following line would try all available backends: # io_pkg : crates pyfits dummy io_pkg : crates [statistics] # 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 [ogip] # 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 [verbosity] # Sherpa Chatter level # a non-zero value will # display full error traceback # This option is only used by Sherpa up to version 4.10.1 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 [parallel] # 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 [multiprocessing] # Define the method by which the multiprocessing package starts # parallel processes. Sherpa requires the "fork" method in order to # utilize multiprocessing to improve performance and pass all tests. # However, on MacOSX there are known issues with using "fork" that # prompted a change in the multiprocessing default to be "spawn" on # MacOSX. Expert users may consider changing this value to either # "spawn" or "default", where the latter will use the # platform-specific start method of the multiprocessing package. multiprocessing_start_method: fork
[options]
plot_pkg
A list of the plotting backends to try, where the list is tried from left to right and stops as soon as a backend is found. For CIAO 4.16 the options are "pylab" (matplotlib) and "bokeh" ,with the Bokeh version being experimental.
io_pkg
A list of the I/O backends to try, where the list is tried from left to right and stops as soon as a backend is found. For CIAO 4.16 the two supported options are "crates" and "pyfits". It is strongly suggested that CIAO users select the crates option (which is the default setting).
Crates
Crates is a software package developed by the CXC and distributed as part of CIAO; see "ahelp crates" for details.
AstroPy
The AstroPy package can be installed into CIAO using the 'pip3' command provided with CIAO - e.g.
unix% pip3 install astropy
or with conda, if available:
unix% conda install astropy
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.
[statistics]
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.
[ogip]
minimum_energy
The value used to replace the minimum energy value of ARF and RMF values that are invalid (i.e. are set to 0).
[verbosity]
arraylength
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.
level
This option is no-longer used by Sherpa and is only kept for backwards compatibility.
[parallel]
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.
[multiprocessing]
The 'multiprocessing_start_method' setting was added to support changes in the multiprocessing module on MacOS in Python 3.8. Please contact the CXC Helpdesk if you find you need to change this setting.
Changing the configuration file
When Sherpa is imported, the SHERPARC environment file is checked and, if set, is used to over-ride the location of the configuration file. This lets users override the settings for a single, such as the following bash invocation to run the Sherpa program pointing to the file pyfits.rc in the current working directory
unix% SHERPARC=pyfits.rc sherpa
or the following tcsh example to use the file /tmp/other.rc
unix% setenv SHERPARC /tmp/other.rc unix% sherpa
Changes in CIAO 4.16
The plot_pkg option can now be set to "bokeh".
Changes in CIAO 4.15
The plot_pkg and io_pkg options can now be set to a space-separated list of backends to try.
Changes in CIAO 4.13
Multiprocessing
The multiprocessing section is new.
Changes in CIAO 4.12
Plotting
The CIAO 4.12 release no-long includes ChIPS, so the plot_pkg setting has been changed to pylab. Sherpa will automatically switch to pylab if it finds a configuration file containing chips, but will warn you about it.
Bugs
See the bugs pages on the Sherpa website for an up-to-date listing of known bugs.