ixpepolarization help file

NAME

ixpepolarization -- Calculates overall Stokes parameters for a user-defined region on a set of up to three input level2 event files.

USAGE

ixpepolarization.py infile1 infile2 infile3 regfile outfile t_lo t_up pi_lo pi_up modfact1 modfact2 modfact3 weight_scheme color clobber

DESCRIPTION

ixpepolarization computes the overall Stokes parameters Q and U for a sky region defined by the user (e.g., using the display program ds9) using the selected weighting scheme over a user-defined time interval and a user-defined PI energy range for up to three input level2 event files. The program outputs a display region file to indicate the polarization position angle on the sky computed from the Q and U. If the region file contains sub-regions, then polarization degrees and angles will be computed for each sub-region. Additionally, the program outputs a FITS file that contains a separate HDU for each input file, each containing rows for each sub-region with the Q, U, Q std error, U std error, Number of events, Minimum detectable polarization (MDP99), polarization degree, polarization angle, and the computed modulation factor.

The tool requires at least one input IXPE event FITS file (infile1), and up to two additional IXPE event FITS files (infile2, infile3), and user-defined time interval (t_lo, t_up), energy bounds (pi_lo, pi_up), Stokes parameter weighting scheme (weight_scheme), and output file name base for the output FITS polarization data and region files. In addition, the user has to option to define the modulation factor files corresponding to each input file (modfact1, modfact2, modfact3), the output region line color (color), and an input region file (regfile) defining the area of the sky used to select events for processing. The default is to compute the Stokes parameters from all events in the file.

It is highly recommended that a region file be provided to ixpepolarization. The output region file includes the original defined region(s) and an additional line region for each, which indicate the magnitude and orientation of the polarization vector.

PARAMETERS

infile1* (str): Input Level2 FITS EVENTS file.
infile2 (str): Optional second input Level2 FITS EVENTS file.
infile3 (str): Optional third input Level2 FITS EVENTS file.
outfile (str): Output base name for both the region and fits output files with optional extension (.reg or .fits) and optional path (default: "ixpepolarization_out"). See "Examples" section for more details.
regfile (str): Path to ASCII region definition file. (default: -, which is no region file)
t_lo (str): ISOT date/time of lower time bound. (default: -, which is t_lo = TSTART)
t_up (str): ISOT date/time of upper time bound. (default: -, which is t_up = TSTOP)
pi_lo (str): Lower PI bound for event filtering. (default: -, which is pi_lo = TLMIN = 0)
pi_up (str): Upper PI bound for event filtering. (default: -, which is pi_up = TLMAX = 374)
modfact1 (str): Modulation factor CALDB file used to process infile1. (default: -, meaning file is looked up in CALDB from DU, filter, and weighting scheme)
modfact2 (str): Modulation factor CALDB file used to process infile2. (default: -, meaning file is looked up in CALDB from DU, filter, and weighting scheme)
modfact3 (str): Modulation factor CALDB file used to process infile3. (default: -, meaning file is looked up in CALDB from DU, filter, and weighting scheme)
weight_scheme (str): Weighting scheme for polarization calculation, may be "unweighted" (or "u"), "simple" (or "s"), or "neff" (or "n"). (default: "neff")
color (str): Polarization vector display color. (default: green)
clobber (Boolean): Flag to overwrite existing output fits and region files. (default: no)

EXAMPLES

Outfile examples

ixpepolarization.py infile1=ixpe01000201_det1_evt2_v02.fits.gz regfile=input_region.reg outfile=- will yield an output FITS file named "ixpepolarization_out.fits" and an output region file named "region_ixpepolarization_out.reg"
ixpepolarization.py infile1=ixpe01000201_det1_evt2_v02.fits.gz regfile=input_region.reg outfile=sub_dir/output_file will yield an output FITS file named "sub_dir/output_file.fits" and an output region file named "sub_dir/region_output_file.reg"
ixpepolarization.py infile1=ixpe01000201_det1_evt2_v02.fits.gz regfile=input_region.reg outfile=rout.reg will yield an output FITS file named "rout.fits" and an output region file named "region_rout.reg"
ixpepolarization.py infile1=ixpe01000201_det1_evt2_v02.fits.gz regfile=input_region.reg outfile=fout.fits will yield an output FITS file named "fout.fits" and an output region file named "region_fout.reg"

BUGS

LAST MODIFIED

Aug 2025