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 :

• This Analysis can be carried out using GDL (version 1.0.1 and above) or IDL (version 7.1.1 and above). Please note that the time to carry out analysis in GDL is ~2-3 times more than on IDL. (Preferable systems: Any high computational machines/workstations/clusters)
• Any new GRB detection by CZTI along with other details (viewing angle, light curves, number of Compton events) are regularly updated in the CZTI GRB Page.
• 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 polarization analysis.
• Download all the codes and the supporting files (section A and B) from this link.
• Refer to Chattopadhyay 2022 for details of GRB polarization analysis methodology using AstroSat CZTI.
• Prerequisites for python codes: Python 3.7, NumPy, AstroPy.
• If you use CZTI polarization data/pipelines in your work, please cite the papers listed below at relevant points in your manuscript, and add acknowledgement in the appropriate place.


1. AstroSat: Singh el al, 2014
2. CZTI: Bhalerao et al, 2017
3. CZTI Polarization analysis: Chattopadhyay et al, 2022

Acknowledgement:

This work used data from the Cadmium Zinc Telluride Imager on board AstroSat, provided by the Indian Space Science Data Centre (ISSDC) of the Indian Space Research Organisation (ISRO). We thank the CZTI Payload Operations Center and the AstroSat Science Support Cell for providing the supplementary data and tools for analysis.

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

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

 

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

 

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

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

 

3. 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])

 

4. 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**)

 

 

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.

 

 

5. GRB Burst Interval

(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

• trigger_time (in AstroSat seconds from CZTI GRB Page)

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: 

 

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)

 

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

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:

• A plot of the light curve of the complete observation containing the GRB will appear. 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/GDL 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 (a gap of 50s is advisable). Do not select the high background region close to the SAA region, if the GRB happened to be close to the SAA).

 

 

• 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 created from the bb_lc.py(BB_lc_time_intervals_v1.txt)

• Post Background Selection
• Two windows will pop up successively. The IDL/GDL 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 end time, (a gap of 50s is advisable). Do not select the SAA region).

 

• Ensure the output files mentioned below are generated inside 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.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)

 

 

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:

 

 

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:

• Combine these files into a single file - Dist_Bayes_factor_YYMMDD_lowEne_highEne_thr_20.txt
  • Command: cat Dist*.txt > Dist_Bayes_factor_YYMMDD_lowEne_highEne_thr_20.txt
• Run the python code: upper_limit_plot.py

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)