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 thus requires a HEASoft installation of course). Note that heasoftpy does NOT provide Python native versions of HEASoft tools.

Installation

As of the HEASoft 6.29 release (July 2021), all downloads include and install HEASoftPy by default, but if you are using an older version of HEASoft, please refer to the following instructions:

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

1. Download the heasoftpy0.1.22 tar file to $HEADAS/lib/python (if $HEADAS/lib/python doesn't exist, please create it).
2. Untar the file (creates a "heasoftpy" directory)
3. Run the installer from the command line:
   $ cd heasoftpy
   $ python3 install.py
   (This process may take a while.)

Python functions corresponding to tasks in the HEASoft suite will be written into the $HEADAS/lib/python/heasoftpy/defs directory. Please note that if you add new tasks to your installation and want heasoftpy to be able to access them, you will need to repeat the process above.

Lastly, to make sure that $HEADAS/lib/python is included in your PYTHONPATH environment variable, you may need to re- initialize HEASoft by sourcing the standard HEASoft setup script:

   $ source $HEADAS/headas-init.sh  (Bourne shell variants)
     Or
   $ source $HEADAS/headas-init.csh (C-shell variants)

Using heasoftpy

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 a 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

Help

Please send any comments or questions to the ftools help desk

Last modified Thursday, 22-May-2025 15:54:02 EDT