---

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

Sherpa version for CIAO 4.17 was released on December 17, 2024. Sherpa in CIAO runs under Python 3.11 (whether installed using the conda package manager or with ciao-install). The full list of the Sherpa updates compared to 4.16.0 is given in the 4.17.0 and 4.16.1 release notes on GitHub. The major updates were made to plotting, adding the 50 new models in XSPEC 12.14.0, improvements to including linked parameters in fits and the guess routine, fixes for support for 1D data with asymmetric errors, updates for the experimental bokeh plotting backend, and bug fixes.

The release highlights include:

XSPEC

Updated to version 12.14.0k of the XSPEC model library, adding 50 new additive models. A number of models have had their defauld paramter values changed to match the XSPEC 12.14.0 values. In particular, a number of models now have a default Redshift of 0.1 rather than 0, the switch parameter has been changed from 1 to 2 for some models and can now extend to 3 to support SPEC data for interpolation, and some parameters have been changed between frozen and thawed status.

Added the show_xsabund, get_xsabundances, and set_xsabundances commands.

sherpa> show_xsabund()
Solar Abundance Table:
angr  Anders E. > Grevesse N. Geochimica et Cosmochimica Acta 53, 197 (1989)
  H : 1.000e+00  He: 9.770e-02  Li: 1.450e-11  Be: 1.410e-11  B : 3.980e-10
  C : 3.630e-04  N : 1.120e-04  O : 8.510e-04  F : 3.630e-08  Ne: 1.230e-04
  Na: 2.140e-06  Mg: 3.800e-05  Al: 2.950e-06  Si: 3.550e-05  P : 2.820e-07
  S : 1.620e-05  Cl: 3.160e-07  Ar: 3.630e-06  K : 1.320e-07  Ca: 2.290e-06
  Sc: 1.260e-09  Ti: 9.770e-08  V : 1.000e-08  Cr: 4.680e-07  Mn: 2.450e-07
  Fe: 4.680e-05  Co: 8.320e-08  Ni: 1.780e-06  Cu: 1.620e-08  Zn: 3.980e-08
sherpa> get_xsabundances()
{'H': 1.0,
 'He': 0.09769999980926514,
 'Li': 1.4500000158901294e-11,
 ...
 'Fe': 4.6799999836366624e-05,
 'Co': 8.319999977857151e-08,
 'Ni': 1.7800000478018774e-06,
 'Cu': 1.619999956403717e-08,
 'Zn': 3.979999974035309e-08}

The load_table_model command will now warn when given an XSPEC table model, since they must be read in using load_xstable_model.

Filtering and grouping

There is better support for PHA files which start the channels at 0 rather than 1. Filter ranges in channel space may be changed because of this (the same data values are used but using a channel filter from CIAO 4.16 may change the noticed range slightly).

It is possible for notice and ignore calls to fail after calling ignore_bad. When this happens there will now be a screen message reporting this failure rather than appearing to succeed.

Models

Added the calc_source and calc_model commands to calculate the predicted model values. These routines should be used in preference to the get_model_plot command for accessing the model values as an array, as the output does not depend on the plot options (such as set_analysis for PHA data). For example, for a particluar PHA dataset (where there are low and high edges for the X axis), with analysis set to "energy":

sherpa> (elo, ehi), y = calc_model()
sherpa>  print(elo[0:5])
[0.292      0.46720001 0.59859997 0.68620002 0.7446    ]
sherpa> print(ehi[0:5])
[0.46720001 0.59859997 0.68620002 0.7446     0.80299997]
sherpa> print(y[0:5])
[16.77329753 25.95777617 22.40904446 18.4142408  20.32061108]

The units depend on the model and dataset; in this case elo and ehi are in keV and the y values are predicted counts.

Model expressions no-longer contain excessive brackets, so after

sherpa> set_source(xsphabs.gal * (xsapec.therm + xspowerlaw.pl + xsgaussian.line))

then we now get

sherpa> print(get_source().name)
xsphabs.gal * (xsapec.therm + xspowerlaw.pl + xsgaussian.line)

rather than (form CIAO 4.16 and earlier):

sherpa> print(get_source().name)
(xsphabs.gal * ((xsapec.therm + xspowerlaw.pl) + xsgaussian.line))

When fitting data, Sherpa now automatically includes any linked parameters (that are thawed) even if the model is not included explicitly in the model expression. The previous work around, of adding the model component but multiplying it by 0, can still be used but is no-longer necessary.

The guess command can now be used with PHA data, although the normalization limits should be checked to make sure they remain sensible.

Data access

Data with asymmetric errors - e.g. loaded with load_ascii_with_errors - can now be plotted after filtering. There have also been improvements to allow the statistic and optimized to be changed when resampling the data.

The way that data is loaded has been changed to reduce differences when loading data with the Crates or pyfits backends. This may mean that slightly different messages are displayed, compared to CIAO 4.16, when loading in data or if there is an issue with the data file.

Plotting improvements

The new plot_model_components and plot_source_components commands will now separate and plot additive components in a source expression. So a source model like "gal * (pl + line)" will display the model (or source) plots of "gal * pl" and "gal * line":

sherpa> plot_model(label="full")
sherpa> plot_model_components(overplot=True, alpha=0.5, label=["powerlaw", "line"])

Residual plots of histogram and PHA data have been changed to match the data and model versions. Here is the output of plot_fit_resid for a PHA dastaset in CIAO 4.16

and now in CIAO 4.17

As part of this, these residual plots now have xhi and xlo attributes rather than an xerr attribute, and the values are now correct when switching to wavelength units.

Axis labels used in plots can now be customized by calling get_data and then using the set_xlabel and set_ylabel methods on the returned object:

sherpa> load_pha("qso.pi")
sherpa> d = get_data()
sherpa> d.set_xlabel("Channel value in keV")
sherpa> d.set_ylabel("Rate")
sherpa> plot_data()

There have been a number of improvements to the plot and contour commands. They now work correctly when used with overplot/overcontour arguments; arguments can now be given as a sequence, which means per-plot values can be given; and the layout can now be changed by setting the cols and rows arguments. As an example,

sherpa> plot("data", "data", rows=1, xlog=[False, True])

will create a one row by two column plot with the data in both, the first plot uses a linear X axis and the second a logarithmic X axis.

The 1D and 2D confidence plots - e.g. created by int_proj, int_unc, reg_proj, and reg_unc - now correctly handle the log parameter when set.

The plot_rmf command will now display the X axis in Angstroms if the analysis setting for the backend has been changed to "wavelength", and in Channels if the setting was changed to "channel".

There have been improvements to the bokeh backend.

This release also includes a number of typing annotations added to some of the routines. The Ahelp page files have been updated to move information about the expected types of function arguments from the SYNTAX to the PARAMETERS section.

Documentation

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.17.0 and 4.16.1 release branches on GitHub.