Sherpa Configuration: Using the State Objects

State Object Basics

The Sherpa state object (a.k.a. configuration variable) is a S-Lang variable that is initialized whenever one starts a Sherpa session or loads the Sherpa S-Lang module. The contents of the state object can be displayed with the print function:

sherpa> print(sherpa)
plot             =  sherpa_Plot_State
dataplot         =  sherpa_Plot_State
fitplot          =  sherpa_FitPlot_State
resplot          =  sherpa_Plot_State
multiplot        =  sherpa_Draw_State
output           =  sherpa_Output_State
regproj          =  sherpa_VisParEst_State
regunc           =  sherpa_VisParEst_State
intproj          =  sherpa_VisParEst_State
intunc           =  sherpa_VisParEst_State
proj             =  sherpa_Proj_State
cov              =  sherpa_Cov_State
unc              =  sherpa_Unc_State
con_levs         =  NULL
modeloverride    =  0
multiback        =  0
deleteframes     =  1
clobber          =  0

The column to the left of the equals signs (=) contains the names of the state object's fields, and the column to the right contains the fields' values. Some of the state object's fields (e.g. multiback) contain simple, atomic values, such as integers or strings; the values of these fields appear in the output of print(sherpa). Others fields (i.e. plot and those whose values are of the form sherpa_..._State) are state objects themselves, which contain fields of their own. To display the contents of these state objects, use the syntax print(sherpa.<name>), as shown below for sherpa.plot.

You can select a specific field of a state object using the dot (.) operator:

sherpa> print(sherpa.modeloverride)
0
sherpa> print(sherpa.plot)
x_errorbars      =  0
y_errorbars      =  0
errs_style       =  bar
errs_type        =  both
...
sherpa> print(sherpa.plot.errs_style)
bar

Each atomic field is a S-Lang variable and can be set using the syntax "<name> = <value>". For example, the following commands set sherpa.modeloverride to 1 and sherpa.plot.errs_style to "standard":

sherpa> sherpa.modeloverride = 1
sherpa> sherpa.plot.errs_style = "standard"

Note that string values must be enclosed in double quotes. The reason is that S-Lang interprets "standard" (with quotes) as a literal string, whereas standard (without quotes) is a variable name.

The sections that follow introduce the state object fields and explain how they affect various features of Sherpa. For more detailed information, see the "Related Links" section of the Overview.

Note that the state object concept is not unique to Sherpa. For example, both Varmm and ChIPS have state objects of their own. Since Sherpa uses Varmm and ChIPS, these state objects are also available within a Sherpa session.

Changing the Appearance of Plots

Five Sherpa state objects control the appearance of plots. The following table lists these state objects and the plot types that they control:

The ahelp files for the individual state objects describe their fields and the plotting options that they control. For more information on configuring plots via the state objects, see the thread "Step-by-Step guide to changing the look of Sherpa plots". For information on how to use the setplot.sl script to simplify plot configuration, see the thread "Changing the look of Sherpa plots using setplot.sl".

sherpa> sherpa.dataplot.x_log = 0
sherpa> sherpa.dataplot.y_log = 1

sherpa> set_xlin
sherpa> set_ylog

Configuring Confidence-Level Calculations

Seven Sherpa state objects control the configuration of confidence-level calculations. The following table lists these state objects and the corresponding Sherpa command that they configure:

The ahelp files for the individual state objects describe them in detail. For an introduction to using these state objects, see the thread "Step-by-Step Guide to Estimating Errors and Confidence Levels". For information on how to use the paramest.sl script to simplify confidence-level calculations, see the thread "Estimating Errors and Confidence Levels".

sherpa> list_proj
Parameter       Current         Default                        Description
--------------------------------------------------------------------------
fast                  1               1    Switch to LM/simplex: 0(n)/1(y)
sigma                 1               1                    Number of sigma

sherpa> restore_proj

Other Configuration Options

Along with plots and confidence calculations, the Sherpa state object controls several other aspects of Sherpa's behavior.

sherpa> sherpa.output.scientific = 1

sherpa> # Default is sherpa.con_levs = NULL (sherpa calculates levels)
sherpa> print(sherpa.con_levs)
NULL
sherpa> # Set levels to 0.5, 1.5, 3
sherpa> sherpa.con_levs = [ 0.5, 1.5, 3 ]

sherpa> print(sherpa.modeloverride)
0
sherpa> powlaw1d[m]
sherpa> gauss[m]
Error: model component name m is already in use.
       If the last command was to use m in a model stack,
       that stack has been deleted.
sherpa> sherpa.modeloverride = 1
sherpa> gauss[m]                
sherpa> show m  
gauss1d[m]  (integrate: on)
...

sherpa> sherpa.multiback = 1

sherpa> # Default is to delete existing frames (sherpa.deleteframes = 1)
sherpa> print(sherpa.deleteframes)
1
sherpa> # Disable frame deletion
sherpa> sherpa.deleteframes = 0

sherpa> sherpa.clobber = 1

Saving and Restoring State Object Settings

The save_state function can be used to save the current state-object settings so that they can be used in another Sherpa session.

If called with no arguments, save_state will write out the contents of all fields of all Sherpa state objects to the file $HOME/.sherpa-state-rc:

sherpa> save_state
sherpa> $ more $HOME/.sherpa-state-rc
% Sherpa state for ciaouser, Wed Jul 30 17:45:13 2006

sherpa.plot.x_errorbars = 0;
sherpa.plot.y_errorbars = 0;
sherpa.plot.errs_style = "bar";
sherpa.plot.errs_type = "both";
...

This file will be over-written without warning, so you should not make changes to it manually. When Sherpa starts, it will automatically load in the settings from this file, so any customizations your have made to the state object will be restored.

If called with a filename as its argument, save_state will write out the settings to the specified file (instead of $HOME/.sherpa-state-rc):

sherpa> save_state("my_settings.shp")
sherpa> $ more my_settings.shp
% Sherpa state for ciaouser, Wed Jul 30 17:45:13 2006

sherpa.plot.x_errorbars = 0;
sherpa.plot.y_errorbars = 0;
...

This file can then be read into a Sherpa session via the USE command. This can be useful, for example, if you want to set up different plot styles for use in different situations.

Creating Aliases for State Objects

The names of the Sherpa state objects and their fields are verbose. This can be a benefit, as longer names are more descriptive and give one a better sense of what particular objects and fields control. However, longer names also require more typing, which can be a nuisance when making frequent changes. To alleviate this problem, one may define aliases for state objects. For example, you can make dp an alias for sherpa.dataplot as follows:

sherpa> dp = sherpa.dataplot

This command creates a S-Lang variable named dp that contains a reference to the sherpa.dataplot state object, allowing one to use dp as an alias for the full name:

sherpa> print(sherpa.dataplot.x_log)
0
sherpa> dp.x_log = 1
sherpa> print(sherpa.dataplot.x_log)
1

If you find aliases helpful, you can add lines to create them to your Sherpa resource file. This will make them available during every Sherpa session.

Note that you can create aliases for state objects but not for atomic fields within state objects. For example, you can create an alias for sherpa or sherpa.multiplot but not for sherpa.modeloverride.