Skip to the navigation links
Last modified: 8 December 2021


Latest Updates

This document highlights important changes and additions to Sherpa functionality in the CIAO 4.14 Sherpa release.

Sherpa version for CIAO 4.14 was released on December 14, 2021. Sherpa in CIAO runs under Python 3.9, 3.8, 3.7 (when installed using the conda package manager) and Python 3.8 (when installed with ciao-install). The full list of the Sherpa updates is given in the 4.14.0 and 4.13.1 release notes on GitHub. The major updates in this release include:


Updated to version 12.12.0 of the XSPEC model library, from version 12.10.1s in CIAO 4.13. Added support for the new models: additive xsgrbjet, xswdem, xsvwdem, xsvvwdem and multiplicative xszxipab.

There are changes to the hard limits of some models, the default parameter values and units, including adding and removing units. Also, XSPEC model parameters now use the same limits for soft and hard (the hard limit from the model.dat file) and the hard limits can be changed for some models which support a value outside the normal parameter range. It is strongly suggested that any parameter set to a value outside of the original limits is also frozen.

New abundance tables (lpgp, lpgs) from Lodders et al, (2009) are added and can be selected with set_xsabund

XSPEC ETABLE table model files can be read by load_xstable_model by setting the etable parameter.

Changed the default XSPEC chatter level from 0 to 10. This may result in screen output the first time an XSPEC model is evaluated. set_xschatter can be used to get back to the previous behavior.

Filtering and grouping

Filtering and grouping area for binned (1D) spectral data has been improved with changes to the default behavior and many bug fixes resulting in changes to the statistics, degrees-of-freedom and energy flux in comparison to the previous version for the same data with the same filter. Highlights include:

Energy and wavelength filters (with notice and ignore) for PHA data are now treated as lo <= x < hi in all cases, and channel filters are lo <= x <= hi (where the channel values must be integers). For Data1DInt cases the notice and ignore filters are treated as lo <= x < hi. This can result in slightly different fit results because the data used in the fit can be changed and hence changing the number of degrees of freedom (by one or two depending on whether the first and last bins have been removed).

Filter expressions for Data1DInt and DataPHA cases now report the start and end value of each set of grouped data rather than use the end points. For PHA data sets users now see the same ranges displayed whether the data is grouped or not. The actual filter remains the same even if the filter expressions has changed slightly.

Updated the image filters: "|" is used now instead of & to combined the regions. This affects the output of get_filter as input to calc_data_sum2d and definitions of very-complex spatial filters. Restoring Sherpa sessions could be impacted.

There are also many bug fixes in this area.

Plotting improvements

CIAO 4.14 continued the improvements to the plotting functionality, and includes the following:

  • plot_model_component and get_model_component add the response for PHA data sets, if there is one. Model expressions which contain a response are not changed.
  • Corrected the order of the points, x, and y values when displaying a CDFPlot object, improve support for a list argument.
  • Bug fixes to plot_source, reg_proj, reg_unc and multi-plots.
  • Internal changes to the plotting code and documentation.
Flux calculations

There are changes to sample_flux which now:

  • uses the id argument rather than always using the data from the default dataset.
  • returns a statistic value for each iteration, even if those rows are not used in the reported flux distribution.
  • returns correct information for the clip column (that is, it matches the clipping done by this routine). There may be changes to the reported error ranges because of this change.
  • no-longer excludes samples at the parameter bounds (soft) when calculating the flux distribution. This could lead to an over-estimation of the flux for upper limits.

The How do we calculate a flux in Sherpa Jupyter notebook has been updated.

Optimization methods

Updated on how the optimization minim will behave if the free parameter is beyond the limit. The default parameter reflect is True (will reflect by an equal amount about the limit). If reflect is set to False then model function will return DBL_MAX (~1e308) and therefore it will not be included in the simplex.

Updated the internal documentation of the methods.


The Sherpa ahelp files have been updated to match the Python docstrings. Each command now has its own ahelp file, rather than combining multiple commands into a single file.


Help can be found either via Python's native help function (that is, Python docstrings), or with the ahelp command (which can be used from both the command line and within the Sherpa interactive environment.

If you spot any errors, or missing information, please submit a pull request to fix it or report the problem.

A standalone the Sherpa documentation provides on-line access to the Python docstrings, as well as general documentation on how to use Sherpa. It is aimed at users who want to use the more object-orientated interface provided by Sherpa rather than the functions from the sherpa.astro.ui module documented on this site, as well as not being tailored to CIAO users, but it is useful for the more advanced Sherpa users who want to use Sherpa in complex Python pipelines.

Bug Fixes

A full list of the bug fixes can be found by viewing the changes made to the 4.14 and 4.13.1 release branches on GitHub.