Skip to main content

GRB Polarimetry Analysis

Version -V1 (September 25 2024)

KEYNOTES :

  • This analysis needs to be carried out on a machine with RAM, preferably more than 16 GB, so the codes (written in IDL and Python) do not crash due to memory constraints. 
    (Preferable systems: Any high computational machines/workstations/clusters)
  • After checking the viewing angle and MDP criteria mentioned in the next section for the GRB, the user can write to the POC for the data and simulation files required to perform polarisation analysis.
  • Download all the codes and the supporting files (section A and B) from this link.
  • Refer to Chattopadhyay 2022 for details of GRB polarisation analysis using AstroSat CZTI, based on this cookbook.
  • Prerequisites for python codes: Python 2.7, NumPy, AstroPy.

GRB Selection Criteria

Criteria to select GRBs for polarisation analysis:

  1. The viewing angle sholud be <60 degrees or >120 degrees. (Refer to CZTI GRB Page)
  Number of compton counts
Theta (<60/>120) 10% MDP 20% MDP 30% MDP 40% MDP
0/180 7094.08 1961.77 986.281 628.455
10/170 7650.32 2102.96 1051.36 667.034
20/160 7954.28 2180 1086.79 687.979
30/150 9797.34 2646.01 1300 813.3
40/140 13737 3638.01 1749.81 1074.75
50/130 19446.4 5070.99 2394.49 1445.37
60/120 46308.3 11795.1 5396.45 3149.55

EXAMPLE: GRB180427A

  • Theta <60 degrees
  • Compton counts: 1038 (~40% MDP)

Compton Counts plots with GRB Page in Background

  1. List of Codes (IDL and Python)
    • doubleEvent_DPH_badpixgen.py
    • bb_lc.py
    • comp_event_extract_t90.pro
      • grb_lc.pro
      • sing_event_extract.pro
    • azimuthal_dist.pro
      • comp_mc.pro
      • czti_sim_mass.pro
      • pix_sim_mass.pro
      • func_azim.pro
      • dph_compton.pro
      • spectrum_comp.pro
      • spectrum_single_veto.pro
    • cal_mu100_ang.pro
    • call_mcmc.pro
      • mcmc.pro
    • mpi_upper_limit.pro
      • upper_limit.pro
      • upper_limit_azim.pro
      • upper_limit_mcmc.pro
    • upper_limit_plot.py

  2. List of supporting files

    1. mod_center.txt
    2. ULD_module.txt
    3. LLD (folder - Inside the LLD folder, there are four files LLD_Q0.txt, LLD_Q1.txt, LLD_Q2.txt and LLD_Q3.txt corresponding to the four quadrants of the CZTI)
    4. lg_gainshift_v2.txt (gain shift value file)
    5. CALDB files

    Files in sections A and B can be downloaded here.  
     

  3. List of data files (GRB specific, contact POC) 
     
    1. *.dblevt file (for double events)
    2. *.evt file (for single event)
    3. *livetime.fits file
    4. The unpolarized simulation file - EventSimulGRBYYMMDD_mass.txt

    5. The polarised simulation folder - pol_sim_files (contains smulation of 100% polarised radiation for 19 angles [0-180])

       

  4. Setting up the codes and GRB data files 
      

     Step D1:

         Install IDL. Before running the codes, download the following required libraries and link them to the IDL.

         The tar file in the link below contains the set of IDL library files most commonly used in astronomy. Untar and put the files in the lib folder of IDL. For example in the folder: 
/home/user/Softwares/idl851_linux/idl85/lib

  1. MPFIT
  2. COYOTE
  3. ASTRON

     Step D2:

             Make a parent folder "GRB_Polarization_Analysis" and keep all the files mentioned under A and B in there.

Step D3:

            Inside the "GRB_Polarization_Analysis" folder, create the GRB folders (Convention to be used while creating GRB folders - GRBYYMMDD)

GRB directory

 

     Step D4:

          Inside the GRB folder, place the files mentioned in section C.

Step D5:

         Unzip the file in the GRB folder.

 

E. GRB Burst Interval 
 

      Step E1:

     To select the burst duration of the GRB of interest, use the Bayesian block analysis code:

           Code: bb_lc.py 

           Syntax: python bb_lc.py GRBYYMMDD trigger_time t90 

            Example: python bb_lc.py GRB180427A 262521423.0 22.0 
 

  • trigger (in AstroSat seconds)


*Note: To get the trigger time in AstroSat seconds use the  AstroSat time Convertor page

  1. sigma: to change the Bayesian binning (default value is 7)
  2. prebkg_start: start value of the pre-background from the burst start value (Default is -300.0)
  3. prebkg_stop: stop value of the pre-background from the burst start value (Default is -50.0)
  4. postbkg_start: start value of the post-background from the burst stop value (Default is 50.0)
  5. postbkg_stop: stop value of the post-background from the burst stop value (Default is 300.0)

OUTPUT FILES: 
Output Plot  

  1. BB_lc_time_intervals_v1.txt in the polarization analysis directory (Contains: GRBYYMMDD trigger_time, start_time, burst_duration)
  2. GRBYYMMDD_BB_lc_v4.pdf in the GRB directory (Bayesian light curve)
  3. GRBYYMMDD_BB_output_v4.txt in the GRB directory (Bayesian block time stamps, Tstart, Tstop, Tmean, prob_density)
  4. GRBYYMMDD_lc_livetime_bkg_sub_v4.pdf in the GRB directory (livetime corrected and background subtracted light curve)

 

F. Polarization Analysis Steps 
 

      Step F1:

           To create the individual badpix file after Compton noise correction

                Code: doubleEvent_DPH_badpixgen.py 

                Syntax: python doubleEvent_DPH_badpixgen.py --indir GRBYYMMDD --outdir GRBYYMMDD --doubleEventfile AS*dblevt --badpixfile AS*badpix.fits 

                Example: python doubleEvent_DPH_badpixgen.py GRB180427A --outdir GRB180427A --doubleEventfile AS*dblevt --badpixfile AS*badpix.fits 
 

                Argument details:

  1. indir: Path to the input directory (GRB folder)(Default is none)
  2. doubleEventfile: Name of the cleaned double event file (*quad_clean.dblevt)(Default is none)
  3. badpixfile: Name of the badpix file (*quad_badpix.fits)(Default is none)
  4. caldb_path: Path to the CALDB bcf folder (Default is current directory)
  5. caldb_badpixfilename: CALDB badpix file name (eg: AS1cztbadpix20160908v01.fits default: AS1cztbadpix20160908v01.fits, note: Try to use the latest CALDB files or the ones closer to the observation )
  6. outdir: Path to the output directory (Default is none, choose the GRBYYMMDD folder)
  7. sigma_good: Sigma for DPH flagging for good pixels in double events (Default is 4)
  8. sigma_banana: Sigma for the DPH flagging for banana pixels in the double events (Default is 3)

OUTPUT FILES: 

  1. badpixlist_Q0.txt
  2. badpixlist_Q1.txt
  3. badpixlist_Q2.txt
  4. badpixlist_Q3.txt

 

      Step F2:

           To extract the Compton and the non-Compton events in the GRB duration based on the Compton criteria for the dector

               Code: comp_event_extract_t90.pro 

               Syntax: comp_event_extract_t90,path 

              Example: comp_event_extract_t90,'./GRB180427A/'

              Argument Details:

  1. path: GRB path which contains the preliminary files (format is './GRBYYMMDD/')


 Steps to follow:

  • The light curve of the complete observation ID plotted, containing GRB. Use the cursor to select the zoom version of the burst region. Make sure to click well before and after the GRB so that pre and post background can be seen (note: select around 500 seconds before and after the burst region such that ample duration of the background is present for the selection analysis).
  • Pre-Background Duration Selection
    • Two windows will pop up successively. The IDL terminal asks the user to use the cursor to click in the current plot window to select the pre-background start and stop time sequentially (note: try to choose a stable background around 300 sec. Avoid the background too close to the burst's start time, keeping a difference in the background stop time and the burst's start time around 50 seconds. Do not select the SAA region).
  • GRB Duration Selection
    • The terminal will ask for the burst start time (in AstroSat Seconds example: 219745960.0d0):”, write it in “*********.****.d0” where d0 is for precision. The terminal will ask for “Burst Duration (e.g. 29.0d0):”, Provide the start time and burst duration from the output file achieved from the bb_lc.py(BB_lc_time_intervals_v1.txt)
  • Post Background Selection
    • Two windows will pop up successively. The IDL terminal asks the user to use the cursor to click in the current plot window to select the post background’s start and stop time sequentially (note: try to choose a stable background around 300 sec. Avoid the background too close to the burst start time, keeping a difference in the background start time and the burst’s stop time around 50 secs. Do not select the SAA region).
  • Ensure the output files mentioned below are there in the respective GRB folder

OUTPUT FILES: 
Single event and double event light curve, single event and double event files based on the polarization selection criteria.

  1. lc_grb_compton.png
  2. Tmp_GRB_ComptonEventFile.dat
  3. Tmp_GRB_NonComptonEventFile.dat
  4. EventFile_GRB.idl
  5. EventFile_GRB_Single.idl
  6. Tmp_GRB_SingleEventFile.dat
  7. lc_grb_single.ong

 

         Step F3:

                  To generate azimuthal distribution file and modulation curve (error from Chi-Square statistics)

                       Code: azimuthal_dist.pro 
                       Syntax: azimuthal_dist,lowEne,highEne,path 
                       Example: azimuthal_dist,100,600,'./GRB180427A/' 

                      Argument Details:

  1. path: Path to directory containing preliminary files (format is './GRBYYMMDD/')
  2. lowEne: Low energy in keV for the analysis (100<lowEne>highEne)
  3. highEne: High energy in keV for the analysis (highEne<600)

 azimuthal_dist plot

OUTPUT FILES: 
Simulation products, azimuthal distribution plots, azimuthal distribution files, GRB results-info file, spectrum plots, spectrum files

  1. module_cnt_comparison_lowEne_highEne.eps
  2. light_curve_compton_lowEne_highEne_thr_20.eps
  3. light_curve_compton_lowEne_highEne_thr_20.png
  4. light_curve_compton_bkg_lowEne_highEne_thr_20.eps
  5. info_160325_lowEne_highEne_thr_20_pre_postbkg.txt
  6. Raw_Aximuthal_Distribution_lowEne_highEne_thr_20.png
  7. Raw_Azimuthal_Distribution_160325_lowEne_highEne_thr_20_PulseAll.txt
  8. Raw_Azimuthal_Distribution_160325_lowEne_highEne_thr_20_only.txt
  9. hist_EventFileSimulGRB160325_mass.txt.ver2.dat_lowEne_highEne_thr_20.txt
  10. final_datapoints_160325_lowEne_highEne_thr_20_PulseAll.txt
  11. Corrected_Azimuthal_Distribution_lowEne_highEne_thr_20.png
  12. *pha file (1.6: Compton)

 

          Step F4:

             To generate a mu 100 file from the simulations containing the mu100 value corresponding to the simulated angle

                   Code: cal_mu100_ang.pro 
                   Syntax: cal_mu100_ang,low_Ene,highEne,path 
                   Example: cal_mu100_ang,100,600,'./GRB180427A/'  

                  Argument Details:

  1. path: Path to directory containing preliminary files (format is './GRBYYMMDD/')
  2. lowEne: Low energy in keV for the analysis (100<lowEne>highEne)
  3. highEne: High energy in keV for the analysis (highEne<600)

OUTPUT FILE:

  1. mu100_angle_lowEne_highEne_thr_20.txt

 

      Step F5:

             To generate the Bayes factor and the posterior distribution of the polarization patameter

                  Code: call_mcmc.pro 
                  Syntax: call_mcmc,path,/bayes_therm,lowEne,highEne,background,Trigger_time 
                  Example: call_mcmc,'./GRB180427A/',/bayes_therm,100,600,'prepost',262521423.0d0

     Argument Details:

  1. path: Path to directory containing preliminary files (format is './GRBYYMMDD/')
  2. lowEne: Low energy in keV for the analysis (100<lowEne>highEne)
  3. highEne: High energy in keV for the analysis (highEne<600)
  4. background: The background substracted modulation file you want to use ('pre'/'post'/'prepost'). The default should be 'preost', but if the GRB lies close to SAA you can use either 'pre' or 'post'.
  5. Trigger_time: Trigger time in AstroSat seconds (To get the trigger time in AstroSat seconds use the AstroSat time Convertor.)

OUTPUT FILES: 
mcmc.pro output plots

  1. par_iter_datapoints_160325_lowEne_highENe_thr_20_PulseAll.txt.eps
  2. par_prob_dist_datapoints_160325_lowEne_highEne_thr+20_PulseAll.txt.eps
  3. modulation_curve_datapoints_160325_lowEne_highEne_thr_20_PulseAll.txt.eps
  4. contour_pol_datapoints_160325_lowEne_highEne_thr_20_PulseAll.txt.png
  5. parameters_plot_datapoints_160325_lowEne_highEne_thr_20_PulseAll.txt.eps
  6. fitted_par_lowEne_highEne.txt
(Note: If the codes compile but don't run, recompile and run again)

*Note:

  1. Follow the steps below to calculate the upper limit on the polarization fraction of a GRB (if the Bayes factor obtained in step F5 is less than 3)
  2. This code works on parallel processing of the IDL script (Statistics: 10 hours using 20 CPUs)
 

       Step F6:

                  Run the command on the terminal: mpirun -npncpu idl mpi_upper_limit.pro

Argument Details:

  1. ncpu: The number of CPUs the user is providing for the code (Varies for the individual system, to check the number of CPUs for your system, use the lscpu command in the terminal.) This is used to run the code in parallel processing, it takes ~10 hours for 20 CPUs
  2. mpi_upper_limit.pro: Open the code and change the following argument as shown in the exapmle below
upper_limit,lowEne,highEne,path,Compton counts

Example: upper_limit,100,600,'./GRB180427A/',1207						
 

OUTPUT FILES: 
Dist_Bayes_factor_YYMMDD_lowEne_highEne_thr_20_*.txt, ncpu number of files will be generated. 
3. From this output file, the upper limit can be calculated following the below mentioned steps:

  • Combine these files into a single file -  
     Dist_Bayes_factor_YYMMDD_lowEne_highEne_thr_20.txt
    • Command: cat Dist*txtDist_Bayes_factor_YYMMDD_lowEne_highEne_thr_20.txt>
  • Run the python code: upper_limit_plot.py 
Syntax: pyrhon upper_limit_plot.py GRBYYMMDD --emax highEne --emin lowEnE

Example: python upper_limit_plot.py GRB160325 --emax 600 --emin 100


OUTPUT FILES:
GRBYYMMDD_lowEne_highEne_uppper_limit.png

(Polarization upper limts for 2 and 3 sigma confidences are printed inside the plot.)
 

For any query Contact:

  1. Payload Operation Center/ POC (cztipoc@iucaa.in) (To request simulation, please get in touch with POC)