XRISM Build 5a CalDB (ID: 20221201) ----------------------------------- This XRISM CalDB version supersedes the Build 5 CalDB (ID: 20220630). There was an error in one of the Resolve gain files, so that CalDB is obsolete and should no longer be used. The new Build 5a CalDB corrects the erroneous gain file, but also has several other updates that are detailed below. 1. Installing the Build 5a CalDB for XRISM ------------------------------------------ (a) The CalDB tar file for this build needs to be unpacked on top of a pre-existing Hitomi CalDB. If you do not already have the latest Hitomi CalDB installed, download the tar file at https://heasarc.gsfc.nasa.gov/FTP/hitomi/postlaunch/softcal/hitomi_calvs10/caldb_hitomi_20180213_all.tar.gz If you already have CalDB installed for other missions, go to the directory given by $CALDB. Here we refer to this directory simply by /my/caldb. Put the Hitomi CalDB tarball here and unpack it: cd /my/caldb tar -zxf caldb_hitomi_20180213_all.tar.gz Download the encrypted XRISM CalDB tar file, which is at https://heasarc.gsfc.nasa.gov/FTP/xrism/prelaunch/caldb/build5a/caldb_xrism_20221201_all.tar.gz.gpg The instructions and password to decrypt the file should have been provided to you in a separate communication. Decrypt the file before proceeding. It is extremely important that the XRISM CalDB is created AFTER the Hitomi CalDB because some files in /my/caldb/data/gen/ are over-written and re-indexed. If you already have a previous XRISM CalDB installed, the previous version should be deleted (or moved) before installing the new XRISM CalDB. To delete the previous XRISM CalDB, execute the following steps: cd /my/caldb/data rm -fr xrism/ Unpack the new XRISM CalDB tarball: cd /my/caldb tar -zxf caldb_xrism_20221201_all.tar.gz Unpacking either of the CalDB tarballs puts the files under a directory /my/caldb/data, with XRISM data in /my/caldb/data/xrism and Hitomi data in /my/caldb/data/hitomi/. Two configuration files called alias_config.fits and caldb.config are also required for a working CalDB. The URLs for these two files are https://heasarc.gsfc.nasa.gov/FTP/xrism/prelaunch/caldb/build5a/alias_config.fits https://heasarc.gsfc.nasa.gov/FTP/xrism/prelaunch/caldb/build5a/caldb.config If you have older versions of these, they should be replaced. Download these files to /my/caldb. To configure your environment in tcsh or csh, do the following: setenv CALDB /my/caldb setenv CALDBCONFIG $CALDB/caldb.config setenv CALDBALIAS $CALDB/alias_config.fits To configure your environment in bash or sh, do the following: export CALDB=/my/caldb export CALDBCONFIG=$CALDB/caldb.config export CALDBALIAS=$CALDB/alias_config.fits 2. CALIBRATION DATABASE UPDATES ------------------------------- The Build 5a XRISM CalDB file updates are summarized here. Note that the revised CalDB still contains many files that are numerically identical to their Hitomi counterparts. These files have the letter 'h' inserted before the version number (e.g. 'v001' becomes 'vh001'). Note that there are several Resolve gain CalDB files that can be selected, based on the date/time of the data being processed. Further details are given below, but here we note that no automated gain file CalDB selection is now appropriate for Hitomi-converted XRISM data. The current scheme gives priority to handling XRISM ground calibration data, and to pave the way for further modifications to the gain file in the future, which will eventually be appropriate for processing actual XRISM flight data. However, the user is reminded that the software always allows any file that is retrieved by a CalDB call, to be specified, instead, as a direct input, as opposed to automated retrieval from CalDB. The older Resolve gain file that was the main Resolve gain file in the CalDB Build 1 release, and is suitable for processing Hitomi-converted data, is still present in the Build 5 CalDB. However, since fully-converted Hitomi data will have event dates and times that run into XRISM ground calibration time intervals, the CalDB file appropriate for Hitomi-converted data will not be selected automatically by the software. After installing and initializing the Build 5a XRISM CalDB, the user can copy the Resolve gain file suitable for Hitomi-converted data over to the current directory by: cp $CALDB/data/xrism/resolve/bcf/gain/xa_rsl_gainpix_20140101vh003.fits . This file is then specified directly as input to the software, instead of "CALDB". All the changes that have been made to CalDB files, compared to Build 5, are summarized below. 1) In the "mkfconf" CalDB file, some changes were made to the names of HK extensions. This file will be valid for observation dates on or after 2022-08-05:00:01:00. Before that date, a CalDB call will pick up the previous version of the file. 2) The Xtend "gain", and RMF CalDB files were replaced, based on revised or new data provided by provided by the Xtend team. Previous versions of these files are obsolete. 3) The Xtend teldef is updated. The file no longer contains any place holders left over from the adoption of the Hitomi teldef data. Some errors and typos in header comments were corrected. Also, some numerical coordinate conversion data that was hard-wired into header comments have been removed so that if/when the data change, the changes will be made only to data tables, and do not have to be mirrored in header changes. The optical axis in this teldef is set to the initial intended aim point on the observation CCD, 8mm from each edge at the corner nearest to the center of the detector. The FOC coordinate offsets are set so that a source appearing at the optical axis in both Resolve and Xtend will appear at the origin of the FOC coordinate system. The optical axis and FOC offsets will be refined in the next version of the teldef, based on ground measurements of the instrument and telescope misalignments, and they will be further refined post-launch, based on inflight data. 4) The Xtend "mask" file that describes the locations of the non-active pixels and calibration sources is updated. Previously it was simply adopted from the Hitomi version. The new version is based on measurements provided by the Xtend instrument team. A corresponding new Xtend instrument map file is included, which also includes relevant keyword and header comment updates corresponding to the Xtend teldef revisions. 5) The Xtend quantum efficiency file is updated, based on new data from the Xtend instrument team. 6) An error was discovered in one of the new Resolve "gainpix" files that was included in the Build 5 CalDB release (for observation times > 2021-12-13:06:54). That file is replaced with a corrected one, and the previous version (xa_rsl_gainpix_20190101v003.fits) is obsolete, and should not be used. For convenience, here is a summary of the Build 5a Resolve gain CalDB files, along with their associated observation time intervals. 6a) t < 2018-09-13 -- Use the Hitomi-based gain file xa_rsl_gainpix_20140101vh003.fits 6b) 2018-09-13 = t < 2019-09-03:18:35:00 -- Use xa_rsl_gainpix_20190101v001.fits, which is based on a ground calibration campaign in September 2018. 6c) 2019-09-03:18:35:00 = t < 2021-12-13:06:54 -- Use xa_rsl_gainpix_20190101v002.fits, which is based on a ground calibration campaign in September 2019. 6d) t = 2021-12-13:06:54 -- Use xa_rsl_gainpix_20190101v004.fits, which is based on a ground calibration campaign in December 2021. The software will pick up the file appropriate for the observation time when CALDB is specified for the file name. However, as noted above, Hitomi-converted XRISM data has observation times that are not compatible with the above gain file time intervals, so the user must manually specify the file listed as 6d) above. 7) One of the new Resolve "confthre" (shape template) files in the Build 5 CalDB release was not indexed correctly because of a keyword error. The erroneous file has been replaced and the indexing has been corrected. The previous file (xa_rsl_confthre_20190101v004.fits) is obsolete and is replaced by xa_rsl_confthre_20190101v005.fits. 8) A new Resolve CalDB file is introduced, which defines a pulse height "clipping threshold" for each pixel. Further details on the clipping thresholds will be provided in updated help files for the relevant software. 9) A new Resolve teldef is included. Some errors and typos in header comments were corrected. The image location of pixel 12 (the calibration pixel) has also been revised. In previous versions of the teldef, in an image made from unfiltered event data, pixel 12 events would appear at the center of the 6x6 Resolve array. However, this location has been changed to a position that is offset from the 6x6 array. The FOC offsets were set so that a source appearing at the optical axis in both Resolve and Xtend will appear at the origin of the FOC coordinate system. The optical axis and FOC offsets will be refined in the next version of the teldef, based on ground measurements of the instrument and telescope misalignments, and they will be further refined post-launch, based on inflight data. The Resolve instrument map CalDB file was also revised to correct header comments and, includes the above FOC offsets. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%