psf_project_ray

Synopsis

Project rays generated by ChaRT onto a semi-infinite detector plane.

psf_project_ray  infile outfile detector [evtfile] [asolfile] [simx]
[simy] [simz] [defocus] [xblur] [yblur] [ablur] [blur_coord] [lcfile]
[randseed] [geompar] [ardlibpar] [detsubsysmod] [clobber] [verbose]

Description

`psf_project_ray' takes the output rays generated by the Chandra Ray Tracer (ChaRT) and projects them onto a semi-infinite detector plane. The rays are randomly discarded based on the mirror weights and the detector QE and QEU (if a reference event file is used). The output is a pseudo event list in detector coordinates (detx,dety).

If a reference event list is provided, then the rays are projected not just to (detx,dety), but all the way to sky coordinates (x,y). In this case, the WCS and SIM information are extracted from the header of the event list and used in the calculations, as long as the simx/y/z parameters are set to "INDEF".

When the tool projects the rays onto the detector plane, the detectors do not have edges. This is important when dealing with a source that is near chip edges. psf_project ray creates the "ideal" PSF, not one that gets cut off at the chip edge. The edges should then be taken into account during modeling by including an exposure map in the convolution.

To simulate detections that include detector edges, the readout streak, pileup, etc., use the MARX software instead.

The ChaRT website has more information, including instructions on how to use the web interface and caveats associated with it.

As of version 2.0, SAOTrace can now simulate the effects of aspect. As the telescope dithers, a fixed point on the sky is seen by slighly different off-axis angles. Thus, the observed PSF is actually a superposition many individual PSFs sampled very nearby. This effect is very, very small. On axis, with HRC and ACIS subpixel algorithms users may notice a blur that is otherwise unaccounted for. Psf_project_ray now takes in an aspect solution file; the same one that is fed into SAOTrace so it can correctly place the dithered events back onto the sky correctly. If the asolfile is not supplied, users will see the Lissajous pattern traced by the aspect solution used in the simultaion.

Examples

Example 1

psf_project_ray HRMA_theta5.949_phi197.7_en1.7_d2.fits
projected_rays.fits "acis_evt2.fits[EVENTS]"

Project the rays from the ChaRT output, using an event file for reference. The default random seed of 0 (the current system time) is used for the projection.

Example 2

psf_project_ray HRMA_theta5.949_phi197.7_en1.7_d2.fits
projected_rays_seed25.fits "acis_evt2.fits[EVENTS]" randseed=25

The previous example is repeated with a specific random seed; this allows the results to be reproduced at a later time.

Example 3

psf_project_ray HRMA_theta5.949_phi197.7_en1.7_d2.fits no_ref_file.fits
evtfile="" detector=ACIS-S

The projection is done by specifying a detector instead of providing an event file. Since no file is available for reference, only detector coordinates are written to the output file.

Example 4

psf_project_ray HRMA_dithered_rays.fits rayevents.fits
evtfile=acis_evt.fits asolfile=pcad_asol.fits

An example showing how the aspect solution is fed in when working with rays that have been dithered by SAOTrace.

Parameters

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input ChaRT ray file

The input ray file from ChaRT that contains the ray positions and direction angles.

Parameter=outfile (file required filetype=output)

Output pseudo event list

The file containing the rays which have been projected onto the detector. The output contains detector coordinates and, if a reference event file was provided, sky coordinates. The SIM information is recorded in the file header.

Parameter=detector (string required default=ACIS-I)

Detector name

Used to set the detector and define the nominal aimpoint (SIM position). This parameter is ignored if an event file is provided.

Parameter=evtfile (file filetype=input)

Reference event file with block name

If this file is provided, the DETNAM header keyword value overrides the value of the detector parameter. The SIM_X/Y/Z values (also from the header) are used to set the correct SIM position. The WCS information, along with the nominal aspect, is used to project the rays onto the sky.

The desired block should be specified, e.g. "acis_evt2.fits[EVENTS]"; if it is not, ARDLIB will use the first "interesting" extension (usually EVENTS).

If no event file is provided, the tool cannot apply QE weighting; however, ray weights will still be applied.

Parameter=asolfile (file filetype=input)

Aspect solution file.

The aspect solution file that was used to simulate the dither rays. The TIME, RA, DEC, ROLL, DY, DZ, and DTHETHA are used to map the rays to the correct sky coordinates.

Note: SAOTrace only takes a single aspect solution file so even if the observation has multiple, they need to be dmmerged together before using SAOTrace. That same file should be used by psf_project_ray.

The aspect solution may include time that is not covered by the event data. Users should time filter the output ray file with the event times, eg rayevents.fits[@acis_evt.fits].

Parameter=simx (real default=INDEF units=mm)

SIM_X position

Sets the SIM_X position for the ray projection. If set to INDEF, the value of the SIM_X keyword in the reference event file header is used. Any other value overrides what is defined in the header.

Parameter=simy (real default=INDEF units=mm)

SIM_Y position

Sets the SIM_Y position for the ray projection. If set to INDEF, the value of the SIM_Y keyword in the reference event file header is used. Any other value overrides what is defined in the header.

Parameter=simz (real default=INDEF units=mm)

SIM_Z position

Sets the SIM_Z position for the ray projection. If set to INDEF, the value of the SIM_Z keyword in the reference event file header is used. Any other value overrides what is defined in the header.

Parameter=defocus (real default=0 units=mm)

Defocus position

Similar to setting SIM_Z. SIM_Z is an absolute position with respect to the spacecraft coordinate system; defocus is the offset from the "best focus", which is different for each detector aimpoint.

If the simz parameter is set, defocus should be left as 0.

Parameter=xblur (real default=0 min=0 units=arcsec)

Gaussian blur applied to rays

The final sky position of the rays can be blurred by a Gaussian with a sigma equal to this amount of blurring in the sky-x direction. [Only the sky positions are affected.]

If set to 0 (the default), no instrumental blurring is applied.

Parameter=yblur (real default=0 min=0 units=arcsec)

Gaussian blur applied to rays

The final sky position of the rays can be blurred by a Gaussian with a sigma equal to this amount of blurring in the sky-y direction. [Only the sky positions are affected.]

If set to 0 (the default), no instrumental blurring is applied.

Parameter=ablur (real default=0 min=-90 max=90 units=deg)

Rotation angle of Gaussian blur.

The final sky position of the rays can be blurred by a Gaussian with a sigma equal to this amount of blurring. [Only the sky positions are affected.]

Parameter=blur_coord (string default=sky)

Coordinate system to apply blur

The blurring parameters (xblur, yblur, and ablur) can be applied to either the "sky" or the "det" coordinate systems. Note that applying a blur in "det" induces a blur in sky coordinates; however, the size and angle are dependent on the instrument geometry.

Parameter=lcfile (file default=)

Lightcurve file to assign times

If supplied, a TIME column will be added to the output file. The times will be randomly assigned using the input lightcurve as a probability distribution. The lightcurve file must have a TIME and COUNTS column; the Data Model virtual file syntax can be used to rename columns if needed (see "ahelp dm"). The GTIs in the input event file are NOT used. They can be applied to the rays with dmcopy after running this tool.

The resulting file will not be time-sorted. Users can sort the file with dmsort if desired.

Parameter=randseed (real default=0)

Random seed

Controls which rays are allowed through based on their weight (which is stored in a column of the ray file) and the QE and QEU of the detector. The seed allows control of this random process so that it's repeatable.

If "randseed=0", the current system time will be used. If "randseed=-1" then no randomization will occur (all input rays will be in output file). Any other value will be used as-is for the random seed.

Parameter=geompar (file default=geom)

Pixlib Geometry parameter file

Parameter=ardlibpar (file default=ardlib.par)

Analysis Reference Data Library (ARDLIB) parameter file

Parameter=detsubsysmod (string default=BPMASK=0)

Ardlib detector sub-system modifier

Unlike some other ARDLIB enabled tools; psf_project_ray runs on multiple chips and as such does not have a detsubsys parameter. This parameter allows one to modify the internal detsubsys value to allow the response product to be modified. Things such as skipping badpixels be overridden (see "ahelp ardlib" for more information). The default "BPMASK=0" skips bad pixels when the PSF is created since the badpixel information is (typically) already included in the exposure maps.

Parameter=clobber (boolean default=no)

Overwrite the output file if it exists?

Parameter=verbose (integer default=0)

Amount of screen output created by the tool.

Bugs

There are no known bugs for this tool.

See Also

calibration

ardlib

psf

psf

tools

acis_bkgrnd_lookup, acis_fef_lookup, acis_set_ardlib, aconvolve, acrosscorr, addresp, aprates, arestore, arfcorr, asphist, combine_grating_spectra, combine_spectra, dither_region, dmarfadd, dmcoords, dmextract, dmfilth, dmregrid, eff2evt, fullgarf, hrc_bkgrnd_lookup, install_marx, make_instmap_weights, make_psf_asymmetry_region, mean_energy_map, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkinstmap, mkpsfmap, mkrmf, mkwarf, psextract, psf_project_ray, psfsize_srcs, readout_bkg, rmfimg, simulate_psf, sky2tdet, specextract, src_psffrac