The XGAIN program evaluates the gain distribution for a source, using the basic events file and the aspect solution. The position of the source must be provided by the user in sky pixel coordinates; extended sources may also be handled, by providing a file containing a list of pixels to be averaged over. The basic problem is that as the ROSAT satellite wobbles, a given source illuminates different parts of the detector, with different gain values. The program derives a time weighted histogram of these values, with a resolution specified by the user. The overall mean gain is also returned.
For each record in the aspect solution whose time lies within the Good Time Intervals of the events file, we take the sky coordinates of the source and de-apply the aspect transformation to obtain the linearized detector coordinates. This calculation requires the nominal pointing direction and the pixel size, which are read from the header of the events table. We note here the important differences between Rev0 and RDF format for both the aspect solution file and the events file. In particular, the Rev0 archival data stores its aspect information as offsets from the nominal direction, in multiple tables which must be concatenated. The RDF archival data stores the aspect solution as absolute pointing directions in a single table. The XGAIN program handles these different formats, at some cost to the complexity of the user interface.
The gain calibration file (gain.fits) contains a sequence of low (2 arcmin) resolution maps of the spatial gain variation on the detector, time-tagged with the Modified Julian Date (MJD). Each gain map pixel corresponds to 256 x 256 full resolution detector pixels. XGAIN will linearly interpolate in time and position to obtain the gain value appropriate for the time of the aspect interval and the calculated detector position. (Since the time interpolation is done repeatedly rather than once per observation, the program will work correctly for combined observation intervals spanning a long period; the extra computation is a small overhead). An optional ASCII `steps calibration file' gives the MJD dates of discontinuities in the detector gain (for instance because of commanded high voltage changes); XGAIN will avoid interpolating across such boundaries.
The program prints a summary of results to the screen and writes the results to a FITS binary table file suitable for further processing. On the screen, only the nonzero elements of the histogram are displayed, while in the FITS table there is one row for each histogram bin. The three columns written out are the bin center gain value, the relative weight of the bin, and the total time exposure on that bin in seconds. The mean gain is written to the header parameter AVG_GAIN. For the case of a single pixel source, the screen output also includes, for each gain bin, the time filters which could be applied to the events file to get data only in that bin, if the filter is simple enough to be conveniently printed. This information is not, however, written to the FITS file.
The program, written in ANSI C and ported to a variety of Unix machines, uses the SAO IRAF-style parameter interface and the CFITSIO library. The full list of parameters is given in Table 1. The EVENTS, ASPECT, OUTFILE, MAPS and STEPS parameters specify the various data files used by the program.
Due to the wobble of the satellite, photon events are recorded over a 5 arcmin path on the detector. This wobbled path can encompass areas on the detector with varying gain levels. Gain levels for an observation can span as much as one channel.
The program will attempt to guess the data format from the name of the aspect file; if it ends in '.ao' it is a Rev0 dataset, otherwise it is an RDF dataset; however, the MODE parameter may be used to override this guess. If MODE is RDF, the event list table name is assumed to be STDEVT, otherwise it is assumed to be EVENTS. The MODE parameter is also used to decide whether the data in the aspect solution are offsets or absolute aspect.
ASPCOLS is the trickiest parameter; unfortunately different versions of the REV0 aspect data have used different column names in the aspect table. To help XGAIN out, we provide it with the names of the columns containing time, RA, Dec and the roll angle. The example values given above are for RDF data; for REV0 you may check the values in your actual data using any FITS printing software, although "TIME,XOFF,YOFF,ROFF" is a common example.
If the POS parameter is not blank, it is assumed to be the name of an ASCII file containing a list of pixel X,Y pairs, one pair per line. Otherwise, the source position is read from the XPOS and YPOS parameters.
The three values read by the gain histogram binning parameter GHIST are the center gain value for the lowest bin, the center gain value for the highest bin, and the bin size.
The boresight offsets, BSO are a correction applied to the aspect solution; unfortunately, they are not stored in a consistent way in the ROSAT aspect solution files. The three numbers required are pixel offsets in the X and Y detector axes and a roll offset in degrees. We recommend the default values be used unless you are an expert on the ROSAT aspect solution.
