Adding a New Mission

XIMAGE can read and display images regardless of whether it "knows" about the mission the data is from. In order to get slide-cell search to work with the mission, however, it must be educated on the mission's PSF and vignetting. Also, there are default settings based on the mission which can be altered.


Ideally, a FORTRAN PSF function which takes an offaxis value and radius from the center of the source, and returns a fractional energy for that position can be integrated into the src/stat/npsf.f code in the XIMAGE distribution. If, however, such a function does not exist, an approximation can be made through the "PSF/MULTPSFFILE=[filename]" command.

First, read in a file with the READ_IMAGE command. An event list is recommended as detector coordinates will be preserved in XIMAGE. If an image is used, the rebin of the image will default to 1, and the center in detector coordinates will be equal to the CRPIX1/2 values present in the FITS file. Likely these will not be the same as the actual detector coordinates. They may require modification with the syntax "CHHEADER/KEY=[key name]/VAL=[value]". The relevant keys are ZMX/ZMY for zoom factor (i.e. rebin) and DRPIX1/DRPIX2 for detector coordinates of the image center.

A PSF can be created with the PSF command by selecting one source if the PSF of the detector is fairly constant across the detector, or selecting more than one at representative distances from the optical axis if the PSF varies widely. Ideally, multiple data sets with the same source at different positions on the detector should be used. The PSF for points falling between the selected sources' offaxis values will be interpolated. Source selection may be made with the CURSOR or XP=[xcenter]/YP=[ycenter]/RADIUS=[radius(arcmin)]. For example:

  • READ/REBIN=2/XP=1000/YP=0 src_at_1000.evt
  • PSF/XP=1000/YP=0/RAD=1.2/MULTPSF=newpsf.dat
  • READ/REBIN=2 src_at_0.evt
  • PSF/XP=0/YP=0/RAD=1.2/MULTPSF=newpsf.dat

Note that each run with the MULTPSF qualifier appends a column to the file. To start a new file, delete the existing one or use a different name. It is best to select radii approximately the same for all selected sources, as selections smaller than those already recorded in the PSF file will be padded with 1.0's and those larger will be truncated.

To set this file as the method for calculating the PSF, the mission must be added to the internal mission database (mdb), and the PSFFILE key defined:

  • CHMDB/ADD/TEL=newtel/INST=newinst
  • CHMDB/KEY=psffile/VAL=newpsf.dat

Note that it may be easier to find an existing mission with similar properties, and modify it.

  • CHMDB/COPY/TEL=oldtel/INST=oldinst/TOTEL=newtel/TOINST=newinst
As a test, run the PSF command with the values used to create the PSF file. The solid line should overlay the individual points exactly.


By default a flat vignetting is assumed, although a FORTRAN vignetting function or vignetting FITS image can be used by XIMAGE. The FORTRAN function must be integrated in src/stat/get_vign.f. While the image does not require any code changes. The image must include the entire detector and the header must contain following critical keywords:

  • CRPIX1/2 - Sets the center in image coordinates
  • DRPIX1/2 - Sets the center in detector coordinates
  • REBIN_X/Y - The rebin factor
  • DATAMAX - Sets the maximum exposure time

To calculate the vignetting correction for a particular point on the detector, DATAMAX is divided by the value at the corresponding point in the vignetting map.

Set the vignetting map for the mission with the command:

  • CHMDB/KEY=vignfile/VAL=newvign.fits

Slide-Cell Search

With the PSF and vignetting set, source detection is possible, however, some tweaking may be necessary to get the best results. For example the default source box size will be set to 8. This may be specified when running:

  • EXCESS/SOURCE_BOX=[box size]


  • DETECT/SOURCE_BOX=[box size]

The default, however, can be set with the command:

  • CHMDB/KEY=detbox/VAL=[box size]

Similarly, the error radius used by the slide-cell search may be set through the mdb keyword ERRRAD.

The mdb keywords DOPTIC1/DOPTIC2 must be set if a PSF or vignetting function is used which takes an offaxis distance. Also, if a vignetting or PSF function requires units of arc, the mdb keyword PIXSIZE must be set in arcsec.

Reader Behavior

When an event file is read in for the new mission, the existing defaults may be inappropriate. The following mdb keywords modifies those defaults:

  • DEFSZX - Image size in x (DEFSZX=DEFSZY if not set)
  • DEFSZY - Image size in y (DEFSZY=DEFSZX if not set)
  • DEFZOOM - Image zoom
  • XCOL - X column
  • YCOL - Y column
  • ECOL - Energy column (PI/PHA)
  • EMIN - Minimum energy channel
  • EMAX - Maximum energy channel

When an image file is read in for the new mission and DRPIX1/2 keywords are not in its header, it will assume the DRPIX1/2 key values in the mdb for the center of the image in detector coordinates if they are set.

Saving New Mission

To save the mdb entry for the new mission, use the command:

  • CHMDB/TEL=newtel/INST=newinst/OUTFILE=newmis.mdb

You can restore these settings in future executions of XIMAGE with the command:

  • CHMDB/INFILE=newmis.mdb

To make the change a permanent part of your XIMAGE distribution:

  • Append newmis.mdb to ximage.mdb in the manager directory.
  • Create a directory inside the cal directory named for the telescope, and inside that a directory named for the instrument.
  • Copy the psf and vignetting files under the directory named for the instrument.

If the psf file is named of the form psf_[instrume].dat, or if detector name is important for the mission, the form psf_[detnam].dat, and the vignetting file is of the form [instrume]_vignetting_correction.fits the PSFFILE and VIGNFILE keys need not be set.

Ximage Home Page Xanadu Home Page Xanadu ftp site

Please send reports of errors to : xanprob@athena.gsfc.nasa.gov

HEASARC Home | Observatories | Archive | Calibration | Software | Tools | Students/Teachers/Public

Last modified: Wednesday, 29-Mar-2006 14:40:17 EST