Description

**Figure 1:** Diagram of rgsproc sub-tasks and data-flow. Each exposure is processed separately until the fluxing stage. Sub-tasks (yellow) appear within solid rectangles and process loops appear within dotted rectangles. Optional data files appear within rounded boxes, data files produced and used within the process are in green, with thick blue borders for permanent output files and dashed borders for incomplete files.
$\begin{figure}\begin{center} \epsfig{height=19cm, file=rgsproc.eps} \end{center} \end{figure}$

This task provides interactive control over the pipeline-style processing of RGS Spectroscopy and High Time Resolution (HTR) data, exposing the important options of the underlying tasks, while sparing the user the tedium and hazards of running each by hand. The user specifies the ODF directory as an environment variable or on the command line (see the OAL documentation). The resulting pipeline products and intermediate data files are created in the current working directory. By default all output files are named according to the convention of the Pipeline Processing Subsystem (PPS). Intermediate files that are discarded by the PPS—and so do not appear in the CD-ROM distribution—are distinguished by the use of lower case characters in the file name. rgsproc can redo later stages of processing without starting from scratch (parameters entrystage and finalstage) and without accessing the original ODF. The five processing stages, or entry points, are the organizing principle for the rest of this document:

rgsproc also allows the user to restrict the scope of processing to an enumerated subset of exposures within the observation (parameter withinstexpids), and an enumerated set of reflection orders (parameter orders). See Figure 1 for a block diagram of the data flow. The first stage of processing performs basic calibrations on the events in separate, CCD-specific intermediate event lists and then gathers them together in the combined event list. The second stage performs the source-specific aspect-drift correction and defines the channel grid for the events and exposure. The third stage performs the most basic filtering of the data—just to remove what is unusable—and generates exposure maps consistent with the filtering. The fourth stage produces spectra. The fifth stage generates response matrices and with them produces a combined, fluxed spectrum for the designated primary source and sixth stage generates source and background time series.

Note that fluxed spectra are inherently just a qualitative summary of the data, not to be used for quantitative analysis. Nevertheless the response matrices constructed in the fifth stage are large enough, by default, for meaningful use with spectral fitting packages such as XSPEC. At default size they take a very long time to compute, and are much larger than is necessary for the purpose of fluxing. Parameter rmfbins=250 produces very small matrices that are still quite adequate for fluxing, and much faster to compute, but such matrices should not be used for other purposes.

The combined event list takes from the intermediate event lists all of the events (combined into a single table), the collections of CCD-specific exposure tables and Good Time Interval (GTI) tables, and the collections of node-specific bad pixel tables and rejectable pixel tables. Name collisions among tables copied in from the intermediate event lists are avoided by placing the corresponding CCD number at the eighth character of the extension name. The following tables document the finished state of the combined event list. Next to the name of each table is the name of the task that created it, and for columns added later by a subsequent task the name of the responsible task is included among the comments. In addition to these and the nine STDGTI0n tables are eighteen node-specific exposure map image blocks, EXPMAPnn, created by rgsfilter.

In HTR mode the entire cross-dispersion dimension is collapsed into one row, inextricably mixing source and background events together. This mode is treated as a degenerate case of Spectroscopy in which the event coordinates are assigned randomly over the whole vertical extent of the chips. Likewise the exposure maps also cover the full cross-dispersion extent of the chips, but with variation only in the dispersion dimension. To annotate the minor structural differences between Spectroscopy and HTR processing, throughout this document a $\dag$ marks items that do not apply to HTR mode data and a $\ddag$ marks items that apply only to HTR mode data.

table: EVENTS — evlistcomb
BETA_CORR, XDSP_CORR	float32	aspect-drift corrected RGS angles — rgsangles
TIME	float64	time stamp of associated frame
FLAG	int32	status bits (boolean attributes)
BETA, XDSP	float32	uncorrected RGS angles
CHIPX, CHIPY	int16	chip-oriented pixel coordinates
PHA	int16	total uncalibrated pulse-height
SHAPE $^{\dag }$	int8	DPP shape code (may be null)
GRADE $^{\dag }$	int8	number of pixels combined
BETA_CHANNEL, XDSP_CHANNEL	int16	binned aspect-drift corrected RGS angles — rgsangles
PI	int16	calibrated pulse-height
CCDNR	int8	CCD number
SC_POINTING_RA,
SC_POINTING_DEC,
SC_POINTING_POS	real32	(optional) spacecraft pointing — rgsangles
M_LAMBDA	real32	(optional) nominal wavelength — rgsangles

table: EXPOSU0n — rgsframes
FRAME	int32	frame number
FLAG	int32	status bits (boolean attributes)
TIMEDEL	real32	integration time
TIME	real64	timestamp
FRACEXP0 $^{\dag }$ , FRACEXP1 $^{\dag }$	real32	node-specific exposure corrections for pixels rejected on-board
ASPCDSP, ASPCXDSP	real32	aspect-drift correction parameters — rgsangles

table: BADPIXnn — rgsbadpix
CHIPX, CHIPY $^{\dag }$	int16	chip-oriented pixel coordinates of column bottom
YEXTENT $^{\dag }$	int16	upward length of bad column
TYPE	int16	bad pixel type code
BADFLAG	int16	bad pixel source identifier

table: REJPIXnn — rgsevents
FRAME	int32	frame number
FLAG	int32	status bits (boolean attributes)
CHIPX, CHIPY $^{\dag }$	int16	chip-oriented pixel coordinates

The intermediate event lists contain some data of diagnostic value that is not carried into the combined event list. Except for this, there is no reason not to delete them, and accordingly they are deleted by default (parameter expunge). The diagnostic value of the intermediate files lies mostly in the PIXELS table, from which the events are reconstructed. In addition to that there are optional detector coordinate columns in the intermediate EVENTS table, which locate the event centroids to greater precision than is preserved in the combined event list. The finished state of these two tables is as follows.

table: PIXELS — rgsframes
FRAME	int32	frame number
TELX, TELY $^{\dag }$	int16	telemetered pixel coordinates
ENERGY	int16	telemetered pulse-height
CCDNODE	int8	CCD node number
SHAPE $^{\dag }$	int8	shape code (from telemetered SER)
GRADE $^{\dag }$	int8	number of pixels (from telemetered SER)
RAWX, RAWY $^{\dag }$	int16	node-oriented pixel coordinates
PI	real32	calibrated pulse-height — rgsenergy
EVENT $^{\dag }$	int32	index to associated event — rgsevents
RAWY $^{\ddag }$	attrib	nominal y-coordinate for all events

table: EVENTS (intermediate) — rgsevents
FRAME	int32	frame number
CHIPX, CHIPY $^{\dag }$	int16	chip-oriented pixel coordinates
BETA, XDSP	real32	uncorrected RGS angles
PI	int32	calibrated pulse-height
FLAG	int32	status bits (boolean attributes)
SHAPE $^{\dag }$	int8	DPP shape code (may be null)
GRADE $^{\dag }$	int8	number of pixels combined
PHA	int32	total uncalibrated pulse-height
TIME	real64	timestamp of associated frame
DETX, DETY, DETZ	real32	(optional) detector coordinates

The remainder of this section summarizes the contribution from each sub-task. The reader should consult the referenced task descriptions for full details.