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 obebhkfile [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. Optionally, by setting the input parameter 'mlicorr' to 'yes', the CALDB on-axis ARF file query for FPMA is temperature dependent. To this end, 'numkarf' reads in input the OBEB Housekeeping FITS File and calculates the average value of the 'OPT0_5TEMP' column.

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.

(mlicorr=no) [boolean]
If set to yes, enables ARF MLI temperature-dependent correction for FPMA data.

obebhkfile [file name]
Name of the input OBEB Housekeeping FITS File (used only if mlicorr=yes).

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

  1. 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
  2. Generates the ARF file appropriate for the point-like source spectrum 'nu40060001001A01_sr.pha'. The ARF MLI temperature-dependent correction is enabled. 

    > 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 mlicorr=yes obebhkfile=nu40060001001_obeb.hk

    BUGS

    SEE ALSO

    LAST MODIFIED

    March 2021