STScI Logo

qpcalc xray.xproto


NAME · USAGE · DESCRIPTION · PARAMETERS · EXAMPLES · TIME_REQUIREMENTS
BUGS · SEE_ALSO

NAME

qpcalc -- Calculate new or modified event-attribute values algebraically

USAGE

qpcalc input_qpoe region qpoe eventdef outname equals

DESCRIPTION

This task evaluates an arbitrary expression that includes event-attribute names, constants, and operators, and creates a specified event-attribute in the QPOE ---or overwrites an existing event-attribute if the specified name already exists. Variables in the expression are event-attribute names in either case.

Event-Attributes may be of any type except string. If the event-attribute name contains non-alphanumeric characters, it should be preceded by a dollar sign and followed by a blank. For example, the expression "date-obs+1." contains the column "date-obs", but the task thinks that it contains two column names, "date" and "obs". To ensure that the expression is evaluated correctly, rewrite it as "$date-obs +1.". The variable "rownum" may also be used in an expression if there is no column in the table of the same name. Its value is the current row number. The expression will be evaluated using the data types of the columns and constants in the expression, with the usual rules of type promotion used in Fortran. Please remember that integer division truncates.

The output value in any row will be set to INDEF if one or more event-attribute values used in the calculation is equal to INDEF. The result will be INDEF if either of the clauses in an if expression contains a row with an INDEF value. If the result of an operation is undefined (such as division by zero) the output column will also be set to INDEF.

The following Fortran-type arithmetic operators are supported. If the second argument of the exponentiation is not an integer, the result will be undefined if the the first argument is not positive. Again, remember that integer division truncates.

+       addition                -       subtraction
*       multiplication          /       division
-       negation                **      exponentiation

The following logical operators are supported. Logical operators will return a value of 1 if true or 0 if false. Logical operators are supported in both their Fortran and SPP form.

.or. ||         logical or      .and.   &&      logical and
.eq. ==         equality        .ne.    !=      inequality
.lt. <          less than       .gt.    >       greater than
.le. <=         less or equal   .ge.    >=      greater or equal
.not. !         not

The following functions are supported. These functions all take a single argument, which may be an expression. The argument or result of trigonometric functions are in radians.

abs     absolute value          acos    arc cosine
asin    arc sine                atan    arc tangent
cos     arc cosine              cosh    hyperbolic cosine
cube    third power             double  convert to double
exp     E raised to power       int     convert to integer
log     natural logarithm       log10   common logarithm
nint    nearest integer         real    convert to real
sin     sine                    sinh    hyperbolic sine
sqr     second power            sqrt    square root
tan     tangent                 tanh    hyperbolic tangent

PARAMETERS

input_qpoe = "" prompt = input qpoe filename
The input qpoe file name. The file must have a ".qp" extension, but may be specified with or without the extension. Qpoe filters can be applied using the bracket notation to filter the input photons.

region = "" prompt = region descriptor

The region descriptor. If null is input, the entire field is copied (subject to the qpoe filters specified with the input file name). Otherwise only those photons are copied which pass the spatial region filter.

qpoe = "" prompt = output qpoe file name

The output qpoe file name. The file must have a ".qp" extension, but may be specified with or without the extension. The output file can be the same as the input file.

eventdef = "" prompt = event definition

The event definition of the output QPOE file. If the user enters the empty string, "", the event definition will be copied from the input QPOE file. See help qpoe for information on modifying the event definition.

(exposure = "NONE") [string]

The PLIO mask containing exposure information for the specified source image. If the null string is input, the name will be the same root as the source image file with a "_exp.pl" extension. If "NONE" is input, no exposure filtering is performed.

(expthresh = 0.) [real]

The percentage of total exposure required for a given source pixel to pass the exposure filter, (if an exposure mask is present). For example, if expthresh is 50.0, then only pixels whose exposure time is >= 50% will be used. An exposure threshold of 0% allows all photons to pass the exposure filter.

(clobber = no) [boolean]

Boolean flag specifying whether or not the qpoe file can be overwritten, if it already exists.

(display = 1) [int]

The display level. A display level of 0 generates no display. A display level of 1 generates a display of header information.

(sort = yes) [boolean]

Flag if events are to be sorted. If true, the type of sort is determined by the sorttype parameter.

(sorttype = "position") [string]

The type of sort to perform. This string consists of a list of event element names that specifies the order in which to sort the event record. For example, "y x time" will sort on the "y" element as the primary key, the "x" element as the secondary key, and "time" as the tertiary key. If sorting is not to be performed, this parameter can be used as a string that will go into the x_sort qpoe param to indicate the type of sorting of the events. For example, if the events are already sorted by time, and are not to be resorted, one can set sort to false and sorttype to "time", and the qpoe file will be indistinguishable from one whose events were sorted by time.

(sortsize = 1000000) [int]

The number of bytes that are to be sorted at a time. This allows users to tailor the task to the amount of available memory. If there is a lot of memory available, sortsize should be set large enough so that the task will do an in-core sort. (This requires knowing the approximate number of events and the byte size of each event.) If only a small amount of memory is available, use a smaller number. In this case, several core loads will be sorted and written to temp files, which are then merged.

(qp_internals = yes) [boolean]

Boolean flag controlling whether the internal qpoe parameters (see below) are prompted for, or whether they are defaulted to internally hardwired values. This parameter is not usually changed by the user. (Prompting is normally turned off during stand-alone debugging only.)

(qp_pagesize = 1024) [int]

Page size for the qpoe file. This parameter is internal to qpoe and should not normally be changed.

(qp_bucketlen = 2048) [int]

Bucket length for the qpoe file. This parameter is internal to qpoe and should not normally be changed.

(qp_blockfact = 1) [int]

The default block factor for IMIO. This parameter is internal to qpoe and should not normally be changed.

(qp_mkindex = yes) [boolean]

Boolean flag that an index should be made for the qpoe file. This parameter is internal to qpoe and should not normally be changed.

(qp_key = "") [string]

Key on which to make the qpoe index. This parameter is internal to qpoe and should not normally be changed.

(qp_debug = 0) [int]

Debug level for qpoe internals. This parameter is internal to qpoe and should not normally be changed.

EXAMPLES

1. Calculate a new column that is 10 times the input PHA Value

xp> qpcalc
input qpoe filename (xdata$rp110590n00.qp): 
region descriptor: 
equation (or file with equation) (): pha*10
name of output element (): pha10
output qpoe file name (.): 
event definition: 
data type for new column (short|integer|long|real|double): short

xdata$rp110590n00.qp (; no exp.) -> ./rp110590n00.qp
Creating QPOE output file: ./rp110590n00.qp

TIME REQUIREMENTS

BUGS

SEE ALSO

Documentation on table calculation (help tcalc ) for a description of the algebraic forms

Documentation on QPOE list(help qplist ) for a description of how to display existing event-attribute names and values.

Documentation on region filtering (help regions ) for a description of the spatial filter user interface.

Documentation on qpoe filtering (help qpoe ) for a description of the qpoe filter user interface.

Documentation on coordinates (help coords ) for a description of PROS coordinate conventions.


Search Form · STSDAS