Last modified: 20 Nov 2023

URL: https://cxc.cfa.harvard.edu/sherpa/threads/sherpa_startup/

Starting Sherpa

Sherpa Threads (CIAO 4.16 Sherpa)


Overview

Synopsis:

This thread describes how to start Sherpa for the first time, how to access the help files for Sherpa commands in a variety of ways, as well as how to customize the Sherpa environment.

Last Update: 20 Nov 2023 - reviewed for CIAO 4.16: Sherpa start-up banner updated


Contents


Starting Sherpa for the First Time

When Sherpa is started from within the CIAO environment, the user is informed of the CIAO and Python version numbers:

unix% sherpa
-----------------------------------------------------
Welcome to Sherpa: CXC's Modeling and Fitting Package
-----------------------------------------------------
Sherpa 4.16.0+3.g80b22a87

Python 3.11.6 | packaged by conda-forge | (main, Oct  3 2023, 10:40:37) [Clang 15.0.7 ]
Type 'copyright', 'credits' or 'license' for more information
IPython 8.17.2 -- An enhanced Interactive Python. Type '?' for help.

IPython profile: sherpa
Installed osx event loop hook.
Using matplotlib backend: MacOSX

[NOTE]
CIAO installation: ciao-install versus conda

The information presented when Sherpa is started depends on

  1. how CIAO was installed (ciao-install or conda)
  2. what version of Python was used (only relevant for the conda installation since ciao-install only supports Python 3.11)

The Sherpa script loads the Sherpa (Python) module, as well as the Crates module, which handles file input and output, and the Matplotlib plotting package.

Default Sherpa settings are defined in the $HOME/.sherpa.rc file, which is processed when Sherpa is started; this file can be modified as described in the section Customizing the Sherpa Environment.

The Sherpa application uses the $HOME/.ipython-ciao/ directory to store configuration information. The first time Sherpa is started you will see a message asking whether you want to update this directory. For example:

unix% sherpa

 ATTENTION: The IPython profile found in /home/ciaoenthusiast/.ipython-ciao/profile_sherpa is not compatible with this version of sherpa.

            Update to a compatible version? [Y/N]:

Unless you have manually changed your $HOME/.ipython-ciao/profile_sherpa file, it is safe to answer "Y" here. The outdated file is renamed with a timestamp to preserve it. The new profile is installed read-only. If you would like to modify how Sherpa uses IPython functions, or call exec/execfile to load Python scripts when Sherpa starts, a customization file should be added to ~/.ipython-ciao/profile_sherpa/startup/. If you would like IPython profiles to be somewhere other than ~/.ipython-ciao, you can set IPYTHONDIR to point to the desired directory.

ChIPS warning

If you have transitioned to Sherpa with a version earlier than CIAO 4.12, then it is likely that you will see this warning when Sherpa starts:

WARNING: chips is not supported in CIAO 4.12+, falling back to matplotlib.
WARNING: Please consider updating your $HOME/.sherpa.rc file to suppress this warning.

Sherpa will work correctly, and create plots with Matplotlib. To stop the warning from appearing please update your Sherpa RC file as described in the FAQ entry.

Command-line options

The following are the remaining command-line options which may be specified when Sherpa is started:

unix% sherpa -h
-- sherpa
  usage: sherpa [-x] [-n] [-b] [-rcfile file] [norcfile] <file>
     -x       launch sherpa shell in separate display terminal
     -n       do not print banner
     -b       batch mode
     -rcfile  load a user specifiable preference file
     -norcfile do not load any user specifiable preference file (overrides -rcfile)
     <file> Python command file to execute

See the section Command-line Options for Sherpa for more details on these Sherpa startup options.


Getting Help

There are several ways to access the Sherpa help files.

[NOTE]
Please use the Python help when possible

The in-built Python help command provides more up-to-date information on a command than the ahelp command. The "downside" is that the documentation is written to match the standards used by other Scientific packages, such as NumPy and AstroPy, rather than to follow the ahelp approach and layout.

The Python help system

When in Sherpa the Python help command can be used to return information on a command or symbol. For example

sherpa> help plot_fit_ratio

and

sherpa> help set_stat

If—as in these examples—you don't surround the argument in parentheses then Sherpa will report to you that it has added in the missing characters. For example after saying help group_counts you will see the following in your terminal (which can be ignored):

-------------> help(group_counts)

From the CIAO command line

  • Python syntax, description and examples for a specific command:

    unix% ahelp <command>
    

From within Sherpa - ahelp

From within Python, ahelp may be called in several ways:

  • sherpa> ahelp("<command>")
    
  • sherpa> ahelp "<command>"
    
  • sherpa> !ahelp <command>
    
  • sherpa> ,ahelp <command>
    

The last two call out explicitly to the ahelp executable, which lets you include command-line flags, such as just listing the examples in a command:

sherpa> !ahelp -b QEXAMPLELIST reg_proj

Finding a Command

Here are some tips on how to find the name of a command while working in Sherpa.

Searching for a name with ?

To search for a phrase, use the "?" system; the ? is placed after the string and the * act as a wild card:

sherpa> *_arf* ?
create_arf
get_arf
get_arf_plot
get_bkg_arf
load_arf
load_bkg_arf
load_multi_arfs
plot_arf
set_arf
unpack_arf

Tab completion

Type the start of a command and hit <TAB> for all possible completions:

sherpa> plot_fit__
plot_fit_delchi() plot_fit_ratio() plot_fit_resid()

Running CIAO and Unix commands from the Sherpa Prompt

Any line beginning with "!" is passed from Sherpa to the shell. This allows you to run CIAO and shell commands from the Sherpa prompt.

For example:

sherpa> !pwd
/data/ciao_demo/threads/acis-s/1838/primary

sherpa> !ls
acisf01838_000N001_bpix1.fits  acisf01838N001_src2.fits
acisf01838N001_evt2.fits       pcadf084244404N001_asol1.fits

sherpa> !dmkeypar acisf01838N001_evt2.fits OBJECT echo+
G21.5-0.9

sherpa> !dmcopy "acisf01838N001_evt2.fits[energy=300:10000]" 1838_energy.fits

Exiting Sherpa

Type "quit" or use <CTRL>-D to exit Sherpa.


Command-line options for Sherpa

The Sherpa command-line options can be listed with the -h flag:

unix% sherpa -h
-- sherpa
  usage: sherpa [-x] [-n] [-b] [-rcfile file] [norcfile] <file>
     -x       launch sherpa shell in separate display terminal
     -n       do not print banner
     -b       batch mode
     -rcfile  load a user specifiable preference file
     -norcfile do not load any user specifiable preference file (overrides -rcfile)
     <file> Python command file to execute
-x

This will create a new Xterm and start Sherpa in it.

-n

This switch causes Sherpa to start without a banner:

unix% sherpa -n
sherpa-1>
-b

Executes Python command file as a non-interactive Sherpa session.

-rcfile

This option allows the user to specify a specific .sherpa.rc file to use; refer to "ahelp sherparc" for details.

-norcfile

This option specifies that a .sherpa.rc file should not be loaded; overrides "-rcfile" if both are set.

<file>

The contents of the file are executed before the user is prompted for further commands. The command must be in the same language as used at the interactive prompt. So, if simple.py contained

load_pha("src.pi")
plot_data()
print("Loaded and plotted data")

then we will load and plot the data if Sherpa is started by saying:

unix% sherpa simple.py
-----------------------------------------------------
Welcome to Sherpa: CXC's Modeling and Fitting Package
-----------------------------------------------------
Sherpa 4.16.0+3.g80b22a87

Python 3.11.6 | packaged by conda-forge | (main, Oct  3 2023, 10:40:37) [Clang 15.0.7 ]
Type 'copyright', 'credits' or 'license' for more information
IPython 8.17.2 -- An enhanced Interactive Python. Type '?' for help.

IPython profile: sherpa
Installed osx event loop hook.
Using matplotlib backend: MacOSX

read ARF file src.arf
read RMF file src.rmf
read background file bgnd.pi
Loaded and plotted data

sherpa>

Running Sherpa Scripts from the Sherpa Prompt

Given the script of Sherpa (and putative Python) commands in the simple.py script described above, the script can be executed from the Sherpa command-line using the iPython %run magic command:

unix% sherpa
-----------------------------------------------------
Welcome to Sherpa: CXC's Modeling and Fitting Package
-----------------------------------------------------
Sherpa 4.16.0+3.g80b22a87

Python 3.11.6 | packaged by conda-forge | (main, Oct  3 2023, 10:40:37) [Clang 15.0.7 ]
Type 'copyright', 'credits' or 'license' for more information
IPython 8.17.2 -- An enhanced Interactive Python. Type '?' for help.

IPython profile: sherpa
Installed osx event loop hook.
Using matplotlib backend: MacOSX

sherpa> %run -i simple.py
sherpa>

Using Sherpa from Python

The Sherpa and Crates modules which come packaged with CIAO can be loaded into Python as follows, enabling the user to access Sherpa functionality on the Python command line.

unix% ipython
Python 3.9.9 (main, Mar 24 2022, 22:02:45) 
Type 'copyright', 'credits' or 'license' for more information
IPython 8.0.0 -- An enhanced Interactive Python. Type '?' for help.

In [1]: from sherpa.astro.ui import *

In [2]: from pycrates import *

In [3]: import matplotlib.pyplot as plt

In [4]: %matplotlib

Using matplotlib backend: TkAgg

[NOTE]
Use the --matplotlib flag

IPython accepts the --matplotlib command-line flag which removes the need to say %matplotlib. The latter is useful when you forget to start IPython with the former!

Sherpa is also available for Python users as a standalone application, independent of CIAO; download instructions and user documentation are available at the Contributed CIAO Sherpa (Python) Extension Packages page.


Customizing the Sherpa Environment

When Sherpa is started, it processes the $HOME/.sherpa.rc resource file, which defines the default behavior for Sherpa commands. You can modify the settings in this file in any text editor to suit your preferences; see the .sherpa.rc ahelp file for detailed descriptions of the available settings.


History

14 Nov 2007 new for CIAO 4.0 Beta 3
15 Dec 2008 CIAO 4.1 - when Sherpa is started a banner is now displayed (by default); Python or S-Lang mode for Sherpa can now be chosen using the -l flag; the SHERPA_SCRIPT_LANG environment variable has been superceded by the CIAO_SCRIPT_LANG variable; a number of command-line options are now available
31 Mar 2009 added section "Customizing the Sherpa Environment"
15 Dec 2009 updated for CIAO 4.2
29 Jun 2010 updated for Sherpa v2 in CIAO 4.2: the Sherpa S-lang interface has been removed.
15 Dec 2010 updated with an explanation of the Sherpa start-up banner
15 Dec 2011 reviewed for CIAO 4.4: Sherpa start-up banner updated
10 Apr 2012 typo in executing python script
13 Dec 2012 new IPython 0.13 profile available in CIAO 4.5
03 Dec 2013 reviewed for CIAO 4.6: Sherpa start-up banner updated
02 Dec 2014 updated for CIAO 4.7
14 Dec 2015 updated for CIAO 4.8
06 Dec 2016 updated for CIAO 4.9
11 Apr 2018 updated for CIAO 4.10, added %run iPython magic command
11 Dec 2018 updated for CIAO 4.11
12 Dec 2019 Updated for CIAO 4.12: noted change to Matplotlib and multiple ways of installing CIAO (ciao-install versus conda).
31 Mar 2022 updated for CIAO 4.14
05 Dec 2022 updated for CIAO 4.15
20 Nov 2023 reviewed for CIAO 4.16: Sherpa start-up banner updated