XISCONTAMICALC (Nov 2006)       suzaku.xis       XISCONTAMICALC (Nov 2006)

NAME
    xiscontamicalc -- Calculate the XIS OBF contamination

USAGE
    [arffile=NONE]
    xiscontamicalc instrume date_obs energy detx dety NONE

    [scale_contaminant=no]
    xiscontamicalc instrume date_obs energy detx dety arffile no

    [scale_contaminant=yes]
    xiscontamicalc instrume date_obs energy detx dety arffile yes \
                   scale_previous scale_factor

DESCRIPTION

    'xiscontamicalc' calculates transmission of the XIS OBF contaminant
    on a date, at an energy and at a detector position (detx, dety)
    specified, referencing to the contamination description file in
    CALDB (arffile=NONE in USAGE). Column densities of the carbon and
    oxygen contamination and transparency at the specified energy are
    displayed in the standard output.

    The task also handles contamination parameters in an ARF file.
    When scale_contaminant=no (see USAGE), the task multiplies the derived
    transmission of the contaminant at each energy channel to the effective
    area without contamination (XRT_EFFAREA * SHIELD_TRANSMIS) and fill the
    result in the SPECRESP column of the input ARF file.
    With scale_contaminant=yes, the task multiplies column density of
    the contamination in the input ARF file (when scale_previous=yes)
    or derived from parameters in the command line (when scale_previous=yes)
    by a factor given in the "scale_factor" option and fills the result
    in the SPECRESP column of the input ARF file.

    Resultant ARF values are always overwritten so that it is recommended to
    back up the original file in advance. The "date_obs", "energy", "detx",
    and "dety" options need to be input every time, even if they are not used.

PARAMETERS

(telescop = SUZAKU) [string]
    Telescope Name should be SUZAKU.

instrume [string]
    Instrument Name (XIS0,XIS1,XIS2,XIS3).

date_obs [string]
    Suzaku TIME, or date string in UTC, 'yyyy-mm-ddThh:mm:ss.sss'.

energy [real]
    X-ray energy in keV.

detx [real]
    Incident X-ray DETX position.

dety [real]
    Incident X-ray DETY position.

(time) [real]
    Returned value of Suzaku TIME (s).

(days) [real]
    Returned value of days after date0 (day).

(date0 = "2005-08-13T09:53:20") [string]
    The origin of days, which should not be changed.

(r_offset) [real]
    Returned value of radial offset (arcmin).

(carbon) [real]
    Returned value of carbon contamination (10**18 cm**-2).

(oxygen) [real]
    Returned value of oxygen contamination (10**18 cm**-2).

(transmis) [real]
    Returned value of transmission of the contaminant.

arffile [file name]
    ARF file name to multiply the transmission.
    You may set to "none" to skip multiplying to ARF.

scale_contaminant [boolean]
    Scale column density of contaminant from nominal value or not.

scale_previous [boolean]
    Adopt previous value of the contaminant as nominal or not.

scale_factor [real]
    Scale factor for the contaminant.

(contamifile = CALDB) [file name]
    Name of the XIS contamination calibration file. If set to CALDB (default)
    the file is automatically selected from the calibration database.
    The root name of the CALDB is 'ae_xiN_contami_YYYYMMDD.fits',
    where N is the XIS unit and  YYYYMMDD is the release date.

(leapfile = CALDB;$ENV{LHEA_DATA}/leapsec.fits) [file name]
    Name of the leap second file. The default value is set to
    indicate that 'xiscontamicalc' 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).

(anl_verbose = 0) [integer]
    ANL verbose level (-1:full, 0:minimum).

(anl_profile = no) [boolean]
    Enable ANL module profiling.

(num_event = -1) [integer]
    number of event (-1:all, 0:exit).

(event_freq = 1000) [integer]
    Event number printout frequency.

(chatter = 2) [integer]
    Message chatter level (0:min, 2:norm, 5:max).

EXAMPLES

1.	Calculate contamination on the back illuminated chip (XIS1)
        at 1 keV

    % xiscontamicalc
    
xiscontamicalc version 2006-11-26
Written by Y.ISHISAKI (TMU)
Built on ANL HEADAS converter 1.80 for ANL version 1.80
Instrument Name (XIS0,XIS1,XIS2,XIS3)[XIS1]
Suzaku TIME, or date string in UTC, 'yyyy-mm-ddThh:mm:ss.sss'[2006-03-01]
X-ray energy in keV[1.0]
incident X-ray DETX position[310]
incident X-ray DETY position[512.5]
ARF file name to multiply the transmission[none]
xis_contami: reading '/caldb/data/suzaku/xis/bcf/ae_xi1_contami_20061016.fits' ...
ngp=522, t0=177242000.0, t1=492342800.0, nen=7900, e0=0.201, e1=15.999

TELESCOP = 'SUZAKU'
INSTRUME = 'XIS1'
CONTAMIFILE = '/caldb/data/suzaku/xis/bcf/ae_xi1_contami_20061016.fits' (CALDB)
LEAPFILE = '/caldb/data/gen/bcf/leapsec_010905.fits' (CALDB)
DATE-OBS = '2006-03-01T00:00:00' ( TIME = 194486401.000000 )
DAYS = 199.588 [dy] after 2005-08-13T09:53:20
ENERGY = 1.000 [keV]
R_OFFSET = 3.517 [arcmin] at ( DETX , DETY ) = ( 310.0 , 512.5 ) [pixel]
CARBON = 2.986882 [10**18 cm**-2]
OXYGEN = 0.497814 [10**18 cm**-2]
TRANSMIS = 8.223178e-01



2. 	Newly multiply the contamination transmission when 
        date_obs=2006-03-01T00:00:00, at (DETX,DETY)=(310,512).

    % xiscontamicalc instrume=XIS1 date_obs=2006-03-01T00:00:00 
      energy=1.0 \
      detx=310 dety=512.5 \
      arffile=ae_xi1_xisnom6_20060615.arf scale_contaminant=no

3.     Newly multiply the contamination transmission
       when date_obs=2006-03-01T00:00:00, at (DETX,DETY)=(310,512),
       scaling the contaminant to scale_factor=2.0.

    % xiscontamicalc instrume=XIS1 date_obs=2006-03-01T00:00:00 \
      energy=1.0 detx=310 dety=512.5 \
      arffile=ae_xi1_xisnom6_20060615.arf \
      scale_contaminant=yes scale_previous=no scale_factor=2.0

      
4.     Scale the current contamination parameters in an ARF by 
       scale_factor=0.25. The date_obs, detx, dety parameters 
       in the command line are ignored.

    % xiscontamicalc instrume=XIS1 date_obs=2006-03-01T00:00:00 \
      energy=1.0 detx=310 dety=512.5 \
      arffile=ae_xi1_xisnom6_20060615.arf scale_contaminant=yes \
      scale_previous=yes scale_factor=0.25

    By setting scale_factor=0.0 in example (3) or (4),
    users can get an ARF without OBF contaminant.
    The resultant ARF is overwritten.

BUGS

None reported
    
    
SEE ALSO

    xissim, xissimarfgen

AUTHOR

    This program was developed Y.ISHISAKI (TMU) and the XIS team.

LAST MODIFIED

    May 2007