XISARFGEN (July 2011) suzaku.xis XISARFGEN (July 2011) NAME xisarfgen -- Calculate Suzaku XIS ARF using PSF & EA CALDB files USAGE xisarfgen phafile=filename rmffile=filename \ source_mode=J2000 source_ra=value source_dec=value \ region_mode=SKYREG num_region=1 regfile1=filename arffile1=filename \ attitude=filename xisarfgen phafile=filename rmffile=filename \ source_mode=J2000 source_ra=value source_dec=value \ region_mode=SKYREG num_region=1 regfile1=filename arffile1=filename \ attitude=none ea1=value ea2=value ea3=value DESCRIPTION 'xisarfgen' outputs an ARF that contains effective area of the XIS system except the detection efficiency. 'xisarfgen' is designed to calculate ARFs for a point-like source using pre-calculated files (via ray-tracing) in the CALDB. This is usually much faster than 'xissimarfgen', which always carries out ray-tracing. The different method of the calculation makes small difference between the effective areas in the ARFs produced by 'xissimarfgen' and 'xisarfgen', which is reported in Suzaku MEMO-2011-01. Difference between 'xissimarfgen' and 'xisarfgen' is summarized as follows: ========================================================================== 'xissimarfgen' 'xisarfgen' -------------------------------------------------------------------------- method Ray-tracing Linear interpolation (Monte-Carlo) of the PSF and EA tables. Energy dependence of the PSF is NOT considered. source mode SKYFITS, DETFITS, J2000 J2000, SKYXY SKYXY, DETXY, UNIFORM (point or extended source) (point source only) region mode SKYFITS, DETFITS, SKYREG, SKYFITS, SKYREG, SKYCIRC DETREG, SKYCIRC, DETCIRC contaminant at a detector position at a detector position of simulated photons of the source position (PSF is considered) (PSF is NOT considered) accuracy User defined Equivalent to num_photon=100000 energy step User defined (estepfile) 2 eV -------------------------------------------------------------------------- Users can calculate the ARF with 'xisarfgen' more quickly than with 'xissimarfgen'. If users ignore the error of the pointing control in one observation ("attitude=none"), the ARF can be generated in a minute. If users takes into the pointing error (attitude=filename), the ARF can be generated in a few hours, depending on the amount of the attitude wobbling during the observation. PARAMETERS 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; also the parameters, source_ra, source_dec, rmffile, date_obs, gtifile need special setting (see description below). (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 J2000, SKYXY, If set to SKYXY, the pixel position either in the sky X/Y 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". This should be set to J2000 if phafile is set to NONE. source_ra [real] Source position R.A. (deg). Used when "source_mode" is J2000. This is required ifphafile is set to NONE. source_dec [real] Source position DEC. (deg). Used when "source_mode" is J2000. This is required if phafile is set to NONE. source_x [real] Source position x (pixel). Used when "source_mode" is SKYXY. source_y [real] Source position y (pixel). Used when "source_mode" is SKYXY. num_region [integer] Number of regions for which the ARF is generated. region_mode [string] Region mode. The allowed values are SKYFITS, SKYREG, and SKYCIRC. If SKYFITS, a sky or detector coordinates image should be entered in the parameter "regfileN". In order to specify an extraction region, pixel values should set to 1 inside the region, and set to 0 outside. If SKYREG, a region (ds9 format) in the sky X/Y pixel coordinates should be entered in the parameter "regfileN". If SKYCIRC, 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 SKYREG. 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) the size of the image should be in the unbinned coordinates, (e,g, 1536x1536 for X and Y, SKYFITS). 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. 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. 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. 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. This is the maximum radius for an annulus region or the radius for a circular region. (detmask = none) [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 = auto) [filename] Input the GTI file or AUTO or NONE. If you input the Suzaku event file, the GTI extension is used. If set to AUTO, the GTI extension of the parameter "phafile" is used. If set to NONE, time of the observation should be entered in the parameter "date_obs". In this case, the Euler angles of the specified time is read from the attitude file. gtifile should be set to NONE if phafile is set to NONE. date_obs [string] Date of observation provided as 2006-04-20T12:00:00. Used when the "gtifile" is set to NONE and/or phafile is set to NONE. attitude [filename] Input Suzaku attitude file. ea1 [real] 1st Euler Angle (deg), used when the "attitude" is set to NONE. ea2 [real] 2nd Euler Angle (deg), used when the "attitude" is set to NONE. ea3 [real] 3rd Euler Angle (deg), used when the "attitude" is set to NONE. rmffile [filename] Input RMF file. Must be always specified. If set to CALDB, it is automatically read from the calibration database. If phafile is set to NONE an rmf file should be provided because the CALDB setting is not valid. (contamifile = CALDB) [file name] Name of XIS contamination file. (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 (shieldfile = CALDB) [filename] XRT thermal shield transmission file. (effareafile = CALDB) [filename] XRT effective area file. (psffile = CALDB) [filename] XRT point spread function file. (aberration = yes) [boolean] If the calculation corrects aberration. (gti_min_sec = 4.0) [boolean] Ignore GTI rows shorter than this number. (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 1. Derive an ARF for the XIS1 detector using an attitude file. % xisarfgen phafile=ae100012010xi1.pi rmffile=CALDB pointing=AUTO \ source_mode=J2000 source_ra=161.264962 source_dec=-59.684517 \ num_region=1 region_mode=SKYREG regfile1=xis1.reg arffile1=xis1.arf \ attitude=ae100012010.att 2. Derive an ARF for the XIS1 detector by specifying euler angles. % xisarfgen phafile=ae100012010xi1.pi rmffile=CALDB pointing=AUTO \ source_mode=J2000 source_ra=161.264962 source_dec=-59.684517 \ num_region=1 region_mode=SKYREG regfile1=xis1.reg arffile1=xis1.arf \ attitude=ae100012010.att ea1=161.2650 ea2=149.6845 ea3=106.1392 BUGS SEE ALSO xissim, xissimarfgen, xiscontamicalc, xisrmfgen, xisexpmapgen, xisputpixelquality AUTHOR This program was developed Yoshitaka Ishisaki (TMU), Yoshitomo Maeda (ISAS), and Chris Baluta (ISAS & NASA), based on 'xissimarfgen'. LAST MODIFIED July 2011