Version -V1 (January 30 2025)

For any query Contact:

  1. Payload Operation Center/ POC (cztipoc@iucaa.in) (To request for GRB data and simulation files, users are instructed to contact the CZTI Payload Operation Centre/POC)

KEYNOTES :

GRB Data Availability

Data files for the 20 GRBs mentioned in Table 1 of Chattopadhyay 2022 are readily available and can be provided by POC, if contacted. For polarization analysis of any new GRB (check CZTI GRB Page), users need to submit a one-page proposal to the POC.

GRB Selection Criteria

Criteria to select GRBs for polarization analysis:

  1. The viewing angle should be <60 degrees from the CZTI Normal or >120 degrees. (Refer to CZTI GRB Page for the viewing angles of the GRB.)
  2. Required number of Compton events for 40% MDP (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

img_1
Compton Counts plot with GRB Page in Background

 

  1. List of Codes (IDL/GDL and Python)
    • doubleEvent_DPH_badpixgen.py
    • bb_lc.py
    • comp_event_extract_t90.pro
      • grb_lc.pro
      • sing_event_extract.pro
    • pix_sim_mass.pro
    • czti_sim_mass.pro
    • azimuthal_dist.pro
      • comp_mc.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

 

  1. 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.txt (gain shift value file)
    5. CALDB file

    Files in sections A and B can be downloaded from here.

 

  1. List of data files (GRB specific, contact POC for files)
    1. *.dblevt file (for double events)
    2. *.evt file (for single event)
    3. *livetime.fits file
    4. *badpix.fits file
    5. The unpolarized simulation file - EventFileSimulGRBYYMMDD_mass.txt
    6. The polarized simulation folder - pol_sim_files (contains simulation of 100% polarized radiation for 19 angles [0-180])

 

  1. Setting up the codes and GRB data files

 

STEP D1: 

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

The tar file in the link below contains the set of IDL/GDL library files most commonly used in astronomy. Untar and put the files in the lib folder of IDL/GDL.

For example in the folder: /home/user/Softwares/idl851_linux/idl85/lib

Link for IDL/GDL libraries:

  1. MPFIT
  2. COYOTE
  3. ASTRON

 

STEP D2: 

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

 

STEP D3: 

Inside the "GRB_Polarization_Analysis" folder, create the GRB folders. Example: GRBYYMMDD (**always use this naming convention**)

 

img_2
GRB Polarization Analysis Codes

 

STEP D4: 

Move the files mentioned in section C and the pol_sim_files folder to the GRB folder. The pol_sim_files folder contains simulation files for the 100% polarized radiation.

 

STEP D5: 

Unzip the files from section C in the GRB folder.

 

img_3
Files in GRB folder

 

  1. GRB Burst Interval
  2. (This code should be run in the polarization analysis directory where the pipeline codes are downloaded. The output of the code will be generated inside the GRB directory.)

 

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 GRB180427 262521423.0 22.0

Argument details:

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

Note: Try to select at least 100 sec background before and after the burst. Select the background at least 30 seconds away from the the burst.

OUTPUT FILES: 

img_4
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)

 

  1. Polarization Analysis Steps

(All the codes should be run at the polarization analysis directory where the pipeline codes are downloaded. The output of all the codes will be stored in the GRB directory.)

 

STEP F1: 

To create the 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 GRB180427 --outdir GRB180427 --doubleEventfile AS1A04_026T04_9000002060_13947cztM0_level2_quad_clean.dblevt --badpixfile AS1A04_026T04_9000002060_13947cztM0_level2_quad_badpix.fits

Argument details:

  1. indir: Path to the input directory (GRB folder)(Default: none)
  2. doubleEventfile: Name of the cleaned double event file (*quad_clean.dblevt)(Default: none)
  3. badpixfile: Name of the badpix file (*quad_badpix.fits)(Default: 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: none, choose the GRBYYMMDD folder)
  7. sigma_good: Sigma for DPH flagging for good pixels in double events (Default: 4)
  8. sigma_banana: Sigma for the DPH flagging for low gain pixels in the double events (Default: 3)

OUTPUT FILES:

  1. badpixlist_Q0.txt
  2. badpixlist_Q1.txt
  3. badpixlist_Q2.txt
  4. badpixlist_Q3.txt
  5. Note: Before running any IDL/GDL code, compile them using the command on the IDL/GDL terminal by:

    syntax: .com code_name

    Example: .com comp_event_extract_t90.pro

 

STEP F2:

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

Code: comp_event_extract_t90.pro

Syntax: comp_event_extract_t90,path

Example: comp_event_extract_t90,'./GRB180427/'

Argument Details:

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

Steps to follow:

img_5
Selecting GRB region

 

 

img_6
Pre Background Duration Selection

 

img_7
GRB Duration Selection
img_8
Post Background Duration Selection

 

img_9
Compton and Non Compton Events LC

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.png

Note: Keep the low energy and high energy values same for the whole analysis hereafter. 

 

STEP F3: 

Simulation data processing

Code: pix_sim_mass.pro

Syntax: pix_sim_mass,path

Example: pix_sim_mass,'./GRB180427/'

Argument Details:

  1. path: Path to directory containing preliminary files (format is './GRBYYMMDD/')

OUTPUT FILES:

  1. EventFileSimulGRBYYMMDD_mass.txt.ver2.dat

 

STEP F4: 

Code: czti_sim_mass.pro

Syntax: czti_sim_mass,threshold,lowEne,highEne,path

Example: czti_sim_mass,20,100,600,'./GRB180427/'

Argument Details:

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

 

OUTPUT FILES:

  1. hist_EventFileSimulGRBYYMMDD_mass.txt.ver2.dat_lowEne_highEne_thr_threshold.txt
  2. Angle_dist_EventFileSimulGRBYYMMDD_mass.txt.ver2.dat_lowEne_highEne_thr_threshold.txt
  3. EventFileSimulGRBYYMMDD_mass.txt.ver2.dat_spectra_lowEne_highEne_thr_threshold.txt
  4. EventFileSimulGRBYYMMDD_mass.txt.ver2.dat_spectra_lowEne_highEne_thr_threshold.eps
  5. EventFileSimulGRBYYMMDD_mass.txt.ver2.dat_angle_lowEne_highEne_thr_threshold.txt

 

STEP F5: 

To generate azimuthal distribution file and modulation curve (the uncertainties are computed using chi-square statistics)

Code: azimuthal_dist.pro

Syntax: azimuthal_dist,lowEne,highEne,path

Example: azimuthal_dist,100,600,'./GRB180427/'

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)

 

img_10
Azimuthal_Dist Code Output

 

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_YYMMDD_lowEne_highEne_thr_20_pre_postbkg.txt
  6. Raw_Aximuthal_Distribution_lowEne_highEne_thr_20.png
  7. Raw_Azimuthal_Distribution_YYMMDD_lowEne_highEne_thr_20_PulseAll.txt
  8. Raw_Azimuthal_Distribution_YYMMDD_lowEne_highEne_thr_20_only.txt
  9. hist_EventFileSimulGRBYYMMDD_mass.txt.ver2.dat_lowEne_highEne_thr_20.txt
  10. final_datapoints_YYMMDD_lowEne_highEne_thr_20_PulseAll.txt
  11. Corrected_Azimuthal_Distribution_lowEne_highEne_thr_20.png
  12. *pha file (1_6: Compton)

 

STEP F6: 

To generate a mu100 file from the simulations containing an array of mu100 values and detector co-ordinate polarization angles.

Code: cal_mu100_ang.pro

Syntax: cal_mu100_ang,low_Ene, highEne, path

Example: cal_mu100_ang,100,600,'./GRB180427/'

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

(new files will be generated in the "pol_sim_files" folder - *.txt.ver2.dat ... 19 such files and *hist*.txt.ver2.dat ... 19 such files)

 

STEP F7: 

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

Code: call_mcmc.pro

Syntax: call_mcmc,path,/bayes_therm,lowEne,highEne,background,Trigger_time

Example: call_mcmc,'./GRB180427/',/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 subtracted modulation file you want to use ('pre'/'post'/'prepost'). The default should be 'prepost', but if the GRB lies close to SAA you can use either 'pre' or 'post'.
  5. Trigger_time: trigger_time in AstroSat seconds from CZTI GRB Page

OUTPUT FILES:

 

img_11
mcmc.pro Plots

 

  1. par_iter_datapoints_YYMMDD_lowEne_highEne_thr_20_PulseAll.txt.eps
  2. par_prob_dist_datapoints_YYMMDD_lowEne_highEne_thr_20_PulseAll.txt.eps
  3. modulation_curve_datapoints_YYMMDD_lowEne_highEne_thr_20_PulseAll.txt.eps
  4. contour_pol_datapoints_YYMMDD_lowEne_highEne_thr_20_PulseAll.txt.png
  5. parameters_plot_datapoints_YYMMDD_lowEne_highEne_thr_20_PulseAll.txt.eps
  6. fitted_par_lowEne_highEne.txt (The final PD, PA, error bars, BF can be found in this text document)

(Note: If the codes compile but don't run, recompile and run again)

According to Chattopadhyay 2022, if Bayes factor >3.2, the burst is polarized else unpolarized. Hence for the unpolarized burst one can calculate the upper limit on PF by following step F8.

*Note: 

  1. This code works on parallel processing of the IDL script (Statistics: 10 hours using 20 CPUs) 
  2. A User can ask POC for the upper limit calculation, if the users do not have access to IDL or high performing machines.

 

STEP F8: 

Run the command on the terminal: mpirun -np ncpu 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 example below

upper_limit,lowEne,highEne,path,Compton counts

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

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. Compton counts: The number of compton counts in the burst region (one can get from the ‘Info_YYMMDD_lowEne_highEne_thr_20_pre_postbkg.txt’ file in the GRB directory)

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:

Syntax: python upper_limit_plot.py GRBYYMMDD --emax highEne --emin lowEne 

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

OUTPUT FILES:

  1. GRBYYMMDD_lowEne_highEne_uppper_limit.png
  2. Upper_limit_param.txt (PF upper limits for different confidence levels)