spibkgsubtrct (Apr 05)           integral              spibkgsubtrct (Apr 05)

NAME
   spibkgsubtrct -- produces a background subtracted spectrum resulting
		      from an initial XSPEC analysis of INTEGRAL/SPI data

USAGE
   spibkgsubtrct inpPHAfil bkgMdlParams bkgRowNum outpPHAfil

DESCRIPTION
   This program produces a background subtracted PHA-II data
   structure, for  INTEGRAL/SPI data which has been analyzed
   using the XSPEC ver. 12+ SPI-specific  functionality to
   solve background and source content of a given observation. 
   Specifically, it reads the output of the XSPEC  tcl procedure
   called "SavBkgMdl",  which uses the SPI background
   models internal to XSPEC, i.e. spibkg_lo,  spibkg_med or
   spibkg_hi, and the derived parameters to compute the
   background for each spectrum included in the analysis. (To
   obtain the  INTEGRAL SPI-specific XSPEC tcl scripts, refer
   to <http://heasarc.gsfc.nasa.gov/docs/integral/inthp_analysis.html>. 
   For instructions on how to analyze SPI data with
   XSPEC, refer to the XSPEC v12 manual and other information in:
   <http://heasarc.gsfc.nasa.gov/docs/xanadu/xspec/>). 
   
   The relevant  PHA-II data file (or user-specified subset
   thereof) is read into memory. The best-fit  background rates
   are then computed through a call to the appropriate XSPEC 
   model, and then subtracted from the data (it is currently
   assumed that COUNTS rather than RATES since this is what
   the INTEGRAL software,"SPIHIST", produces by default). A
   new PHA-II data file is then output, containing  the
   background subtracted data. Note that if some row-selection
   cut is made  in the analysis, e.g. if rows 181-360 are used out
   of 1-504 total rows,  the rows 1-180 and 361-504 will
   contain the original (i.e.  source+background) data, with only
   181-360 being background subtracted.  Thus, if a row-selection
   cut is made at an early stage of the analysis  it should
   be used throughout.

   
   
PARAMETERS

     inpPHAfil  [string]	Name (including directory path) of the 
                                input (FITS) PHA-II spectral data file
				for which the background model is to be 
				subtracted.

     bkgMdlParams [string]	Name of ascii file (including directory path)
				produced by XSPEC SavBkgMdl 
				procedure which contains the sectrum-row 
				number, plus associated backound model
				parameters


     outpPHAfil  [string]       PHA-II output file to be used for 
				subsequent XSPEC analysis. Note that that 
				only the subset of rows that were used in the
				initial XSPEC analysis have been changed. This
				should be taken into accoiunt when loading the 
				background subtracted data into XSPEC.
				

     SPIbkgInitFil  [string]    Name of FITS file produced by "spibkg_init"
				prior to the inital XSPEC analysis


     bkgSpecNum   [int]		row number of the "SPI.-RSP.-DBS" table
	                        extension of the PHA-II input file which
				references the background respoonse matrices. 
				If this is not specified, the user must 
				manually remove this row from the table.


EXAMPLES:

Complete an XSPEC session:

XSPEC> ... perform analysis of SPI data for Vela X-1 ...
XSPEC> source /myScripts/SavBkgMdl.tcl
XSPEC> SavBkgMdl ... VelaX1.parms

Then run spibkgsubtrct with the following par file:
 
inPHAfil,s,ql,"/myData/VelaX1_20-300keV.pha",,,"Input PHA-II data file:"
bkgMdlParams,s,ql,"/myWorkArea/VelaX1.params",,,"Input SPI background model parameters:"
outpPHAfil,s,ql,"VelaX1_20-300keV_noBkg.pha",,,"Name of output PHA-II file:"
SPIbkgInitFil,s,ql,"/myData/spibkg_inp_dat_VelaX1.fits",,,"Name background template file"
bkgSpecNum,i,ql,2,,,"source number for background (as used in XSPEC) (<=0 to ignore)"

Then use the output file in XSPEC:

XSPEC> data VelaX1_20-300keV_nobkg.pha{n-m}
XSPEC> ... reload source model, and optionally, other datasets, refit ...
    

FILES NEEDED     
     The type-II PHA data file produced by  the INTEGRAL OSA package specfically, the 
     "SPIHIST" routine, is needed, as is an ascii file produced from the intial XSPEC
     analysis, by the tcl script "SavBkgMdl". Additionally, a FITS file produced from
     the XSPEC response matrices and the input PHA-II file by the "SPIBKG_INIT" FTOOL
     is needed. 
   
BUGS 
    

SEE ALSO 
     Related utilities from the INTEGRAL (OSA) suite: SPIHIST,
     SPIRMF, SPIARF, SPIBACK, and FTOOL SPIBKG_INIT. Also, refer to the XSPEC
     version 12 users manual for instructions on how to analyze INTEGRAL/SPI
     data with XSPEC.