heasoftpy is a python wrapper around the HEASoft tools.
This notebooks is a quick "Getting Started" guide. It contains a walkthough the main features of the package
The first thing we need is to import the heasoftpy package.
Please follow the insallation instructions in in README file.
import sys
import os
# check the installation #
if not 'HEADAS' in os.environ:
raise RuntimeError('Heasoft is not initalized')
try:
sys.path.insert(0, os.path.abspath(os.path.join(os.path.abspath(''), '..')))
import heasoftpy as hsp
except ImportError:
raise RuntimeError('Please ensure heasoftpy is in your PYTHONPATH')
if not hasattr(hsp, 'ftlist'):
raise RuntimeError('Heasoftpy is not full installed. Please run the install.py script')
print(hsp.__version__)
1.0
The general package help can printed by doing hsp? or hsp.help()
hsp.help()
DESCRIPTION: ----------- HEASoftpy is a Python package to wrap the HEASoft tools so that they can be called from python scripts, interactive ipython sessions, or Jupyter Notebooks. >>> import heasoftpy as hsp >>> help(hsp.fdump) ... >>> result = hsp.ftlist(infile='input.fits', option='T') >>> print(result.stdout) ...
ftlist¶The simplest way to run a task is call the function directly (after installing the package) as: hsp.taks_name(...)
Here too, we can print the help text for a task using standard python help: hsp.task_name?
result = hsp.ftlist?
Signature: hsp.ftlist(args=None, **kwargs) Docstring: Automatically generated function for Heasoft task ftlist. Additional help may be provided below. Args: infile (Req) : Input file name (default: tmpI.lc) option (Req) : Print options: H C K I T (default: C) outfile : Optional output file (default: -) clobber : Overwrite existing output file? (default: no) include : Include keywords list (default: *) exclude : Exclude keywords list (default: ) section : Image section to print, eg, '2:8,1:10' (default: *) columns : Table columns to print (default: *) rows : Table rows or ranges to print, eg, '2,6-8' (default: -) vector : Vector range to print, eg, '1-5' (default: -) separator : Column separator string (default: ) rownum : Print row number? (default: yes) colheader : Print column header? (default: yes) mode : Mode (default: ql) -------------------------------------------------- The following has been generated from fhelp -------------------------------------------------- NAME ftlist - List the contents of the input file. USAGE ftlist infile[ext][filters] option DESCRIPTION 'ftlist' displays the contents of the input file. Depending on the value of the 'option' parameter, this task can be used to list any combination of the following: ...
For ftlist, there two required inputs: infile and option, so that both paramters need to be provided, otherwise, we will get prompted for the missing parameters
result = hsp.ftlist(infile='../tests/test.fits', option='T', colheader='no')
Running a task returns an HSPResult instance, which is a simple container for the results that contains:
returncode: a return code: 0 if the task executed without errors (int).stdout: standard output (str).stderr: standard error message (str).params: dict of user parameters in case the task changed them, used to update the .par file.custom: dict of any other variables to returned by the task.In this case, we may want to just print the output as:
print('return code:', result.returncode)
print(result.stdout)
return code: 0 1 1164.29445392592 18.2019 1.22564 2 1164.43056492592 16.3479 1.38458 3 1164.43167642593 17.2304 1.48210 4 1164.77686142593 14.8949 1.54721 5 1164.85352792592 14.7539 1.32291 6 1164.85463892593 14.2253 0.989307 7 1164.85463892593 14.3773 1.86374 8 1166.26056492592 19.2784 1.28549 9 1166.26167642593 17.5375 0.767405 10 1166.26167642593 19.7158 1.08722
A returncode = 0 indicates the task executed without problems.
We can print the content result to see all the returns of the task:
print(result)
--------------------- :: Execution Result :: --------------------- > Return Code: 0 > Output: 1 1164.29445392592 18.2019 1.22564 2 1164.43056492592 16.3479 1.38458 3 1164.43167642593 17.2304 1.48210 4 1164.77686142593 14.8949 1.54721 5 1164.85352792592 14.7539 1.32291 6 1164.85463892593 14.2253 0.989307 7 1164.85463892593 14.3773 1.86374 8 1166.26056492592 19.2784 1.28549 9 1166.26167642593 17.5375 0.767405 10 1166.26167642593 19.7158 1.08722 > Parameters: infile : ../tests/test.fits option : T outfile : - clobber : no include : * exclude : section : * columns : * rows : - vector : - separator : rownum : yes colheader : yes mode : ql
We can modify the parameters returned in results, and pass them again to the task.
Say we want to print the column header:
params = result.params
params['colheader'] = 'yes'
result2 = hsp.ftlist(params)
print(result2.stdout)
TIME RATE ERROR
d counts/s counts/s
1 1164.29445392592 18.2019 1.22564
2 1164.43056492592 16.3479 1.38458
3 1164.43167642593 17.2304 1.48210
4 1164.77686142593 14.8949 1.54721
5 1164.85352792592 14.7539 1.32291
6 1164.85463892593 14.2253 0.989307
7 1164.85463892593 14.3773 1.86374
8 1166.26056492592 19.2784 1.28549
9 1166.26167642593 17.5375 0.767405
10 1166.26167642593 19.7158 1.08722
Notice how the column header is printed now!
If we forget to pass a required parameter, we will be prompted for it. For example:
result = hsp.ftlist(infile='../tests/test.fits')
In this case, parameter filist:option was missing, so we are prompted for it, and the default value is printed between brackets: (T), we can type a value, just press Return to accept the default value.
For tasks that take longer to run, the user may be interested in the seeing the output as the task runs. There is a verbose option to print the output of the command similar to the standard output in command line tasks.
result = hsp.ftlist(infile='../tests/test.fits', option='T', verbose=True)
TIME RATE ERROR
d counts/s counts/s
1 1164.29445392592 18.2019 1.22564
2 1164.43056492592 16.3479 1.38458
3 1164.43167642593 17.2304 1.48210
4 1164.77686142593 14.8949 1.54721
5 1164.85352792592 14.7539 1.32291
6 1164.85463892593 14.2253 0.989307
7 1164.85463892593 14.3773 1.86374
8 1166.26056492592 19.2784 1.28549
9 1166.26167642593 17.5375 0.767405
10 1166.26167642593 19.7158 1.08722
There is an alternative way to calling a task, and that is by creating an instance of HSPTask and calling it. For the example of ftlist, we would do:
# create a task object
ftlist = hsp.HSPTask('ftlist')
the ftlist instance acts just like the function hsp.ftlist above.
# run the task
out = ftlist(infile='../tests/test.fits', option='T')
print(out.stdout)
TIME RATE ERROR
d counts/s counts/s
1 1164.29445392592 18.2019 1.22564
2 1164.43056492592 16.3479 1.38458
3 1164.43167642593 17.2304 1.48210
4 1164.77686142593 14.8949 1.54721
5 1164.85352792592 14.7539 1.32291
6 1164.85463892593 14.2253 0.989307
7 1164.85463892593 14.3773 1.86374
8 1166.26056492592 19.2784 1.28549
9 1166.26167642593 17.5375 0.767405
10 1166.26167642593 19.7158 1.08722
The parameters of the task are attributes of the HSPTask object (called ftlist here), so they can be easily modified:
ftlist.colheader = 'no'
out = ftlist()
print(out.stdout)
1 1164.29445392592 18.2019 1.22564 2 1164.43056492592 16.3479 1.38458 3 1164.43167642593 17.2304 1.48210 4 1164.77686142593 14.8949 1.54721 5 1164.85352792592 14.7539 1.32291 6 1164.85463892593 14.2253 0.989307 7 1164.85463892593 14.3773 1.86374 8 1166.26056492592 19.2784 1.28549 9 1166.26167642593 17.5375 0.767405 10 1166.26167642593 19.7158 1.08722
Note that the line out = ftlist() executes without querying for parameters because it uses parameters from the previous run, which are stored in ftlist.params and returned in out.params
For some tasks, particularly pipelines, the user may want to runs the task without querying all the parameters.
In that case, we can pass the noprompt=True when calling the task, and heasoftpy will run the task without
checking the prameters. For example, to process the NuSTAR observation 60001111003, we can do:
r = hsp.nupipeline(indir='60001111003', outdir='60001111003_p', steminputs='nu60001111003',
noprompt=True, verbose=True)
this will call nupipeline without querying all parameters (using the defaults), and printing all progress as it runs (verbose=True)