NAME

fselect -- Creates a new FITS file by selected rows in an input FITS file based on the result of applying a boolean expression to the values found in each row of a FITS table extension.


USAGE

        fselect infile[ext#] outfile expr

DESCRIPTION

FSELECT is at the heart of the data selection capabilities of the FTOOLS. Primary use is for the filtering of data on a row by row basis using values found locally within the FITS table extension. Filtering criteria are built up with boolean subexpressions which apply to each column of data in a FITS table extension. The whole expression evaluates to true or false depending on the filtering criteria and the values of the data stored in the columns. If the expression is found to be true for a particular row, then that row is copied into a new output file specified by the user. This output file will by default include all other extensions found in the FITS file. But the user has the option of only having a basic primary extension and the table extension for which the expression is being applied placed in the output file.

General Expression Syntax

The expression can be an arbitrarily complex series of operations performed on constants, keyword values, and column data taken from the specified FITS TABLE extension. The expression must evaluate to a boolean value for each row of the table, where a value of FALSE means that the row will be excluded.

Keyword and column data are referenced by name. Any string of characters not surrounded by quotes (ie, a constant string) or followed by an open parentheses (ie, a function name) will be initially interpreted as a column name and its contents for the current row inserted into the expression. If no such column exists, a keyword of that name will be searched for and its value used, if found. To force the name to be interpreted as a keyword (in case there is both a column and keyword with the same name), precede the keyword name with a single pound sign, '#', as in '#NAXIS2'. Due to the generalities of FITS column and keyword names, if the column or keyword name contains a space or a character which might appear as an arithmetic term then inclose the name in '$' characters as in $MAX PHA$ or #$MAX-PHA$. Names are case insensitive.

To access a table entry in a row other than the current one, follow the column's name with a row offset within curly braces. For example, 'PHA{-3}' will evaluate to the value of column PHA, 3 rows above the row currently being processed. One cannot specify an absolute row number, only a relative offset. Rows that fall outside the table will be treated as undefined, or NULLs.

Boolean operators can be used in the expression in either their Fortran or C forms. The following boolean operators are available:

     "equal"         .eq. .EQ. ==  "not equal"          .ne.  .NE.  !=
     "less than"     .lt. .LT. <   "less than/equal"    .le.  .LE.  <= =<
     "greater than"  .gt. .GT. >   "greater than/equal" .ge.  .GE.  >= =>
     "or"            .or. .OR. ||  "and"                .and. .AND. &&
     "negation"     .not. .NOT. !  "approx. equal(1e-7)"  ~

Note that the exclamation point, '!', is a special UNIX character, so if it is used on the command line rather than entered at a task prompt, it must be preceded by a backslash to force the UNIX shell to ignore it.

The expression may also include arithmetic operators and functions. Trigonometric functions use radians, not degrees. The following arithmetic operators and functions can be used in the expression (function names are case insensitive). A null value will be returned in case of illegal operations such as divide by zero, sqrt(negative) log(negative), log10(negative), arccos(.gt. 1), arcsin(.gt. 1).

     "addition"           +          "subtraction"          -
     "multiplication"     *          "division"             /
     "negation"           -          "exponentiation"       **   ^
     "absolute value"     abs(x)     "cosine"               cos(x)
     "sine"               sin(x)     "tangent"              tan(x)
     "arc cosine"         arccos(x)  "arc sine"             arcsin(x)
     "arc tangent"        arctan(x)  "arc tangent"          arctan2(y,x)
     "hyperbolic cos"     cosh(x)    "hyperbolic sin"       sinh(x)
     "hyperbolic tan"     tanh(x)    "round to nearest int" round(x)
     "round down to int"  floor(x)   "round up to int"      ceil(x)
     "exponential"        exp(x)     "square root"          sqrt(x)
     "natural log"        log(x)     "common log"           log10(x)
     "modulus"            x % y      
     "bitwise AND"        x & y      "bitwise OR"           x | y
     "bitwise XOR"        x ^^ y     (bitwise operators are 32-bit int only)
     "random # [0.0,1.0)" random()
     "random Gausian"     randomn()  "random Poisson"       randomp(x)
     "minimum"            min(x,y)   "maximum"              max(x,y)
     "cumulative sum"     accum(x)   "sequential difference" seqdiff(x)
     "if-then-else"       b?x:y
     "angular separation" angsep(ra1,dec1,ra2,de2) (all in degrees)
     "substring"          strmid(s,p,n) "string search"     strstr(s,r)

The bitwise operators for AND, OR and XOR operate upon 32-bit integer expressions only.

Three different random number functions are provided: random(), with no arguments, produces a uniform random deviate between 0 and 1; randomn(), also with no arguments, produces a normal (Gaussian) random deviate with zero mean and unit standard deviation; randomp(x) produces a Poisson random deviate whose expected number of counts is X. X may be any positive real number of expected counts, including fractional values, but the return value is an integer.

When the random functions are used in a vector expression, by default the same random value will be used when evaluating each element of the vector. If different random numbers are desired, then the name of a vector column should be supplied as the single argument to the random function (e.g., "flux + 0.1 * random(flux)", where "flux" is the name of a vector column). This will create a vector of random numbers that will be used in sequence when evaluating each element of the vector expression.

An alternate syntax for the min and max functions has only a single argument which should be a vector value (see below). The result will be the minimum/maximum element contained within the vector.

The accum(x) function forms the cumulative sum of x, element by element. Vector columns are supported simply by performing the summation process through all the values. Null values are treated as 0. The seqdiff(x) function forms the sequential difference of x, element by element. The first value of seqdiff is the first value of x. A single null value in x causes a pair of nulls in the output. The seqdiff and accum functions are functional inverses, i.e., seqdiff(accum(x)) == x as long as no null values are present.

The angsep function computes the angular separation in degrees between 2 celestial positions, where the first 2 parameters give the RA-like and Dec-like coordinates (in decimal degrees) of the first position, and the 3rd and 4th parameters give the coordinates of the second position.

In the if-then-else expression, "b?x:y", b is an explicit boolean value or expression. There is no automatic type conversion from numeric to boolean values, so one needs to use "iVal!=0" instead of merely "iVal" as the boolean argument. x and y can be any scalar data type (including string).

The substring function strmid(S,P,N) extracts a substring from S, starting at string position P, with a substring length N. The first character position in S is labeled as 1. If P is 0, or refers to a position beyond the end of S, then the extracted substring will be NULL. S, P, and N may be functions of other columns.

The string search function strstr(S,R) searches for the first occurrence of the substring R in S. The result is an integer, indicating the character position of the first match (where 1 is the first character position of S). If no match is found, then strstr() returns a NULL value.

The following type casting operators are available, where the inclosing parentheses are required and taken from the C language usage. Also, the integer to real casts values to double precision:

                 "real to integer"    (int) x     (INT) x
                 "integer to real"    (float) i   (FLOAT) i

In addition, several constants are built in for use in numerical expressions:

        #pi           3.1415...         #e            2.7182...
        #deg          #pi/180           #row          current row number
        #null         undefined value   #snull        undefined string

A string constant must be enclosed in quotes as in 'Crab'. The "null" constants are useful for conditionally setting table values to a NULL, or undefined, value (eg., "col1==-99 ? #NULL : col1").

Integer constants may be specified using the following notation,

            13245   decimal integer
            0x12f3  hexidecimal integer
            0o1373  octal integer
            0b01001 binary integer

Note that integer constants are only allowed to be 32-bit, i.e. between -2^(31) and +2^(31). Integer constants may be used in any arithmetic expression where an integer would be appropriate. Thus, they are distinct from bitmasks (which may be of arbitrary length, allow the "wildcard" bit, and may only be used in logical expressions; see below).

There is also a function for testing if two values are close to each other, i.e., if they are "near" each other to within a user specified tolerance. The arguments, value_1 and value_2 can be integer or real and represent the two values who's proximity is being tested to be within the specified tolerance, also an integer or real:

                     near(value_1, value_2, tolerance)

When a NULL, or undefined, value is encountered in the FITS table, the expression will evaluate to NULL unless the undefined value is not actually required for evaluation, eg. "TRUE .or. NULL" evaluates to TRUE. The following two functions allow some NULL detection and handling:

              "a null value?"              ISNULL(x)
              "define a value for null"    DEFNULL(x,y)
              "declare certain value null" SETNULL(x,y)

ISNULL(x) returns a boolean value of TRUE if the argument x is NULL. DEFNULL(x,y) "defines" a value to be substituted for NULL values; it returns the value of x if x is not NULL, otherwise it returns the value of y. SETNULL(x,y) allows NULL values to be inserted into a variable; if x==y, a NULL value is returned; otherwise y is returned (x and y must be numerical, and x must be a scalar).

Bit Masks

Bit masks can be used to select out rows from bit columns (TFORMn = #X) in FITS files. To represent the mask, binary, octal, and hex formats are allowed:

                  binary:   b0110xx1010000101xxxx0001
                  octal:    o720x1 -> (b111010000xxx001)
                  hex:      h0FxD  -> (b00001111xxxx1101)

In all the representations, an x or X is allowed in the mask as a wild card. Note that the x represents a different number of wild card bits in each representation. All representations are case insensitive. Although bitmasks may be of arbitrary length and contain a wildcard, they may only be used in logical expressions, unlike integer constants (see above) which may be used in any arithmetic expression.

To construct the boolean expression using the mask as the boolean equal operator described above on a bit table column. For example, if you had a 7 bit column named flags in a FITS table and wanted all rows having the bit pattern 0010011, the selection expression would be:

                             flags == b0010011

or

                             flags .eq. b10011

It is also possible to test if a range of bits is less than, less than equal, greater than and greater than equal to a particular boolean value:

                             flags <= bxxx010xx
                             flags .gt. bxxx100xx
                             flags .le. b1xxxxxxx

Notice the use of the x bit value to limit the range of bits being compared.

It is not necessary to specify the leading (most significant) zero (0) bits in the mask, as shown in the second expression above.

Bit wise AND, OR and NOT operations are also possible on two or more bit fields using the '&'(AND), '|'(OR), and the '!'(NOT) operators. All of these operators result in a bit field which can then be used with the equal operator. For example:

                           (!flags) == b1101100
                           (flags & b1000001) == bx000001

Bit fields can be appended as well using the '+' operator. Strings can be concatenated this way, too.

Vector Columns

Vector columns can also be used in building the expression. No special syntax is required if one wants to operate on all elements of the vector. Simply use the column name as for a scalar column. Vector columns can be freely intermixed with scalar columns or constants in virtually all expressions. The result will be of the same dimension as the vector. Two vectors in an expression, though, need to have the same number of elements and have the same dimensions. The only places a vector column cannot be used (for now, anyway) are the SAO region functions and the NEAR boolean function.

Arithmetic and logical operations are all performed on an element by element basis. Comparing two vector columns, eg "COL1 == COL2", thus results in another vector of boolean values indicating which elements of the two vectors are equal.

Eight functions are available that operate on a vector and return a scalar result:

         "minimum"      MIN(V)          "maximum"               MAX(V)
         "average"      AVERAGE(V)      "median"                MEDIAN(V)
         "sumation"     SUM(V)          "standard deviation"    STDDEV(V)
         "# of values"  NELEM(V)        "# of non-null values"  NVALID(V)

where V represents the name of a vector column or a manually constructed vector using curly brackets as described below. The first 6 of these functions ignore any null values in the vector when computing the result. The STDDEV() function computes the sample standard deviation, i.e. it is proportional to 1/SQRT(N-1) instead of 1/SQRT(N), where N is NVALID(V).

The SUM function literally sums all the elements in x, returning a scalar value. If V is a boolean vector, SUM returns the number of TRUE elements. The NELEM function returns the number of elements in vector V whereas NVALID return the number of non-null elements in the vector. (NELEM also operates on bit and string columns, returning their column widths.) As an example, to test whether all elements of two vectors satisfy a given logical comparison, one can use the expression

               SUM( COL1 > COL2 ) == NELEM( COL1 )

which will return TRUE if all elements of COL1 are greater than their corresponding elements in COL2.

To specify a single element of a vector, give the column name followed by a comma-separated list of coordinates enclosed in square brackets. For example, if a vector column named PHAS exists in the table as a one dimensional, 256 component list of numbers from which you wanted to select the 57th component for use in the expression, then PHAS[57] would do the trick. Higher dimensional arrays of data may appear in a column. But in order to interpret them, the TDIMn keyword must appear in the header. Assuming that a (4,4,4,4) array is packed into each row of a column named ARRAY4D, the (1,2,3,4) component element of each row is accessed by ARRAY4D[1,2,3,4]. Arrays up to dimension 5 are currently supported. Each vector index can itself be an expression, although it must evaluate to an integer value within the bounds of the vector. Vector columns which contain spaces or arithmetic operators must have their names enclosed in "$" characters as with $ARRAY-4D$[1,2,3,4].

A more C-like syntax for specifying vector indices is also available. The element used in the preceding example alternatively could be specified with the syntax ARRAY4D[4][3][2][1]. Note the reverse order of indices (as in C), as well as the fact that the values are still ones-based (as in Fortran -- adopted to avoid ambiguity for 1D vectors). With this syntax, one does not need to specify all of the indices. To extract a 3D slice of this 4D array, use ARRAY4D[4].

Variable-length vector columns are not supported.

Vectors can be manually constructed within the expression using a comma-separated list of elements surrounded by curly braces ('{}'). For example, '{1,3,6,1}' is a 4-element vector containing the values 1, 3, 6, and 1. The vector can contain only boolean, integer, and real values (or expressions). The elements will be promoted to the highest datatype present. Any elements which are themselves vectors, will be expanded out with each of its elements becoming an element in the constructed vector.

Good Time Interval Filtering and Calculation

There are two functions for filtering and calculating based on Good Time Intervals, or GTIs. GTIs are commonly used to express fragmented time ranges that are not easy to express with a single start and stop time. The time intervals are defined in a FITS table extension which contains 2 columns giving the start and stop time of each good interval.

A common filtering method involves selecting rows which have a time value which lies within any GTI. The gtifilter() filtering operation accepts only those rows of the input table which have an associated time which falls within one of the time intervals defined in a separate GTI extension. gtifilter(a,b,c,d) evaluates each row of the input table and returns TRUE or FALSE depending whether the row is inside or outside the good time interval. The syntax is

           gtifilter( [ "gtifile" [, expr [, "STARTCOL", "STOPCOL" ] ] ] )
         or
           gtifilter( [ 'gtifile' [, expr [, 'STARTCOL', 'STOPCOL' ] ] ] )

where each "[]" demarks optional parameters. Note that the quotes around the gtifile and START/STOP column are required. Either single or double quotes may be used. In cases where this expression is entered on the Unix command line, enclose the entire expression in double quotes, and then use single quotes within the expression to enclose the 'gtifile' and other terms. It is also usually possible to do the reverse, and enclose the whole expression in single quotes and then use double quotes within the expression. The gtifile, if specified, can be blank ("") which will mean to use the first extension with the name "*GTI*" in the current file, a plain extension specifier (eg, "+2", "[2]", or "[STDGTI]") which will be used to select an extension in the current file, or a regular filename with or without an extension specifier which in the latter case will mean to use the first extension with an extension name "*GTI*". Expr can be any arithmetic expression, including simply the time column name. A vector time expression will produce a vector boolean result. STARTCOL and STOPCOL are the names of the START/STOP columns in the GTI extension. If one of them is specified, they both must be.

In its simplest form, no parameters need to be provided -- default values will be used. The expression "gtifilter()" is equivalent to

        gtifilter( "", TIME, "*START*", "*STOP*" )

This will search the current file for a GTI extension, filter the TIME column in the current table, using START/STOP times taken from columns in the GTI extension with names containing the strings "START" and "STOP". The wildcards ('*') allow slight variations in naming conventions such as "TSTART" or "STARTTIME". The same default values apply for unspecified parameters when the first one or two parameters are specified. The function automatically searches for TIMEZERO/I/F keywords in the current and GTI extensions, applying a relative time offset, if necessary.

A separate function, gtioverlap(a,b,c,d,e), computes the overlap between a user-requested time range and the entries in a GTI. The cases of no overlap, partial overlap, or overlap of many GTIs within the user requested range are handled. gtioverlap() is very useful for calculating exposure times and fractional exposures of individual time bins, say for a light curve. The syntax of gtioverlap() is

           gtioverlap( "gtifile" , startExpr, stopExpr [, "STARTCOL", "STOPCOL" ] )
         or
           gtioverlap( 'gtifile' , startExpr, stopExpr [, 'STARTCOL', 'STOPCOL' ] )

The requirements for specifying the gtifile are the same as for gtifilter() as described above. Unlike gtifilter(), the startExpr and stopExpr are not optional. startExpr provides a start of the user requested time interval. startExpr is typically TIME, but can be any valid expression. Likewise, stopExpr provides the stop of the user requested time interval, and can be an expression. For example, for a light curve with a TIME column and time bin size of 1.0 seconds, the expression

           gtioverlap('gtifile',TIME,TIME+1.0)

would calculate the amount of overlap exposure time between each one second time bin and the GTI in 'gtifile'. In this case the time bin is assumed to begin at the time specified by TIME and end 1 second later. Neither startExpr nor stopExpr are required to be constant, and a light curve is not required to have a constant bin size. For tables, the overlap is calculated for each entry in the table.

It is also possible to calculate a single overlap value, which would typically be placed in a keyword. For example, a way to to compute the total overlap exposure of a file whose TIME column is bounded by the keywords TSTART and TSTOP, overlapping with the specified GTI, would be

           #EXPOSURE = gtioverlap('gtifile',#TSTART,#TSTOP)

The #EXPOSURE syntax with a leading # ensures that the requested values are treated as keywords. Otherwise, a column named EXPOSURE will be created with the (constant) exposure value in each entry.

Spatial Region Filtering

Another common filtering method selects rows based on whether the spatial position associated with each row is located within a given 2-dimensional region. The syntax for this high-level filter is

        regfilter( "regfilename" [ , Xexpr, Yexpr [ , "wcs cols" ] ] )

where each "[]" demarks optional parameters. The region file name is required and must be enclosed in quotes. The remaining parameters are optional. The region file is an ASCII text file which contains a list of one or more geometric shapes (circle, ellipse, box, etc.) which defines a region on the celestial sphere or an area within a particular 2D image. The region file is typically generated using an image display program such as fv/POW (distribute by the HEASARC), or ds9 (distributed by the Smithsonian Astrophysical Observatory). Users should refer to the documentation provided with these programs for more details on the syntax used in the region files.

In its simpliest form, (e.g., regfilter("region.reg") ) the coordinates in the default 'X' and 'Y' columns will be used to determine if each row is inside or outside the area specified in the region file. Alternate position column names, or expressions, may be entered if needed, as in

             regfilter("region.reg", XPOS, YPOS)

Region filtering can be applied most unambiguously if the positions in the region file and in the table to be filtered are both give in terms of absolute celestial coordinate units. In this case the locations and sizes of the geometric shapes in the region file are specified in angular units on the sky (e.g., positions given in R.A. and Dec. and sizes in arcseconds or arcminutes). Similarly, each row of the filtered table will have a celestial coordinate associated with it. This association is usually implemented using a set of so-called 'World Coordinate System' (or WCS) FITS keywords that define the coordinate transformation that must be applied to the values in the 'X' and 'Y' columns to calculate the coordinate.

Alternatively, one can perform spatial filtering using unitless 'pixel' coordinates for the regions and row positions. In this case the user must be careful to ensure that the positions in the 2 files are self-consistent. A typical problem is that the region file may be generated using a binned image, but the unbinned coordinates are given in the event table. The ROSAT events files, for example, have X and Y pixel coordinates that range from 1 - 15360. These coordinates are typically binned by a factor of 32 to produce a 480x480 pixel image. If one then uses a region file generated from this image (in image pixel units) to filter the ROSAT events file, then the X and Y column values must be converted to corresponding pixel units as in:

             regfilter("rosat.reg", X/32.+.5, Y/32.+.5)

Note that this binning conversion is not necessary if the region file is specified using celestial coordinate units instead of pixel units because CFITSIO is then able to directly compare the celestial coordinate of each row in the table with the celestial coordinates in the region file without having to know anything about how the image may have been binned.

The last "wcs cols" parameter should rarely be needed. If supplied, this string contains the names of the 2 columns (space or comma separated) which have the associated WCS keywords. If not supplied, the filter will scan the X and Y expressions for column names. If only one is found in each expression, those columns will be used, otherwise an error will be returned.

These region shapes are supported (names are case insensitive):

        Point         ( X1, Y1 )               <- One pixel square region
        Line          ( X1, Y1, X2, Y2 )       <- One pixel wide region
        Polygon       ( X1, Y1, X2, Y2, ... )  <- Rest are interiors with
        Rectangle     ( X1, Y1, X2, Y2, A )       | boundaries considered
        Box           ( Xc, Yc, Wdth, Hght, A )   V within the region
        Diamond       ( Xc, Yc, Wdth, Hght, A )
        Circle        ( Xc, Yc, R )
        Annulus       ( Xc, Yc, Rin, Rout )
        Ellipse       ( Xc, Yc, Rx, Ry, A )
        Elliptannulus ( Xc, Yc, Rinx, Riny, Routx, Routy, Ain, Aout )
        Sector        ( Xc, Yc, Amin, Amax )

where (Xc,Yc) is the coordinate of the shape's center; (Xn,Yn) are the coordinates of the shape's edges; Rxxx are the shapes' various Radii or semimajor/minor axes; and Axxx are the angles of rotation (or bounding angles for Sector) in degrees. For rotated shapes, the rotation angle can be left off, indicating no rotation. Common alternate names for the regions can also be used: rotbox = box; rotrectangle = rectangle; (rot)rhombus = (rot)diamond; and pie = sector. When a shape's name is preceded by a minus sign, '-', the defined region is instead the area *outside* its boundary (ie, the region is inverted). All the shapes within a single region file are OR'd together to create the region, and the order is significant. The overall way of looking at region files is that if the first region is an excluded region then a dummy included region of the whole detector is inserted in the front. Then each region specification as it is processed overrides any selections inside of that region specified by previous regions. Another way of thinking about this is that if a previous excluded region is completely inside of a subsequent included region the excluded region is ignored.

The positional coordinates may be given either in pixel units, decimal degrees or hh:mm:ss.s, dd:mm:ss.s units. The shape sizes may be given in pixels, degrees, arcminutes, or arcseconds. Look at examples of region file produced by fv/POW or ds9 for further details of the region file format.

There are three functions that are primarily for use with SAO region files and the FSAOI task, but they can be used directly. They return a boolean true or false depending on whether a two dimensional point is in the region or not:

     "point in a circular region"
           circle(xcntr,ycntr,radius,Xcolumn,Ycolumn)
     
     "point in an elliptical region"
          ellipse(xcntr,ycntr,xhlf_wdth,yhlf_wdth,rotation,Xcolumn,Ycolumn)
     
     "point in a rectangular region"
              box(xcntr,ycntr,xfll_wdth,yfll_wdth,rotation,Xcolumn,Ycolumn)
     
     where 
        (xcntr,ycntr) are the (x,y) position of the center of the region
        (xhlf_wdth,yhlf_wdth) are the (x,y) half widths of the region
        (xfll_wdth,yfll_wdth) are the (x,y) full widths of the region
        (radius) is half the diameter of the circle
        (rotation) is the angle(degrees) that the region is rotated with
              respect to (xcntr,ycntr)
        (Xcoord,Ycoord) are the (x,y) coordinates to test, usually column
              names
        NOTE: each parameter can itself be an expression, not merely a
              column name or constant.


PARAMETERS

infile [filename]
A file name (including optional extension number in square brackets) of the FITS table to be filtered by the boolean expression.

outfile [filename]
The name of the created FITS file to contain the selected rows from the input table. If preceeded by a !, an existing file of the same name will be overwritten.

expr [string]
The boolean expression used to select out rows in the FITS file. A text file containing the expression can be specified by preceding the filename with '@', such as '@file.txt'. The expression in the file can be arbitrarily complex and extend over multiple lines of the file. Lines that begin with 2 slash characters ('//') will be ignored and may be used to add comments to the file.

(histkw=yes) [boolean]
If true, history records will be added to the output file primary header indicating that FSELECT created the file, and a history records of the expression used will be added to the extension header.

(copyall=yes) [boolean]
If true(yes), all other extensions, including the primary array are copied to the output file.

(keycopy=yes) [boolean]
If true, all extra keywords, in the extension where selection is being applied are copied to the output file. If false, only the required set of keywords will be written.

(clobber=no) [boolean]
If true, an existing file with the same name as the requested output file will be overwritten.


EXAMPLES

1. Extract all binary stars brighter than fifth magnitude from a FITS file named stars.fits and write the result to a FITS file named bbright.fits:

           ft> fselect stars.fits bbright.fits "binary && mag <= 5.0"

2. Extract all rows between 125 and 175 from a FITS file named manyrows.fits and write the result to a FITS file named somerows.fits:

           ft> fselect manyrows.fits somerows.fits "#row >= 125 && #row <= 175"

3. Extract all rows that have the (4,5) component of the IMAGE column greater than 100 in a FITS file named vectors.fits and write the result to a FITS file named vec.fits:

           ft> fselect vector.fits vec.fits "IMAGE[4,5] .gt. 100"

4. Extract all rows having the absolute value of the sine of theta less than a half from a FITS file named angles.fits and write the result to a FITS file named result.fits where the angles are tabulated in degrees:

           ft> fselect angles.fits result.fits "abs(sin(theta * #deg)) < 0.5"

5. Extract all rows containing a spectrum, held in vector column SPEC, with at least one value 3 times greater than the background level held in a keyword, BACKGRND:

           ft> fselect spec.fits out.fits "SUM( SPEC > 3*BACKGRND )>=1"

6. Select rows whose TIME column value lies within the START and STOP times of the GTI (Good Time Interval) extension (which in this case is in the same input file as the EVENTS extension).

           ft> fselect "rosat.fits[events]" out.fits 
              "gtifilter('',time,'start','stop')"

Note that the whole expression is enclosed in double quotes and the individual terms are enclosed in single quotes.


BUGS


SEE ALSO

ftselect, ftcalc, ftcopy, fsaoi. fv, the interactive FITS file editor, can also be used to extract selected rows from a table.

CATEGORY

Jul98 ftools.futils