heasoftpy: A Python Interface To HEASoft

What is heasoftpy?

heasoftpy is a Python 3 package that allows users to more easily integrate HEASoft tools into their Python workflow. heasoftpy provides Python wrappers to the HEASoft tools (and so requires a HEASoft installation of course). Note that heasoftpy does NOT provide Python native versions of HEASoft tools.

Please note that this initial release is a BETA release, so some functionality may be missing, and improvements may be forthcoming.


Installation of heasoftpy is simple. Assuming you have HEASoft initialized and the environment variable $HEADAS is defined, you should:

  1. Download the heasoftpy0.1.10 tar file to $HEADAS/lib/python (if $HEADAS/lib/python doesn't exist, please create it).
  2. Untar the file

This will create a heasoftpy subdirectory in $HEADAS/lib/python. To make sure that $HEADAS/lib/python is in your PYTHONPATH environment variable, you may need to re-initialize HEASoft by sourcing the $HEADAS/headas-init.sh[.csh] file.

Using heasoftpy

The first time HEASoftPy is imported, Python functions corresponding to tasks in the HEASoft suite will be written into the $HEADAS/lib/python/heasoftpy/defs directory. (This process may take a while.) The heasoftpy functions in $HEADAS/lib/python/heasoftpy/defs are wrappers to whatever HEASoft tools you currently have installed (this could be all HEASoft tasks or some subset of the full distribution, depending on which package choices you made when downloading).

The heasoftpy functions run HEASoft tools and return a RESULT object. The RESULT object is a container for data returned from heasoftpy call to a HEAsoft tool, and has the following attributes:

  • ret_code (status; equals 0 if no errors occurred)
  • std_out (captures STDOUT)
  • std_err (captures STDERR, default = None)
  • parms (a dictionary of the parmeter list for the specified tool, default = None)
  • custom (default = None)

Some Usage Examples

Importing and using heasoftpy in a Python 3 session is simple:
% ipython
In [1]: import heasoftpy as hsp
In [2]: hsp? # get help on the heasoftpy package
In [3]: myfitsfile = 'Test.fits'
In [4]: hsp_result = hsp.ftverify(myfitsfile)
In [5]: print(hsp_result.stdout)
In [6]: output = hsp_result.stdout.split('\n')
in [7]: verification =  [x for x in output if 'Verification found' in x]  # list of the verification strings in the output
To find the effective area for NICER, you could do this:
In [1]: import heasoftpy as hsp
In [2]: hsp_result = hsp.quzcif() # heasoftpy will prompt you for unspecified required parameters
Name of Mission> nicer
Name of Instrument> xti
Name of Detector (- if not required)> -
Name of Filter (- if not required)> -
Calibration Dataset Codename> SPECRESP
Requested Date in yyyy-mm-dd format> now
Requested Time in hh:mm:ss format> now
Boolean selection expression for Boundary params(- if not required)> -
In [3]: hsp_result.stdout
Out[3]: 'https://heasarc.gsfc.nasa.gov/FTP/caldb/data/nicer/xti/cpf/arf/nixtiaveonaxis20170601v004.arf   1\n'
In [4]: arf = hsp_result.stdout.split()[0]
In [5]: print('The current NICER ARF is {0}'.format(arf))
The current NICER ARF is https://heasarc.gsfc.nasa.gov/FTP/caldb/data/nicer/xti/cpf/arf/nixtiaveonaxis20170601v004.arf


Please send any comments or questions to the ftools help desk

Last modified Monday, 05-Oct-2020 13:59:02 EDT


If FTOOLS has been useful in your research, please reference this site (http://heasarc.gsfc.nasa.gov/ftools) and use the ASCL reference for HEASoft [ascl:1408.004] or the ASCL reference for the original FTOOLs paper [ascl:9912.002]:

Blackburn, J. K. 1995, in ASP Conf. Ser., Vol. 77, Astronomical Data Analysis Software and Systems IV, ed. R. A. Shaw, H. E. Payne, and J. J. E. Hayes (San Francisco: ASP), 367.

Web page maintained by: Bryan K. Irby

HEASARC Home | Observatories | Archive | Calibration | Software | Tools | Students/Teachers/Public

Last modified: Monday, 05-Oct-2020 13:59:02 EDT