How to analyse GRB SPI data

How to derive images of short bursts, such as GRB, from SPI data

In the explanation below, we assume that readers have some knowledge about SPI data analysis with the ISDC spi_science_analysis script. Please follow the cookbook example first if it is not your case.

1. The first step is to record the start (grb_start) and stop (grb_stop) times of the period you want to use to derive the image, and possibly the time before (sec_to_avoid_before_grb) and after (sec_to_avoid_after_grb) the burst that should not be included in the period used to derive the background. Times can be in UTC or IJD. The best way to look at the timing is to display the burst light curve, for example from IOSM. Of course, you can repeat the analysis in as many time bins as you wish, e.g., to derive a set of images and a SPI lightcurve. Below is an illustration of the required times on top of a real GRB lightcurve.

2. Set up your analysis environment as indicated in the "Setting up the analysis environment" section of the SPI data analysis cookbook.
3. Identify the pointing encompassing the burst, and use og_create to build an observation group (only analysis of single pointing are possible in this frame).

4. Move to the observation group location (cd obs/grb030501_osa50 in our example).
5. Two alternatives can be used to specify the parameters of your analysis

•   Run "spi_science_analysis" and specify parameters through the GUI.

• If you do not want to use the GUI, you can specify the above parameters by editing the spi_science_analysis.par file located in your $PFILES directory. Check at least the following parameters:

detectors,s,ql,"0-18",,,"List of (pseudo) detectors to be used in the analysis (0-141)"
spiros_source-cat-dol,s,ql,,,,"Enter DOL for source catalogue:"
coordinates,s,ql,"RADEC",RADEC|GALACTIC,,"Coordinate system (RADEC or GALACTIC)"

spibounds_nregions,i,ql,1,1,,Number of regions:
spibounds_regions,s,ql,"20,400",,,"Region bounds [keV]:"
spibounds_nbins,s,ql,"1",,,"Number of bins in regions:"

spiros_mode,s,ql,"IMAGING",IMAGING|SPECTRA|TIMING|DIFFUSE,,"Select processing mode:"
spiros_energy-subset,s,hl,,,,"Enter subset of energy bins [a-b,c-d,f,g.....]:"
spiros_pointing-subset,s,ql,,,,"Enter subset of pointing bins [a-b,c-d,f,g.....]:"
spiros_detector-subset,s,ql,,,,"Enter subset of detector bins [a-b,c-d,f,g.....]:"
spiros_background-method,i,ql,1,0|1|2|3|4|5|6|7,,Enter background handling method [0=ZERO
spiros_srclocbins,s,ql,"FIRST",,,"Enter count spectrum bins used for source location [Blank,SUM,FIRST,ALL]:"
spiros_image-proj,s,ql,"CAR",CAR|TAN|AIT,,"Enter output image projection type [CAR,TAN,AIT]:"
spiros_image-fov,s,ql,"POINTING+ZCFOV",,,"Enter extent and location of output image:"
spiros_image-orient,s,hl,"STANDARD",USER|STANDARD,,"Enter output image orientation [USER,STANDARD]:"
spiros_nofsources,i,ql,3,0,,Enter maximum number of sources to be searched for [0
spiros_sigmathres,r,hl,6,0.0,,Enter lower sigma threshold to stop source search:
spiros_iteration-output,s,hl,"NO",YES|NO,,"Enter whether output should be produced at each iteration [YES/NO]:"
spiros_optistat,s,hl,"CHI2",CHI2|LIKEH,,"Enter optimization statistic [CHI2,LIKEH]:"
spiros_solution-constr,s,hl,"NONE",NONE|POSITIVE,,"Enter image solution constraints [NONE,POSITIVE]:"

6. The spi_science_analysis.par file located in your $PFILES directory now contains the main parameters you want to use in your burst analysis. This file will be used in the next steps. Therefore, you have to make sure that no one else (or no other processes) can modify this file between the time you made the specifications and the time you run the following task. Modify the PFILES variable to point to a private location if you encounter any problems.
7. Run spi_grb_analysis. Without any command line argument you get the following help text.

You know the input parameters from the first point above, so you can then launch the spi_grb_analysis script. Make sure the "grb_start" - "sec_to_avoid_before_grb" is not before the pointing start, and that "grb_stop" + "sec_to_avoid_after_grb" is not after the pointing end, as there is no corresponding checks in the spi_grb_analysis script.

In our example:  spi_grb_analysis 2003-05-01T03:10:10.000 2003-05-01T03:10:30.000 UTC 10 10.  You can re-run in the same directory spi_grb_analysis as many times as you wish, changing the parameters as explain in above section 5. However, when making a new run, the outputs of the previous run will be deleted. If you want to keep your outputs before making a new run save them by copying the entire directory (e.g., cd ..; cp -r grb030501_osa50 grb030501_OSA50_imaging; cd grb030501_osa50) before continuing.

8. "spi_grb_analysis" is calling a number of executables and "spi_science_analysis" several times. Since "spi_science_analysis" produces its own log file, the log file situation after running "spi_grb_analysis" is somewhat complicated. The resulting "spi_grb_analysis.log" is the high level log file, containing logs from the executables called directly by "spi_grb_analysis". In addition, you can find three spi_sa_<<date>>.log. The first contains the outputs of spi_obs_point, the second includes the logs from the bining to background steps, and the third contains the results from spiros.
9. After a successful execution of "spi_grb-analysis", it is also possible to run spiros again with the "spi_science_analysis" script. Launch "spi_science_analysis", make sure you select only the spiros step (if you select any other step, the burst background produced by "spi_grb_analysis" will be deleted and you will have to start it all again), change the required spiros parameters (making a LIKEH analysis rather than a Chi2 one for example), and run the show again.
10. Please consult the cookbook for information about the analysis results (and for more information about the analysis parameters).