|AHELP for CIAO 4.2||
Project rays generated by ChaRT onto a semi-infinite detector plane.
psf_project_ray infile outfile detector [evtfile] [simx] [simy] [simz] [defocus] [xblur] [yblur] [ablur] [lcfile] [randseed] [geompar] [ardlibpar] [detsubsysmod] [clobber] [verbose]
`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.
The ChaRT website has more information, including instructions on how to use the web interface and caveats associated with it.
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.
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.
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.
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)
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=simx (real default=INDEF units=mm)
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)
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)
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)
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.]
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.]
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=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)
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.
See the bugs page for this tool on the CIAO website for an up-to-date listing of known bugs.
- acis_bkgrnd_lookup, acis_fef_lookup, acis_set_ardlib, acisspec, aconvolve, acrosscorr, add_grating_orders, add_grating_spectra, arestore, asphist, dither_region, dmarfadd, dmcoords, dmextract, dmfilth, dmregrid, eff2evt, fullgarf, hrc_bkgrnd_lookup, make_instmap_weights, merge_all, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkinstmap, mkpsf, mkpsfmap, mkrmf, mkwarf, psextract, rmfimg, specextract