NAME

ixpecalcarf -- Constructs an on-axis ARF or MRF from component files that correctly accounts for off-axis vignetting and source extraction radius.

USAGE

ixpecalcarf.py evtfile attfile [ox] [oy] [offarcmin] [vignfile] [reeffile] [radius] [uvfilt] [grfilt] [detfilter] [axeffa] [modfact] [qefile] [specfile] [arfin] [resptype] [weight] [arfout] [clobber]

DESCRIPTION

ixpecalcarf reads the components to construct the instrument response to on-axis x-rays and applies corrections for vignetting due to dithering and encircled energy due to the extraction radius. The module reads the GTI information from a Level 2 event file evtfile and off-axis angle pointing information from either the TXYDZ column of a corresponding Level 1 attitude file attfile with an optional offsets of the optical axis from the center of the TXYDZ array (ox and oy or, optionally, for a fixed off-axis angle offarcmin. From this, it creates a one-dimensional histogram of off-axis angles, which it normalizes into a weighted distribution of off-axis angle. This distribution is used with the information from the mirror vignetting file vignfile (averaged over azimuthal angle and interpolated over off-axis angle and energy) to create a weighted vignetting correction vs. energy array. Similarly, the same information is used with the radial encircled-energy function file reeffile to create a reef correction vs. energy array, if an extraction radius radius other than zero is used.

The on-axis response function is created by combining CALDB data from the transmission of the detector UV filter (uvfilt), the transmission of the optional GRAY filter (grfilt and selected by detfilter), the detector modulation factor if calculating polarization response (modfact), the detector quantum efficiency (qefile), and the mirror axial effective area (axeffa). This on-axis response function is then multiplied with the vignetting vs. energy and reef vs. energy arrays to create an output response function that accounts for the time spent off-axis and the size of the extraction region. This file is written to the output response file, and if present, the ANCRFILE value of the specfile is updated to the name of this new response file.

The type of output response file is determined from the inputs in the following order of precedence (highest to lowest): the file type of the ANCRFILE entry from specfile, the file type of arfin (see NOTE below), resptype, or the file type of arfout. Next, the name of the input response file is determined from the inputs in the following order of precedence (highest to lowest): The file name from the ANCRFILE entry of specfile; the given input arf input file name arfin (see NOTE below); or the file name looked up in the caldb.indx using quzcif given the DETNAM value from evtfile, weight, detfilter and response file type derived from the previous step. Finally, the output filename is determined from the inputs in the following order of precedence (highest to lowest): arfout, with the extension overridden by the extension of arfin (see NOTE below), if necessary; the base name of specfile with the appropriate response file type extension, or the base name of evtfile with the appropriate response file type extension.

PARAMETERS

evtfile* (str)
Input FITS Level 2 Event file. Used to determine the GTI to be applied to attfile.

attfile (str)
Input FITS Level 1 attitude file. Used to determine the distribution of off-axis pointing angle. Not used if offarcmin >= 0, but required if offarcmin < 0 (none or path name, default: none)

ox (float)
X-axis offset in pixels of optical axis from the origin of the attitude TXYDZ column (default: 0).

oy (float)
Y-axis offset in pixels of optical axis from the origin of the attitude TXYDZ column (default: 0).

offarcmin (float)
Fixed off-axis observing angle in arc minutes. If >= 0, overrides attfile. (< 0 to disable: default = -1.0, indicating disabled.)

radius (float)
Radius of circular extraction region in arc minutes. 0 indicates no aperture correction is to be applied. (default: 0)

detfilter (int)
Detector filter (0 = Open, 1 = Gray, default: 0)

specfile (str)
Input FITS spectrum model file with a valid "ANCRFILE" value. If not none, will override resptype and arfin (none or path name, default: none)

arfin (str)
Input on-axis ancillary response CALDB file name, for backward compatibility only (see NOTE below). If used, overrides uvfilt, resptype, and weight (none, caldb, or path name, default: none, indicating not used)

resptype (str)
Response function type (arf or mrf, default: arf).

arfout (str)
File name of output file, which is the ancillary response file of type resptype

weight (int)
For "mrf" files, the weighting scheme used for calculating Stokes parameters. (default: 1)
0 = unweighted, 1 = N-effective (neff), 2 = simple

clobber (Boolean)
Overwrite existing output file? (default: no)

** The remaining parameters are path names. Most users will want to leave them as the default value "caldb".

vignfile (str)
Path to the off-axis mirror vignetting CALDB file (default: caldb, indicating lookup from CALDB)

reeffile (str)
Path to the mirror radial encircled-energy CALDB file (default: caldb, indicating lookup from CALDB)

uvfilt (str)
Path to the detector UV filter CALDB file ({none, caldb, or full path name} default: caldb, indicating lookup from CALDB)

grfilt (str)
Path to the detector gray filter CALDB file ({none, caldb, or full path name} default: caldb, indicating lookup from CALDB)

modfact (str)
Path to the detector modulation factor CALDB file ({none, caldb, or full path name} default: caldb, indicating lookup from CALDB)

qefile (str)
Path to the detector quantum efficiency CALDB file ({none, caldb, or full path name} default: caldb, indicating lookup from CALDB)

axeffa (str)
Path to the mirror axial effective area CALDB file ({none, caldb, or full path name} default: caldb, indicating lookup from CALDB)

NOTE

Support for "arfin" files is for backward compatibility only. Production of new on-axis arf files has ceased. Users are therefore encouraged to use the component files that make up the on-axis response which will continue to be updated through the remainder of the mission.

EXAMPLES

Case 1: Make an MRF (for Q and U spectra) with a constant off-axis angle and spectral extraction aperture

ixpecalcarf evtfile=ixpe02001001_det1_evt2_v02.fits offarcmin=1.5 radius=1.0 specfile=none resptype=mrf clobber=yes

Here ixpecalcarf recognized rseptype=mrf and saved the output MRF file as ixpe02001001_det1_evt2_v02.mrf.

Case 2: Make an ARF and save the out to a designated filename with a .arf extension.

ixpecalcarf evtfile=ixpe02001001_det1_evt2_v02.fits offarcmin=2.5 radius=2.0 specfile=none arfout=ixpe02001001_det1.arf clobber=yes

Between Case 1 and Case 2, ixpecalarf would attempt to make a file of the type specified by the arfout argument if it's parsed. Otherwise, it requires a resptype argument to tell it to either make an ARF (for I spectra), or an MRF (for Q and U spectra)

Case 3: Making an ARF for an existing spectra -- warning, header keyword will be updated!

ixpecalcarf evtfile=event_l2/ixpe01004601_det1_evt2_v05.fits attfile=hk/ixpe01004601_det1_att_v02.fits.gz specfile=ixpe01004601_src_DU1_pha1.fits clobber=yes radius=1.0

In this case, a new file ixpe01004601_src_DU1_pha1.arf was made and placed in the same folder as the spectrum file, and is associated to the original spectrum file by updating the ANCRFILE keyword in it.

BUGS

SEE ALSO

LAST MODIFIED

Feb 2024