Appendix

Tips and tricks for running spiros

This is an updated version of the notes which I provided in 2002 and which were extended by Volker Beckmann and incorporated in his web page http://heasarc.gsfc.nasa.gov/docs/integral/spi/pages/spiros_tricks.html

G.K. Skinner Oct 2003 / V. Beckmann April 2004

Here we give some advice, how to use SPIROS more efficient. For more detailed information please read the SPIROS user manual

· The normal value of the background-method for SPIROS is 2.

Use anything else with caution.

With method 2, the background model(s) specified at the SPIBACK stage are taken to show how components of the background vary with time. A separate scaling factor for each (pseudo-)detector and each energy bin is adjusted to give the best fit to the data.

Method 2 can only work if there is more than one pointing per background component (>1 for a constant background; >2 for constant + linear ...). Normally there will be 7 or more pointings of a dither pattern, so there will not be a problem. With less pointings there will be more unknowns than observations.

Method 3 can be use in case this condition is not met. In this case a single scaling factor (per background component, per energy bin) for all the detectors is found. It is assumed that the relative intensities of the components between detectors is given in the model (these relative values are defaulted to 1, which is not realistic).

Method 4 is like Method 3 except that a different multiplier is fitted for each ‘group’ of pseudo detectors (single 0-18, doubles 19-60, triples 61-84).

Method 5 is the Mean Count Modulation (MCM) method. This will cause SPIROS to ignore any background models from SPIBACK and calculate spectra and images using count fluctuations about each mean pointing value. It effectively includes the mean pointing residues in the background.

The most useful output image to look at first is the ‘Sigma’ one.

The one called something like image_sigma_1.fits is before any sources are fitted ; later ones by default have fitted sources replaced by a peak which is neither a delta function nor the width of the PSF but between the two.

Intensity maps tend to show large positive and negative values towards the edge of the field of view where the uncertainties are high and are more quantitative, but more difficult to interpret.

Do not trust ANY results where the chi-squared is much greater than the number of degrees of freedom.

Just what 'much greater than' means is a bit difficult to say. In principle it should be dof +/- dof^0.5. This is rearely achieved with real SPI data except in narrow energy bands or in very short times. If chisqd > 10 dof, something is very wrong; a factor of two may just mean that the background model is not perfect.

If the chi-squared is high, an indication of why can often be found by looking at the tables in the log file showing how the total is broken down by detector and pointing (in the case of spectral mode, by energy bin as well). A single bad data point corrupting the data can easily be picked up in this way; background trends or a bad detector should also be apparent. The gory detail (the residue for each detector/pointing/energy bin) is available in the SPI.-MAXL-RES file, normally called something like spiros_ml_residues.fits

SPIROS will be slow if all the pseudo detectors are used and very slow if the maximum likelihood option is adopted. (You can guess what happens if you ask for both of these together).

For an initial run to find all but the weakest sources use: Detectors 0-18, optistat = CHI2, and a single energy band (probably this will be one predominantly at lowish energies). If SPIHIST has been run with multiple energy bins, a single band for analysis can be specified with srclocbins=1, srclocbins=SUM, srclocbins=FIRST or something like srclocbins="20-50keV", as appropriate.

You need to be aware of the behaviour when the STAT_ERR associated with a bin in the spihist output file is zero. SPIHIST will not use such bins in the analysis in the normal case where the chi-squared parameter is used. The STAT_ERR = 0 situation will arise if the corresponding count is zero because spihist puts STAT_ERR equal to the square root of the count. To get a file which is runnable on such data, there is a fudge:

fcalc infile=evts_det_spec.fits outfile=evts_det_spec_1.fits clname=STAT_ERR expr="MAX(SQRT(COUNTS),1)"
mv evts_det_spec_1.fits evts_det_spec.fits

This places 1 in those positions where the STAT_ERR would be zero. This can overestimate the uncertainties, lead to a spuriously good chi-squared and lead to some loss of sensitivity, but normally it works remarkably well.

The maximum likelihood option (optistat=LIKEH) is appropriate where there is a significant number of bins where the count rate is so low that this occurs by chance. The above rule about ignoring data with STAT_ERR=0 does not apply if this choice is made. The analysis is currently slower and more prone to difficulties than the chi-squared one.

There is an option srclocbins=ALL which will do an IROS imaging analysis in each energy bin in turn. There is then an attempt to decide what sources are there and to fit sources at those positions. I would recommend against using this mode. It is slow and the algorithm for identifying sources that are common to the separate analyses and for finding their mean position doesn't always work. Also the source positions are not reoptimised in the final analysis.

At present the source position uncertainties seem to be underestimated. This is to some extent to be expected where they turn out to be very small, because systematic errors are inevitable. But the problem seems to be more general.

Sources found by SPIROS can be outside the field of view requested by the user. This happens only rarely. It arises if in the mapping stage the highest point was right at the border and the subsequent fitting leads to finding an optimum with the source displaced to a point beyond the limits of the map

SPIROS 6.0 (or higher) offers the possibility to reject data automatically. By setting the parameter pointing-subset="AUTO-sigma" where "sigma" is the upper sigma exclusion threshold in the ML/CHI2 residues. You can also add it after any pointings you want to exclude for some other reason. Just "AUTO" will only take out any pointings with extreme values after reading in the observation count data and nothing later. It is important to know that SPIROS is not trying to reject data to get the ML/CHI2 parameter to some nice value, but assumes the residues to be Gaussian distributed and will stop rejecting data if the current ML/CHI2 residues have a RMS deviation below 1.0

SPIROS 9.2.d offers the possibility to include data with and without dead detectors By setting the parameter detector_subset="AUTO" SPIROS recognizes the three cases (19 detectors alive, detector #2 dead, detectors #2 and #17 dead). This functionality works in MCM mode. It works also together with a manual selection, like detector_subset="0-18,AUTO"

If one allows SPIROS to choose the region to be mapped (by using image-fov="POINTING" or ="POINTING-FCFOV" or = "POINTING-ZCFOV", then the algorithm used is fairly basic. It works fine for a reasonable compact group of pointing in a general part of the sky but it can give unexpected results, where there is a big spread of pointing directions or near to one of the poles.

Very often you might only want to re-run the SPIROS step (e.g. to exclude some pointings using the pointings-subset parameter). You can do the cleaning using the script, but it is usually faster to do it manually:
rm spi/spiros*
rm spi/source_res.fits
Then open the observation group, e.g.
fv og_spi.fits
Open the Table. Delete the lines which correspond to the files you created in the previous spiros run; usually these are the lines 14-17 (when you apply PSD tools) or 11-14 (without PSD tools).
Open the header. Change the ISDCLEVL keyword to "RSP_I". Do not forget to confirm with "Enter" and to "Save" the fits file!
If you think you re-run this step more often, make now a copy of og_spi.fits (e.g. cp og_spi.fits og_spi.clean) then you can just re-use this group after the next SPIROS processing.
start again with:
spi_science_analysis startLevel="IMA" endLevel="IMA"