STScI Logo

xhadd xray.ximages



xhadd -- add an "x_hist" history record to a qpoe or image file


xhadd image type task history


The task xhadd adds a record of "x_hist" history information to a qpoe or image file. The history record is also written to the standard IRAF history parameter.

History information is stored in the header of qpoe and imh files in parameters with the names "x_hist<nn>", where <nn> is a number from 1 to 99. (This naming convention allows all history records to be unique to 8 characters, as is required by current IRAF and FITS conventions.) History records are added automatically by xray tasks that create images or qpoe files, but can also be added manually using the xhadd task in other cases (such as imcopy or imcalc).


image = "" prompt = image file name

The image or qpoe data file. The task tries to access the image as a qpoe file, and failing that, as an image. Therefore, the file extension is only required if an image and a qpoe file exist with the same root.

type = "" prompt = special history type, if desired

The type (label) to be attached to the history record. Any string is valid, including the null string, but the following are special, in that xhdisp can selectively display records of these types: "vignetting", "exposure", "background", "bkgd", "user". Also, if the specified type is an abbreviation of one of the above, the type is expanded automatically. Thus, for example, "v" will create a vignetting history record.

task = "" prompt = task performing the operation, if desired

The name of the task that caused the historic event. Typically, this will be a standard IRAF task such as imcopy or imcalc, which, unlike xray tasks, do not update x_hist history records automatically. If the null string is entered, the history record will contain the string "no task".

history = "" prompt = history string to add

The history string to be added. Typically, this string describes the change taking place in the file and is of the form:

	task: input_file (params and aux. files) -> output_file

If the null string is entered, the history record will contain the string "no history".
(display = 1) [int]

The display level. If display is 0, no history is displayed. If display is 1, only history records of the type specified in the type parameter are displayed. If display is greater than or equal to 2, all history records are displayed.


1. Add a "user" history record to an image file - don't display history.

	cl> xhadd snr_smrot.qp "user" "" "This file was rotated..." 


A history record typically contains the name of the task that was executed to create a change in the file, and a description of the task's action:

	task: input_file (params and aux. files) -> output_file

For example, consider qpcopy, which copies one qpoe file to another through filters. This task adds history records such as:

	xhist02 = 'qpcopy: small.qp[pi=(0:5)] (circle 511 511 50)
			-> foo.qp'

where, in the given case, only photons within the specified circle and of the specified pi range are being copied to the new file.

Note, however, that the task parameter need not contain an actual task name, and the history parameter need not describe a change to the file, since these two values are merely concatenated to create a history record. One can therefore write comments into history records. For example:

	xhist03 = 'Warning: this file can be hazardous to your health'

If a null task string is input, the string "(no task)" is put into the history record. Similarly, if a null history string is input, the string "(no history)" is put into the history record.

History records can be labelled. The type argument specifies a tag that is applied to a history record. If the label is one of the recognized "special" labels, a cross reference parameter is created, if necessary, and updated with the number of that history record. The currently recognized special labels are: "vignetting", "exposure", "background", "bkgd", and "user", and the cross-reference parameters corresponding to them are: "x_vign", "x_exp", "x_bkgd", "x_bkgd", and "x_user". If a label is not recognized as one of these special ones, the history record is still labelled, but no corresponding cross-reference parameter is created.

The special labelling is used in two ways. First of all, xhdisp will selectively display specially labelled history records, if requested. For example, suppose the following history records are defined:

	xhist01 = 'xpr2qp: small.xpr (small.hdr, small.tgr, no aspect
			file) -> small.qp'
	xhist02 = 'qpcopy: small.qp[pi=(0:5)] (circle 640 513 100) ->
	xhist03 = '*user* (no task): goo only contains photons from
			sdf source #2'

If the input type parameter to xhdisp is "history" or NULL, all records will be displayed, whereas if the label string is "user" (or any abbreviation), only history record #3 will be displayed.

Secondly, note that if a particular type of label has not been added to any history record, that cross-reference parameter will not exist. Thus applications tasks need only check for existence of a parameter (using qp_accessf or imaccessf) to see if a special type of correction (e.g. exposure correction or vignetting correction, etc.) has been performed on the image.




Source Code · Search Form · STSDAS