NAME

nuexpomap -- Generate exposure maps for NuSTAR event files

USAGE

nuexpomap infile mastaspectfile attfile det1reffile expomapfile [parameter = < value >]

DESCRIPTION

'nuexpomap' generates an exposure map that accounts for detector bad and hot pixels, detector gaps, attitude variations, mast movements and, optionally, telescope vignetting.

'nuexpomap' first generates a set of instrument maps in Focal Plane Bench DET1 coordinates where bad/hot pixels and detector gaps are marked using information from the 'BADPIX' extension of the input event file (parameter 'infile') and from the CALDB Instrument Probability Map File (parameter 'instrprobmapfile'), respectively.

The set of DET1 instrument maps is constructed as follows. First, the task reads the input file 'det1reffile' which stores the X/Y SKY position as a function of time of a reference pixel in the DET1 coordinate system (see help file of 'nuskypos' for further details). Second, the X/Y offsets relative to their minimum value in the 'det1reffile' are calculated. Third, the X/Y offsets are binned with a bin size in pixels specified by the input parameter 'pixbin'. Each bin defines a time interval during which the spatial fluctuations due to attitude variations and mast movements are below the 'pixbin' value and are considered constant. This information is then used by 'nuexpomap' to build the aspect histogram which defines, for each spatial offset bin, the time interval and duration of each single DET1 instrument map. By setting the parameters 'offsetfile' and 'aspecthistofile' not to 'NONE' the task saves in the current directory the spatial offset and aspect histogram files, respectively.

Each DET1 instrument map is then transformed in the Optics Bench DET2 frame using the mast aspect solution (parameter 'mastaspectfile') and the CALDB align file (parameter 'alignfile'). In this step, 'nuexpomap' makes use of the multi-mission FTOOLs 'combinexform' and 'imagetrans'. Optionally, if the parameter 'vignflag' is set to 'yes', the task applies the vignetting correction to the DET2 instrument maps using the vignetting CALDB file (parameter 'vignfile'). The vignetting correction is applied at the energy value specified by the parameter 'energy'.

Next, the DET2 instrument maps are transformed in the SKY frame using the attitude information provided in input through the parameter 'attfile'. To this end, the multi-mission FTOOLs 'getxform', 'imagetrans' and 'getwcs' are used by 'nuexpomap'. The total exposure map, storing in each pixel the net exposure time of the observation, is then calculated by summing the single exposure maps in sky coordinates. Dead time corrections are included in the total exposure map.

By setting the parameters 'det1instrfile','det2instrfile' and 'skyinstrfile' not to 'NONE' the task saves in the current directory the single DET1, DET2 and SKY instrument maps as FITS IMAGE extensions in the corresponding output files.

Optionally, the task allows to generate reduced exposure maps covering a user region of the SKY grid defined by the input parameters 'skyx', 'skyy' and 'skysize'.

The 'nuexpomap' task can also generate an ouput exposure map using as input a DET2 instrument map not corrected for vignetting produced in a previous run. This can be achieved by setting the input parameter 'indet2instrfile'. Note that in this case maps with reduced size cannot be generated.

PARAMETERS

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.

(vignfile=CALDB) [filename]
Name of the input vignetting file or CALDB.

(indet2instrfile=NONE) [filename]
Name of the input DET2 Instrument Map File or NONE for none.

(aberration=no) [boolean]
If set to yes, aberration is included in aspecting.

(vignflag=yes) [boolean]
If set to yes, the vignetting correction is applied.

(energy = 10) [real]
Energy value for vignetting calculation (keV).

det1reffile [file name]
Name of the input DET1 Reference Pixel File.

(skyx = 500.5) [real]
SKY Exposure Map File center X coordinate.

(skyy = 500.5) [real]
SKY Exposure Map File center Y coordinate.

(skysize = 1000) [integer]
SKY Exposure Map File size (pixels).

(pixbin = 5) [integer]
Bin size of aspect histogram in pixels (pixel size = 2.46 arcsec).

(offsetfile=NONE) [filename]
Name of the output DET1 Offset File or NONE for none.

(aspecthistofile=NONE) [filename]
Name of the output Aspect Histogram File or NONE for none.

(det1instrfile=NONE) [filename]
Name of the output DET1 Instrument Map File or NONE for none.

(det2instrfile=NONE) [filename]
Name of the output DET2 Instrument Map File or NONE for none.

(skyinstrfile=NONE) [filename]
Name of the output SKY Instrument Map File or NONE for none.

(expomapfile=NONE) [filename]
Name of the output Exposure Map File.

(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.

(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. Produces an exposure map in the current directory for the NuSTAR event file 'nu40060001001A01_cl.evt'. The vignetting correction calculated at energies 25 keV is applied and the name of the output exposure map is 'nu40060001001A01_ex.img'. 

    > nuexpomap infile=nu40060001001A01_cl.evt attfile=nu40060001001_att.fits 
  mastaspectfile=nu40060001001_mast.fits det1reffile=nu40060001001A_det1.fits
  energy=25 expomapfile=nu40060001001A01_ex.img

  2. Same as above, but providing in input a DET2 instrument map (not corrected for vignetting). 

    > nuexpomap infile=nu40060001001A01_cl.evt attfile=nu40060001001_att.fits 
  energy=25 expomapfile=nu40060001001A01_ex.img indet2instrfile=nu40060001001A01_det2.fits

    BUGS

    SEE ALSO

    LAST MODIFIED

    April 2014