How to analyse GRB SPI data

How to derive spectra of short burst, 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.

If you have already followed "how to derive images of short bursts from SPI data", you can start directly below point 5.

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.

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. The burst position at which you want to extract a spectrum must now be specified. This is done by providing a "source_cat.fits" file containing the GRB position. You can either use an existing file, or create a new one using the spi_science_analysis to run the catalogue extraction step, as follow

Select "catalogue extraction" and (make sure all other tasks are unselected) click on "catalog" enter the catalogue task parameters. Click "Ok" to close the "catalogue" window, and on "Run" in the main frame to execute spi_science_analysis. The catalogue produced, "source_cat.fits", will contain irrelevant data. It will probably includes a number of catalogue sources that may be detected on longer observation, and certainly not the GRB position at which we want to extract a spectrum. The catalogue file should include a single row with the GRB identification and position. Edit this file with "fv" and enter the correct identification and position, deleting extra rows if any, and save the result.  The position from the SPI image analysis can be used, although in most cases a more accurate position should be available from IBIS or other sources.

If you  use an existing "source_cat.fits" file make sure with fv that it contains the correct identification and position of the GRB and that the ISDCLEVL keyword of this file is CAT_I.

7. Two alternatives can be used to specify the parameters of your analysis

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

Specify the "List of detectors" in that window, deselect "catalogue extraction", enter the name of your file in the "SPIROS Input Catalog" entry field, and click on "energy_definition" to open the following window.

Select your energy bins (in this case 6 bins ranging from 20 to 200 keV, logarithmically spaced as the bin number is negative), click "Ok". This will close this window. Back in the parent window click "spiros" to open the following window.



Select the spiros mode "SPECTRA", specify the "Background method" and the "Optimization statistic". Background method "1" means that the background derived from the periods before and after the burst, and rescaled to the burst duration will be subtracted from the burst data as a fixed background. With background method "3" the background will be scaled through the image deconvolution process, solving for a single background scaling coefficient. Do not use other options. For the "Optimization statistic", Chi2 is recommended, while LIKEH can be tried in a second run.

Close this sub-window by clicking "Ok" and click "Save" and "Quit" (YES, we only use the GUI to enter parameters and we do not want to start the analysis yet) in the main GUI window. FOR OSA5.1 USERS: THE "SAVE" BUTTON OF THE MAIN GUI NO LONGER EXIST.  A SOLUTION IS TO UN-SELECT ALL TASKS IN THE MAIN GUI AND "RUN" THE SCRIPT. IT WILL DO SOME CHECKINGS AND EXIT RELATIVELY QUICKLY SAVING ALL LEARNED PARAMETERS IN THE PAR FILE (EXACTLY WHAT WAS DOING THE "SAVE" BUTTON IN OSA5.0). ALTERNATIVELY THE PARAMETER FILE CAN BE EDITED AS EXPLAIN BELOW.

• 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)"
coordinates,s,ql,"RADEC",RADEC|GALACTIC,,"Coordinate system (RADEC or GALACTIC)"

spiros_source-cat-dol,s,ql,"source_cat.fits",,,"Enter DOL for source catalogue:"

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:"q

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]:"

8. 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.
9. 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 7. 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_spectrum; cd grb030501_osa50) before continuing.

9. After a successful run of "spi_grb_analysis" (step 7) you obtain a spectrum of the burst,  called spectrum_<<your GRB ID>>.fits, containing a link to the appropriate RMF response. You can directly enter XSPEC to display and fit your resulting spectrum (see here for more information).
   
10. "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. However, if you have run an GRB image analysis before, you will find more logfiles. Look then at the three youngest.
11. 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.
12. Please consult the cookbook for information about the analysis results (and for more information about the analysis parameters).