Ahelp: mkpsf - CIAO 3.4

Description

Given an energy, defocus and sky or detector physical coordinates, mkpsf extracts a PSF model image from a given standard PSF library hypercube.

The PSF library hypercube contains PSF-model images with pixel sizes smaller (or equal to) the instrument pixels sizes for a set of energies and defocus positions. If the requested energy and/or coordinates do not match exactly the available information in the library file, mkpsf linearly interpolates between the PSF model images in the hypercube. If the energy or position lie outside of the boundaries of the hypercube, the closest energy or position is used.

Sky pixel (SKY) or the detector physical (DET) coordinate systems are allowed.

If SKY is selected, the program requires an input file. mkpsf will automatically match the binning in the image and the output is a scaled PSF model image based on binning information provided in the input file. The user can override this automatic scaling by specifying the output pixel size to match the selected PSF library file pixels (binspax, binspay) and image size in units of output PSF image pixels (sizeoutx, sizeouty). The output PSF model image may be rotated by the roll as specified by the keyword ROLL_NOM in the header of the input file. The rotation is approximate and is based on rotating a number of points per pixel specified by rotpts.

If DET is selected and an input file is supplied, it is not used. The user must provide the values for x and y in detector physical coordinates. The program will then extract a PSF model from the hypercube corresponding to the requested energy and position on the detector.

The output of the program is an image. Optionally, by specifying a filename (outpsffile), the PSF library images used in the interpolation of the requested PSF image can also be output.

The PSFs extracted using mkpsf and the standard PSF library files are by no means the "exact" PSFs needed for detailed analysis or for deconvolution. The current PSFs will help estimate the size of the PSF and provide information on how the PSF shape changes as a function of off-axis angles and energy. This would help avoid misidentification of PSF-related structures as structures intrinsic to the observed source.

The PSF library grids used by the CIAO tool mkpsf are very coarse (azimuth and elevation angular off-sets of 1' or 5', only 5 energies, and only one defocus position). Therefore, the user needs to interpolate in these grids to get a PSF for the off-axis angle and the energies (spectrum) of the observed source. If the current linear spatial/spectral interpolation incorporated in the mkpsf tool is not satisfactory to the user for their analysis, users can use their own interpolation scheme using the outpsffile parameter to extract the PSF models in detector coordinates. Up to eight files will be output, representing PSF's at the four grid points closest to the location of the source at each of the two closest energies. The files created in this way should not be used for detailed scientific analysis.

For best results, we suggest library file No. 1 ("f1") if the off-axis angle of the source is within the library field of view. For larger off-axis angles please use library file "f2". As said before, use with caution.

Example 1

mkpsf coord=SKY infile=acic_s_test.fits energy=1.5 x=4940 y=6040
psflibfile=CALDB outfile=test1.fits outpsffile=""

Extract a PSF model image from a PSF library hypercube. Use input file header keywords to determine which instrument's PSF image is to be extracted (in this example, ACIS-S). Automatically select a PSF library file at the specified off-axis SKY physical coordinates for the chosen instrument. Maintain output image binning identical to input image binning. Rotate output image to ROLL_NOM specified in infile, using default value of rotpoints=9. The psflib data images used in interpolation are not written out.

Example 2

mkpsf coord=DET energy=1.5 x=5800 y=4096
psflibfile=/my_path/psf_file2_TESTR1.fits outfile=test2.fits
outpsffile="."

Extract a PSF model image from a given PSF library hypercube for ACIS-S in detector physical coordinates. Write psflib data images used to interpolate image using "outfile" directory and filename for outpsffile path and name.

Example 3

mkpsf coord=DET binspax=2 binspay=2 sizeoutx=128 sizeouty=128
energy=2.77 x=4150 y=4150 psflibfile=/my_path/psf_acisi_file2.fits
outfile=test3.fits outpsffile="/newpath/."

Extract a PSF model image from a given PSF library hypercube for ACIS-I in detector physical coordinates. Rebin the PSF image so that image pixels are 2 times the detector pixel size in each direction (i.e., 48 by 48 microns, 2 times the ACIS pixel size of 24 by 24 microns). Rescale the image to be 128 by 128 rebinned pixels, or 6144 microns by 6144 microns. Write psflib data images used to interpolate image to "newpath" directory, and use the outfile filename for outpsffile root name.

Parameters

name	type	ftype	def	min	max	units	reqd	autoname
coord	string		SKY	SKY\|DET			yes
binspax	float		INDEF	0.25	256.0		yes
binspay	float		INDEF	0.25	256.0		yes
sizeoutx	integer		INDEF	2	2048		yes
sizeouty	integer		INDEF	2	2048		yes
infile	file	input					yes
energy	float			0		keV	yes
x	float						yes
y	float						yes
psflibfile	file	ARD	CALDB				yes
outfile	file	output					yes	yes
outpsffile	file	output					yes	yes
geompar	file		geom
rotpts	integer		9	1
verbose	integer		0	0	5
clobber	boolean		no

Detailed Parameter Descriptions

Parameter=coord `(string required default=SKY min=SKY|DET)`

The coordinate system for x and y.

The coordinate system for x and y. Currently only the sky pixel or the detector physical coordinate system are allowed. If SKY is selected the x and y are the sky physical coordinates of the location on the detector where the user wants the PSF model. If DET is selected, x and y are the detector physical coordinates of the location on the detector where the user wants the PSF model. (SKY|DET)

Parameter=binspax `(float required default=INDEF min=0.25 max=256.0)`

PSF binning in x direction

Specifies the output pixel size in the x direction, which should match the selected PSF library file pixels. INDEF bins to the same scale as in the input image (coord=SKY) or to the selected PSF library file pixel size (coord=DET).

Parameter=binspay `(float required default=INDEF min=0.25 max=256.0)`

PSF binning in y direction

Specifies the output pixel size in the y direction, which should match the selected PSF library file pixels. INDEF bins to the same scale as in the input image (coord=SKY) or to the selected PSF library file pixel size (coord=DET).

Parameter=sizeoutx `(integer required default=INDEF min=2 max=2048)`

PSF size in x direction

Specifies desired PSF output size in x direction in units of output PSF image pixels.

Parameter=sizeouty `(integer required default=INDEF min=2 max=2048)`

PSF size in y direction

Specifies desired PSF output size in y direction in units of output PSF image pixels.

Parameter=infile `(file required filetype=input)`

Input file name of a FITS image.

FITS image header info will be used to obtain binning information and the roll (ROLL_NOM).

Parameter=energy `(float required min=0 units=keV)`

Energy in keV of required PSF model image.

Parameter=x `(float required)`

x coordinate.

If SKY coordinates are selected, then x is the sky physical x coordinate of a selected location in the input image (e.g. using ds9 display). If the selected coordinate system is DET, then x should be specified in detector physical coordinates.

Parameter=y `(float required)`

y coordinate.

If SKY coordinates are selected, then y is the sky physical y coordinate of a selected location in the input image (e.g. using ds9 display). If the selected coordinate system is DET, then y should be specified in detector physical coordinates.

Parameter=psflibfile `(file required filetype=ARD default=CALDB)`

PSF library hypercube file name.

This file should be an ACIS-I, ACIS-S, HRC-I or HRC-S standard PSF library hypercube FITS file containing a set of PSF models for a given instrument, a set of energies and a set of defocus positions on a grid of off-axis angles covering the detector. The standard PSF library hypercube can be selected by the user by entering its name. If the selected PSF library hypercube FITS file is not found at run time it could be (a) gzipped or (b) does not exist. In case (a) the user should gunzip it; in case (b) the user should download the most current version of the calibration data base (CALDB).

If the user does not wish to enter a particular PSF library hypercube file and an input file is provided, the default value of CALDB may be used. A PSF library file for the instrument identified in the input file will be automatically chosen for the specified off-axis position. Note that in some cases finer resolution is available by directly specifying an alternate PSF library file.

BUG (CALDB): the option to automatically select the CALDB psflib hypercube file works for event files with header keywords for the detector name, DETNAM, which uses the "-I" or "-S" syntax. This is always true for HRC observations, but ACIS observations will typically have the chip numbers used in this keyword (e.g. "DETNAM=ACIS-012367"). One workaround for ACIS observations is to manually set the detector, when calling the CALDB. The syntax is as follows: instead of "CALDB", use "CALDB(DETECTOR=ACIS-I)" (or "-S"). Further details can be found in the "Interface to Tools" section of "ahelp caldb."

Parameter=outfile `(file required filetype=output autoname=yes)`

Output FITS image file name.

If "." or "path/." is specified, the output file name will be created from the input file name by adding an extension of "psf2D".

Parameter=outpsffile `(file required filetype=output default= autoname=yes)`

Output file root name for PSF library images used as interpolation data for output FITS image.

The root filenames for PSF library images will be generated by replacing the last extension in outpsffile (if any) with _eng_detx_dety, following autonaming conventions. In the appended extension, "eng" is the energy coordinate, and "detx" and "dety" are the detector x and y coordinates. These images are always at roll = 0, even when the interpolated PSF image has been rolled. They are always binned to the pixel size of the user specified PSF library file. Specifying outpsffile="." uses the outfile path and name. Specifying outpsffile="path/." uses the path and the filename portion of outfile as the root. Specifying outpsffile="" creates no image files.

Parameter=geompar `(file default=geom)`

The name of the Pixlib Geometry parameter file.

Parameter=rotpts `(integer default=9 min=1)`

Number of points per pixel used in rotation calculations.

The rotation is approximate - the more points are used, the more accurate results. However, a larger number results in increased computation time; therefore, a number larger than 20 is not recommended.

Parameter=verbose `(integer default=0 min=0 max=5)`

Display level. 0 = no display.

Parameter=clobber `(boolean default=no)`

Overwrite output file if it exists?

Synopsis

Syntax

Description

Example 1

Example 2

Example 3

Parameters

Detailed Parameter Descriptions

Parameter=coord `(string required default=SKY min=SKY|DET)`

Parameter=binspax `(float required default=INDEF min=0.25 max=256.0)`

Parameter=binspay `(float required default=INDEF min=0.25 max=256.0)`

Parameter=sizeoutx `(integer required default=INDEF min=2 max=2048)`

Parameter=sizeouty `(integer required default=INDEF min=2 max=2048)`

Parameter=infile `(file required filetype=input)`

Parameter=energy `(float required min=0 units=keV)`

Parameter=x `(float required)`

Parameter=y `(float required)`

Parameter=psflibfile `(file required filetype=ARD default=CALDB)`

Parameter=outfile `(file required filetype=output autoname=yes)`

Parameter=outpsffile `(file required filetype=output default= autoname=yes)`

Parameter=geompar `(file default=geom)`

Parameter=rotpts `(integer default=9 min=1)`

Parameter=verbose `(integer default=0 min=0 max=5)`

Parameter=clobber `(boolean default=no)`

Bugs

See Also

Parameter=coord (string required default=SKY min=SKY|DET)

Parameter=binspax (float required default=INDEF min=0.25 max=256.0)

Parameter=binspay (float required default=INDEF min=0.25 max=256.0)

Parameter=sizeoutx (integer required default=INDEF min=2 max=2048)

Parameter=sizeouty (integer required default=INDEF min=2 max=2048)

Parameter=infile (file required filetype=input)

Parameter=energy (float required min=0 units=keV)

Parameter=x (float required)

Parameter=y (float required)

Parameter=psflibfile (file required filetype=ARD default=CALDB)

Parameter=outfile (file required filetype=output autoname=yes)

Parameter=outpsffile (file required filetype=output default= autoname=yes)

Parameter=geompar (file default=geom)

Parameter=rotpts (integer default=9 min=1)

Parameter=verbose (integer default=0 min=0 max=5)

Parameter=clobber (boolean default=no)

Parameter=coord `(string required default=SKY min=SKY|DET)`

Parameter=binspax `(float required default=INDEF min=0.25 max=256.0)`

Parameter=binspay `(float required default=INDEF min=0.25 max=256.0)`

Parameter=sizeoutx `(integer required default=INDEF min=2 max=2048)`

Parameter=sizeouty `(integer required default=INDEF min=2 max=2048)`

Parameter=infile `(file required filetype=input)`

Parameter=energy `(float required min=0 units=keV)`

Parameter=x `(float required)`

Parameter=y `(float required)`

Parameter=psflibfile `(file required filetype=ARD default=CALDB)`

Parameter=outfile `(file required filetype=output autoname=yes)`

Parameter=outpsffile `(file required filetype=output default= autoname=yes)`

Parameter=geompar `(file default=geom)`

Parameter=rotpts `(integer default=9 min=1)`

Parameter=verbose `(integer default=0 min=0 max=5)`

Parameter=clobber `(boolean default=no)`