   How to use the JEM-X spectral repair kit?

      DSRI 2004-05-18  Niels J. Westergaard & Ruben Farinelli

Introduction
============

The spectral extraction efficiency depends on the detector
efficiency for accepting the events as X-ray photons and
the efficiency of the spectral extraction software to assign
a count to a particular source. The detector efficiency
has two components: 1) the electronic low signal threshold
(only important for low energy events, but perhaps up to 10 keV)
2) the background rejection criteria used by the on-board
software.

Altogether these effects are expressed in the ARF array
(Ancillary Response Function) which can basically be interpreted
as the quantum efficiency times the exposed detector area.

The spectral extraction software produces two files:
jmxi_srcl_spe.fits and jmxi_srcl_arf.fits (standard names in
OSA). The first one holds the spectra and the second one
the ARF tables as taken from the IC files: jmxi_rmf_grp_ssss.fits
where 'ssss' is the instance-number selected automatically by
the scripts.

Unfortunately the jmxi_rmf_grp_ssss.fits files cannot be updated
as quickly as the hardware and software changes.

In order to make it possible to do a good spectral analysis anyhow
a socalled 'arf_repair_kit' has been made. This tool is based on
IDL version 5.6 and will only work on Unix or Linux systems.

Current situation
==================

As mentioned above the spectral extraction efficiency depends on
the actual executable that does the job. Here OSA3 with j_src_spectra-3.5.1
has been assumed. For best results the same version must be
used by the observer. A new version of the tool for j_src_spectra-4.0.0
will be released in connection with OSA4.

Due to changes in the settings of the JEM-X instruments in the
course of time six calibration periods have been defined.

JEM-X1      IJD        RMF
       start    stop
1    1020.17  1043.33  0006  No calibration; pre-launch estimates are used
2    1043.33  1059.33  0007  No calibration; pre-launch estimates are used
3    1059.33  1151.29  0008  Crab calibration rev. 44
4    1151.29  1237.70  0009  Crab calibration rev. 45
5    1237.70  1507.50  0010  Crab calibration rev. 102
6    1507.50    -      0011  Crab calibration rev. 170

JEM-X2      IJD        RMF
       start    stop
1    1020.17  1046.33  0006  No calibration; pre-launch estimates are used
2    1043.33  1059.33  0007  No calibration; pre-launch estimates are used
3    1059.33  1151.29  0008  Crab calibration rev. 44
4    1151.29  1237.70  0009  Crab calibration rev. 45
5    1237.70  1426.10  0010  Crab calibration rev. 102
6    1426.10  1536.50  0011  Crab calibration rev. 170
(Currently - i.e. from March 2004 - there is no calibration for JEM-X2, but
this instrument has been put in hibernation at least until next Crab calibration in
August 2004)

Based on four in-flight calibration campaigns with the Crab Nebula
on-axis (or nearly so) the best ARF function has been determined for
each time period.

What 'substitute_arf' does
==========================

The by far most important change in the calibration is the sensitivity
at energies below 10 keV. The ARF describes this and substitute_arf is
a procedure that takes the proper ARF from the ARF catalog jmx1_all_arf_0002.fits
or jmx2_all_arf_0002.fits and replaces the ARF in jmxi_srcl_arf.fits while
keeping an account of the vignetting factor.

Prescription
============

When level 'SPE' (spectral analysis) has been requested in the ISSW
jemx_science_analysis then 'jmxi_srcl_spe.fits' and 'jmxi_srcl_arf.fits'
are created in the 'res' directory. If several spectra are combined
then an analoguous pair of files is created.

1) Go to any directory where you have write permission. Then unpack the
   the files in arf_repair_kit_b.tar

2) It is strongly recommended to do a back-up of the ARF files that will be
   affected by the updating process.

3) start IDL
   IDL> .r arf_idl_lib

   This should compile the necessary IDL routines.

   IDL> substitute_arf,arfdir,datadir

      Here 'arfdir' is the directory where the two files: jmx1_all_arf_0002.fits
      and jmx2_all_arf_0002.fits from the arf_repair_kit_b.taf can be found.

      'datadir' is the directory that will be searched for jmx?_srcl_spe.fits
      files and all the corresponding jmx?_srcl_arf.fits files will be updated.

      A log file by name of: substitute_arf.log is created with detailed information
      about the substitutions.

      In the case where you only want to updated a subset of the spectral files
      there are two options: 1) give a filename of a text file with a list of
      spectral files by keyword 'txtfile' 2) give a string array with the names
      of the spectral files by keyword 'filelist'.
      In these two cases the naming convention (jmxi_srcl_spe.fits etc.) is
      unimportant.

   If you enter

   IDL> substitute_arf

   you'll get a summary of the required input (also reproduced below)

4) Now you are ready to do e.g. an XSPEC spectral analysis.
   It is not important which version of the RMF you use since
   the energy resolution calibration has not been changed yet.
   jmxi_rmf_grp_0005.fits is the latest release.

In the case you want to analyse data before IJD = 1059.33 (2002-11-25)
then it must be discussed separately.

I hope this works, else I'll be here to answer question and improve the
package

NJW, njw@dsri.dk

   print,'Syntax: substitute_arf, arfdir, datadir[,filelist=][,txtfile=]'
   print,'  where ''arfdir'' is the directory where jmx1_all_arf_0002.fits'
   print,'                  and jmx2_all_arf_0002.fits can be found'
   print,'       ''datadir'' is the top directory for the search for'
   print,'       files with name ''jmx?_srcl_spe.fits'' where the spectra are found'
   print
   print,' If the keyword ''filelist'' is given it is assumed that it is a string'
   print,'       array that contains a list of all spectral files where ARF update'
   print,'       is requested. The path given in ''datadir'' will be disregarded.'
   print
   print,' If the keyword ''txtfile'' is given it is assumed that it is the name'
   print,'       of a text file that contains a list of spectral files. Also here'
   print,'       the path in ''datadir'' is disregarded.'
   print
   print, 'Examples'
   print, 'substitute_arf, ''/userdir/'', ''/REP_BASE_PROD/obs/og_id/scw/''
   print, 'to substitute all ARF under a same OG'
   print
   print,'substitute_arf, ''/userdir'', ''datadir'', $'
   print,'       filelist=[''/my_source/obs1/res/jmx1_srcl_spe.fits'', $'
   print,'                 ''/my_source/obs2/res/jmx2_srcl_spe.fits'']'
   print
   print,'substitute_arf, ''/userdir'', ''datadir'', $'
   print,'       txtfile=''/userdir/arf_repair/test/list_of_files''
   print, 'where list_of_files has the content:'
   print, '/vesta/INTEGRAL/TOO_XTE1720/obs/too_jmx_rev46/scw/004600200010/jmx2/res/jmx1_srcl_spe.fits'
   print, '/vesta/INTEGRAL/TOO_XTE1720/obs/too_jmx_rev46/scw/004600210010/jmx2/res/jmx1_srcl_spe.fits'
   print
   print,' It is strongly recommended to make sure that you can (easily)'
   print,' recreate the relevant files before running this procedure'
   print
