Chandra X-Ray Observatory
	(CXC)
Skip to the navigation links
Last modified: 5 Dec 2016

URL: http://cxc.harvard.edu/sherpa/threads/runscripts/

Running Scripts in Sherpa

Sherpa Threads (CIAO 4.9 Sherpa v1)


Overview

Synopsis:

This thread lists the available options for running scripts of Sherpa commands in the Python interface of Sherpa. In this thread we refer to a "script" as an ASCII file containing a list of Python Sherpa commands.

Last Update: 5 Dec 2016 - Updated for CIAO 4.9


Contents


Running scripts in Python

You can run scripts (sets of Python commands) directly, or from within Sherpa, as shown below. The main difference is whether or not you want to remain within the Sherpa interactive environment after running the commands.

In the following we will use this script as an example:

unix% cat example.py
# Use the same seed so the different runs create the same results
np.random.seed(101)

# Create randomized data
x = np.arange(0, 100, 10)
y = np.random.normal(loc=1e3, scale=100, size=x.size)
load_arrays(1, x, y)

# Set up model (it isn't the same as used to create the data)
set_source(1, polynom1d.mdl)
thaw(mdl.c1)

# Fit and display results
fit(1)
covar(1)
set_preferences(['window.display', False])
plot_fit_delchi(1)
print_window('example.png', ['clobber', True])

# Display the fit results to the screen
cr = get_covar_results()
print("")
print("---- results ----")
for (n, f, l, h) in zip(cr.parnames, cr.parvals, cr.parmins, cr.parmaxes):
    print(" {:10s} = {:7.2f}  ({:+8.2f} to {:+8.2f})".format(n, f, l, h))

The script creates a randomized data set - using one of the many routines from the NumPy random sampling module—fits it, calculates the parameter errors, and then plots the results, writing them to the file example.png. Since the window's display preference was turned off before creating the plot, no on-screen window will be created while running the script. The final step is to display a formatted version of the best-fit results.

Note that the random number generator is set to use a fixed seed, so that the results below are the same, however the code is run. The np.random.seed line would be removed before using this for data analysis!

Although the suffix .py is commonly used to refer to a Python script, it is not required that scripts use this scheme.

Although not shown in this example, the script can contain, and call, Python function definitions, or import and use other modules.


From the command line

If you just want to run the commands and return to the command lines you can either use the batch mode of Sherpa or use python to run the commands.

Sherpa's batch mode

The -b command-line flag for Sherpa turns on batch mode: this means that the starting banner is not displayed and that the interactive mode is not entered. Here is an example of running the above script:

unix% sherpa -b example.py
Dataset               = 1
Method                = levmar
Statistic             = chi2gehrels
Initial fit statistic = 9716.47
Final fit statistic   = 77.1754 at function evaluation 15
Data points           = 10
Degrees of freedom    = 8
Probability [Q-value] = 1.80694e-13
Reduced statistic     = 9.64693
Change in statistic   = 9639.29
   mdl.c0         1149.13     
   mdl.c1         -2.70027    
Dataset               = 1
Confidence Method     = covariance
Iterative Fit Method  = None
Fitting Method        = levmar
Statistic             = chi2gehrels
covariance 1-sigma (68.2689%) bounds:
   Param            Best-Fit  Lower Bound  Upper Bound
   -----            --------  -----------  -----------
   mdl.c0            1149.13     -20.2657      20.2657
   mdl.c1           -2.70027    -0.369379     0.369379

---- results ----
 mdl.c0     = 1149.13  (  -20.27 to   +20.27)
 mdl.c1     =   -2.70  (   -0.37 to    +0.37)

and the PNG version of the plot (example.png) has been created in the working directory.

[NOTE]
Python modules

Since we used Sherpa to evaluate the script, we did not have to load in the Sherpa or ChIPS modules, and could assume that the NumPy module was loaded as np.


Python

The script can be run by explicitly calling Python, or by setting it up as an executable script.

However, before we can do this, we need to modify the script to load in the necessary Python modules. The following lines should appear at the start of the script:

import numpy as np
from sherpa.astro.ui import *
from pychips import *

At this point you may also need to load in other modules that your script uses, such as pycrates.

With these changes, you can run the script (here called example2.py):

unix% python example2.py
... same output as above ...

If you want to run the script as an executable, then you need to make further changes:

  1. the first line of the script should say (before the Python imports):

    #!/usr/bin/env python
  2. the script should be made executable:

    unix% chmod u+x example3

    Note that it is not necessary to drop the .py suffix.

which allows you to do:

unix% ./example3
... same output as above ...

Within Sherpa

Here we want to remain within the Sherpa interactive environment after executing the script.

Starting with a script

If the -b flag is not given when running Sherpa, then the script will be executed and then the interactive environment will start up:

unix% sherpa example.py
-----------------------------------------------------
Welcome to Sherpa: CXC's Modeling and Fitting Package
-----------------------------------------------------
CIAO 4.9 Sherpa version 1 Friday, December 2, 2016

Dataset               = 1
Method                = levmar
Statistic             = chi2gehrels
Initial fit statistic = 9716.47
Final fit statistic   = 77.1754 at function evaluation 15
Data points           = 10
Degrees of freedom    = 8
Probability [Q-value] = 1.80694e-13
Reduced statistic     = 9.64693
Change in statistic   = 9639.29
   mdl.c0         1149.13     
   mdl.c1         -2.70027    
Dataset               = 1
Confidence Method     = covariance
Iterative Fit Method  = None
Fitting Method        = levmar
Statistic             = chi2gehrels
covariance 1-sigma (68.2689%) bounds:
   Param            Best-Fit  Lower Bound  Upper Bound
   -----            --------  -----------  -----------
   mdl.c0            1149.13     -20.2657      20.2657
   mdl.c1           -2.70027    -0.369379     0.369379

---- results ----
 mdl.c0     = 1149.13  (  -20.27 to   +20.27)
 mdl.c1     =   -2.70  (   -0.37 to    +0.37)
sherpa-1> print(cr)
datasets    = (1,)
methodname  = covariance
iterfitname = none
fitname     = levmar
statname    = chi2gehrels
sigma       = 1
percent     = 68.2689492137
parnames    = ('mdl.c0', 'mdl.c1')
parvals     = (1149.1339181885337, -2.7002666765005863)
parmins     = (-20.265696894022124, -0.36937921936207141)
parmaxes    = (20.265696894022124, 0.36937921936207141)
nfits       = 0
sherpa> quit()
[NOTE]
Note

Top-level variables defined in the script, such as cr in example.py, can be accessed after the script has been run.


From the interactive session

Scripts can also be run at any time within the Sherpa interactive session by using the exec command.

sherpa> exec(open("./example.py").read())
... same output as above
[WARNING]
The existing Sherpa state

Care should be taken when writing a script for an existing Sherpa session to either make sure that the script either sets everything it needs—such as the optimizer and method—in case it has been changed by the user before loading the script, or that such changes are expected (e.g. to see how changing the optimizer changes the results).

[WARNING]
Window display

Since the window display was set to False in the script, an on-screen version of the plot will not be created when the script is run, although the PNG version will be.

Until the window display setting is changed, any future plot calls within the session will appear to make no change, so if you have changed the window display setting you should call

sherpa> set_window(['display', True])

to make changes appear in the current window, and

sherpa> set_preferences(['window.display', True])

to make sure that any new window that is created is also shown on screen.


History

09 Jun 2009 original version
17 Dec 2009 updated for Sherpa 4.2
29 Jun 2010 updated for CIAO 4.2 Sherpa v2: the Sherpa S-Lang interface has been removed.
15 Dec 2010 Sherpa start-up banner updated for CIAO 4.3
15 Dec 2011 Sherpa start-up banner updated for CIAO 4.4
13 Dec 2012 Sherpa start-up banner updated for CIAO 4.5
26 Aug 2013 Rewritten to include an example script.
03 Dec 2013 Sherpa start-up banner updated for CIAO 4.6, outputs to match 4.6 results.
02 Dec 2014 Updated for CIAO 4.7
14 Dec 2015 Updated for CIAO 4.8
05 Dec 2016 Updated for CIAO 4.9


Last modified: 5 Dec 2016
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email:   cxchelp@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2017. All rights reserved.