NAME
numkarf -- Generates an ARF file for an input PHA file for NuSTAR
USAGE
numkarf phafile outfile optaxisfile offaxisfile offaxishisto apstophisto grhisto infile mastaspectfile attfile det1reffile [parameter = < value >]
DESCRIPTION
'numkarf' generates an OGIP-style Ancillary Response Function (ARF)
file which is suitable for input into the spectral fitting program
XSPEC. The ARF file contains the effective area of the telescope as a
function of energy needed to perform spectral analysis. This is
calculated correcting the input CALDB ARF file storing the effective area of
a source located on-axis without Point Spread Function (PSF) losses.
The input CALDB ARF file is modified taking into account the
vignetting, the aperture stop, the ghost rays, the detector absorption
and the PSF corrections. These terms are dependent on the source
off-axis angle, the azimuth angle and are functions of the energy. The
PSF and ghost rays corrections are also dependent on the radius of the
PHA file extraction region. The PSF correction term also includes the
corrections for the exposure map such as detector gaps and
mast/attitude variations.
The input files for on-axis effective area, PSF, aperture stop, ghost
rays, detector absorption and vignetting are, by default, read from
the Calibration Database (CALDB). For the PSF files, the CALDB stores
a set of files which are energy dependent. The association between
energy and CALDB PSF files is specified in the CALDB PSF Grouping File
provided in input through the parameter 'grppsffile'.
The time dependent off-axis angle, azimuth value and distance between
the optical axis and the aperture stop center are calculated using the
position of the telescope optical axis and of the aperture stop center
stored in the input file 'optaxisfile' (see 'nuskypos' and 'nucoord'
help files), and written in the output file 'offaxisfile'. The
distributions of off-axis and azimuth angles for the vignetting
correction are stored in the output file 'offaxishisto'. The
distributions of off-axis, azimuth angles and distance between the
optical axis and the aperture stop center for the aperture stop and
ghost rays corrections are stored in the output files 'apstophisto'
and 'grhisto' files, respectively.
The vignetting, aperture stop, ghost rays and PSF corrections are
calculated, taking into account the source off-axis and azimuth angle
distributions, by a weighted mean of the input CALDB values.
If parameters 'psfflag', 'apstopflag', 'grflag', 'detabs' and
'vignflag' are set to 'yes', the PSF, the aperture stop, the ghost
rays, the detector absorption and the vignetting correction are
applied to the input ARF file, respectively.
The source position and the radius of the extraction region is read
from the input spectrum (parameter 'phafile') in the 'REG00101'
extension. Only for the detector absorption correction, the source
extraction region is read from the input parameter
'srcregionfile'. Circular, elliptical and annular extraction regions
centred on the source are supported by the task. The ghost rays
correction is supported only for point-like sources (parameter
'extended=no') and for circular extraction regions.
The task can generate the ARF file also for extended sources, such as
clusters of galaxies or supernova remnants, by setting the parameter
'extended' to 'yes'. For the extended source case, to follow the
spatial variations of the detector properties, the extraction region
file, read from the first extension of the input spectrum file, is
divided in boxes of size chosen by the user (parameter 'boxsize'). For
each subregion, an ARF is produced with the vignetting correction, the
aperture stop correction and the detector absorption correction, but
without including the point-like PSF correction. This set of ARF
files are then weighted and combined using the 'addarf' FTOOL to
produce the output ARF. In the 'addarf' run the weights of each
individual ARF file is calculated using the fractional number of
counts in the corresponding box. The energy range used to evaluate the
fractional number of counts is defined by the input parameters
'pilowarf' and 'pihigharf'. Optionally, by setting the input
parameter 'flatflag' to 'yes', a flat spatial distribution of
counts in each box is applied. Note that for the extended case there
are no restrictions on the shape of the extraction region.
For extended sources, the task execution time can be reduced by
providing in input a sky exposure map file not corrected for
vignetting (parameter 'inexpomapfile').
PARAMETERS
- phafile [file name]
- Name of the input PHA FITS File
- outfile [file name]
- Name of output ARF FITS File.
- optaxisfile [file name]
- Name of the input Optical Axis File.
- offaxisfile [file name]
- Name of the output Off-Axis File or NONE for none (only if extended=no).
- offaxishisto [file name]
- Name of the output Off-Axis Histogram or NONE for none (only if extended=no).
- apstophisto [file name]
- Name of the output Aperture Stop Histogram or NONE (only if extended=no).
- grhisto [file name]
- Name of the output Ghost Rays Histogram or NONE (only if extended=no).
- infile [file name]
- Name of the input FITS Event File.
- (pixposfile=CALDB) [filename]
- Name of the input pixel location file or CALDB.
- (alignfile=CALDB) [filename]
- Name of the input alignment file or CALDB.
- mastaspectfile [file name]
- Name of the input Mast Aspect Solution File.
- attfile [file name]
- Name of FITS attitude file.
- (teldef=CALDB) [filename]
- Name of teldef calibration file or CALDB.
- (instrprobmapfile=CALDB) [filename]
- Name of the input Instrument Probability Map File or CALDB.
- (inexpomapfile=NONE) [filename]
- Name of the input Exposure Map File or NONE for none (only if extended=yes).
- (aberration=no) [boolean]
- If set to yes, aberration is included in aspecting.
- det1reffile [file name]
- Name of the input DET1 Reference Point File.
- (pixbin = 5) [integer]
- Bin size of aspect histogram in pixels (pixel size = 2.46 arcsec).
- (phibin = 30) [real]
- Azimuth angle bin size for vignetting correction (degrees).
- (apstopphibin = 10) [real]
- Azimuth angle bin size for Aperture Stop correction (degrees).
- (grphibin = 10) [real]
- Azimuth angle bin size for Ghost Rays correction (degrees).
- (inarffile=CALDB) [filename]
- Name of the input ARF file or CALDB.
- (grppsffile=CALDB) [filename]
- Name of the input 2D-PSF Grouping File or CALDB.
- (psfdir=CALDB) [filename]
- Name of the input 2D-PSF files directory or CALDB.
- (vignfile=CALDB) [filename]
- Name of the input vignetting file or CALDB.
- (apstopcorrfile=CALDB) [filename]
- Name of the input Aperture Stop Correction file or CALDB.
- (grcorrfile=CALDB) [filename]
- Name of the input Ghost Rays Correction file or CALDB.
- (detabscorrfile=CALDB) [filename]
- Name of the input DETABS Correction file or CALDB.
- srcregionfile [file name]
- Name of the input source region file (used only for DETABS correction).
- (psfflag=yes) [boolean]
- If set to yes, apply psf correction (used only if extended=no).
- (vigflag=yes) [boolean]
- If set to yes, apply vignetting correction.
- (apstopflag=yes) [boolean]
- If set to yes, apply aperture stop correction.
- (grflag=yes) [boolean]
- If set to yes, apply ghost rays correction (only if extended=no).
- (detabsflag=yes) [boolean]
- If set to yes, apply DETABS correction.
- (extended=no) [boolean]
- Extended source?(yes/no).
- (cutmaps=yes) [boolean]
- If set to yes, use resized exposure maps for PSF correction (only if extended=no).
- (boxsize=20) [integer]
- Size in pixel for the subimage boxes (used if extended=yes).
- (pilowarf=35) [integer]
- Minimum PI value for subregion ARF weight calculation (only if extended=yes).
- (pihigharf=1909) [integer]
- Maximum PI value for subregion ARF weight calculation (only if extended=yes).
- (flatflag=no) [boolean]
- If set to yes, use flat distribution for addarf execution (only if extended=yes).
- (percent = 0.02) [real]
- Probability threshold for DET1 instrument map generation.
- (initseed=no) [boolean]
- If set to yes, the random number generator uses a frozen seed value. If set to no, different seeds are generated for each run.
- (cleanup=yes) [boolean]
- If set to 'yes', the task deletes temporary files.
- (clobber=no) [boolean]
- If set to yes, overwrite the output file.
- (history=yes) [boolean]
- If set to yes, write parameter values and other information in HISTORY blocks.
- (chatter = 2) [integer]
- Chatter Level (min=0, max=5).
EXAMPLES
- Generates the ARF file appropriate for the point-like source spectrum 'nu40060001001A01_sr.pha'.
> numkarf phafile=nu40060001001A01_sr.pha outfile=nu40060001001A01_sr.arf optaxisfile=nu40060001001A_oa.fits
offaxisfile=NONE offaxishisto=NONE apstophisto=NONE grhisto=NONE infile=nu40060001001A01_cl.evt
attfile=nu40060001001_att.fits mastaspectfile=nu40060001001_mast.fits det1reffile=nu40060001001A_det1.fits
BUGS
SEE ALSO
LAST MODIFIED
May 2015