add_pha - documentation


Program: add_pha


Add the COUNTS columns from multiple commensurate input files and write the result to a standard OGIP Type I PHA file.

Input files can be Type I or Type II, and may represent source or background counts. The EXPOSURE keywords in the input files will be averaged, and the mean exposure written to the output header. The BACKSCAL keywords in the input files will be summed weighting by exposure and written to the output file header.

With Parameter I/O Interface

If the CIAO envirnoment is detected (via the ASCDS_INSTALL environment variable), then the paramio interface will be invoked via a CIAO S-Lang module. To configure the CIAO environment for external scripts, they must be run with CIAO's ciaorun wrapper script.


  • ciaorun add_pha infile=infiles outfile=outfile [ comment=comments ]
  • ciaorun add_pha infiles outfile [ comments ]
  • infile: Input PHA file specification, specifying two or more counts spectra. The list can be given as a comma-delimited (no spaces between filenames) list of file specifications. The file specification may be given as a CFITSIO virtual file reference (spaces are permitted within the "[]" of the virtual file specification). (See the Examples). Alternatively, the list may be indirectly referenced with the "@file" syntax, in which "file" is the name of a file containing a list of file specifications, one per line (see the Examples). Input files may be Type I or Type II PHA files.
  • outfile: Name of the output file, which will be an OGIP Type I PHA spectrum file.
  • comments: An optional comma-delimited list of comments to be written to the output file. Alternatively, the list may be referenced via the "@file" syntax, and the file should contain one comment per line.
  • verbose: unused.
  • clobber: "yes" or "no" controls whether the an existing output file is over-written.
  • mode: Paramio mode flag. See the CIAO documentation on "parameter".

Without Parameter I/O Interface

If the CIAO environment is not detected, then there is no attempt to load the paramio S-Lang module, and a positional interface is used without the parameter keyword qualifiers, and there will be no prompting if paramtgers are omitted.


  • add_pha infiles outfile [ comments ]
The arguments are given as for the paramio interface.

ISIS Library Function

Using the ISIS library function directly allows spectra to be summed from within S-Lang scripts. The function add_pha_counts() is defined in
  • USAGE: add_pha_counts( infiles, outfile[,comments] );
    • infiles String or string array specifying one or more PHA files. The files may be specified with cfitio virtual file syntax.
    • outfile gives the name of the output file. If the file exists, it will be over-written.
    • comments String or string array giving a list of comments to be written to the output header.

    infiles = [ "pha-1.fits[tg_part==2 && (tg_m==-1 || tg_m==1)]",
                "pha-2.fits[#row==9 || #row==10]",
                "pha-3.fits" ];
    add_pha_counts( infiles, "pha-123.fits", ["Capella", "MEG -1,+1"] );

Technical Note

This technical note provides some detailed technical background and issues regarding definition and use of summed spectra.

This page was last updated Sep 3, 2013 by David P. Huenemoerder. To comment on it or the material presented here, send email to
Valid HTML 4.01! Made with JED. Viewable With Any Browser.