XISRMFGEN (Aug 2018) suzaku.xis XISRMFGEN (Aug 2018) NAME xisrmfgen -- create the XIS energy Redistribution Matrix File (RMF) USAGE xisrmfgen phafile outfile See `description' for the other usage DESCRIPTION 'xisrmfgen' creates an XIS RMF file fit for a Suzaku pha file or any parameters affecting the instrumental response such as the XIS units, CCD clock modes, observation date, and so on. 'xisrmfgen' calculates a line profile of monochromatic X-rays at each energy bins with energy between the event threshold up to the energy with x0.01 of the probability at the event threshold energy. The information required to calculate the RMF (XIS unit, CCD clock mode, telemetry edit mode, charge injection mode, and observation date) are obtained in a different way, depending on how the parameter 'phafile' is set. If 'phafile' is set to an existing input spectrum or image file, the XIS instrument unit, CCD clock mode, telemetry edit mode, window option, and change injection mode are obtained from the keywords INSTRUME, CLK_MODE, EDITMODE, WINOPT, and CI, respectively. The observation date is calculated from the TSTART and TSTOP keywords as (TSTART + TSTOP)/2. Note that 'xisrmfgen' also requires in the calculation a weighted map in DET coordinates. Therefore the primary header of the spectral file should contain a WMAP in DET coordinates and the image file also should be constructed in the same DET coordinates. If 'phafile' is set to NONE, the information required by xisrmfgen to generate the RMF is prompt via the following parameters 'instrume', 'clk_mode', 'editmode', 'winopt', 'ci', and 'date_obs'. Note these parameters are ignored (not asked) when a file is input. The WMAP in this case is assumed uniform on the whole CCD. The energy bin of the RMF by default are set with a constant width of 2 eV within the energy range 0.2-16 keV (see parameter ebin_mode=0). The width and the energy range can be changed using the parameters 'ebin_width', 'ebin_lowermost,and 'ebin_uppermost' for a constant binning. If the parameter 'ebin_mode' is set to 1, energy bin width may not be constant. In this case the lower and high energy boundaries for each bin are read from an ARF or RMF input loaded from the ebinfile option. There are so called 'Si-K edge problem' around the Si-K edge (1.839 keV), namely, there remains systematic residuals in spectral fits around the edge. An attempt to solve this problem was introduced in 2012 partly in the updates in the XIS quantum efficiency files ae_xi[0-3]_quanteff_20120428.fits for all the XIS sensors. Only for the BI sensor (XIS1), additional updates were introduced into xisrmfgen version 2012-04-21. The implementation consists of the followings - Equalize the energy resolutions of main and sub-components - Introduce a discontinuous change of ratio among components and they are activated when the parameter 'bi_si_edge_mode' is set to 1. Although these modifications are implemented only for BI, the parameter 'fi_si_edge_mode' was also added for possible future use. However, a different implementation to solve the Si-K edge problem for both the BI and the FI sensors was introduced into xisrmfgen version 2018-08-07. In this implemenation, a jump in the energy and the pulse height relation is allowed at the Si K edge (See Okazaki, Hayashida et al., Proc SPIE 10709, 107091F (2018). The jump is specified with two parameters for each sensor, xi{0,1,2,3}_jmp_loene and xi{0,1,2,3}_jmp_hiene. In addition, a parameter jnct_hiene is used to specify the energy above which the original energy pulse height relation is employed. All these parameters are hidden and their default values are calibrated with bi_si_edge_mode=0 and fi_si_edge_mode=0. Note that the implementation of bi_si_edge_mode=1 is incompatible with that with the jump. The quantum efficiency files ae_xi[0-3]_quanteff_20120428.fits are not compatible, either. We recommend general users to use default set of parameters for the countermeasures to the Si K edge problem, i.e., bi_si_edge_mode, fi_si_edge_mode, xi{0,1,2,3}_jmp_loene, xi{0,1,2,3}_jmp_hiene, and jnct_hiene. To reproduce the response without either of the two implementations for the Si-K edge problem, set bi_si_edge_mode=0, xi{0,1,2,3}_jmp_loene=0, and xi{0,1,2,3}_jmp_hiene=0. The quantum efficiency files ae_xi[0-3]_quanteff_20180807.fits or later should be used. PARAMETERS phafile [filename] Name of the input file. The input file can be a spectrum or image file. If set to 'NONE' the task calculates the response based on the input parameters: 'instrume', 'clk_mode', 'editmode', 'winopt', 'ci', and 'date_obs'. outfile [filename] Name of output RMF. (rebin = 1) [integer] Rebinning factor. The default is set to 1. For higher rebinning use even values (2,4,8...). (clobber = yes) [boolean] Overwrite output file if exists. (telescop=SUZAKU) [string] Telescope name. This should be set always to SUZAKU. Used when phafile='NONE'. instrume [string] XIS unit name (XIS0 , XIS1, XIS2, XIS3). This parameter is required when phafile='NONE'. date_obs [string] Date and time of the observation. The format can be Suzaku TIME (time in seconds from the mission start) or UTC 'yyyy-mm-ddThh:mm:ss.sss'. This parameter is required when phafile='NONE'. clk_mode [string] CCD clock mode (normal, burst or psum). This parameter is required when phafile='NONE'. editmode [string] Edit mode of telemetry (5x5, 3x3, 2x2 or timing) This parameter is required when phafile='NONE'. winopt [integer] Window option (0:off, 1:1/4, 2:1/8, 3:1/16). This parameter is required when phafile='NONE'. ci [integer] Charge injection mode (0:no CI, 1:diagnostic CI, 2:SCI 54 rows, 3:SCI 108 rows). This parameter is required when phafile='NONE'. (enable_scirmf = yes) [boolean] Enable SCI RMF generation. (edge_treatment = 1) [integer] How to treat atomic edges (0:ignore, 1:shift ebin). (bi_si_edge_mode = 0) [integer] Switch to use or not to use Si edge RMF parameters for BI introduced in 2012-04-21 (0:not to use,1:use). Note that implementation with the energy pulse height relation jump (xi{0,1,2,3}_jmp_loene, xi{0,1,2,3}_jmp_hiene, and jnct_hiene) is not compatible with bi_si_edge_mode = 1. (fi_si_edge_mode = 0) [integer] How to use Si edge RMF parameters for FI (reserved for future use). (xi0_jmp_loene = 0.2) [real] Amount of the jump in the energy pulse height relation of XIS0 sensor at the low energy side of the Si-K edge (1.839 keV) in the unit of pulse height channel. (xi0_jmp_hiene = 4.5) [real] Amount of the jump in the energy pulse height relation of XIS0 sensor at the high energy side of the Si-K edge (1.839 keV) in the unit of pulse height channel. (xi1_jmp_loene = -2.0) [real] Amount of the jump in the energy pulse height relation of XIS1 sensor at the low energy side of the Si-K edge (1.839 keV) in the unit of pulse height channel. The default value is calibrated in the case with bi_si_edge_mode = 1. (xi1_jmp_hiene = -4.7) [real] Amount of the jump in the energy pulse height relation of XIS1 sensor at the high energy side of the Si-K edge (1.839 keV) in the unit of pulse height channel. The default value is calibrated in the case with bi_si_edge_mode = 1. (xi2_jmp_loene = 0.2) [real] Amount of the jump in the energy pulse height relation of XIS2 sensor at the low energy side of the Si-K edge (1.839 keV) in the unit of pulse height channel. (xi2_jmp_hiene = 4.5) [real] Amount of the jump in the energy pulse height relation of XIS2 sensor at the high energy side of the Si-K edge (1.839 keV) in the unit of pulse height channel. (xi3_jmp_loene = 0.1) [real] Amount of the jump in the energy pulse height relation of XIS3 sensor at the low energy side of the Si-K edge (1.839 keV) in the unit of pulse height channel. (xi3_jmp_hiene = 4.4) [real] Amount of the jump in the energy pulse height relation of XIS3 sensor at the high energy side of the Si-K edge (1.839 keV) in the unit of pulse height channel. (jnct_hiene = 5.9) [real] The energy pulse height relation above the Si-K edge should converge to the original one at this energy (keV). Common values for all the sensors. (ebin_mode = 0) [integer] Mode for the energy bin. When ebin_mode = 0 (default) the energy bin width is set to constant within the energy range, specified in 'ebin_lowermost' and 'ebin_uppermost'. The bin width can be changed from the 'ebin_width' parameter. When ebin_mode = 1, the energy ranges described in the response file and bin width are read from a file load from the 'ebinfile' option. (ebin_lowermost = 0.20) [real] Lowermost energy bin in keV, required when ebin_mode=0. (ebin_uppermost = 16.0) [real] Uppermost energy bin in keV, required when ebin_mode=0. (ebin_width = 2.0) [real] Constant energy bin width in eV, required when ebin_mode=0. ebinfile [file name] Input an ARF or RMF file, from which the format of the response table (i.e. ENERG_LO and ENERG_HI columns) is read. This parameter is required when ebin_mode=1. (leapfile = CALDB;$ENV{LHEA_DATA}/leapsec.fits) [filename] Name of the leap second file. The default set-up searches the latest leapfile in CALDB or in the LHEA_DATA directory (environment variable created when the software is initialized). (quantefffile = CALDB) [filename] Name of the quantum efficiency calibration file. If set to CALDB (default) an appropriate file is automatically selected from the calibration database. The root name of the calibration file is 'ae_xisN_quanteff_YYYYMMDD.fits', where N is the XIS unit and YYYYMMDD is the release date. (rmfparamfile = CALDB) [filename] Name of the spectral response calibration file. If set to CALDB (default) an appropriate file is automatically selected from the calibration database. The root name of the calibration files is 'ae_xisN_rmfparam_YYYYMMDD.fits', where N is the XIS unit and YYYYMMDD is the release date. (makepifile = CALDB) [filename] Name of the gain and split threshold calibration file. If set to CALDB (default) an appropriate file is automatically selected from the calibration database. The root name of the calibration files is 'ae_xisN_makepi_YYYYMMDD.fits', where N is the XIS unit and YYYYMMDD is the release date. (anl_verbose = 1) [integer] ANL verbose level (-1:full, 0:minimum). (anl_profile = yes) [boolean] Enable ANL module profiling. (num_event = -1) [integer] number of frames (-1:all, 0:exit). (event_freq = 1000) [integer] Frame number printout frequency. (chatter = 2) [integer] message chatter level (0:min, 2:norm, 5:max). EXAMPLES 1. Create a response file (src_xis1.rmf), corresponding to the input spectrum file `src_xis1.pi'. All the calibration parameters are read from CALDB. % xisrmfgen phafile=src_xis1.pi outfile=xis1.rmf 2. Create a response file (src_xis1.rmf), corresponding to the input detector image file `src_xis1.img'. The energy bins are read from the input ARF file `ae_xi1_xisnom6_20060615.arf'. % xisrmfgen phafile=src_xis1.img outfile=xis1.rmf ebin_mode=1 \ ebinfile=ae_xi1_xisnom6_20060615.arf 3. Create a response file (src_xis1.rmf) from instrumental or observing parameters specified. % xisrmfgen phafile=none outfile=xis1.rmf instrume=XIS1 \ date_obs=2006-04-20T12:00:00 \ clk_mode=normal editmode=5x5 winopt=0 ci=0 BUGS 'xisrmfgen' generates the same RMF files for the burst mode as those for the normal mode since we found no remarkable difference in response between the burst mode and the normal mode. Detailed quantitative studies of the response in the burst mode is underway. 'xisrmfgen' also generates the same RMF file for a window option as for data with the identical observing and instrumental parameters but without the window option. However, please note that the gain and resolution of the window option can be slightly different from those without that option. 'xisrmfgen' generates the same RMF files for the 2x2 mode data as those for the 5x5/3x3 mode data since we found no remarkable difference in response between the 2x2 mode data and the 5x5/3x3 mode data. SEE ALSO Yamaguchi, H. et al., Proc.of The X-ray Universe 2005, Madrid, Spain, 26-30 Sep. 2005 Nakajima, H. et al. 2005, NIM A, 541, p.365-371 Nakajima, H. et al. 2004, Proc. of SPIE, 2004, 5488, p.124-135 LaMarr, B. et al. 2004, Proc. of SPIE, 2004, 5501, p.385-391 Okazaki, K. et al. 2018, Proc of SPIE, 2018, 10709, 107091F AUTHOR This program was developed by Hiroshi Nakajima, Hiroya Yamaguchi (Kyoto Univ), Ryohei Kaida (Miyazaki Univ), Y.ISHISAKI (TMU), K. Okazaki, K. Hayashida (Osaka Univ.) and the XIS team. LAST MODIFIED Aug 2018