XISSIMARFGEN (Mar 2008) suzaku.xis XISSIMARFGEN (Mar 2008) NAME xissimarfgen -- Calculate Suzaku XIS ARF using XRT ray-tracing simulator USAGE xissimarfgen instrume=name pointing=value \ source_mode=J2000 source_ra=value source_dec=value \ region_mode=value num_region=1 regfile1=value arffile1=filename \ limit_mode=NUM_PHOTON num_photon=value \ phafile=filename detmask=filename gtifile=filename attitude=filename \ rmffile=filename estepfile=filename See description for the other usages. DESCRIPTION 'xissimarfgen' generates the Ancillary Response Files (ARFs) of the Suzaku XIS detectors through Monte-Carlo simulations for many combination of user-input, such as arbitrary X-ray emitting region and event extracting region. Its core-tool 'xissim' simulates detected photon events in each energy band, and then calculates the detection efficiency for each selected source region. 'xissimarfgen' can simulate incoming X-ray photons and event extracting regions in both the SKY (X,Y) and DETECTOR (DETX, DETY) coordinates. Different coordinate systems can be used for the source emitting region and event extracting region. Users can simulate the incoming X-ray photons from celestial sources including their morphology and their positions using the option "source_mode" and its additional options. 'xissimarfgen' can simulate ARFs for a point source, by setting the "source_mode" to J2000, SKYXY or DETXY, or for a circularly extended source centered at the optical axis (source_mode=UNIFORM). Alternatively if "source_mode" is set to SKYFITS or DETFITS, a FITS image may be input. CAVEATS: The ARF is normalized to the flux from the whole emission region, which can be outside of the event extraction region. The parameter "region_mode" allows users to use different coordinate systems for the extraction of the region file. If the "region_mode" is SKYREG and DETREG, the input is a file defining the regions. The format of the region is that generated by ds9 "save-region" command. The image from which these files are generated should be unbinned (either in X and Y or DETX and DETY coordinates) If the "region_mode" is SKYFITS or DETFITS, a FITS image is required. This is useful to describe a complicated source extracting region. CAVEATS: (1) The output ARFs are weighted by the intensity of the input image. If the image is used to specify only the extraction region, the pixel values should be of 1 inside the extracting region and 0 outside. Pixels with negative values are counted in the calculation. (2) The region defined should always be inside of the exposed detector area, e.g. if the data are taken in 1/4 or 1/8 window modes the region file should not be larger than the window area. 'xissimarfgen' can also exclude regions using the parameter "detmask" and input the mask as an image FITS file. This option is useful to exclude for the ARF generation, the calibration source regions or bad columns. For example to exclude calibration source regions, it is recommended to use the file in CALDB, ae_xiN_calmask_YYYYMMDD.fits, where N is the XIS unit and YYYYMMDD is the release date. As for any Monte-Carlo based simulators, enough statistic is crucial. When "limit_mode" is set to NUM_PHOTON, the code generates a fixed number of photons, set up by the parameter "num_photon", in each energy bin. Users should know that this method ignores the fact that high-energy bins, above 10 keV, do not require the same number of photons as low energy. If "limit_mode" is set to MIXED the number of simulated photons is optimized per energy bin and save computation time. In this case users can set an accuracy via the parameter "accuracy". 'xissimarfgen' can include the degradation of the XIS soft response, using the same algorithm than the XIS task 'xiscontamicalc'. The contamination can be included by setting the parameter "contamifile" set to CALDB. In this case the calibration file containing the spatial and temporal dependence of the contaminant is automatically selected from the calibration database and the computation is done using the appropriate information for the specific observation time. Alternatively if the option is set to "none", the effective area of the simulated ARF will not include the correction due to the contamination. 'xissimarfgen' considers attitude wobbling during an observation by inputing the attitude file via the parameter "attitude". This file can be found in the "auxil" directory associated with the data delivered. The parameter "estepfile" specifies the energy steps that will be used in the effective area computation. There are two choices: 1) an ASCII file (their own or GOF recommended file). In that case, the required format is three columns containing the energy range (columns Emin and Emax) and the step (column Ebin) provided in keV for that energy range. 2) build-in steps. The different choices are FULL, DENSE, MEDIUM or SPARSE (see keyword explanation below). The 'xissimarfgen' version 2007-05-28 or later automatically generates the detector mask image, considering e.g. bad columns, SCI rows, hot/flickering pixels, and the 55Fe calibration source area, and merge it with the "detmask" image. Parameters same as 'xisexpmapgen' ftool are usable, namely, "hotpixfiles", "badcolumfile", "calmaskfile", "pixq_min", "pixq_max", "pixq_and", and "pixq_eql". See help file of 'xisexpmapgen' for details. This feature can be turned off by setting "enable_pixq=no" for backward compatibility. See the help file of 'xissim' for the description of the simulator. OUTPUT FORMAT OF OUTPUT ARF FILE The primary extension contains a simulated image in DET or SKY coordinates, depending of the "region_mode" parameter. You can see the image with DS9 and examine whether extraction region is appropriate or not. The 1st extension contains the generated ARF response, ENERG_LO, ENERG_HI, SPECRESP, and other comprehensive information. RESPERR and RESPRERR is the estimated absolute and relative errors of the calculated effective area (SPECRESP). XRT_EFFAREA is the XRT-only effective area, SHIELD_TRANSMIS is the thermal shield transmission, and CONTAMI_TRANSMIS is the average transmission of the XIS OBF contamination. No. Type EXTNAME BITPIX Dimensions(columns) PCOUNT GCOUNT 0 PRIMARY -32 1536 1536 0 1 1 BINTABLE SPECRESP 8 60(15) 7900 0 1 Column Name Format Dims Units TLMIN TLMAX 1 ENERG_LO 1E keV 2 ENERG_HI 1E keV 3 SPECRESP 1E cm**2 4 RESPERR 1E cm**2 5 RESPRERR 1E 6 XRT_EFFAREA 1E cm**2 7 SHIELD_TRANSMIS 1E 8 CONTAMI_TRANSMIS 1E 9 INDEX 1J 10 S 1E 11 T 1E 12 INPUT 1E count 13 DETECT 1E count 14 WEISUM 1E count 15 RELERR 1E PARAMETERS (telescop = SUZAKU) [string] Telescope name. This should be set always to SUZAKU. instrume [string] Instrument name, e.g. one of the XIS unit on board Suzaku. The possible values are: XIS0 , XIS1, XIS2, XIS3. (rand_seed = 7) [integer] Random seed number. (rand_skip = 0) [integer] Random number skip step. (simulation_mode = 1) [integer] Simulation mode (0:discard, 1:weight). (teldef = CALDB) [filename] Teldef file appropriate for the XIS unit chosen for the arf generation. This file is automatically read from the calibration database. (leapfile = CALDB;$ENV{LHEA_DATA}/leapsec.fits) [file name] Name of the leap second file. The default value is set to indicate that 'xissimarfgen' will search for the file in CALDB first and then in the LHEA_DATA directory if necessary (the actual path for the HEADAS installation in use will be shown). (pointing = AUTO) [string] Pointing type. This parameter is used when the "source_mode" is set to SKYXY or the "region_mode" is SKYFITS, SKYREG or SKYCIRC. The allowed values are AUTO or USER. If set to USER the parameters "ref_alpha", "ref_delta" and "ref_roll" are also prompt. If set to AUTO and an attitude file (parameter "attitude") is provided the parameters "ref_alpha", "ref_delta", "ref_roll" are not prompt. If set to AUTO and no attitude is provided the reference are from the Euler angle parameters "ea1", "ea2" and "ea3". ref_alpha [real] R.A. of the sky reference position. This must be specified if "pointing=USER". ref_delta [real] DEC. of the sky reference position. This must be specified if "pointing=USER". ref_roll [real] Roll angle of the sky reference. This must be specified if "pointing=USER". source_mode [string] Source mode. The allowed values are SKYFITS, DETFITS, J2000, SKYXY, DETXY and UNIFORM. If set to SKYFITS or DETFITS, a sky or detector coordinates image should be entered in the parameter "source_image". If set to SKYXY or DETXY, the pixel position either in X/Y or DETX/DETY coordinates should be entered in the parameters "source_x" and "source_y". If set to J2000, the RA and Dec in degrees should be entered in the parameters "source_ra" and "source_dec". If set to UNIFORM, users should provide an inner and outer radii in the parameters "source_rmin" "source_rmax". source_image [filename] Source image file name. The source_mode must be SKYFITS or DETFITS. The image can be a real sky taken from any satellite for SKYFITS, or the unbinned detector image (1024x1024) of Suzaku for DETFITS. The WMAP image in the primary header of a spectrum file is also usable. source_ra [real] Source position R.A. (deg). Used when "source_mode" is J2000. source_dec [real] Source position DEC. (deg). Used when "source_mode" is J2000. source_x [real] Source position x (pixel). Used when "source_mode" is SKYXY or DETXY. source_y [real] Source position y (pixel). Used when "source_mode" is SKYXY or DETXY. source_rmin [real] Minimum source radius (arcmin). Used when "source_mode" is UNIFORM. source_rmax [real] Maximum source radius (arcmin). Used when "source_mode" is UNIFORM. num_region [integer] Number of regions for which the ARF is generated. region_mode [string] Region mode. The allowed values are SKYFITS, DETFITS, SKYREG, DETREG, SKYCIRC and DETCIRC. If SKYFITS or DETFITS a sky or detector coordinates image should be entered in the parameter "regfileN". NOTE to specify only the extraction region pixel values should set to 1 inside the extracting region and 0 outside the extracting region. If SKYREG or DETREG a region (ds9 format) in either X/Y pixel coordinates (SKYREG) or in the DETX/DETY pixel coordinates (DETREG) should be entered in the parameter "regfileN". If SKYCIRC or DETCIRC, a file is not required and it is possible to enter either a circular or annulus region using the parameters "region_xN", "region_yN", region_rminN" and "region_rmaxN" to specify the center of the region and the radii. regfile1-9 [filename] Region file #1-9. This is used when the "region_mode" is set to SKYFITS or DETFITS or SKYREG, or DETREG. The region file can be either a FITS image file or an ASCII region file (ds9 format). If the region is input as an image fits file ("region_mode" set to SKYFITS or DETFITS) the size of the image should be in the unbinned coordinates, (e,g, 1536x1536 for X and Y, SKYFITS; 1024x1024 for the DETX and DETY, DETFITS). The WMAP image in the primary header of a spectrum file is also usable. arffile1-9 [filename] Output ARF name #1-9 region_x1-4 [real] Region x #1-4. Used when the "region_mode" is set to SKYCIRC or DETCIRC. This is the x-coordinate of the center of the circular region. region_y1-4 [real] Region y #1-4. Used when the "region_mode" is set to SKYCIRC or DETCIRC. This is the y-coordinate of the center of the circular region. (region_rmin1-4 = 0.0) [real] Region inner radius #1-4. Used when the "region_mode" is set to SKYCIRC or DETCIRC. This is the minimum radius for an annulus region. region_rmax1-4 [real] Region outer radius #1-4. Used when the "region_mode" is set to SKYCIRC or DETCIRC. This is the maximum radius for an annulus region or the radius for a circular region. limit_mode [string] Limit mode. Possible values are ACCURACY, NUM_PHOTON or MIXED. Recommended setting is NUM_PHOTON. num_photon [integer] Number of photons for each energy bin. Used when the "limit_mode" is set to NUM_PHOTON or MIXED. The minimum recommended value is about 100000 photons. accuracy [real] Calculation accuracy for each energy bin. Used when the "limit_mode" is set to ACCURACY or MIXED. The recommended value is 0.005 phafile [filename] Name of the input spectrum or event file to get observation mode. If "NONE", WINOPT=0, WIN_ST=0, WIN_SIZ=1024, and CI=0, i.e. window off and SCI off, are assumed. detmask [filename] XIS DET-coordinates mask image file. To exclude calibration source enter the calmask from CALDB, however the full file path to the file should be specified. gtifile [filename] Input GTI file or none. If you input the Suzaku event file, the GTI extension is used. If set to none the date of the observation should be entered in the parameter "date_obs". date_obs [string] Date of observation provided as 2006-04-20T12:00:00. Used when the "gtifile" is set to none. attitude [filename] Input Suzaku attitude file. ea1 [real] Default 1st Euler Angle (deg). Used when the "attitude" is set to none. ea2 [real] Default 2nd Euler Angle (deg). Used when the "attitude" is set to none. ea3 [real] Default 3rd Euler Angle (deg). Used when the "attitude" is set to none. rmffile [filename] Input RMF file. Must be always specified. (contamifile = CALDB) [file name] Name of XIS contamination file. estepfile [filename] Energy step file or build in steps. The build-in energy steps are: "full" : calculate effective area in each RMF energy bins. Very slow. "dense" or "default" : dense sampling (2303 steps). Slow. "medium" : medium sampling (157 steps). Moderate. "sparse" : sparse sampling (55 steps). Fast. To use the build-in energy steps enter one of the following values: full, dense (or default), medium or sparse. (enable_pixq = yes) [boolean] Enable the pixel quality selection with parameters: "pixq_min", "pixq_max", "pixq_and", and "pixq_eql". (hotpixfiles = none) [filename] Names of input hot pixel files. Hot pixels excluded onboard XIS-DE is stored in the DarkInit and DarkUpdate files in the XIS trend archive. Multiple file names can be specified by the comma/SPACE/TAB/semicolon separated list, or "@FILELIST" to read the file names from an indirect file of FILELIST. (badcolumfile = CALDB) [filename] Input file that describes the XIS bad columns and flickering pixels, or "CALDB" to automatically read from the calibration database. The name is ae__badcolum_YYYYMMDD.fits where is a string set to xi0, xi1, xi2, xi3 indicating the sensor and YYYYMMDD is the release date. (calmaskfile = CALDB) [filename] Input file that describes the irradiation area of 55Fe calibration source on the XIS CCD, or "CALDB" to read from the calibration database. The name is ae__calmask_YYYYMMDD.fits where is a string set to xi0, xi1, xi2, xi3 indicating the sensor and YYYYMMDD is the release date. (pixq_min = 0) [real] Minimum value of pixel quality to be considered. (pixq_max = 524287) [real] Maximum value of pixel quality to be considered. (pixq_and = 65536) [real] Bit AND mask for pixel quality. The default value of 65536 is set to remove the 55Fe calibration source area. (pixq_eql = 0) [real] Allowed pixel quality after bit AND mask. Users can choose pixels with the pixel quality values on "pixq_and" (0: exclude, 1: include). The pixel quality, equivalent to the STATUS column of event files, are selected as: pixq_min <= STATUS && STATUS <= pixq_max && (STATUS & pixq_and) == pixq_eql (aberration = yes) [boolean] If the calculation corrects aberration. (aperture_cosine = yes) [boolean] If the calculation considers aperture decrease by cosine factor. (minangle = 0.0) [real] Minimum telescope angle (deg). Should not be changed (maxangle = 360.0) [real] Maximum telescope angle (deg). Should not be changed (minradius = 57.96755) [real] Minimum telescope radius (mm). Should not be changed (maxradius = 200.10644) [real] Maximum telescope radius (mm). Should not be changed (mirrorfile = CALDB) [filename] XRT Mirror Geometry File name. (mirror = mirror) [string] Mirror geometry extension name. (obstruct = obstruct) [string] Obstruction geometry extension name. (quadrant = quadrant) [string] Quadrant geometry extension name. (pcol = pcol) [string] Pre-Collimator geometry extension name. (reflectfile = CALDB) [filename] Reflection Table File name. (backproffile = CALDB) [filename] XRT Back Surface Reflection Profile File name. (shieldfile = CALDB) [filename] XRT thermal shield transmission file. (clobber = yes) [boolean] If the task overwrites output file if exists. (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 events (All events: -1, No events: 0). (event_freq = 10000) [integer] Event number printout frequency. (chatter = 2) [integer] Message chatter level (0:min,2:norm,5:max). EXAMPLES Note: parameter names need to be always written when specifying parameters on the command line. 1. Derive an ARF for a point source for the XIS1 detector. The time of the observation is taken from the gti of the event file. The source emission is uniformly extended inside 20' from the optical axis. The extraction region is specified as a ds9 region file in X/Y coordinates. % xissimarfgen instrume=XIS1 pointing=AUTO source_mode=J2000 \ source_ra=161.264962 source_dec=-59.684517 num_region=1 \ region_mode=SKYREG regfile1=etacar_phys.reg arffile1=xis1_etacar.arf \ limit_mode=NUM_PHOTON num_photon=400000 phafile=none detmask=none \ gtifile=100012010/xis/event_cl/ae100012010xi1_1_3x3n001_cl.evt \ attitude=100012010/auxil/ae100012010.att \ rmffile=ae_xi1_20060213.rmf estepfile=default 2. As for the example 1 , but the observation date is specified via the parameter "date_obs" instead of providing a gti file. % xissimarfgen instrume=XIS1 pointing=AUTO source_mode=J2000 \ source_ra=161.264962 source_dec=-59.684517 num_region=1 \ region_mode=SKYREG regfile1=etacar_phys.reg arffile1=xis1_etacar.arf \ limit_mode=NUM_PHOTON num_photon=400000 phafile=none detmask=none \ gtifile=none date_obs=2005-08-30T00:00:00 \ attitude=100012010/auxil/ae100012010.att \ rmffile=ae_xi1_20060213.rmf estepfile=default 3. Generate an ARF of the entire XIS1 chip including the calibration source region. The source emission is uniformly extended inside 20' from the optical axis. The pointing is set to AUTO and no attitude is provided, the reference position are from the Euler angles ea1, ea2, ea3. % xissimarfgen instrume=XIS2 pointing=AUTO \ attitude=none ea1=83.63 ea2=67.97 ea3=0.0 \ source_mode=UNIFORM source_rmin=0 source_rmax=20 num_region=1 \ region_mode=SKYREG regfile1=carneb_phys.reg arffile1=uniform.arf \ pixq_and=0 limit_mode=NUM_PHOTON num_photon=100000 phafile=none \ detmask=none gtifile=none date_obs=2006-08-30T00:00:00 \ rmffile=../refdata/xis_rsp_20060213/ae_xi1_20060213c.rmf \ estepfile=default 4. Derive an ARF for an extended region for the XIS2 detector. The source emission is assumed to be "UNIFORM", up to 20 arcmin. Two extraction regions are provided and two ARFs are generated. The contamination is read from CALDB. % xissimarfgen instrume=XIS2 pointing=AUTO source_mode=UNIFORM \ source_rmin=0 source_rmax=20 num_region=2 \ region_mode=SKYREG regfile1=nep_tophalf_phys.reg \ regfile2=nep_bottomhalf_phys.reg arffile1=nep_tophalf.arf \ arffile2=nep_bottomhalf.arf limit_mode=MIXED num_photon=1000000 \ accuracy=0.005 phafile=none detmask=none \ gtifile=100018010/xis/event_cl/ae100018010xi2_1_3x3n000_cl.evt \ attitude=100018010/auxil/ae100018010.att rmffile=ae_xi2_20060213.rmf \ estepfile=default BUGS SEE ALSO xissim, xiscontamicalc, xisrmfgen, xisexpmapgen, xisputpixelquality AUTHOR This program was developed mostly in the ASTRO-E ANL environment by Yoshitaka Ishisaki (TMU) and Yoshihiro Ueda (ISAS/JAXA). The XRT ray-tracing library 'xrrt' was originally developed by Richard Fink (GSFC) and updated for Suzaku by Suzaku XRT team. LAST MODIFIED March 2008