Plotting in Sherpa Using Common Options

Introduction

Sherpa uses the ChIPS plotting package by default for 1-D visualization. This thread presents two examples of creating default Sherpa plots with commonly used Sherpa plotting commands, and modifying the plots using ChIPS commands from the Sherpa prompt. As of CIAO 4.4, a ChIPS GUI is available to support easy modification of the attributes of a visualization. The GUI capabilities are available however a ChIPS plot is normally created within Sherpa.

unix% ciao
unix% sherpa
-----------------------------------------------------
Welcome to Sherpa: CXC's Modeling and Fitting Package
-----------------------------------------------------
CIAO 4.4 Sherpa version 1 Friday, December 2, 2011

sherpa-1> show_gui()

Figure 1: ChIPS GUI

Figure 1: ChIPS GUI

The ChIPS GUI may be launched from within a Sherpa analysis session for modifying plots of spectral data.

In this thread, we demonstrate the use of ChIPS plotting commands on the Sherpa prompt, as opposed to using the GUI for modifying plots, in order to seamlesssly integrate ChIPS plot-editing capapiblilites into our spectral analysis script. To learn more about using the ChIPS GUI, refer to the ChIPS threads.

Getting Started

The sample data files used in this thread are available in sherpa.tar.gz, as explained in the Sherpa Getting Started thread, in the setplot_manual sub-directory directory:

  case1_1.pha
  core1.arf
  core1.rmf

In the first example, we create X-ray spectral plots, altering plotting preferences to create custom labels, colors, and axes ranges. In the second example, we use the same X-ray spectral profile, but re-plot it as a line plot instead of a scatter plot.

Plotting X-ray Spectra

We begin by loading a PHA data set and its associated instrument response using load_pha, and filter the data to include only the range between 0.3-7.0 keV with notice_id. Then plotting the data is simply done with plot_data (Figure 1):

sherpa> load_pha("case1_1.pha")

sherpa> notice_id(1,0.3,7.)

sherpa> plot_data()

Figure 2: Plot of PHA Dataset

Figure 2: Plot of PHA Dataset

Plot of count-rate spectrum with the default plotting parameters.

As we can see, Sherpa plots data in linear-scale by default, but sometimes, it is more useful to plot a logarithmic-scale. To switch to log-scale, we can use the ChIPS command log_scale as follows (where we also use the limits command to limit the y-axis range to 0.001-0.1 cts/s/keV, as shown in Figure 2).

sherpa> log_scale()
sherpa> limits(Y_AXIS,0.001,0.1)
        

Calling log_scale() without arguments is equivalent to log_scale(XY_AXIS).

Figure 3: Plot of PHA Dataset on Log-Scale

Figure 3: Plot of PHA Dataset on Log-Scale

Plot of count-rate spectrum on logarithmic-scale with the y-axis range limited to 0.001-0.1 cts/sec/keV.

The Sherpa commands available for setting the axis scale of plots are get_data_plot_prefs/get_model_plot_prefs and set_xlog/set_ylog, set_xlinear/set_ylinear.

To change the settings for plot_data so that both the X and Y axes will be drawn using a log scale each time the function is called, use get_data_plot_prefs as follows:

sherpa> p = get_data_plot_prefs() 
sherpa> p["xlog"] = True
sherpa> p["ylog"] = True

The set_xlog and set_ylog commands set the scale of the X and Y axes of a specified plot type to use logarithmic scale, and linear scale is set with the set_xlinear and set_ylinear commands. They are issued before generating the desired plot; i.e., these commands will not alter a plot which has already been created. Once a command has been issued for a specific plot type - e.g., for all fit plots with 'set_xlog("fit")' - it will remain in effect for all such plots created in the current Sherpa session. These commands accepts argument values similar to the generic Sherpa plot function, e.g., "data", "model", "source", "fit", "delchi", etc. When called with no arguments, the axes of all plots created in the current Sherpa session will be set to use log or linear scale.

For example, the following set of commands will display all plots created in the current Sherpa session in linear scale, except the Y axis of model plots; these should be log scale.

sherpa> set_xlinear()
sherpa> set_ylinear()
sherpa> set_ylog("model")

Grouping Data

In order to use Gaussian statistics to fit a model to a data set, it is often necessary to "group" the data - i.e., combine channels until you have enough counts - before use. It is possible to set and change the grouping of a file after it has been read into Sherpa by using the group commands: set_grouping, group, group_counts, group_snr, group_adapt, group_adapt_snr, group_bins, and group_width. (See the Sherpa thread Changing the grouping scheme of a data set within Sherpa for details.)

We use the group_counts command in this example to force each bin to have a minimum number of counts (Figure 3).

sherpa> group_counts(15)

sherpa> notice_id(1,0.3,7.)

sherpa> plot_data()
sherpa> log_scale()
             

Figure 4: Plot of Grouped PHA Dataset on Log-Scale

Figure 4: Plot of Grouped PHA Dataset on Log-Scale

Plot of the grouped, filtered count-rate spectrum on logarithmic-scale.

Notice that the noise/error-bars have been reduced by the grouping. Also note that after using a Sherpa group function, any notice/ignore filters which had previously been applied to the data must be re-applied, as the group functions restore use of the full range of the data in the analysis.

---

Fitting a Model to Data

Next we will fit a simple, 1-D absorbed power-law model to the data and plot the fit using plot_fit (Figure 4). Note that by default, plot_fit creates a plot with data points marked by symbols and associated error bars, and the model over-plotted as a solid red line. The model line is plotted using the highest resolution available for creating a model.

sherpa> set_source(xsphabs.abs1*powlaw1d.p1)
sherpa> abs1.nH=0.039

sherpa> fit()
Dataset               = 1
Method                = levmar
Statistic             = chi2gehrels
Initial fit statistic = 1.42205e+12
Final fit statistic   = 58.5512 at function evaluation 25
Data points           = 88
Degrees of freedom    = 85
Probability [Q-value] = 0.987303
Reduced statistic     = 0.688838
Change in statistic   = 1.42205e+12
   abs1.nh        0.0321289
   p1.gamma       1.73998
   p1.ampl        4.00946e-05

sherpa> plot_fit()
sherpa> log_scale()              

Figure 5: Plot of Grouped PHA Dataset and Fitted Model

Figure 5: Plot of Grouped PHA Dataset and Fitted Model

The grouped, filtered count-rate spectrum on logarithmic-scale, with an absorbed power-law model fitted to the data (red). A hydrogen column density of 3.9×10²⁰ cm^-2 is assumed.

The plot_model and plot_source commands are available for plotting the total convolved and unconvolved source model, respectively; and plot_model_component and plot_source_component plot one or a combination of individual model components contributing to a fit, where a multi-component source model is used (see the thread "Fitting a PHA Data Set with Multiple Responses" for a demonstration of this functionality).

The plot_source command supports the 'factor' setting of the set_analysis command. This means that calling plot_source while the set_analysis 'factor' setting is '1' will plot E F(E) versus E in keV, or λ f(λ) versus λ in Angstroms, depending on which units are set for the spectral analysis. A set_analysis 'factor=2' setting will plot E² F(E) versus E, or λ² f(λ) versus λ.

sherpa> set_analysis("energy", factor=1)
sherpa> plot_source()

sherpa> set_analysis("wavelength", factor=2)
sherpa> plot_source()

In the first example above, the unconvolved source model for data set 1 would be plotted in units of photons sec^-1 cm^-2 versus keV. In the second example, the units would be Angstroms photons sec^-1 cm^-2 versus Angstroms.

---

Creating Multi-Plots

We will now create a multi-plot with the plot_fit_delchi function, which plots the fitted spectrum and the delta-chi residuals of the fit.

sherpa> plot_fit_delchi()

sherpa> log_scale(X_AXIS)
sherpa> limits(X_AXIS, 0.2,7)

Figure 6: Model Fit and Delta-Chi Residuals Multi-Plot

Figure 6: Model Fit and Delta-Chi Residuals Multi-Plot

The upper plot shows the data (white) with fitted model (red), and the delta-chi residuals plot is shown on the bottom. The x-axis is scaled logarithmically.

plot_fit_delchi automatically generates a strip chart, which by default, has bound axes. When the logarithmic-scaling was applied to the x-axis, and the plotted energy range limited to 0.2-7.0 keV, both plots were altered. Additional customization options for plot axes are available with the plot and strip_chart functionality.

We may learn about the ChIPS properties of each plot by using info, and alter the plotting preferences with commands like set_curve, set_plot, and set_axis.

sherpa> info()

Window [win1]
  Frame [frm4]
    Plot [plot1]   (0.15,0.40)  .. (0.90,0.90)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      X Axis [ax1]
      Y Axis [ay1]
      Curve [crv1]
      Curve [crv2]
    Plot [plot2]   (0.15,0.15)  .. (0.90,0.40)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      X Axis [ax1]
      Y Axis [ay1]
      Curve [crv1]
      Line [line1]

sherpa> set_curve(["symbol.size",5])
sherpa> set_curve(["symbol.color","blue"])
sherpa> set_curve(["err.color","blue"])

sherpa> set_plot_xlabel("Energy (keV)")

sherpa> set_axis(["label.size",20])

Figure 7: Changing the Lower Plot

Figure 7: Changing the Lower Plot

Since current_plot="plot2", the ChIPS commands act only on the lower plot, which we can see has changed the plot to blue and symbol and label font sizes.

As can be seen (Figure 6), the set_curve function increases the symbol size and changes the symbol color and error bars to blue on the lower plot. Since the last object plot_fit_delchi produced was the lower plot with delta-chi residuals, ChIPS treats the lower plot as the current plot on which to be operated. Therefore, the set_plot_xlabel command sets the x-axis label on the lower plot, and set_axis is changes the font size of the axes labels.

In order to modify the upper plot, we first look through the objects and object names returned by the info command (Plot [plot1]...Plot [plot2]), to find the one which corresponds to the upper plot. We find that the upper plot displaying the fitted model corresponds to plot1, so we use set_current_plot to choose plot1 as the next plot to be operated on by ChIPS:

sherpa> set_current_plot("plot1")

sherpa> set_plot_title("Power-Law Model")
sherpa> set_plot_ylabel("counts s^{-1} keV^{-1}")
sherpa> set_axis(["label.size",20])

Figure 8: Changing the Upper Plot

Figure 8: Changing the Upper Plot

Since current_plot="plot1", the ChIPS commands act only on the upper plot, which we can see have changed the plot title and y-axis label, as well as increased the font size in the axes labels.

We have now changed the plot title and y-axis label to be more descriptive, and increased the font size in the axes labels. A particularly nice feature is that ChIPS readily interprets LaTeX mathematical commands for label entries.

Since ChIPS is still operating on the upper-plot, plot1, we can add a label to the plot with add_label (Figure 8) and remove it with delete_label.

sherpa> add_label(2.0,0.03,"Chandra")

sherpa> info()

Window [win1]
  Frame [frm4]
    Plot [plot1]   (0.15,0.40)  .. (0.90,0.90)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      X Axis [ax1]
      Y Axis [ay1]
      Curve [crv1]
      Curve [crv2]
      Label [lbl1]
    Plot [plot2]   (0.15,0.15)  .. (0.90,0.40)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      X Axis [ax1]
      Y Axis [ay1]
      Curve [crv1]
      Line [line1]

sherpa> delete_label("lbl1")

sherpa> add_label(2.0,0.03,"Model 1")

sherpa> info()

Window [win1]
  Frame [frm4]
    Plot [plot1]   (0.15,0.40)  .. (0.90,0.90)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      X Axis [ax1]
      Y Axis [ay1]
      Curve [crv1]
      Curve [crv2]
      Label [lbl2]
    Plot [plot2]   (0.15,0.15)  .. (0.90,0.40)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      X Axis [ax1]
      Y Axis [ay1]
      Curve [crv1]
      Line [line1]

Notice that in the current info output, a new Label[label name] item is included under plot1, and that the label name changes after delete_label is used.

Figure 9: Adding Labels to Plot

Figure 9: Adding Labels to Plot

Adding labels to plots by executing: add_label(2.0,0.03,"Chandra") (left) → delete_label("lbl1") → add_label(2.0,0.03,"Model 1") (right).

Finally, we reposition the label and change its font size and color to red (Figure 9):

sherpa> move_label(4.,0.04)
sherpa> set_label("lbl2",["size", 18, "color", "red"])
               

Figure 10: Changing Properties of Labels

Figure 10: Changing Properties of Labels

The label has been moved to the upper-right corner of the plot, and the font color has been changed to red and the size increased.

Changing a Scatter Plot to a Line Plot

We continue on with an example of how to modify the current scatter plot into a line plot.

First, we replot the fit/delta-chi plot, which also resets the color palate. We then remove the error bars from the data and delta-chi plot. (Figure 10):

sherpa> plot_fit_delchi()
sherpa> log_scale()

sherpa> info()
Window [win1]
  Frame [frm3]
    Plot [plot1]   (0.15,0.40)  .. (0.90,0.90)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      X Axis [ax1]
      Y Axis [ay1]
      Curve [crv1]
      Curve [crv2]
    Plot [plot2]   (0.15,0.15)  .. (0.90,0.40)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      X Axis [ax1]
      Y Axis [ay1]
      Curve [crv1]
      Line [line1]

sherpa> set_current_plot("plot1")
sherpa> set_curve("crv1",["err.*","false"])


sherpa> set_current_plot("plot2")
sherpa> set_curve("crv1",["err.*","false"])

Figure 11: Removing Error Bars

Figure 11: Removing Error Bars

The error bars of the delta-chi residuals plot have been removed.

The info command shows that the plot with data and model fit corresponds to Plot [plot1], where the data is Curve [crv1], and the model fit is Curve [crv2]. The delta-chi plot is Plot [plot2], with the calculated values represented by Curve [crv1]. We had to change the plot currency above using set_current_plot in order to manipulate each plot separately.

Next, we modify the model fit plot by removing the error bars; connecting the data points with a solid line; and then hiding the data points from the plot window, creating the typical, spectral profile (Figure 11):

sherpa> set_current_plot("plot1")

sherpa> set_curve("crv1",["err.*","false"])
sherpa> set_curve("crv1",["line.style","solid","symbol.style","none"]) 

Figure 12: Removing Error Bars for a Spectral Profile

Figure 12: Removing Error Bars for a Spectral Profile

The error bars of the model fit plot are removed and points are hidden and connected with a solid line.

We can change the color of the fitted model, using the information returned by info. We can also remove the symbols in the delta-chi plot and display the information with a dotted line instead (Figure 12).

sherpa> set_current_plot("plot1")
sherpa> set_curve("crv2","line.color=yellow")

sherpa> set_current_plot("plot2")
sherpa> set_curve("crv1","symbol.style=none")
sherpa> set_curve("crv1","line.style=dot")

Figure 13: Changing the Model Fit Line and Residuals Plot

Figure 13: Changing the Model Fit Line and Residuals Plot

The line representing the fitted model is changed to yellow, and the delta-chi residual plot symbols are removed and replaced with a dotted line.

Note that executing the following set of commands:

sherpa> set_curve("crv1","symbol.style=none")
sherpa> set_curve("crv1","line.style=dot") 

is equivalent to the single command:

sherpa> set_curve("crv1",["symbol.style","none","line.style","dot"])

Using Preferences to Create a Line Plot

In this section, we introduce the usage of plot "preferences," where ChIPS preferences are accessed with set_preference and Sherpa preferences are manipulated with get_xxx_plot_prefs (in the example, we use this as an alternative method for creating line plots). To learn more about ChIPS preferences, see ChIPS Concepts: Preferences. The usage of set_preferences allows for selected attributes to be applied to all new objects for the duration of the Sherpa session.

If we replot our fit and residuals with plot_fit_delchi:

sherpa> plot_fit_delchi()
sherpa> log_scale(X_AXIS)
          

we return to Figure 5. Rather than removing error bars for each curve with a syntax of the form 'set_curve("crv",["err.*", "false"])', we can use a set_preference command:

sherpa> set_preference("curve.err.*","False")


sherpa> plot_fit_delchi()
sherpa> log_scale()

Which returns the plot in Figure 10. Replotting this in the same window, we find that the error bars continue to be suppressed. Unfortunately, due to the implementation of ChIPS in Sherpa, on occasion, ChIPS preferences are superseded by Sherpa preferences. For example, using the ChIPS preference to change the color of the fitted curve to yellow:

sherpa> set_preference("curve.line.color","yellow")
sherpa> plot_fit_delchi()
          

fails to produce a change, but the Sherpa preference does:

sherpa> get_model_plot_prefs()["linecolor"]="yellow"
sherpa> plot_fit_delchi()
          

Sherpa preferences apply to "data" and "model" plots and are controlled by get_data_plot_prefs and get_model_plot_prefs, respectively. Where there is no get_xxx_plot_prefs tool to manipulate Sherpa preferences, the get_xxx_plot may be used. For example, if we wanted to change only the color of the residual plot within a multi-plot to red, we would use the Sherpa command get_delchi_plot, as follows:

sherpa> get_delchi_plot().plot_prefs["symbolcolor"]="red"
          

Using the ChIPS preference 'set_preference("curve.symbol.color","red")' would cause both the data and residuals points to turn red.

Sherpa preferences can also be used to control the default scale of plot axes, so that log_scale and lin_scale do not have to be executed each time Sherpa plot command is used:

sherpa> get_data_plot().plot_prefs["xlog"]=True
sherpa> get_data_plot_prefs()["ylog"]=False

sherpa> get_delchi_plot().plot_prefs["xlog"]=True
sherpa> get_delchi_plot().plot_prefs["ylog"]=False

sherpa> plot_fit_delchi()

Figure 14: Using ChIPS and Sherpa Preferences

Figure 14: Using ChIPS and Sherpa Preferences

The line representing the fitted model is changed to yellow, and the delta-chi residual plot points are changed from their default color (white) to red. The x-axis is logarithmically scaled while the y-axis maintains the default linear-scale.

Notice that get_data_plot_prefs() behaves the same as get_data_plot().plot_prefs (Figure 13).

To finally change the plot from a scatter plot to a line plot, we will hide the symbols marking the data points and connect them with a line (a solid line for the model fit plot, and a dotted line for the residual plot).

sherpa> get_data_plot_prefs()["linestyle"]=chips_solid
sherpa> get_data_plot_prefs()["symbolstyle"]=chips_none

sherpa> get_delchi_plot().plot_prefs["linestyle"]=chips_dot
sherpa> get_delchi_plot().plot_prefs["symbolstyle"]=chips_none
sherpa> get_delchi_plot().plot_prefs["linecolor"]="red"

sherpa> plot_fit_delchi()

Figure 15: Line Plot using ChIPS and Sherpa Preferences

Figure 15: Line Plot using ChIPS and Sherpa Preferences

The line plot produced using ChIPS and Sherpa preferences.

Setting Default Plot Preferences

In order to change the default plot preferences for Sherpa plotting commands - e.g., to have plot_data create data plots with a logarithmic scaling by default, as opposed to linear - you should add the appropriate get_*_plot_prefs() command(s) to your Sherpa customization file, located in ~/.ipython-ciao/ipythonrc-sherpa-user, as shown in the following example :

unix% more  ~/.ipython-ciao/ipythonrc-sherpa-user
# Include default Sherpa application profile
# DO NOT REMOVE THE NEXT LINE -- EVER!
include ipythonrc-sherpa
#***************************************************************************
# Add user customizations (if any) below this line:
#***************************************************************************

execute get_data_plot_prefs()["xlog"] = True
execute get_data_plot_prefs()["ylog"] = True
execute get_model_plot_prefs()["xlog"] = True
execute get_model_plot_prefs()["ylog"] = True

These settings specify that both the X and Y axes of data and model plots created in Sherpa should be drawn using a logarithmic scale, each time a function like plot_data or plot_fit is called. Note that adding the get_model_plot_prefs commands will not change the default axis scaling to logarithmic for model plots created with plot_model, it will remain linear. However, models plotted with plot_fit will be scaled logarithmically.

Writing Plots to File

Before exiting Sherpa, you may want to save your plot to file. In this example, we will create encapsulated Postscript, PDF, and PNG versions of the plot.

sherpa> print_window("line.eps", ["orientation", "landscape"])
sherpa> print_window("line.pdf", ["orientation", "landscape"])
sherpa> print_window("line.png")

Note that print_window automatically inverts the black and white colors for the output files.

If you set the printdialog option of print_window to True, then you can set the print options using a GUI; for instance

sherpa> print_window("line", ["printdialog", True])

Figure 16: The print_window GUI

Figure 16: The print_window GUI

Using the print_window GUI to control print output.

Scripting It

The file fit.py is a Python script which performs the primary commands used above; it can be executed by typing execfile("fit.py") on the Sherpa command line.

The Sherpa script command may be used to save everything typed on the command line in a Sherpa session:

sherpa> script(filename="sherpa.log", clobber=False)

(Note that restoring a Sherpa session from such a file could be problematic since it may include syntax errors, unwanted fitting trials, etcetera.)

The CXC is committed to helping Sherpa users transition to new syntax as smoothly as possible. If you have existing Sherpa scripts or save files, submit them to us via the CXC Helpdesk and we will provide the CIAO/Sherpa 4.5 syntax to you.