Remember always to set SWITCH_disablePICsIT="NO", since the PICsIT analysis in OSA is disabled by default
(SWITCH_disablePICsIT="YES").
on 10/12/2007 for the OSA7 release.
CAVEATS (or what PICsIT and OSA can and cannot do):
We assume we are using rev_2 data. After the og_create step (use always only pointing ScW to create an observation group), it is necessary to run the ibis_science_analysis script. The selection of the parameters are function of what the user wants to do. Most (if not all) the parameters shown here are already implemented in OSA as default. Nevertheless, for demo purposes, it is useful to analyze them explicitly.
Remember always to set SWITCH_disablePICsIT="NO", since the PICsIT analysis in OSA is disabled by default
(SWITCH_disablePICsIT="YES").
Here are hints for some cases of data analysis:
Image Analysis:
As previously stated, the background is one of the most important problems in the PICsIT data analysis. One step in OSA deals with the background subtraction, by using background maps. OSA provides some maps already prepared in a set of default energy bands.
The basic command to run OSA for PICsIT to obtain images per ScW is:
ibis_science_analysis ogDOL="./og_ibis.fits[1]" startLevel="BIN_I" endLevel="IMA2" OBS1_ScwType="ANY" CAT_refCat="$ISDC_REF_CAT" SWITCH_disablePICsIT="NO" SWITCH_disableIsgri="YES" IBIS_IPS_ChanNum=0 SCW1_BKG_P_method=1 PICSIT_inCorVar=0 PICSIT_outVarian=0 SCW1_BKG_picsSUnifDOL="-" SCW1_BKG_picsMUnifDOL="-"
It is important to set the endLevel="IMA2" (while for ISGRI you set simply endLevel="IMA"), otherwise there will not be the image deconvolution.
The parameter IBIS_IPS_ChanNum=0 is to select the number of energy bands: if set equal to 0, this means that the default energy bands (8 for single events plus 8 for multiple events) are selected (it this parameter is set to -1 the executable read the energy band of the default RMF). For these default bands, OSA provides background maps. If the user wants to change the energy bands, then he/she should also prepare by him/herself the corresponding maps. For example, the above command extended to use the energy bands parameters becames:
ibis_science_analysis ogDOL="./og_ibis.fits[1]" startLevel="BIN_I" endLevel="IMA2" OBS1_ScwType="ANY" CAT_refCat="$ISDC_REF_CAT" SWITCH_disablePICsIT="NO" SWITCH_disableIsgri="YES" IBIS_IPS_ChanNum=8 IBIS_IPS_E_band_min_s="203 252 336 448 672 1036 1848 3584" IBIS_IPS_E_band_max_s="252 336 448 672 1036 1848 3584 6720" IBIS_IPS_E_band_min_m="336 448 672 1036 1848 3584 6720 9072" IBIS_IPS_E_band_max_m="448 672 1036 1848 3584 6720 9072 13440" IBIS_P_convFact=7.1 SCW1_BKG_P_method=1 PICSIT_inCorVar=0 PICSIT_outVarian=0 SCW1_BKG_picsSUnifDOL="-" SCW1_BKG_picsMUnifDOL="-"
The parameter SCW1_BKG_P_method=1 is to select the method of background subtraction. Indeed, the background maps are shadowgrams accumulated over a long time (up to 1.7 Ms) and should be compared with a typical shadowgram integrated over a ScW (2 ks). The two shadowgrams must be renormalized before the subtraction. Two methods are available: by means of the exposures (SCW1_BKG_P_method=0) or the mean counts value averaged over the whole detector (SCW1_BKG_P_method=1). The latter is sometimes better, although meaningful differences are observed seldom.
The PICsIT detector has also some instrinsic non-uniformities and proper maps are needed to correct this effect. These maps are not yet available and therefore the corresponding parameters should be set to read nothing. (SCW1_BKG_picsSUnifDOL="-" SCW1_BKG_picsMUnifDOL="-"). However, it is worth noting that since background maps are built from real data, these contains some correction for detector non-uniformities too.
Another important set of parameters is represented by PICSIT_inCorVar and PICSIT_outVarian. The first is to select what type of variance shadowgrams should be read as input in the sky image deconvolution. The parameter set to 0 means that the shadowgrams to be read are obtained from the count shadowgram of the observation (in the case of photon counting statistics, the equation counts=σ2 holds for each pixel, under nominal conditions), without any correction. If the parameter is set to 1, then a corrected variance shadowgram is read. The correction is performed during the background subtraction and it consists (mainly) in adding the variance of the background maps to the variance of the observation shadowgram. The selection of this parameter has impact in interpreting the significance map in output: if set to 0 (no correction), than the significance image can be interpreted in the usual way for a coded-mask instrument. If set to 1 (correction), than the significance is already corrected for the background subtraction (this is the best option).
The second parameter (PICSIT_outVarian) is to have in output the variance map. Indeed, the output of the deconvolution, stored in the file picsit_ima.fits in every ScW, is composed of three maps for each energy band: INTENSITY, VARIANCE, SIGNIFICANCE. With PICSIT_outVarian=1 the variance map is present, otherwise (PICSIT_outVarian=0), this map is suppressed and the output is composed of INTENSITY and SIGNIFICANCE maps only. All these information can be read with fv in the GROUPING extension of any picsit_ima.fits file.
Mosaic:
As known, INTEGRAL performs dithering patterns around the target and therefore the integration of ScW can be done only after the deconvolution, on the sky images (i.e. with WCS coordinates). To make mosaics from PICsIT sky images there are several ways. First, it is possible to have mosaics in output directly from the OSA pipeline, but in this case it is necessary to modify the command given in the previous section as:
ibis_science_analysis ogDOL="./og_ibis.fits[1]" startLevel="BIN_I" endLevel="CLEAN" GENERAL_levelList="BIN_I,BKG_I,CAT_I,IMA,IMA2,CLEAN" OBS1_ScwType="ANY" CAT_refCat="$ISDC_REF_CAT" SWITCH_disablePICsIT="NO" SWITCH_disableIsgri="YES" IBIS_IPS_ChanNum=0 SCW1_BKG_P_method=1 PICSIT_inCorVar=0 PICSIT_outVarian=0 SCW1_BKG_picsSUnifDOL="-" SCW1_BKG_picsMUnifDOL="-"
This is because the executable ip_skymosaic has been put at the CLEAN level in the OSA pipeline. It is possible to make some selection on the maps to be integrated with the parameter OBS2_imgSel and OBS2_projSel. The first has default OBS2_imgSel="EVT_TYPE=='SINGLE' && E_MIN==252 && E_MAX==336", meaning that the mosaic is obtained by integrating the single events maps with energy bands 252-336 keV. The second parameter is to select the sky projection: -TAN, ARC, or STG. Please use the stereographic projection: in OSA7, it will be the default value, also for the single pointing image.
Another option is to run the OSA pipeline up to IMA2 level and then to run separately the ip_skymosaic command:
ip_skymosaic inOG="" idxScw="" outOG="./og_ibis.fits[1]" outMosaic="./pics_mosa_ima2.fits(PICS-MOSA-IMA-IDX.tpl)" outPicsitCat="./pics_mosa_res2.fits(PICS-MOSA-RES-IDX.tpl)" inCat="./isgri_catalog.fits[1]" detThr=3.0 imgSel="EVT_TYPE=='SINGLE' && E_MIN==252 && E_MAX==336" projSel="STG"
If you want to run different times the ip_skymosaic executable, than it is necessary to change the name of the output files or to delete the old ones before every run.
Still another way is to use the varmosaic tool of HEASoft. In this case, you should have run OSA up to IMA2 level with PICSIT_outVarian=1. Then, generate the list of files with the command:
ls scw/*/picsit_ima.fits > list
Check that the sky images files are all of the same type: indeed, there can be empty files (no data) or with single events only or with multiple events only. Since varmosaic tool has not been built specifically for PICsIT, the user must make these checks manually and build a homogeneous list of files. After this selection, it is possible to run the tool:
varmosaic list name_output_file.fits
Despite these limitations, this tool is really powerful and the user is encouraged to use it.
In the case of staring observations, it is possible to integrate the shadowgrams before the deconvolution. To do this in OSA for PICsIT, it is necessary to set the parameters: staring=yes, tolerance=0.1 [degrees] and stop at IMA2 level. That is:
ibis_science_analysis ogDOL="./og_ibis.fits[1]" startLevel="BIN_I" endLevel="IMA2" OBS1_ScwType="ANY" CAT_refCat="$ISDC_REF_CAT" SWITCH_disablePICsIT="NO" SWITCH_disableIsgri="YES" IBIS_IPS_ChanNum=0 SCW1_BKG_P_method=1 PICSIT_inCorVar=0 PICSIT_outVarian=0 SCW1_BKG_picsSUnifDOL="-" SCW1_BKG_picsMUnifDOL="-" staring=yes tolerance=0.1
WARNING: there is a bug in the pipeline scripts of OSA7: the files with shadowgrams passed to the executable ip_skyimage are not those with the integrated shadowgrams, but those of the first ScW. Therefore, the staring option is not working in OSA7.
The outputs are stored in the main directory.
Spectral extraction:
Although the spectral extraction with the PIF method is present in OSA, it is an experimental executable and it is better for the user to perform the spectral extraction from the images. This is also because the RMF/ARF available in OSA are optimized for count spectra extracted from deconvolved images. In addition, the RMF in OSA are already rebinned for the default energy bands of the imaging pipeline. Please note that you can select IBIS_IPS_ChanNum=-1 to force the binning step to select the energy bands of the default RMF.
A useful script by M. Chernyakova is available at ISDC. Otherwise, the user can perform manually this operation by extracting the rates from the brightest pixel in the INTENSITY maps and the error can be estimated by the corresponding pixel in the SIGNIFICANCE maps.
Timing Analysis (GRB, Pulsars):
An individual ScW is generally 2000 s long and in such a short time, PICsIT can detect only sources with high fluxes, like GRB. There can be some detections in the imaging pipeline, but these are generally fake detections due to local high background or artifacts (indeed, these are almost always in the zones close to the border of the detector). Spectral timing data can be used to build lightcurves which contain the whole detector counts integrated over a short time (of the order of ms) at expenses of spatial information. The lightcurve can be obtained by running the following command:
ibis_science_analysis ogDOL="./og_ibis.fits[1]" startLevel="DEAD" endLevel="LCR" OBS1_ScwType="ANY" CAT_refCat="$ISDC_REF_CAT" SWITCH_disablePICsIT="NO" SWITCH_disableIsgri="YES" GENERAL_levelList="DEAD,LCR"
The startLevel="DEAD" is to re-run the deadtime level; you can also start directly from LCR level (startLevel="LCR"), since the deadtime is already calculated in rev_2 data. The parameter GENERAL_levelList="DEAD,LCR" is to perform only the two levels DEAD and LCR, bypassing everything is in between. If you start directly from LCR level, you can avoid setting this parameter.
If you are studying a GRB, you can now check the file picsit_lcr.fits in the ScW directory. It contains a few extensions (use the FTOOL fv to look at the extensions of a FITS file), one for every energy band. You can use the standard HEASARC xronos tools to study the lightcurves. For example, to study the lightcurve of the first extension (first energy band):
scw/004100010010.001> lcurve
lcurve 1.0 (xronos5.21)
Number of time series for this task[1]
Ser. 1 filename +options (or @file of filenames +options)[file1] picsit_lcr.fits[2]
Series 1 file 1:picsit_lcr.fits[2]
Selected FITS extensions: 2 - RATE TABLE;
| Source ............ | Start Time (d) .... 12683 04:55:46.660 |
| FITS Extension .... 2 - `PICS-EVTS-` | Stop Time (d) ..... 12683 06:40:35.664 |
| No. of Rows ....... 5879465 | Bin Time (s) ...... 0.9766E-03 |
| Right Ascension ... | Internal time sys.. Converted to TJD |
| Declination ....... | Experiment ........ INTEGRAL IBIS |
Selected Columns: 1- Time; 5- Y-axis; 6- Y-error; 7- Fractional exposure;
File contains binned data.
...and so on.
If you want to fold the lightcurves over a known period (pulsar studies), you need to perform the barycentric correction before the folding. This can be done by using the OSA tool barycent with this command (example from Crab data):
barycent inDOL='picsit_lcr.fits[2]' inCOL=TIME outDOL='lcr.fits[2]' outCOL=TIME auxDOL='/path_to/scw/0041/004100010010.001/swg.fits[1]' raOBJ=83.6292 decOBJ=22.013140
Please note that the tool overwrite the TIME column with the corrected times and therefore, it is better to duplicate the picsit_lcr.fits file into, e.g. lcr.fits, and then run barycent tool. It works on one individual ScW and one single energy band, so that it should be run for every energy band and for every Scw lightcurve. After the correction, it is possible to fold all the ScW lightcurves with efold (xronos tool).
CAVEAT: Sometimes, the time in xronos is not correctly displayed. However, the TIME column of the picsit_lcr.fits is correct. In case of doubts, please refer to the latter.
WARNING 1: For unknown reasons, there was a bit of confusion in the response matrices in OSA7 release. The matrices for multiple events are indeed for spectral timing data, while rmf/arf for multiple events are missing. For the sake of simplicity, you can download them here:
WARNING 2: For unknown reasons, the spectral timing channels are inverted in the preprocessing phase. This means that the first channel is the last and viceversa. This bug will be corrected in the future versions of OSA.
.
Use of rev_1 and/or near-real time data.
Some particular attention is necessary when dealing with rev_1 and/or near-real time (NRT) data. The basic reason is due to the need for PICsIT to integrate on board the data before the download. This implies that when PICsIT is collecting data from a pointing, the integrated data of the previous pointing ScW (not slews!, where PICsIT is switched to photon-by-photon mode) is simultaneously downloaded to the ground.
During the ground preprocessing phase, the histogram found in a certain pointing generally belongs to the previous one and there is need to restore the original time sequence. To this aim, the preprocessing needs to analyze simultaneously several ScW. To save time, the near-real time preprocessing considers 3 ScW (with sequence pointing-slew-pointing), while the consolidated preprocessing, that has no time requirements, considers 5-6 ScW. If, for any reason, the sequence pointing-slew-pointing does not hold, the preprocessing can miss some histogram. These data are not lost and are restored in the consolidated processing. However, this means that NRT can seriously limit the availability of PICsIT data (the other instruments are not affected, since these are all operated in photon-by-photon mode). Therefore, it is strongly suggested to work mainly on the consolidated data and, when NRT data are analyzed, it is always better to run again OSA on the consolidated data when these are available.
Another issue to be taken into account when analyzing NRT data is that these have the same structure of rev_1 data, with certain differences with respect to rev_2 data. Specifically, for PICsIT it is necessary to start from the COR level, instead of BIN_I level as in rev_2 data, to allow OSA to calculate Good-Time-Intervals (GTI) and other stuff. All the other parameters are the same of rev_2 data. Just for example, this means that the command to obtain images per ScW should be changed as follows:
ibis_science_analysis ogDOL="./og_ibis.fits[1]" startLevel="COR" endLevel="IMA2" OBS1_ScwType="ANY" CAT_refCat="$ISDC_REF_CAT" SWITCH_disablePICsIT="NO" SWITCH_disableIsgri="YES" IBIS_IPS_ChanNum=0 SCW1_BKG_P_method=1 PICSIT_inCorVar=0 PICSIT_outVarian=0 SCW1_BKG_picsSUnifDOL="-" SCW1_BKG_picsMUnifDOL="-"
Go to PICsIT Home Page
