SPIHIST

User Guide

Version 2.2.0

 

PDF file for download

1. Introduction

SPIHIST is a SPI Instrument Specific Software (ISSW) analysis executable designed to histogram event data given in an ISDC INTEGRAL/SPI FITS data structure (as defined in the SPI /ICD). The current version of SPIHIST has been written using the ISDC Data Access Layer (DAL), Report Interface Library (RIL), Parameter Interface Library (PIL) and the SPI-DAL3 application library. The output FITS files are formatted using a set of template files, each appended with a ".tpl" extension, which should be placed in your working directory. Run-time options are controlled by a parameter file called spihist.par and through a previously defined Observation Group (OG). The related SPI utilites SPIPOINT, SPIGTI, SPIDEAD, and SPIBOUNDS are generally run prior to running SPIHIST. This manual is designed to give the reader a concise tutorial on the use and features of SPIHIST.

2. spihist.par

Analogous to the HEASARC FTOOLs or the NOAO IRAF package, SPIHIST run options are controlled by a parameter file called spihist.par. This file, along with the SPIHIST executable and template files are required. spihist.par should be placed in the directory where the environmental variable PFILES points. The parameter file is easily edited to customize SPIHIST. It contains, in order, the input parameter names, their data type, whether the user is prompted for a value, whether the parameter value used in the latest successful run is saved as the new default value, the current default value, and the prompt message. NEVER change the parameter name or enter extraneous text in the parameter file. The parameter data types are: string (s), Boolean (b), integer (i), and real (r). The parameter is either hidden (h) or queried (q) with an (l) denoting that the default parameter value is replaced by the value in the latest run. A sample spihist.par file follows. Note that only those parameters that are queried can be changed once execution has begun. Hidden parameters can be changed when beginning execution by specifying a parameter and its value on the command line after typing ./spihist. For example:

 > ./spihist psdtype=raw

will set the parameter psdtype equal to "raw". The user can change hidden parameters to queried ones by replacing the appropriate "h" with a "q" in the parameter file. 

3. Parameter Options

The manual pages reprinted at the end of this guide in Appendix I describe each variable in the parameter file and its possible values. Here we will only discuss the most important parameters for using SPIHIST effectively.

 

3.1 File Input and Output

The FITS event data is histogrammed through the mechanism of an input Observation Group (OG). The OG, which is defined prior to running SPIHIST, consists of pointers to files containing the spacecraft pointing information for the observation being analyzed, lists of the "good time" intervals and "dead time" correction factors (see the documentation for SPIGTTI and SPIDEAD) as well as energy-bin definitions. In a typical example, a user should first run the SPIBOUNDS procedure to specify output-energy bin boundaries and build an OG which is subsequently input to SPIHIST.

Output is in general written to the FITS "DETE_SPECTRA" table specified by the SPI Interface Control Document (ICD); this is a simple FITS table whose rows consist of binned Count spectra and the corresponding statistical errors. There is a one-to-one correspondence between the rows of this table and that in the SPI_GTI table. Currently, a second output option exits which allows the user to write the binned detector spectra into a HEASARC compatible PHA-II data structure for subsequent use with the XSPEC spectral analysis software. The type of output file is given using outputformat which, at present, can have values of ISDC (for the aforementioned DETE_SPECTRA table) or PHA (for a Type II PHA FITS file). Samples of these file formats are given in Appendix II. Also note that SPIHIST will automatically append a ".fits" extension to the specified output file name if the format is PHA. The output data type is selectable using dtype where 1=counts, 2=counts/s/bin, and 3=counts/s/keV. The dead-time corrected exposure time is used to calculate rates. Note however, that this option cannot currently be used in conjunction with user-selected time windows which are subsets of the total livetime of a given pointing.

 

3.2 Detector Specifications

The SPI instrument consists of 19 separate Ge detectors. However, it will often be that case that a photon deposits portions of its energy in more than one detector – such events are referred to as "multiples". The mechanism through which such events are handled by SPIHIST and other SPI ISSW applications involves defining a set of "pseudo detectors". A photon event for example recorded by both detectors 0 and 1 would be assigned to a pseudo detector "20001" - the leading digit indicating the level of multiplicity (i.e. 2) and the subsequent integer fields "00" and "01" indicating detectors 0 and 1 were hit. In an analogous manner, events triggering the onboard pulse-shape discriminator logic (PSD events) might be assigned to a separate set of 19 pseudo detectors to distinguish these events from non-PSD events. Refer to Table 5 of the SPI/ICD for a complete listing of the pseudo-detector definitions. The user thus has a variety of detector-selection options. These selections are generally made prior to running SPIHIST, in the SPIGTI utility (see also 3.3.2). The FITS table column DET_NUM produced by SPIGTI then contains the subset of pseudo detectors that will be used.

If the "PHA-II" outputformat option is selected, a parameter "detnums", can be entered interactively or by editing the spihist.par file to select the desired list of detectors. The detector numbers are given separated by commas. For example, ranges of detector numbers are specified by giving the first and last detector in the range separated by a hyphen, e.g. to use detectors 0 to 5 and 10 to 11, the detnums entry would be “0-5,10-11". Additional details on the detnums parameter are given in Appendix I. Again, detnums can be specified ONLY in conjunction with the PHA-II outputformat.

Two additional options available only when the PHA outputformat is selected, are detsummed,, which instructs SPIHIST to produce a set of spectra which are summed over detectors, and pntgsummed, which leads to spectra summed over dither pointings (or science windows). Setting both of these parameters to “y” for example, leads to an output file containing a single spectrum formed from all single events from all 19 detectors, for all pointings of the observation group.

 

3.3 Binning Options

 3.3.1 Bin Size and Number

The number and size of the histogram bins is specified prior to running SPIHIST in the SPIBOUNDS procedure, the output of which is a FITS "EBOUNDS" table. This table is then part of the input OG that SPIHIST uses for subsequent analysis. SPIBOUNDS gives the user flexibility in binning their data. For example, one can choose logarithmically- or linearly-spaced bin boundaries or separate regions of coarsely- and finely-binned regions to handle continuum plus line sources. However, one should note that appropriate response matrices will have to be constructed for customized binning schemes. For more details, refer to the SPIBOUNDS documentation.

 3.3.2 Event Selection

Many event-selection options, such as what subset of real + pseudo detectors to use (and thus what multiplicities to consider), are made prior to running SPIHIST. The selection on multiplicities for example is done by running SPIGTI which establishes a subset of the detectors (from a master list of real + pseudo detectors) and updating the OG which is then input to SPIHIST. The pseudo-detector master-list is presented in Appendix A of the SPI ICD.

3.4 Other Parameters

We have gone over the most important parameters for effectively using SPIHIST. Most of the remaining parameters affect only information that is recorded in the headers of the output FITS files. Please see Appendix I for a short explanation of all parameters.

4. Known Problems

 Selection of Tstart and Tstop values, other than "INDEF" which indicates that the entire observation is to be used, will lead to incorrect count-rate determinations. Thus, an error will be issued if the user specifies Tstart, Tstop plus dtype=2 (cts/sec) or 3 (cts/sec/keV).

 

APPENDIX I: Manual Page (Including Examples)

SPIHIST (Sep2002) issw.integral SPIHIST (Sep2002)

NAME

    spihist -- Bins calibrated event data

        

USAGE spihist in-og-dol det-spec-dol out-og-dol detnums dtype tstart tstop outputformat chantype telescope instrume psdtype detsummed pntgsummed outfile chatter clobber mode

DESCRIPTION

spihist bins event data for individual detectors and/or for the entire detctor array. The events are grouped by pointing direction. Multiple detector events are allocated to a virtual "pseudo detectors." Similarly, if selected, different pulse-shape discrimination (PSD) data types are assigned to specifc pseudo detectors. A description if the pseudo detector definitions is avaliable in the SPI Interface Control Document (ICD).

The available output FITS file formats are ISDC/SPI spectral data structures (SPI.-OBS.-DSP) or OGIP PHA-II formats. Binned data is produced in counts, and for PHA-II format, counts/s/bin or counts/s/keV are supported as well. ISDC format should be selected, if the output spectra are to be used as input to the SPI image reconstruction tools, such as spiros or spiskymax. PHA mode should be selected for subsequent spectral analysis using the XSPEC (version 12 or higher) analysis software. In that case, the accompanying utilites "spirmf" and "spiarf" should be run, subsequent to spihist.

The output spectral-channel boundaries

(i.e. energy binning) is user specified, by running the related application spibounds prior to spihist.

For PHA mode only, it is possible to produce summed spectra. Summations can be over dither pointings, over all (or a subset) detectors, or both.

A more complete description of spihist is given in the users manual, <http://isdcul3.unige.ch/Instrument/spi/>.

PARAMETERS

  in-og-dol [character string]

Input FITS file which defines observation group to be processed.

  det-spec-dol [character string]

Output FITS structure containing binned detector spectra and uncertainties.

 out-og-dol [character string]

Output FITS file containing the updated observation group.

The following 4 optional dol parameters are for overriding the structures specified in the og table:

  swg-index-dol [character string]

Input FITS table containing index of science windows to be analyzed.

  gti-dol [character string]

Input FITS table containing the "good-time" intervals (i.e. start and stop times) for each detector, for each pointing. Times are in onboard clock units and UT.

  dead-time-dol [character string]

Input FITS table containing the deadtime (and livetime) correction factors for each pointing ID and each detector. A correction factor of (1-deadtime) is applied by to each good-time interval by SPIHIST in computing rates.

  ebounds-dol [character string]

Fits table containing the detector energy (or raw pulse-height) bin boundaries to be applied by SPIHIST.

  psdtype [character string]

Determines which type of PSD selection is desired. There are 2 PSD flags, one in the raw data which is created by the onboard software, and one in the corrected (cor) data which is created on the ground. The user has the option of selecting "raw" or "cor". The value of the PSD flag, 0 or 1, indicates whether a PSD event is characterized by single or multiple peaks.

  tstart [character string]

The start of the spectra accumulation time interval. If the value is INDEF, tstart is effectively disabled.

  tstop [character string]

The end of the spectra accumulation time interval. If the value is INDEF, tstop is effectively disabled.

Note that in versions 2.0.0 and higher, values of Tstart, Tstop other than INDEF are incompatible with dtypes 2 and 3. This is due to our current lack of information on how to compute the deadtime correction for sub-good-time intervals.

  instrume [character string]

Name of the instrument or detector.

 

  chatter [integer]

Flag to specify how verbose the screen output is. Lower/higher chatter levels produce less/more diagnostic output. Chatter values >= 20 will produce verbose output to log.

clobber [boolean]

If yes then an existing file can be overwritten.

outputformat [character string]

The available output file formats are "ISDC", in which case an ISDC SPI OBS table will be produced, or "PHA"in which case a PHA- II data structure will be output

Additional parameters when run in PHA mode:

   detnums [character string]

   Specifies the detectors for which binned data is produced. Individual detectors are specified by their detector numbers separated by commas. A range of detector numbers can be specified by giving the first and last detectors in the range separated by a "-". Omitting the lower limit of the range ("-n") results in the processing of all detectors from the first detector to "n". Similarly, omitting the upper limit ("n- ") results in the processing of all detectors starting from "n".

   For example, "-3,10-12,17-" would generate individual spectra for detectors 0,1,2,3,10,11,12,17,18 plus all pseudo detectors.

   The detector numbers should be input in order of increasing value, otherwise results are unpredictable. The bare hyphen option ("-") will process all individual detectors with non-zero "good time" intervals, and thus all multiplicites, represented in the input master detector list. It will also produce summed spectra over both pointings and detectors, regardless of the settings of the two flag parameters below.

   detsummed [boolean]

   Flag to indicate whether spectra should be summed over all detectors in each pointing. If set to yes, individual detector spectra will not be generated, only the sum over the pointing. If pntgsummed flag is also set to yes, only one spectrum is produced: the sum over all detectors in all the pointings.

   This flag is ignored if the "-" option is given for detnums, in which case all possible summations will be produced in addition to all the individual detector spectra.

   pntgsummed [boolean]

   Flag to indicate whether spectra should be summed over all pointings for each particular detector. If set to yes, individual detector spectra will not be generated, only the sum across pointings. If detsummed flag is also set to yes, only one spectrum is produced: the sum over all detectors in all the pointings.

   This flag is ignored if the "-" option is given for detnums, in which case all possible summations will be produced in addition to all the individual detector spectra.

   

   outfile [character string]

   Name of the output PHA-II format spectra file.

   

   

EXAMPLE

1. Create calibrated count spectra for an observation group previously updated with the SPIBOUNDS procedure. Select PSD events based on the raw flag.

>spihist in-og-dol=og_ibin_spi.fits[GROUPING] \ out-og-dol=spi_evts_det_grp.fits(GNRL-OBSG-GRP.tpl) \ det-spec-dol=spi_evts_det_spec.fits(SPI.-OBS.-DSP.tpl) \ psdtype=raw tstart=INDEF tstop=INDEF outputformat=ISDC dtype=1

2. Create same spectra, but for a subset of detectors in PHA-II mode.

>spihist in-og-dol=og_ibin_spi.fits[GROUPING] \ outfile=pha2.output.pha detnums="0-84" psdtype=raw \ tstart=INDEF tstop=INDEF outputformat=PHA dtype=1 detsummed=n \ pntgsummed=n

3. Same as above, but only produce the sum of the detectors for each pointing.

>spihist in-og-dol=og_ibin_spi.fits[GROUPING] \ outfile=pha2.output.pha detnums="0-84" psdtype=raw tstart=INDEF \ tstop=INDEF outputformat=PHA dtype=1 detsummed=y pntgsummed=n \

4. Same as above, but produce spectra for all detectors and all possible summations of spectra.

>spihist in-og-dol=og_ibin_spi.fits[GROUPING] \ outfile=pha2.output.pha detnums="-" psdtype=raw tstart=INDEF \ tstop=INDEF outputformat=PHA dtype=1 detsummed=n (or y) \ pntgsummed=n (or y)

PRIMARY AUTHORS: Craig Gordon NASA/GSFC Sandhia Bansal NASA/GSFC   Report problems to: isdc-help@obs.unige.ch

APPENDIX II: Output Files

 

There are two format options available for the FITS output files generated by SPIHIST: SPI OBS-data structures as defined by the SPI ICD and TYPE II PHA. The OBS data structures are defined in the SPI ICD. For a detailed description of the PHA-II data structure, refer to the GSFC SPI WWW site: <

 

1. SPI OBS Data Structure

SPIHIST produces two the two columns of the DETE_SPECTRA table (see the SPI ICD, Figure 11). Each row contains vectors representing respectively the detector spectra and the corresponding statistical uncertainty.

2. PHA TYPE II

 The Type II PHA file is readable by XSPEC. It contains a primary header and a number of extensions. The files for both summed and distinct pointings contain GROUPING, SPECTRUM, EBOUNDS, and POINTING extensions. The GROUPING extension is created by DAL and contains a listing of the other extensions in the file. In the SPECTRUM extension there are as many rows as the number of requested detectors. Each row contains a spectrum index number, a spectrum ID, the bin numbers, the counts/rates in each bin, the error for each bin, and a grouping number. In addition, an extension table is optionally added to the PHA-II file by the SPIARF utility, which contains information which can be used by XSPEC to map sources/models onto the appropriate response data.

Users Guide PDF file for download