diff options
| author | William Joye <wjoye@cfa.harvard.edu> | 2016-10-26 21:13:00 (GMT) |
|---|---|---|
| committer | William Joye <wjoye@cfa.harvard.edu> | 2016-10-26 21:13:00 (GMT) |
| commit | da2e3d212171bbe64c1af39114fd067308656990 (patch) | |
| tree | 9601f7ed15fa1394762124630c12a792bc073ec2 /funtools/doc/programs.html | |
| parent | 76b109ad6d97d19ab835596dc70149ef379f3733 (diff) | |
| download | blt-da2e3d212171bbe64c1af39114fd067308656990.zip blt-da2e3d212171bbe64c1af39114fd067308656990.tar.gz blt-da2e3d212171bbe64c1af39114fd067308656990.tar.bz2 | |
rm funtools for update
Diffstat (limited to 'funtools/doc/programs.html')
| -rw-r--r-- | funtools/doc/programs.html | 3497 |
1 files changed, 0 insertions, 3497 deletions
diff --git a/funtools/doc/programs.html b/funtools/doc/programs.html deleted file mode 100644 index 00d4dc7..0000000 --- a/funtools/doc/programs.html +++ /dev/null @@ -1,3497 +0,0 @@ -<HTML> -<HEAD> -<TITLE>Funtools Programs</TITLE> -</HEAD> -<BODY> -<H2>Funtools Programs</H2> - -<H2>Summary</H2> - -<P> -<PRE> - -<A HREF="./programs.html#funcalc">funcalc</A> [-n] [-a argstr] [-e expr] [-f file] [-l link] [-p prog] [-u] <iname> [oname [columns]] - -<A HREF="./programs.html#funcen">funcen</A> [-i] [-n iter] [-t tol] [-v lev] <iname> <region> - -<A HREF="./programs.html#funcnts">funcnts</A> [switches] <source_file> [source_region] [bkgd_file] [bkgd_region|bkgd_cnts] - -<A HREF="./programs.html#funcone">funcone</A> [-n] [-x|-X|-j|-J] [[-l|-L] list] [-r ra_col] [-d dec_col] <iname> <oname> <ra[hdr]> <dec[hdr]> <radius[dr'"]> [columns] - -<A HREF="./programs.html#fundisp">fundisp</A> [-f format] [-l] [-n] [-T] <iname> [columns|bitpix=n] - -<A HREF="./programs.html#funhead">funhead</A> [-a] [-l] [-s] [-t] [-L] <iname> [oname ename] - -<A HREF="./programs.html#funhist">funhist</A> [-n|-w|-T] <iname> [column] [[lo_edge:hi_edge:]bins] - -<A HREF="./programs.html#funimage">funimage</A> [-a] [-l] [-p x|y] <iname> <oname> [bitpix=n] - -<A HREF="./programs.html#funindex">funindex</A> <iname> <key> [oname] - -<A HREF="./programs.html#funjoin">funjoin</A> [switches] <ifile1> <ifile2> ... <ifilen> <ofile> - -<A HREF="./programs.html#funmerge">funmerge</A> <iname1> <iname2> ... <oname> - -<A HREF="./programs.html#funsky">funsky</A> [switches] <iname1> [<lname2> <col1> <col2>] - -<A HREF="./programs.html#funtable">funtable</A> [-a] [-i|-z] [-m] [-s cols] <iname> <oname> [columns] - -<A HREF="./programs.html#funtbl">funtbl</A> [-c cols] [-h] [-n table] [-p prog] [-s sep] [-T] <iname> -</PRE> - -<!-- =defdoc funcalc funcalc 1 --> - -<!-- =section funcalc NAME --> -<H2><A NAME="funcalc">funcalc - Funtools calculator (for binary tables)</A></H2> -<!-- =section funcalc SYNOPSIS --> -<B> -<PRE> -funcalc [-n] [-a argstr] [-e expr] [-f file] [-l link] [-p prog] <iname> [oname [columns]] -</PRE> -</B> - -<!-- =section funcalc OPTIONS --> -<P> -<PRE> - -a argstr # user arguments to pass to the compiled program - -e expr # funcalc expression - -f file # file containing funcalc expression - -l libs # libs to add to link command - -n # output generated code instead of compiling and executing - -p prog # generate named program, no execution - -u # die if any variable is undeclared (don't auto-declare) -</PRE> - -<!-- =section funcalc DESCRIPTION --> -<P> -<B>funcalc</B> is a calculator program that allows arbitrary -expressions to be constructed, compiled, and executed on columns in a -Funtools table (FITS binary table or raw event file). It works by -integrating user-supplied expression(s) into a template C program, -then compiling and executing the program. <B>funcalc</B> expressions -are C statements, although some important simplifications (such -as automatic declaration of variables) are supported. - -<P> -<B>funcalc</B> expressions can be specified in three ways: on the -command line using the <B>-e [expression]</B> switch, in a file using -the <B>-f [file]</B> switch, or from stdin (if neither <B>-e</B> nor -<B>-f</B> is specified). Of course a file containing <B>funcalc</B> -expressions can be read from stdin. - -<P> -Each invocation of <B>funcalc</B> requires an input Funtools table -file to be specified as the first command line argument. The output -Funtools table file is the second optional argument. It is needed only -if an output FITS file is being created (i.e., in cases where the -<B>funcalc</B> expression only prints values, no output file is -needed). If input and output file are both specified, a third optional -argument can specify the list of columns to activate (using -<A HREF="./library.html#funcolumnactivate">FunColumnActivate()</A>). Note -that <B>funcalc</B> determines whether or not to generate code for -writing an output file based on the presence or absence of an -output file argument. - -<P> -A <B>funcalc</B> expression executes on each row of a table and -consists of one or more C statements that operate on the columns of -that row (possibly using temporary variables). Within an expression, -reference is made to a column of the <B>current</B> row using the C -struct syntax <B>cur->[colname]</B>, e.g. cur->x, cur->pha, etc. -Local scalar variables can be defined using C declarations at very the -beginning of the expression, or else they can be defined automatically -by <B>funcalc</B> (to be of type double). Thus, for example, a swap of -columns x and y in a table can be performed using either of the -following equivalent <B>funcalc</B> expressions: - -<PRE> - double temp; - temp = cur->x; - cur->x = cur->y; - cur->y = temp; -</PRE> - -or: - -<PRE> - temp = cur->x; - cur->x = cur->y; - cur->y = temp; -</PRE> - -When this expression is executed using a command such as: -<PRE> - funcalc -f swap.expr itest.ev otest.ev -</PRE> -the resulting file will have values of the x and y columns swapped. - -<P> -By default, the data type of the variable for a column is the same as -the data type of the column as stored in the file. This can be changed -by appending ":[dtype]" to the first reference to that column. In the -example above, to force x and y to be output as doubles, specify the -type 'D' explicitly: -<PRE> - temp = cur->x:D; - cur->x = cur->y:D; - cur->y = temp; -</PRE> - -Data type specifiers follow standard FITS table syntax for defining -columns using TFORM: -<UL> -<LI>A: ASCII characters -<LI>B: unsigned 8-bit char -<LI>I: signed 16-bit int -<LI>U: unsigned 16-bit int (not standard FITS) -<LI>J: signed 32-bit int -<LI>V: unsigned 32-bit int (not standard FITS) -<LI>E: 32-bit float -<LI>D: 64-bit float -<LI>X: bits (treated as an array of chars) -</UL> -Note that only the first reference to a column should contain the -explicit data type specifier. - -<P> -Of course, it is important to handle the data type of the columns -correctly. One of the most frequent cause of error in <B>funcalc</B> -programming is the implicit use of the wrong data type for a column in -expression. For example, the calculation: -<PRE> - dx = (cur->x - cur->y)/(cur->x + cur->y); -</PRE> -usually needs to be performed using floating point arithmetic. In -cases where the x and y columns are integers, this can be done by -reading the columns as doubles using an explicit type specification: -<PRE> - dx = (cur->x:D - cur->y:D)/(cur->x + cur->y); -</PRE> - -Alternatively, it can be done using C type-casting in the expression: -<PRE> - dx = ((double)cur->x - (double)cur->y)/((double)cur->x + (double)cur->y); -</PRE> - -<P> -In addition to accessing columns in the current row, reference also -can be made to the <B>previous</B> row using <B>prev->[colname]</B>, -and to the <B>next</B> row using <B>next->[colname]</B>. Note that if -<B>prev->[colname]</B> is specified in the <B>funcalc</B> -expression, the very first row is not processed. If -<B>next->[colname]</B> is specified in the <B>funcalc</B> -expression, the very last row is not processed. In this way, -<B>prev</B> and <B>next</B> are guaranteed always to point to valid -rows. For example, to print out the values of the current x column -and the previous y column, use the C fprintf function in a -<B>funcalc</B> expression: -<PRE> - fprintf(stdout, "%d %d\n", cur->x, prev->y); -</PRE> - -<P> -New columns can be specified using the same <B>cur->[colname]</B> -syntax by appending the column type (and optional tlmin/tlmax/binsiz -specifiers), separated by colons. For example, cur->avg:D will define -a new column of type double. Type specifiers are the same those -used above to specify new data types for existing columns. - -<P> -For example, to create and output a new column that is the average value of the -x and y columns, a new "avg" column can be defined: -<PRE> - cur->avg:D = (cur->x + cur->y)/2.0 -</PRE> -Note that the final ';' is not required for single-line expressions. - -<P> -As with FITS TFORM data type specification, the column data type -specifier can be preceded by a numeric count to define an array, e.g., -"10I" means a vector of 10 short ints, "2E" means two single precision -floats, etc. A new column only needs to be defined once in a -<B>funcalc</B> expression, after which it can be used without -re-specifying the type. This includes reference to elements of a -column array: - -<PRE> - cur->avg[0]:2D = (cur->x + cur->y)/2.0; - cur->avg[1] = (cur->x - cur->y)/2.0; -</PRE> - -<P> -The 'X' (bits) data type is treated as a char array of dimension -(numeric_count/8), i.e., 16X is processed as a 2-byte char array. Each -8-bit array element is accessed separately: -<PRE> - cur->stat[0]:16X = 1; - cur->stat[1] = 2; -</PRE> -Here, a 16-bit column is created with the MSB is set to 1 and the LSB set to 2. - -<P> -By default, all processed rows are written to the specified output -file. If you want to skip writing certain rows, simply execute the C -"continue" statement at the end of the <B>funcalc</B> expression, -since the writing of the row is performed immediately after the -expression is executed. For example, to skip writing rows whose -average is the same as the current x value: - -<PRE> - cur->avg[0]:2D = (cur->x + cur->y)/2.0; - cur->avg[1] = (cur->x - cur->y)/2.0; - if( cur->avg[0] == cur->x ) - continue; -</PRE> - -<P> -If no output file argument is specified on the <B>funcalc</B> command -line, no output file is opened and no rows are written. This is useful -in expressions that simply print output results instead of generating -a new file: -<PRE> - fpv = (cur->av3:D-cur->av1:D)/(cur->av1+cur->av2:D+cur->av3); - fbv = cur->av2/(cur->av1+cur->av2+cur->av3); - fpu = ((double)cur->au3-cur->au1)/((double)cur->au1+cur->au2+cur->au3); - fbu = cur->au2/(double)(cur->au1+cur->au2+cur->au3); - fprintf(stdout, "%f\t%f\t%f\t%f\n", fpv, fbv, fpu, fbu); -</PRE> -In the above example, we use both explicit type specification -(for "av" columns) and type casting (for "au" columns) to ensure that -all operations are performed in double precision. - -<P> -When an output file is specified, the selected input table is -processed and output rows are copied to the output file. Note that -the output file can be specified as "stdout" in order to write the -output rows to the standard output. If the output file argument is -passed, an optional third argument also can be passed to specify which -columns to process. - -<p> -In a FITS binary table, it sometimes is desirable to copy all of the -other FITS extensions to the output file as well. This can be done by -appending a '+' sign to the name of the extension in the input file -name. See <B>funtable</B> for a related example. - -<P> -<B>funcalc</B> works by integrating the user-specified expression -into a template C program called <A HREF="./tabcalc.c">tabcalc.c</A>. -The completed program then is compiled and executed. Variable -declarations that begin the <B>funcalc</B> expression are placed in -the local declaration section of the template main program. All other -lines are placed in the template main program's inner processing -loop. Other details of program generation are handled -automatically. For example, column specifiers are analyzed to build a -C struct for processing rows, which is passed to -<A HREF="./library.html#funcolumnselect">FunColumnSelect()</A> and used -in <A HREF="./library.html#funtablerowget">FunTableRowGet()</A>. If -an unknown variable is used in the expression, resulting in a -compilation error, the program build is retried after defining the -unknown variable to be of type double. - -<P> -Normally, <B>funcalc</B> expression code is added to -<B>funcalc</B> row processing loop. It is possible to add code -to other parts of the program by placing this code inside -special directives of the form: -<PRE> - [directive name] - ... code goes here ... - end -</PRE> - -The directives are: -<UL> -<LI><B>global</B> add code and declarations in global space, before the main routine. - -<LI><B>local</B> add declarations (and code) just after the local declarations in -main - -<LI><B>before</B> add code just before entering the main row processing loop - -<LI><B>after</B> add code just after exiting the main row processing loop -</UL> - -Thus, the following <B>funcalc</B> expression will declare global -variables and make subroutine calls just before and just after the -main processing loop: -<PRE> - global - double v1, v2; - double init(void); - double finish(double v); - end - before - v1 = init(); - end - ... process rows, with calculations using v1 ... - after - v2 = finish(v1); - if( v2 < 0.0 ){ - fprintf(stderr, "processing failed %g -> %g\n", v1, v2); - exit(1); - } - end -</PRE> -Routines such as init() and finish() above are passed to the generated -program for linking using the <B>-l [link directives ...]</B> -switch. The string specified by this switch will be added to the link -line used to build the program (before the funtools library). For -example, assuming that init() and finish() are in the library -libmysubs.a in the /opt/special/lib directory, use: -<PRE> - funcalc -l "-L/opt/special/lib -lmysubs" ... -</PRE> - -<p> -User arguments can be passed to a compiled funcalc program using a string -argument to the "-a" switch. The string should contain all of the -user arguments. For example, to pass the integers 1 and 2, use: -<PRE> - funcalc -a "1 2" ... -</PRE> -The arguments are stored in an internal array and are accessed as -strings via the ARGV(n) macro. For example, consider the following -expression: -<PRE> - local - int pmin, pmax; - end - - before - pmin=atoi(ARGV(0)); - pmax=atoi(ARGV(1)); - end - - if( (cur->pha >= pmin) && (cur->pha <= pmax) ) - fprintf(stderr, "%d %d %d\n", cur->x, cur->y, cur->pha); -</PRE> -This expression will print out x, y, and pha values for all rows in which -the pha value is between the two user-input values: -<PRE> - funcalc -a '1 12' -f foo snr.ev'[cir 512 512 .1]' - 512 512 6 - 512 512 8 - 512 512 5 - 512 512 5 - 512 512 8 - - funcalc -a '5 6' -f foo snr.ev'[cir 512 512 .1]' - 512 512 6 - 512 512 5 - 512 512 5 -</PRE> - -<P> -Note that it is the user's responsibility to ensure that the correct -number of arguments are passed. The ARGV(n) macro returns a NULL if a -requested argument is outside the limits of the actual number of args, -usually resulting in a SEGV if processed blindly. To check the -argument count, use the ARGC macro: -<PRE> - local - long int seed=1; - double limit=0.8; - end - - before - if( ARGC >= 1 ) seed = atol(ARGV(0)); - if( ARGC >= 2 ) limit = atof(ARGV(1)); - srand48(seed); - end - - if ( drand48() > limit ) continue; -</PRE> - -<P> -The macro WRITE_ROW expands to the FunTableRowPut() call that writes -the current row. It can be used to write the row more than once. In -addition, the macro NROW expands to the row number currently being -processed. Use of these two macros is shown in the following example: -<PRE> - if( cur->pha:I == cur->pi:I ) continue; - a = cur->pha; - cur->pha = cur->pi; - cur->pi = a; - cur->AVG:E = (cur->pha+cur->pi)/2.0; - cur->NR:I = NROW; - if( NROW < 10 ) WRITE_ROW; -</PRE> - -<p> -If the <B>-p [prog]</B> switch is specified, the expression is not -executed. Rather, the generated executable is saved with the specified -program name for later use. - -<P> -If the <B>-n</B> switch is specified, the expression is not -executed. Rather, the generated code is written to stdout. This is -especially useful if you want to generate a skeleton file and add your -own code, or if you need to check compilation errors. Note that the -comment at the start of the output gives the compiler command needed -to build the program on that platform. (The command can change from -platform to platform because of the use of different libraries, -compiler switches, etc.) - -<P> -As mentioned previously, <B>funcalc</B> will declare a scalar -variable automatically (as a double) if that variable has been used -but not declared. This facility is implemented using a sed script -named <A HREF="./funcalc.sed">funcalc.sed</A>, which processes the -compiler output to sense an undeclared variable error. This script -has been seeded with the appropriate error information for gcc, and for -cc on Solaris, DecAlpha, and SGI platforms. If you find that automatic -declaration of scalars is not working on your platform, check this sed -script; it might be necessary to add to or edit some of the error -messages it senses. - -<P> -In order to keep the lexical analysis of <B>funcalc</B> expressions -(reasonably) simple, we chose to accept some limitations on how -accurately C comments, spaces, and new-lines are placed in the -generated program. In particular, comments associated with local -variables declared at the beginning of an expression (i.e., not in a -<B>local...end</B> block) will usually end up in the inner loop, not -with the local declarations: -<PRE> - /* this comment will end up in the wrong place (i.e, inner loop) */ - double a; /* also in wrong place */ - /* this will be in the the right place (inner loop) */ - if( cur->x:D == cur->y:D ) continue; /* also in right place */ - a = cur->x; - cur->x = cur->y; - cur->y = a; - cur->avg:E = (cur->x+cur->y)/2.0; -</PRE> -Similarly, spaces and new-lines sometimes are omitted or added in a -seemingly arbitrary manner. Of course, none of these stylistic -blemishes affect the correctness of the generated code. - -<P> -Because <B>funcalc</B> must analyze the user expression using the data -file(s) passed on the command line, the input file(s) must be opened -and read twice: once during program generation and once during -execution. As a result, it is not possible to use stdin for the -input file: <B>funcalc</B> cannot be used as a filter. We will -consider removing this restriction at a later time. - -<P> -Along with C comments, <B>funcalc</B> expressions can have one-line -internal comments that are not passed on to the generated C -program. These internal comment start with the <B>#</B> character and -continue up to the new-line: -<PRE> - double a; # this is not passed to the generated C file - # nor is this - a = cur->x; - cur->x = cur->y; - cur->y = a; - /* this comment is passed to the C file */ - cur->avg:E = (cur->x+cur->y)/2.0; -</PRE> - -<P> -As previously mentioned, input columns normally are identified by -their being used within the inner event loop. There are rare cases -where you might want to read a column and process it outside the main -loop. For example, qsort might use a column in its sort comparison -routine that is not processed inside the inner loop (and therefore not -implicitly specified as a column to be read). To ensure that such a -column is read by the event loop, use the <b>explicit</b> keyword. -The arguments to this keyword specify columns that should be read into -the input record structure even though they are not mentioned in the -inner loop. For example: - <PRE> - explicit pi pha -</PRE> -will ensure that the pi and pha columns are read for each row, -even if they are not processed in the inner event loop. The <b>explicit</b> -statement can be placed anywhere. - -<P> -Finally, note that <B>funcalc</B> currently works on expressions -involving FITS binary tables and raw event files. We will consider -adding support for image expressions at a later point, if there is -demand for such support from the community. - -<!-- =defdoc funcen funcen 1 --> - -<!-- =section funcen NAME --> -<H2><A NAME="funcen">funcen - find centroid (for binary tables)</A></H2> -<!-- =section funcen SYNOPSIS --> -<B> -<PRE> -funcen [-i] [-n iter] [-t tol] [-v lev] <iname> <region> -</PRE> -</B> - -<!-- =section funcen OPTIONS --> -<P> -<PRE> - -i # use image filtering (default: event filtering) - -n iter # max number of iterations (default: 0) - -t tol # pixel tolerance distance (default: 1.0) - -v [0,1,2,3] # output verbosity level (default: 0) -</PRE> - -<!-- =section funcen DESCRIPTION --> -<P> -<B>funcen</B> iteratively calculates the centroid position within one -or more regions of a Funtools table (FITS binary table or raw event -file). Starting with an input table, an initial region specification, -and an iteration count, the program calculates the average x and y -position within the region and then uses this new position as the -region center for the next iteration. Iteration terminates when the -maximum number of iterations is reached or when the input tolerance -distance is met for that region. A count of events in the final region -is then output, along with the pixel position value (and, where -available, WCS position). - -<P> -The first argument to the program specifies the Funtools table file to -process. Since the file must be read repeatedly, a value of "stdin" -is not permitted when the number of iterations is non-zero. Use -<A HREF="./files.html">Funtools Bracket Notation</A> to specify FITS -extensions and filters. - -<P> -The second required argument is the initial region descriptor. Multiple -regions are permitted. However, compound regions (accelerators, -variable argument regions and regions connected via boolean algebra) -are not permitted. Points and polygons also are illegal. These -restrictions might be lifted in a future version, if warranted. - -<p> -The <B>-n</B> (iteration number) switch specifies the maximum number of -iterations to perform. The default is 0, which means that the program will -simply count and display the number of events in the initial region(s). -Note that when iterations is 0, the data can be input via stdin. - -<p> -The <B>-t</B> (tolerance) switch specifies a floating point tolerance -value. If the distance between the current centroid position value and -the last position values is less than this value, iteration terminates. -The default value is 1 pixel. - -<p> -The <B>-v</B> (verbosity) switch specifies the verbosity level of the -output. The default is 0, which results in a single line of output for -each input region consisting of the following values: -<pre> - counts x y [ra dec coordsys] -</pre> -The last 3 WCS values are output if WCS information is available in the -data file header. Thus, for example: -<pre> - [sh] funcen -n 0 snr.ev "cir 505 508 5" - 915 505.00 508.00 345.284038 58.870920 j2000 - - [sh] funcen -n 3 snr.ev "cir 505 508 5" - 1120 504.43 509.65 345.286480 58.874587 j2000 -</pre> -The first example simply counts the number of events in the initial region. -The second example iterates the centroid calculation three times to determine -a final "best" position. - -<p> -Higher levels of verbosity obviously imply more verbose output. At -level 1, the output essentially contains the same information as level -0, but with keyword formatting: - - [sh] funcen -v 1 -n 3 snr.ev "cir 505 508 5" - event_file: snr.ev - initial_region: cir 505 508 5 - tolerance: 1.0000 - iterations: 1 - - events: 1120 - x,y(physical): 504.43 509.65 - ra,dec(j2000): 345.286480 58.874587 - final_region1: cir 504.43 509.65 5 -</pre> -Level 2 outputs results from intermediate calculations as well. - -<p> -Ordinarily, region filtering is performed using analytic (event) -filtering, i.e. that same style of filtering as is performed by -<b>fundisp</b> and <b>funtable</b>. Use the <b>-i</b> switch to specify image -filtering, i.e. the same style filtering as is performed by <b>funcnts</b>. -Thus, you can perform a quick calculation of counts in regions, using -either the analytic or image filtering method, by specifying the - <b>-n 0</b> and optional <b>-i</b> switches. These two method often -give different results because of how boundary events are processed: -<pre> - [sh] funcen snr.ev "cir 505 508 5" - 915 505.00 508.00 345.284038 58.870920 j2000 - - [sh] funcen -i snr.ev "cir 505 508 5" - 798 505.00 508.00 345.284038 58.870920 j2000 -</pre> -See <A HREF="./regbounds.html">Region Boundaries</A> for more information -about how boundaries are calculated using these two methods. - -<!-- =defdoc funcnts funcnts 1 --> - -<!-- =section funcnts NAME --> -<H2><A NAME="funcnts">funcnts - count photons in specified regions, with bkgd subtraction</A></H2> - -<!-- =section funcnts SYNOPSIS --> -<B> -<PRE> -funcnts [switches] <source_file> [source_region] [bkgd_file] [bkgd_region|bkgd_value] -</PRE> -</B> - -<!-- =section funcnts OPTIONS --> -<P> -<PRE> - -e "source_exposure[;bkgd_exposure]" - # source (bkgd) FITS exposure image using matching files - -w "source_exposure[;bkgd_exposure]" - # source (bkgd) FITS exposure image using WCS transform - -t "source_timecorr[;bkgd_timecorr]" - # source (bkgd) time correction value or header parameter name - -g # output using nice g format - -G # output using %.14g format (maximum precision) - -i "[column;]int1;int2..." # column-based intervals - -m # match individual source and bkgd regions - -p # output in pixels, even if wcs is present - -r # output inner/outer radii (and angles) for annuli (and pandas) - -s # output summed values - -v "scol[;bcol]" # src and bkgd value columns for tables - -T # output in starbase/rdb format - -z # output regions with zero area -</B> -</PRE> - -<!-- =section funcnts DESCRIPTION --> -<P> -<B>funcnts</B> counts photons in the specified source regions and -reports the results for each region. Regions are specified using the -<A HREF="./regions.html">Spatial Region Filtering</A> mechanism. -Photons are also counted in the specified bkgd regions applied to the -same data file or a different data file. (Alternatively, a constant -background value in counts/pixel**2 can be specified.) The bkgd regions -are either paired one-to-one with source regions or pooled and -normalized by area, and then subtracted from the source counts in each -region. Displayed results include the bkgd-subtracted counts in each -region, as well as the error on the counts, the area in -each region, and the surface brightness (cnts/area**2) calculated for -each region. - -<P> -The first argument to the program specifies the FITS input image, array, or -raw event file to process. If "stdin" is specified, data are read from -the standard input. Use <A HREF="./files.html">Funtools Bracket -Notation</A> to specify FITS extensions, image sections, and filters. - -<P> -The optional second argument is the source region descriptor. If no -region is specified, the entire field is used. - -<P> -The background arguments can take one of two forms, depending on -whether a separate background file is specified. If the source -file is to be used for background as well, the third argument can be -either the background region, or a constant value denoting background -cnts/pixel. Alternatively, the third argument can be a background -data file, in which case the fourth argument is the background region. -If no third argument is specified, a constant value of 0 is used -(i.e., no background). - -<P> -In summary, the following command arguments are valid: -<PRE> - [sh] funcnts sfile # counts in source file - [sh] funcnts sfile sregion # counts in source region - [sh] funcnts sfile sregion bregion # bkgd reg. is from source file - [sh] funcnts sfile sregion bvalue # bkgd reg. is constant - [sh] funcnts sfile sregion bfile bregion # bkgd reg. is from separate file -</PRE> - -<P> -NB: unlike other Funtools programs, source and background regions are -specified as separate arguments on the command line, rather than being -placed inside brackets as part of the source and background filenames. -This is because regions in funcnts are not simply used as data -filters, but also are used to calculate areas, exposure, etc. If you -put the source region inside the brackets (i.e. use it simply as a -filter) rather than specifying it as argument two, the program still -will only count photons that pass the region filter. However, the area -calculation will be performed on the whole field, since field() is the -default source region. This rarely is the desired behavior. On the -other hand, with FITS binary tables, it often is useful to put a column -filter in the filename brackets, so that only events matching the -column filter are counted inside the region. - -<P> -For example, to extract the counts within a radius of 22 pixels from the -center of the FITS binary table snr.ev and subtract the background determined -from the same image within an annulus of radii 50-100 pixels: -<PRE> - [sh] funcnts snr.ev "circle(502,512,22)" "annulus(502,512,50,100)" - # source - # data file: snr.ev - # degrees/pix: 0.00222222 - # background - # data file: snr.ev - # column units - # area: arcsec**2 - # surf_bri: cnts/arcsec**2 - # surf_err: cnts/arcsec**2 - - # background-subtracted results - reg net_counts error background berror area surf_bri surf_err - ---- ------------ --------- ------------ --------- --------- --------- --------- - 1 3826.403 66.465 555.597 5.972 96831.98 0.040 0.001 - - - # the following source and background components were used: - source region(s) - ---------------- - circle(502,512,22) - - reg counts pixels - ---- ------------ --------- - 1 4382.000 1513 - - background region(s) - -------------------- - annulus(502,512,50,100) - - reg counts pixels - ---- ------------ --------- - all 8656.000 23572 -</PRE> -The area units for the output columns labeled "area", "surf_bri" -(surface brightness) and "surf_err" will be given either in -arc-seconds (if appropriate WCS information is in the data file -header(s)) or in pixels. If the data file has WCS info, but you do not -want arc-second units, use the <B>-p</B> switch to force output in -pixels. Also, regions having zero area are not normally included in -the primary (background-subtracted) table, but are included in the -secondary source and bkgd tables. If you want these regions to be -included in the primary table, use the <B>-z</B> switch. - -<P> -Note that a simple sed command will extract the background-subtracted results -for further analysis: -<PRE> - [sh] cat funcnts.sed - 1,/---- .*/d - /^$/,$d - - [sh] sed -f funcnts.sed funcnts.out - 1 3826.403 66.465 555.597 5.972 96831.98 0.040 0.001 -</PRE> - -<P> -If separate source and background files are specified, <B>funcnts</B> will -attempt to normalize the the background area so that the background -pixel size is the same as the source pixel size. This normalization -can only take place if the appropriate WCS information is contained in -both files (e.g. degrees/pixel values in CDELT). If either -file does not contain the requisite size information, the normalization -is not performed. In this case, it is the user's responsibility to -ensure that the pixel sizes are the same for the two files. - -<P> -Normally, if more than one background region is specified, <B>funcnts</B> -will combine them all into a single region and use this background -region to produce the background-subtracted results for each source -region. The <B>-m</B> (match multiple backgrounds) switch tells -<B>funcnts</B> to make a one to one correspondence between background and -source regions, instead of using a single combined background region. -For example, the default case is to combine 2 background -regions into a single region and then apply that region to each of the -source regions: - -<PRE> - [sh] funcnts snr.ev "annulus(502,512,0,22,n=2)" "annulus(502,512,50,100,n=2)" - # source - # data file: snr.ev - # degrees/pix: 0.00222222 - # background - # data file: snr.ev - # column units - # area: arcsec**2 - # surf_bri: cnts/arcsec**2 - # surf_err: cnts/arcsec**2 - - # background-subtracted results - reg net_counts error background berror area surf_bri surf_err - ---- ------------ --------- ------------ --------- --------- --------- --------- - 1 3101.029 56.922 136.971 1.472 23872.00 0.130 0.002 - 2 725.375 34.121 418.625 4.500 72959.99 0.010 0.000 - - - # the following source and background components were used: - source region(s) - ---------------- - annulus(502,512,0,22,n=2) - - reg counts pixels - ---- ------------ --------- - 1 3238.000 373 - 2 1144.000 1140 - - background region(s) - -------------------- - annulus(502,512,50,100,n=2) - - reg counts pixels - ---- ------------ --------- - all 8656.000 23572 -</PRE> -Note that the basic region filter rule "each photon is counted once -and no photon is counted more than once" still applies when using The -<B>-m</B> to match background regions. That is, if two background -regions overlap, the overlapping pixels will be counted in only one of -them. In a worst-case scenario, if two background regions are the same -region, the first will get all the counts and area and the second -will get none. - -<P> -Using the <B>-m</B> switch causes <B>funcnts</B> to use each of the two -background regions independently with each of the two source regions: - -<PRE> - [sh] funcnts -m snr.ev "annulus(502,512,0,22,n=2)" "ann(502,512,50,100,n=2)" - # source - # data file: snr.ev - # degrees/pix: 0.00222222 - # background - # data file: snr.ev - # column units - # area: arcsec**2 - # surf_bri: cnts/arcsec**2 - # surf_err: cnts/arcsec**2 - - # background-subtracted results - reg net_counts error background berror area surf_bri surf_err - ---- ------------ --------- ------------ --------- --------- --------- --------- - 1 3087.015 56.954 150.985 2.395 23872.00 0.129 0.002 - 2 755.959 34.295 388.041 5.672 72959.99 0.010 0.000 - - - # the following source and background components were used: - source region(s) - ---------------- - annulus(502,512,0,22,n=2) - - reg counts pixels - ---- ------------ --------- - 1 3238.000 373 - 2 1144.000 1140 - - background region(s) - -------------------- - ann(502,512,50,100,n=2) - - reg counts pixels - ---- ------------ --------- - 1 3975.000 9820 - 2 4681.000 13752 -</PRE> - -<P> -Note that most floating point quantities are displayed using "f" -format. You can change this to "g" format using the <B>-g</B> -switch. This can be useful when the counts in each pixel is very -small or very large. If you want maximum precision and don't care -about the columns lining up nicely, use <B>-G</B>, which outputs -all floating values as %.14g. - -<P> -When counting photons using the annulus and panda (pie and annuli) -shapes, it often is useful to have access to the radii (and panda -angles) for each separate region. The <B>-r</B> switch will add radii -and angle columns to the output table: - -<PRE> - [sh] funcnts -r snr.ev "annulus(502,512,0,22,n=2)" "ann(502,512,50,100,n=2)" - # source - # data file: snr.ev - # degrees/pix: 0.00222222 - # background - # data file: snr.ev - # column units - # area: arcsec**2 - # surf_bri: cnts/arcsec**2 - # surf_err: cnts/arcsec**2 - # radii: arcsecs - # angles: degrees - - # background-subtracted results - reg net_counts error background berror area surf_bri surf_err radius1 radius2 angle1 angle2 - ---- ------------ --------- ------------ --------- --------- --------- --------- --------- --------- --------- --------- - 1 3101.029 56.922 136.971 1.472 23872.00 0.130 0.002 0.00 88.00 NA NA - 2 725.375 34.121 418.625 4.500 72959.99 0.010 0.000 88.00 176.00 NA NA - - - # the following source and background components were used: - source region(s) - ---------------- - annulus(502,512,0,22,n=2) - - reg counts pixels - ---- ------------ --------- - 1 3238.000 373 - 2 1144.000 1140 - - background region(s) - -------------------- - ann(502,512,50,100,n=2) - - reg counts pixels - ---- ------------ --------- - all 8656.000 23572 -</PRE> - -<P> -Radii are given in units of pixels or arc-seconds (depending on the -presence of WCS info), while the angle values (when present) are in -degrees. These columns can be used to plot radial profiles. For -example, the script <B>funcnts.plot</B> in the funtools -distribution) will plot a radial profile using gnuplot (version 3.7 or -above). A simplified version of this script is shown below: - -<PRE> - #!/bin/sh - - if [ x"$1" = xgnuplot ]; then - if [ x`which gnuplot 2>/dev/null` = x ]; then - echo "ERROR: gnuplot not available" - exit 1 - fi - awk ' - BEGIN{HEADER=1; DATA=0; FILES=""; XLABEL="unknown"; YLABEL="unknown"} - HEADER==1{ - if( $1 == "#" && $2 == "data" && $3 == "file:" ){ - if( FILES != "" ) FILES = FILES "," - FILES = FILES $4 - } - else if( $1 == "#" && $2 == "radii:" ){ - XLABEL = $3 - } - else if( $1 == "#" && $2 == "surf_bri:" ){ - YLABEL = $3 - } - else if( $1 == "----" ){ - printf "set nokey; set title \"funcnts(%s)\"\n", FILES - printf "set xlabel \" radius(%s)\"\n", XLABEL - printf "set ylabel \"surf_bri(%s)\"\n", YLABEL - print "plot \"-\" using 3:4:6:7:8 with boxerrorbars" - HEADER = 0 - DATA = 1 - next - } - } - DATA==1{ - if( NF == 12 ){ - print $9, $10, ($9+$10)/2, $7, $8, $7-$8, $7+$8, $10-$9 - } - else{ - exit - } - } - ' | gnuplot -persist - 1>/dev/null 2>&1 - - elif [ x"$1" = xds9 ]; then - awk ' - BEGIN{HEADER=1; DATA=0; XLABEL="unknown"; YLABEL="unknown"} - HEADER==1{ - if( $1 == "#" && $2 == "data" && $3 == "file:" ){ - if( FILES != "" ) FILES = FILES "," - FILES = FILES $4 - } - else if( $1 == "#" && $2 == "radii:" ){ - XLABEL = $3 - } - else if( $1 == "#" && $2 == "surf_bri:" ){ - YLABEL = $3 - } - else if( $1 == "----" ){ - printf "funcnts(%s) radius(%s) surf_bri(%s) 3\n", FILES, XLABEL, YLABEL - HEADER = 0 - DATA = 1 - next - } - } - DATA==1{ - if( NF == 12 ){ - print $9, $7, $8 - } - else{ - exit - } - } - ' - else - echo "funcnts -r ... | funcnts.plot [ds9|gnuplot]" - exit 1 - fi -</PRE> - -Thus, to run <B>funcnts</B> and plot the results using gnuplot (version 3.7 -or above), use: -<PRE> - funcnts -r snr.ev "annulus(502,512,0,50,n=5)" ... | funcnts.plot gnuplot -</PRE> - -<P> -The <B>-s</B> (sum) switch causes <B>funcnts</B> to produce an -additional table of summed (integrated) background subtracted values, -along with the default table of individual values: - -<PRE> - [sh] funcnts -s snr.ev "annulus(502,512,0,50,n=5)" "annulus(502,512,50,100)" - # source - # data file: snr.ev - # degrees/pix: 0.00222222 - # background - # data file: snr.ev - # column units - # area: arcsec**2 - # surf_bri: cnts/arcsec**2 - # surf_err: cnts/arcsec**2 - - # summed background-subtracted results - upto net_counts error background berror area surf_bri surf_err - ---- ------------ --------- ------------ --------- --------- --------- --------- - 1 2880.999 54.722 112.001 1.204 19520.00 0.148 0.003 - 2 3776.817 65.254 457.183 4.914 79679.98 0.047 0.001 - 3 4025.492 71.972 1031.508 11.087 179775.96 0.022 0.000 - 4 4185.149 80.109 1840.851 19.786 320831.94 0.013 0.000 - 5 4415.540 90.790 2873.460 30.885 500799.90 0.009 0.000 - - - # background-subtracted results - reg counts error background berror area surf_bri surf_err - ---- ------------ --------- ------------ --------- --------- --------- --------- - 1 2880.999 54.722 112.001 1.204 19520.00 0.148 0.003 - 2 895.818 35.423 345.182 3.710 60159.99 0.015 0.001 - 3 248.675 29.345 574.325 6.173 100095.98 0.002 0.000 - 4 159.657 32.321 809.343 8.699 141055.97 0.001 0.000 - 5 230.390 37.231 1032.610 11.099 179967.96 0.001 0.000 - - - # the following source and background components were used: - source region(s) - ---------------- - annulus(502,512,0,50,n=5) - - reg counts pixels sumcnts sumpix - ---- ------------ --------- ------------ --------- - 1 2993.000 305 2993.000 305 - 2 1241.000 940 4234.000 1245 - 3 823.000 1564 5057.000 2809 - 4 969.000 2204 6026.000 5013 - 5 1263.000 2812 7289.000 7825 - - background region(s) - -------------------- - annulus(502,512,50,100) - - reg counts pixels - ---- ------------ --------- - all 8656.000 23572 -</PRE> - -<P> -The <B>-t</B> and <B>-e</B> switches can be used to apply timing and -exposure corrections, respectively, to the data. Please note that -these corrections are meant to be used qualitatively, since -application of more accurate correction factors is a complex and -mission-dependent effort. The algorithm for applying these simple -corrections is as follows: -<PRE> - C = Raw Counts in Source Region - Ac= Area of Source Region - Tc= Exposure time for Source Data - Ec= Average exposure in Source Region, from exposure map - - B= Raw Counts in Background Region - Ab= Area of Background Region - Tb= (Exposure) time for Background Data - Eb= Average exposure in Background Region, from exposure map -</PRE> -Then, Net Counts in Source region is -<PRE> - Net= C - B * (Ac*Tc*Ec)/(Ab*Tb*Eb) -</PRE> -with the standard propagation of errors for the Error on Net. -The net rate would then be -<PRE> - Net Rate = Net/(Ac*Tc*Ec) -</PRE> -The average exposure in each region is calculated by summing up the -pixel values in the exposure map for the given region and then -dividing by the number of pixels in that region. Exposure maps often -are generated at a block factor > 1 (e.g., block 4 means that each -exposure pixel contains 4x4 pixels at full resolution) and -<B>funcnts</B> will deal with the blocking automatically. Using the -<B>-e</B> switch, you can supply both source and background exposure -files (separated by ";"), if you have separate source and background -data files. If you do not supply a background exposure file to go with -a separate background data file, <B>funcnts</B> assumes that exposure -already has been applied to the background data file. In addition, it -assumes that the error on the pixels in the background data file is -zero. - -<P> -NB: The <B>-e</B> switch assumes that the exposure map overlays the -image file <B>exactly</B>, except for the block factor. Each pixel in -the image is scaled by the block factor to access the corresponding -pixel in the exposure map. If your exposure map does not line up -exactly with the image, <B>do not use</B> the <B>-e</B> exposure -correction. In this case, it still is possible to perform exposure -correction <B>if</B> both the image and the exposure map have valid -WCS information: use the <B>-w</B> switch so that the transformation -from image pixel to exposure pixel uses the WCS information. That is, -each pixel in the image region will be transformed first from image -coordinates to sky coordinates, then from sky coordinates to exposure -coordinates. Please note that using <B>-w</B> can increase the time -required to process the exposure correction considerably. - -<P> -A time correction can be applied to both source and -background data using the <B>-t</B> switch. The value for the correction can -either be a numeric constant or the name of a header parameter in -the source (or background) file: -<PRE> - [sh] funcnts -t 23.4 ... # number for source - [sh] funcnts -t "LIVETIME;23.4" ... # param for source, numeric for bkgd -</PRE> -When a time correction is specified, it is applied to the net counts -as well (see algorithm above), so that the units of surface brightness -become cnts/area**2/sec. - -<P> -The <B>-i</B> (interval) switch is used to run <b>funcnts</b> on multiple -column-based intervals with only a single pass through the data. It is -equivalent to running <b>funcnts</b> several times with a different column -filter added to the source and background data each time. For each -interval, the full <b>funcnts</b> output is generated, with a linefeed -character (^L) inserted between each run. In addition, the output for -each interval will contain the interval specification in its header. -Intervals are very useful for generating X-ray hardness ratios -efficiently. Of course, they are only supported when the input data -are contained in a table. - -<P> -Two formats are supported for interval specification. The most general -format is semi-colon-delimited list of filters to be used as intervals: -<PRE> - funcnts -i "pha=1:5;pha=6:10;pha=11:15" snr.ev "circle(502,512,22)" ... -</PRE> -Conceptually, this will be equivalent to running <b>funcnts</b> three times: -<PRE> - funcnts snr.ev'[pha=1:5]' "circle(502,512,22)" - funcnts snr.ev'[pha=6:10]' "circle(502,512,22)" - funcnts snr.ev'[pha=11:15]' "circle(502,512,22)" -</PRE> -However, using the <B>-i</B> switch will require only one pass through -the data. - -<P> -Note that complex filters can be used to specify intervals: -<PRE> - funcnts -i "pha=1:5&&pi=4;pha=6:10&&pi=5;pha=11:15&&pi=6" snr.ev ... -</PRE> -The program simply runs the data through each filter in turn and generates -three <b>funcnts</b> outputs, separated by the line-feed character. - -<P> -In fact, although the intent is to support intervals for hardness ratios, -the specified filters do not have to be intervals at all. Nor does one -"interval" filter have to be related to another. For example: -<PRE> - funcnts -i "pha=1:5;pi=6:10;energy=11:15" snr.ev "circle(502,512,22)" ... -</PRE> -is equivalent to running <b>funcnts</b> three times with unrelated filter -specifications. - -<P> -A second interval format is supported for the simple case in which a -single column is used to specify multiple homogeneous intervals for -that column. In this format, a column name is specified first, -followed by intervals: -<PRE> - funcnts -i "pha;1:5;6:10;11:15" snr.ev "circle(502,512,22)" ... -</PRE> -This is equivalent to the first example, but requires less typing. The -<b>funcnts</b> program will simply prepend "pha=" before each of the specified -intervals. (Note that this format does not contain the "=" character in -the column argument.) - -<P> -Ordinarily, when <b>funcnts</b> is run on a FITS binary table (or a -raw event table), one integral count is accumulated for each row -(event) contained within a given region. The <B>-v "scol[;bcol]"</B> -(value column) switch will accumulate counts using the value from the -specified column for the given event. If only a single column is -specified, it is used for both the source and background regions. Two -separate columns, separated by a semi-colon, can be specified for source -and background. The special token '$none' can be used to specify that -a value column is to be used for one but not the other. For example, -'pha;$none' will use the pha column for the source but use integral -counts for the background, while '$none;pha' will do the converse. -If the value column is of type logical, then the value used will be 1 -for T and 0 for F. Value columns are used, for example, to integrate -probabilities instead of integral counts. - -<P> -If the <B>-T</B> (rdb table) switch is used, the output will conform -to starbase/rdb data base format: tabs will be inserted between -columns rather than spaces and line-feed will be inserted between -tables. - -<P> -Finally, note that <B>funcnts</B> is an image program, even though it -can be run directly on FITS binary tables. This means that image -filtering is applied to the rows in order to ensure that the same -results are obtained regardless of whether a table or the equivalent -binned image is used. Because of this, however, the number of counts -found using <B>funcnts</B> can differ from the number of events found -using row-filter programs such as <B>fundisp</B> or <B>funtable</B> -For more information about these difference, see the discussion of -<A HREF="./regbounds.html">Region Boundaries</A>. - -<!-- =defdoc funcone funcone 1 --> - -<!-- =section funcone NAME --> -<H2><A NAME="funcone">funcone - cone search of a binary table containing RA, Dec columns</A></H2> - -<!-- =section funcone SYNOPSIS --> -<B> -<PRE> -funcone <switches> <iname> <oname> <ra[hdr]> <dec[hdr]> <radius[dr'"]> [columns] -</PRE> -</B> - -<!-- =section funcone OPTIONS --> -<P> -<PRE> - -d deccol:[hdr] # Dec column name, units (def: DEC:d) - -j # join columns from list file - -J # join columns from list file, output all rows - -l listfile # read centers and radii from a list - -L listfile # read centers and radii from a list, output list rows - -n # don't use cone limits as a filter - -r racol:[hdr] # RA column name, units (def: RA:h) - -x # append RA_CEN, DEC_CEN, RAD_CEN, CONE_KEY cols - -X # append RA_CEN, DEC_CEN, RAD_CEN, CONE_KEY cols, output all rows -</PRE> - -<!-- =section funcone DESCRIPTION --> -<P> -Funcone performs a cone search on the RA and Dec columns of a FITS -binary table. The distance from the center RA, Dec position to the RA, -Dec in each row in the table is calculated. Rows whose distance is -less than the specified radius are output. - -<P> -The first argument to the program specifies the FITS file, raw event -file, or raw array file. If "stdin" is specified, data are read from -the standard input. Use <A HREF="./files.html">Funtools Bracket -Notation</A> to specify FITS extensions, and filters. The second -argument is the output FITS file. If "stdout" is specified, the FITS -binary table is written to the standard output. - -<P> -The third and fourth required arguments are the RA and Dec center -position. By default, RA is specified in hours while Dec is specified -in degrees. You can change the units of either of these by appending -the character "d" (degrees), "h" (hours) or "r" (radians). Sexagesimal -notation is supported, with colons or spaces separating hms and dms. -(When using spaces, please ensure that the entire string is quoted.) - -<P> -The fifth required argument is the radius of the cone search. By default, -the radius value is given in degrees. The units can be changed by appending -the character "d" (degrees), "r" (radians), "'" (arc minutes) or -'"' (arc seconds). - -<P> -By default, all -columns of the input file are copied to the output file. Selected -columns can be output using an optional sixth argument in the form: -<PRE> - "column1 column1 ... columnN" -</PRE> -A seventh argument allows you to output selected columns from the list -file when <B>-j</B> switch is used. Note that the RA and Dec columns -used in the cone calculation must not be de-selected. - -<P> -Also by default, the RA and Dec column names are named "RA" and "Dec", -and are given in units of hours and degrees respectively. You can -change both the name and the units using the -r [RA] and/or -d [Dec] -switches. Once again, one of "h", "d", or "r" is appended to the -column name to specify units but in this case, there must be a colon ":" -between the name and the unit specification. - -<P> -If the <B>-l [listfile]</B> switch is used, then one or more of the -center RA, center Dec, and radius can be taken from a list file (which -can be a FITS table or an ASCII column text file). In this case, the -third (center RA), fourth (center Dec), and fifth (radius) command -line arguments can either be a column name in the list file (if that -parameter varies) or else a numeric value (if that parameter is -static). When a column name is specified for the RA, Dec, or radius, -you can append a colon followed by "h", "d", or "r" to specify units -(also ' and " for radius). The cone search algorithm is run once for -each row in the list, taking RA, Dec, and radius values from the -specified columns or from static numeric values specified on the -command line. - -<P> -When using a list, all valid rows from each iteration are written to a -single output file. Use the <B>-x</B> switch to help delineate which -line of the list file was used to produce the given output row(s). -This switch causes the values for the center RA, Dec, radius, and row -number to be appended to the output file, in columns called RA_CEN, -DEC_CEN, RAD_CEN and CONE_KEY, respectively. Alternatively, the -<B>-j</B> (join) switch will append all columns from the list row to -the output row (essentially a join of the list row and input row), -along with the CONE_KEY row number. These two switches are mutually -exclusive. - -<P> -The <b>-X</b> and <b>-J</b> switches write out the same data as their -lower case counterparts for each row satisfying a cone search. In -addition, these switches also write out rows from the event file that -do not satisfy any cone search. In such cases, that CONE_KEY column -will be given a value of -1 and the center and list position information -will be set to zero for the given row. Thus, all rows of the input -event file are guaranteed to be output, with rows satisfying at least -one cone search having additional search information. - -<p> -The <b>-L</b> switch acts similarly to the <b>-l</b> switch in that it -takes centers from a list file. However, it also implicitly sets the --j switch, so that output rows are the join of the input event row and -the center position row. In addition, this switch also writes out all -center position rows for which no event satisfies the cone search -criteria of that row. The CONE_KEY column will be given a value of -2 -for center rows that were not close to any data row and the event -columns will be zeroed out for such rows. In this way, all centers -rows are guaranteed to be output at least once. - -<p> -If any of "all row" switches (<b>-X</b>, <b>-J</b>, or <b>-L</b>) are -specified, then a new column named JSTAT is added to the output table. -The positive values in this column indicate the center position row number -(starting from 1) in the list file that this data row successful matched -in a cone search. A value of -1 means that the data row did not match -any center position. A value of -2 means that the center position was -not matched by any data row. - -<P> -Given a center position and radius, the cone search algorithm -calculates limit parameters for a box enclosing the specified cone, -and only tests rows whose positions values lie within those limits. -For small files, the overhead associated with this cone limit -filtering can cause the program to run more slowly than if all events -were tested. You can turn off cone limit filtering using the <B>-n</B> -switch to see if this speeds up the processing (especially useful when -processing a large list of positions). - -<P> -For example, the default cone search uses columns "RA" and "Dec" in hours -and degrees (respectively) and RA position in hours, Dec and radius in degrees: -<PRE> - funone in.fits out.fits 23.45 34.56 0.01 -</PRE> -To specify the RA position in degrees: -<PRE> - funcone in.fits out.fits 23.45d 34.56 0.01 -</PRE> -To get RA and Dec from a list but use a static value for radius (and -also write identifying info for each row in the list): -<PRE> - funcone -x -l list.txt in.fits out.fits MYRA MYDec 0.01 -</PRE> -User specified columns in degrees, RA position in hours (sexagesimal -notation), Dec position in degrees (sexagesimal notation) and radius -in arc minutes: -<PRE> - funcone -r myRa:d -d myDec in.fits out.fits 12:30:15.5 30:12 15' -</PRE> - -<!-- =defdoc fundisp fundisp 1 --> - -<!-- =section fundisp NAME --> -<H2><A NAME="fundisp">fundisp - display data in a Funtools data file</A></H2> - -<!-- =section fundisp SYNOPSIS --> -<B> -<PRE> -fundisp [-f format] [-l] [-n] [-T] <iname> [columns|bitpix=n] -</PRE> -</B> - -<!-- =section fundisp OPTIONS --> -<P> -<PRE> - -f # format string for display - -l # display image as a list containing the columns X, Y, VAL - -n # don't output header - -F [c] # use specified character as column separator (def: space) - -T # output in rdb/starbase format (tab separators) -</PRE> - -<!-- =section fundisp DESCRIPTION --> -<P> -<B>fundisp</B> displays the data in the specified -<A HREF="./files.html">FITS Extension</A> -and/or -<A HREF="./files.html#sections">Image Section</A> -of a FITS file, or in a -<A HREF="./files.html#sections">Section</A> -of a non-FITS array or raw event file. -<P> -The first argument to the program specifies the FITS input image, array, or -raw event file to display. If "stdin" is specified, data are read from -the standard input. Use <A HREF="./files.html">Funtools Bracket -Notation</A> to specify FITS extensions, image sections, and filters. - -<P> -If the data being displayed are columns (either in a FITS binary table -or a raw event file), the individual rows are listed. Filters can be -added using bracket notation. Thus: -<PRE> - [sh] fundisp "test.ev[time-(int)time>.15]" - X Y PHA PI TIME DX DY - ------- ------- ------- --------- ---------------- ---------- ---------- - 10 8 10 8 17.1600 8.50 10.50 - 9 9 9 9 17.1600 9.50 9.50 - 10 9 10 9 18.1600 9.50 10.50 - 10 9 10 9 18.1700 9.50 10.50 - 8 10 8 10 17.1600 10.50 8.50 - 9 10 9 10 18.1600 10.50 9.50 - 9 10 9 10 18.1700 10.50 9.50 - 10 10 10 10 19.1600 10.50 10.50 - 10 10 10 10 19.1700 10.50 10.50 - 10 10 10 10 19.1800 10.50 10.50 -</PRE> -[NB: The FITS binary table test file test.ev, as well as the FITS -image test.fits, are contained in the funtools funtest directory.] - -<P> -When a table is being displayed using <B>fundisp</B>, a second optional -argument can be used to specify the columns to display. For example: -<PRE> - [sh] fundisp "test.ev[time-(int)time>=.99]" "x y time" - X Y TIME - -------- -------- --------------------- - 5 -6 40.99000000 - 4 -5 59.99000000 - -1 0 154.99000000 - -2 1 168.99000000 - -3 2 183.99000000 - -4 3 199.99000000 - -5 4 216.99000000 - -6 5 234.99000000 - -7 6 253.99000000 -</PRE> - -<P> -The special column <B>$REGION</B> can be specified to display the -region id of each row: -<PRE> - [sh $] fundisp "test.ev[time-(int)time>=.99&&annulus(0 0 0 10 n=3)]" 'x y time $REGION' - X Y TIME REGION - -------- -------- --------------------- ---------- - 5 -6 40.99000000 3 - 4 -5 59.99000000 2 - -1 0 154.99000000 1 - -2 1 168.99000000 1 - -3 2 183.99000000 2 - -4 3 199.99000000 2 - -5 4 216.99000000 2 - -6 5 234.99000000 3 - -7 6 253.99000000 3 -</PRE> -<P> -Here only rows with the proper fractional time and whose position also is -within one of the three annuli are displayed. -<P> -Columns can be excluded from display using a minus sign before the -column: -<PRE> - [sh $] fundisp "test.ev[time-(int)time>=.99]" "-time" - X Y PHA PI DX DY - -------- -------- -------- ---------- ----------- ----------- - 5 -6 5 -6 5.50 -6.50 - 4 -5 4 -5 4.50 -5.50 - -1 0 -1 0 -1.50 0.50 - -2 1 -2 1 -2.50 1.50 - -3 2 -3 2 -3.50 2.50 - -4 3 -4 3 -4.50 3.50 - -5 4 -5 4 -5.50 4.50 - -6 5 -6 5 -6.50 5.50 - -7 6 -7 6 -7.50 6.50 -</PRE> -All columns except the time column are displayed. -<P> -The special column <B>$N</B> can be specified to display the -ordinal value of each row. Thus, continuing the previous example: -<PRE> - fundisp "test.ev[time-(int)time>=.99]" '-time $n' - X Y PHA PI DX DY N - ------- -------- -------- ---------- ----------- ----------- ---------- - 5 -6 5 -6 5.50 -6.50 337 - 4 -5 4 -5 4.50 -5.50 356 - -1 0 -1 0 -1.50 0.50 451 - -2 1 -2 1 -2.50 1.50 465 - -3 2 -3 2 -3.50 2.50 480 - -4 3 -4 3 -4.50 3.50 496 - -5 4 -5 4 -5.50 4.50 513 - -6 5 -6 5 -6.50 5.50 531 - -7 6 -7 6 -7.50 6.50 550 -</PRE> -Note that the column specification is enclosed in single quotes to protect -'$n' from begin expanded by the shell. - -<P> -In general, the rules for activating and de-activating columns are: -<UL> -<LI> If only exclude columns are specified, then all columns but -the exclude columns will be activated. -<LI> If only include columns are specified, then only the specified columns -are activated. -<LI> If a mixture of include and exclude columns are specified, then -all but the exclude columns will be active; this last case -is ambiguous and the rule is arbitrary. -</UL> -In addition to specifying columns names explicitly, the special -symbols <B>+</B> and <B>-</B> can be used to activate and -de-activate <B>all</B> columns. This is useful if you want to -activate the $REGION column along with all other columns. According -to the rules, the syntax "$REGION" only activates the region column -and de-activates the rest. Use "+ $REGION" to activate all -columns as well as the region column. - -<P> -If the data being displayed are image data (either in a FITS primary -image, a FITS image extension, or an array file), an mxn pixel display -is produced, where m and n are the dimensions of the image. By -default, pixel values are displayed using the same data type as in the -file. However, for integer data where the BSCALE and BZERO header parameters -are present, the data is displayed as floats. In either case, the -display data type can be overridden using an optional second argument -of the form: -<PRE> - bitpix=n -</PRE> -where n is 8,16,32,-32,-64, for unsigned char, short, int, float and double, -respectively. - -<P> -Of course, running <B>fundisp</B> on anything but the smallest image -usually results in a display whose size makes it unreadable. -Therefore, one can uses bracket notation (see below) -to apply section and/or blocking to the image before generating a -display. For example: -<PRE> - [sh] fundisp "test.fits[2:6,2:7]" bitpix=-32 - 2 3 4 5 6 - ---------- ---------- ---------- ---------- ---------- - 2: 3.00 4.00 5.00 6.00 7.00 - 3: 4.00 5.00 6.00 7.00 8.00 - 4: 5.00 6.00 7.00 8.00 9.00 - 5: 6.00 7.00 8.00 9.00 10.00 - 6: 7.00 8.00 9.00 10.00 11.00 - 7: 8.00 9.00 10.00 11.00 12.00 -</PRE> - -<P> -Note that is is possible to display a FITS binary table as an image -simply by passing the table through <B>funimage</B> first: -<PRE> - [sh] ./funimage test.ev stdout | fundisp "stdin[2:6,2:7]" bitpix=8 - 2 3 4 5 6 - ------- ------- ------- ------- ------- - 2: 3 4 5 6 7 - 3: 4 5 6 7 8 - 4: 5 6 7 8 9 - 5: 6 7 8 9 10 - 6: 7 8 9 10 11 - 7: 8 9 10 11 12 -</PRE> - -If the <B>-l</B> (list) switch is used, then an image is displayed as a -list containing the columns: X, Y, VAL. For example: -<PRE> - fundisp -l "test1.fits[2:6,2:7]" bitpix=-32 - X Y VAL - ---------- ---------- ----------- - 2 2 6.00 - 3 2 1.00 - 4 2 1.00 - 5 2 1.00 - 6 2 1.00 - 2 3 1.00 - 3 3 5.00 - 4 3 1.00 - 5 3 1.00 - 6 3 1.00 - 2 4 1.00 - 3 4 1.00 - 4 4 4.00 - 5 4 1.00 - 6 4 1.00 - 2 5 1.00 - 3 5 1.00 - 4 5 1.00 - 5 5 3.00 - 6 5 1.00 - 2 6 1.00 - 3 6 1.00 - 4 6 1.00 - 5 6 1.00 - 6 6 2.00 - 2 7 1.00 - 3 7 1.00 - 4 7 1.00 - 5 7 1.00 - 6 7 1.00 -</PRE> - -<p> -If the <B>-n</B> (nohead) switch is used, then no header is output for -tables. This is useful, for example, when fundisp output is being -directed into gnuplot. - -<P> -The <B>fundisp</B> program uses a default set of display formats: -<PRE> - datatype TFORM format - -------- ----- -------- - double D "%21.8f" - float E "%11.2f" - int J "%10d" - short I "%8d" - byte B "%6d" - string A "%12.12s" - bits X "%8x" - logical L "%1x" -</PRE> -Thus, the default display of 1 double and 2 shorts gives: -<PRE> - [sh] fundisp snr.ev "time x y" - - TIME X Y - --------------------- -------- -------- - 79494546.56818075 546 201 - 79488769.94469175 548 201 - ... -</PRE> -You can change the display format for individual columns or for all -columns of a given data types by means of the -f switch. The format -string that accompanies -f is a space-delimited list of keyword=format -values. The keyword values can either be column names (in which case -the associated format pertains only to that column) or FITS table -TFORM specifiers (in which case the format pertains to all columns -having that data type). For example, you can change the double and -short formats for all columns like this: -<PRE> - [sh] fundisp -f "D=%22.11f I=%3d" snr.ev "time x y" - - TIME X Y - ---------------------- --- --- - 79494546.56818075478 546 201 - 79488769.94469174743 548 201 - ... -</PRE> - -<p> -Alternatively, you can change the format of the time and x columns like this: -<pre> - [sh] fundisp -f "time=%22.11f x=%3d" snr.ev "time x y" - - TIME X Y - ---------------------- --- -------- - 79494546.56818075478 546 201 - 79488769.94469174743 548 201 - ... -</pre> -Note that there is a potential conflict if a column has the same name -as one of the TFORM specifiers. In the examples above, the the "X" -column in the table has the same name as the X (bit) datatype. To -resolve this conflict, the format string is processed such that -TFORM datatype specifiers are checked for first, using a -case-sensitive comparison. If the specified format value is not an -upper case TFORM value, then a case-insensitive check is made on the -column name. This means that, in the examples above, "X=%3d" will refer -to the X (bit) datatype, while "x=%3d" will refer to the X column: -<pre> - [sh] fundisp -f "X=%3d" snr.ev "x y" - - X Y - -------- -------- - 546 201 - 548 201 - ... - - [sh] fundisp -f "x=%3d" snr.ev "x y" - - X Y - --- -------- - 546 201 - 548 201 - ... -</pre> -As a rule, therefore, it is best always to specify the column name in -lower case and TFORM data types in upper case. - -<p> -The <B>-f [format]</B> will change the format for a single execution -of fundisp. You also can use the <B>FUN_FORMAT</B> envronment variable -to change the format for all invocations of fundisp. The format of this -environment variable's value is identical to that used with -the <B>-f</B> switch. This global value can be overridden in -individual cases by use of the <B>-f [format]</B> switch. - -<P> -Caveats: Please also note that it is the user's responsibility to -match the format specifier to the column data type correctly. Also -note that, in order to maintain visual alignment between names and -columns, the column name will be truncated (on the left) if the -format width is less than the length of the name. However, truncation -is not performed if the output is in RDB format (using the -T switch). - -<p> -[An older-style format string is supported but deprecated. It -consists of space-delimited C format statements for all data types, -specified in the following order: -<PRE> - double float int short byte string bit. -</PRE> -This order of the list is based on the assumption that people generally -will want to change the float formats. -<P> -If "-" is entered instead of a format statement for a given data type, the -default format is used. Also, the format string can be terminated without -specifying all formats, and defaults will be used for the rest of the -list. Note that you must supply a minimum field width, i.e., "%6d" and -"%-6d" are legal, "%d" is not legal. - -By using -f [format], you can change the double and short formats like this: -<PRE> - [sh] fundisp -f "22.11f - - 3d" snr.ev "time x y" - - TIME X Y - ---------------------- --- --- - 79494546.56818075478 546 201 - 79488769.94469174743 548 201 - ... -</PRE> -NB: This format is deprecated and will be removed in a future release.] - -<P> -The <B>-F[c]</B> switch can be used to specify a (single-character) -column separator (where the default is a space). Note that column -formatting will almost certainly also add spaces to pad individual -columns to the required width. These can be removed with a program -such as sed, at the cost of generating unaligned columns. For example: -<PRE> -fundisp -F',' snr.ev'[cir 512 512 .1]' - X, Y, PHA, PI, TIME, DX, DY ---------,--------,--------,--------,---------------------,--------,-------- - 512, 512, 6, 7, 79493997.45854475, 578, 574 - 512, 512, 8, 9, 79494575.58943175, 579, 573 - 512, 512, 5, 6, 79493631.03866175, 578, 575 - 512, 512, 5, 5, 79493290.86521725, 578, 575 - 512, 512, 8, 9, 79493432.00990875, 579, 573 - -fundisp -F',' snr.ev'[cir 512 512 .1]' | sed 's/ *, */,/g' - X,Y,PHA,PI,TIME,DX,DY ---------,--------,--------,--------,---------------------,--------,-------- - 512,512,6,7,79493997.45854475,578,574 - 512,512,8,9,79494575.58943175,579,573 - 512,512,5,6,79493631.03866175,578,575 - 512,512,5,5,79493290.86521725,578,575 - 512,512,8,9,79493432.00990875,579,573 - -fundisp -f "x=%3d y=%3d pi=%1d pha=%1d time=%20.11f dx=%3d dy=%3d" -F',' snr.ev'[cir 512 512 .1]' | sed 's/ *, */,/g' - X,Y,A,I,TIME,DX,DY ----,---,-,-,--------------------,---,--- -512,512,6,7,79493997.45854474604,578,574 -512,512,8,9,79494575.58943174779,579,573 -512,512,5,6,79493631.03866174817,578,575 -512,512,5,5,79493290.86521725357,578,575 -512,512,8,9,79493432.00990875065,579,573 - -</PRE> - -<P> -If the <B>-T</B> (rdb table) switch is used, the output will conform -to starbase/rdb data base format: tabs will be inserted between -columns rather than spaces. This format is not available when -displaying image pixels (except in conjunction with the <B>-l</B> -switch). - -<P> -Finally, note that <B>fundisp</B> can be used to create column filters from -the auxiliary tables in a FITS file. For example, the following shell code -will generate a good-time interval (GTI) filter for X-ray data files that -contain a standard GTI extension: -<PRE> - #!/bin/sh - sed '1,/---- .*/d - /^$/,$d' | awk 'tot>0{printf "||"};{printf "time="$1":"$2; tot++}' -</PRE> -If this script is placed in a file called "mkgti", it can be used in a -command such as: -<PRE> - fundisp foo.fits"[GTI]" | mkgti > gti.filter -</PRE> -The resulting filter file can then be used in various funtools programs: -<PRE> - funcnts foo.fits"[@gti.filter]" ... -</PRE> -to process only the events in the good-time intervals. - -<!-- =defdoc funhead funhead 1 --> - -<!-- =section funhead NAME --> -<H2><A NAME="funhead">funhead - display a header in a Funtools file</A></H2> - -<!-- =section funhead SYNOPSIS --> -<B> -<PRE> -funhead [-a] [-s] [-t] [-L] <iname> [oname ename] -</PRE> -</B> - -<!-- =section funhead OPTIONS --> -<P> -<PRE> - -a # display all extension headers - -s # display 79 chars instead of 80 before the new-line - -t # prepend data type char to each line of output - -L # output in rdb/starbase list format -</PRE> - -<!-- =section funhead DESCRIPTION --> -<P> -<B>funhead</B> displays the FITS header parameters in the specified -<A HREF="./files.html">FITS Extension</A>. -<P> -The first argument to the program specifies the Funtools input file -to display. If "stdin" is specified, data are read from -the standard input. <A HREF="./files.html">Funtools Bracket -Notation</A> is used to specify particular FITS extension to process. -Normally, the full 80 characters of each header card is output, -followed by a new-line. - -<P> -If the <B>-a</B> switch is specified, the header from each FITS -extensions in the file is displayed. Note, however, that the <B>-a</B> -switch does not work with FITS files input via stdin. We hope to -remove this restriction in a future release. - -<P> -If the <B>-s</B> switch is specified, only 79 characters are output -before the new-line. This helps the display on 80 character terminals. - -<P> -If the <B>-t</B> switch is specified, the data type of the parameter -is output as a one character prefix, followed by 77 characters of the -param. The parameter data types are defined as: FUN_PAR_UNKNOWN -('u'), FUN_PAR_COMMENT ('c'), FUN_PAR_LOGICAL ('l'), FUN_PAR_INTEGER -('i'), FUN_PAR_STRING ('s'), FUN_PAR_REAL ('r'), FUN_PAR_COMPLEX ('x'). - -<P> -If the <B>-L</B> (rdb table) switch is used, the output will conform -to starbase/rdb data base list format. - -<P> -For example to display the EVENTS extension (binary table): -<PRE> - [sh] funhead "foo.fits[EVENTS]" - XTENSION= 'BINTABLE' / FITS 3D BINARY TABLE - BITPIX = 8 / Binary data - NAXIS = 2 / Table is a matrix - NAXIS1 = 20 / Width of table in bytes - NAXIS2 = 30760 / Number of entries in table - PCOUNT = 0 / Random parameter count - GCOUNT = 1 / Group count - TFIELDS = 7 / Number of fields in each row - EXTNAME = 'EVENTS ' / Table name - EXTVER = 1 / Version number of table - TFORM1 = '1I ' / Data type for field - TTYPE1 = 'X ' / Label for field - TUNIT1 = ' ' / Physical units for field - TFORM2 = '1I ' / Data type for field - etc. ... - END -</PRE> - -<P> -To display the third header: -<PRE> - [sh] funhead "foo.fits[3]" - XTENSION= 'BINTABLE' / FITS 3D BINARY TABLE - BITPIX = 8 / Binary data - NAXIS = 2 / Table is a matrix - NAXIS1 = 32 / Width of table in bytes - NAXIS2 = 40 / Number of entries in table - PCOUNT = 0 / Random parameter count - GCOUNT = 1 / Group count - TFIELDS = 7 / Number of fields in each row - EXTNAME = 'TGR ' / Table name - EXTVER = 1 / Version number of table - TFORM1 = '1D ' / Data type for field - etc. ... - END -</PRE> - -<P> -To display the primary header (i.e., extension 0): -<PRE> - sh> funhead "coma.fits[0]" - SIMPLE = T /STANDARD FITS FORMAT - BITPIX = 16 /2-BYTE TWOS-COMPL INTEGER - NAXIS = 2 /NUMBER OF AXES - NAXIS1 = 800 / - NAXIS2 = 800 / - DATATYPE= 'INTEGER*2' /SHORT INTEGER - END -</PRE> - -<P> -The funhead program also can edit (i.e. add, delete, or modify) or -display individual headers parameters. Edit mode is signalled by the -presence of two additional command-line arguments: output file and -edit command file, in that order. Edit mode acts as a filter: the -output file will contain the entire input FITS file, including other -extensions. The edit command file can be "stdin", in which case edit -command are read from the standard input. - -<P> -The edit command file contains parameter comments (having '#' in the -first column) and delete and assignment(modify or add) operations. A -delete operation is specified by preceding the parameter name with a -minus sign "-". A display operation (very useful in interactive -sessions, i.e., where the edit commands are taken from stdin) is -specified by preceding the parameter name with a question mark "?". In -either case, a parameter value need not be specified. An assignment -operation is specified in the same two ways that a parameter is -specified in a text header (but without the comment character that -precedes header params), i.e.: - -<UL> -<LI> FITS-style comments have an equal sign "=" between the keyword and -value and an optional slash "/" to signify a comment. The strict FITS -rules on column positions are not enforced. - -<LI> Free-form comments can have an optional colon separator between the -keyword and value. In the absence of quote, all tokens after the -keyword are part of the value, i.e. no comment is allowed. -</UL> - -<P> -For example, the following interactive session checks for the -existence of parameters, adds new parameters, modifies them, and -modifies and deletes existing parameters: -<PRE> - sh$ ./funhead snr.ev foo.fits - - # look for FOO1 - ? FOO1 - WARNING: FOO1 not found - # add new foo1 - FOO1 = 100 - # add foo2 - FOO2 = 200 - # reset foo1 to a different value - FOO1 -1 - # delete foo2 - -FOO2 - # change existing value - EXTVER 2 - ? XS-SORT - XS-SORT = 'EOF ' / type of event sort - # delete existing value - -XS-SORT - # exit - ^D -</PRE> - -<P> -See <A HREF="./text.html">Column-based Text Files</A> -for more information about header parameter format. - -<P> - -<P> -<!-- =defdoc funhist funhist 1 --> - -<!-- =section funhist NAME --> -<H2><A NAME="funhist">funhist - create a 1D histogram of a column (from a FITS binary table or raw event file) or an image</A></H2> - -<!-- =section funhist SYNOPSIS --> -<B> -<PRE> -funhist [-n|-w|-T] <iname> [column] [[lo:hi:]bins] -</PRE> -</B> - -<!-- =section funhist OPTIONS --> -<P> -<PRE> - -n # normalize bin value by the width of each bin - -w # specify bin width instead of number of bins in arg3 - -T # output in rdb/starbase format (tab separators) -</PRE> - -<!-- =section funhist DESCRIPTION --> -<P> -<B>funhist</B> creates a one-dimensional histogram from the specified -columns of a <A HREF="./files.html">FITS Extension</A> -binary table of a FITS file (or from a non-FITS raw event file), or -from a FITS image or array, and writes that histogram as an ASCII -table. Alternatively, the program can perform a 1D projection of one -of the image axes. - -<P> -The first argument to the program is required, and specifies the -Funtools file: FITS table or image, raw event file, or array. If -"stdin" is specified, data are read from the standard input. Use -<A HREF="./files.html">Funtools Bracket Notation</A> to specify FITS -extensions, and filters. - -<P> -For a table, the second argument also is required. It specifies the -column to use in generating the histogram. If the data file is of -type image (or array), the column is optional: if "x" (or "X"), "y" -(or "Y") is specified, then a projection is performed over the x -(dim1) or y (dim2) axes, respectively. (That is, this projection will -give the same results as a histogram performed on a table containing -the equivalent x,y event rows.) If no column name is specified or -"xy" (or "XY") is specified for the image, then a histogram is -performed on the values contained in the image pixels. - -<P> -The argument that follows is optional and specifies the number of bins -to use in creating the histogram and, if desired, the range of bin -values. For image and table histograms, the range should specify the -min and max data values. For image histograms on the x and y axes, -the range should specify the min and max image bin values. If this -argument is omitted, the number of output bins for a table is -calculated either from the TLMIN/TLMAX headers values (if these exist -in the table FITS header for the specified column) or by going through -the data to calculate the min and max value. For an image, the number -of output bins is calculated either from the DATAMIN/DATAMAX header -values, or by going through the data to calculate min and max value. -(Note that this latter calculation might fail if the image cannot be -fit in memory.) If the data are floating point (table or image) and -the number of bins is not specified, an arbitrary default of 128 is -used. - -<P> -For binary table processing, the <B>-w</B> (bin width) switch can be used -to specify the width of each bin rather than the number of bins. Thus: -<PRE> - funhist test.ev pha 1:100:5 -</PRE> -means that 5 bins of width 20 are used in the histogram, while: -<PRE> - funhist -w test.ev pha 1:100:5 -</PRE> -means that 20 bins of width 5 are used in the histogram. - -<P> -The data are divvied up into the specified number of bins and the -resulting 1D histogram (or projection) is output in ASCII table -format. For a table, the output displays the low_edge (inclusive) and -hi_edge (exclusive) values for the data. For example, a 15-row table -containing a "pha" column whose values range from -7.5 to 7.5 -can be processed thus: - -<PRE> - [sh] funhist test.ev pha - # data file: /home/eric/data/test.ev - # column: pha - # min,max,bins: -7.5 7.5 15 - - bin value lo_edge hi_edge - ------ --------- --------------------- --------------------- - 1 22 -7.50000000 -6.50000000 - 2 21 -6.50000000 -5.50000000 - 3 20 -5.50000000 -4.50000000 - 4 19 -4.50000000 -3.50000000 - 5 18 -3.50000000 -2.50000000 - 6 17 -2.50000000 -1.50000000 - 7 16 -1.50000000 -0.50000000 - 8 30 -0.50000000 0.50000000 - 9 16 0.50000000 1.50000000 - 10 17 1.50000000 2.50000000 - 11 18 2.50000000 3.50000000 - 12 19 3.50000000 4.50000000 - 13 20 4.50000000 5.50000000 - 14 21 5.50000000 6.50000000 - 15 22 6.50000000 7.50000000 - - [sh] funhist test.ev pha 1:6 - # data file: /home/eric/data/test.ev - # column: pha - # min,max,bins: 0.5 6.5 6 - - bin value lo_edge hi_edge - ------ --------- --------------------- --------------------- - 1 16 0.50000000 1.50000000 - 2 17 1.50000000 2.50000000 - 3 18 2.50000000 3.50000000 - 4 19 3.50000000 4.50000000 - 5 20 4.50000000 5.50000000 - 6 21 5.50000000 6.50000000 - - [sh] funhist test.ev pha 1:6:3 - # data file: /home/eric/data/test.ev - # column: pha - # min,max,bins: 0.5 6.5 3 - - bin value lo_edge hi_edge - ------ --------- --------------------- --------------------- - 1 33 0.50000000 2.50000000 - 2 37 2.50000000 4.50000000 - 3 41 4.50000000 6.50000000 -</PRE> - -<P> -For a table histogram, the <B>-n</B>(normalize) switch can be used to -normalize the bin value by the width of the bin (i.e., hi_edge-lo_edge): -<PRE> - [sh] funhist -n test.ev pha 1:6:3 - # data file: test.ev - # column: pha - # min,max,bins: 0.5 6.5 3 - # width normalization (val/(hi_edge-lo_edge)) is applied - - bin value lo_edge hi_edge - ------ --------------------- --------------------- --------------------- - 1 16.50000000 0.50000000 2.50000000 - 2 6.16666667 2.50000000 4.50000000 - 3 4.10000000 4.50000000 6.50000000 -</PRE> -This could used, for example, to produce a light curve with values -having units of counts/second instead of counts. - -<P> -For an image histogram, the output displays the low and high image -values (both inclusive) used to generate the histogram. For example, -in the following example, 184 pixels had a value of 1, 31 had a value -of 2, while only 2 had a value of 3,4,5,6, or 7: -<PRE> - [sh] funhist test.fits - # data file: /home/eric/data/test.fits - # min,max,bins: 1 7 7 - - bin value lo_val hi_val - ------ --------------------- --------------------- --------------------- - 1 184.00000000 1.00000000 1.00000000 - 2 31.00000000 2.00000000 2.00000000 - 3 2.00000000 3.00000000 3.00000000 - 4 2.00000000 4.00000000 4.00000000 - 5 2.00000000 5.00000000 5.00000000 - 6 2.00000000 6.00000000 6.00000000 - 7 2.00000000 7.00000000 7.00000000 -</PRE> - -<P> -For the axis projection of an image, the output displays the low and -high image bins (both inclusive) used to generate the projection. For -example, in the following example, 21 counts had their X bin value of -2, etc.: -<PRE> - [sh] funhist test.fits x 2:7 - # data file: /home/eric/data/test.fits - # column: X - # min,max,bins: 2 7 6 - - bin value lo_bin hi_bin - ------ --------------------- --------------------- --------------------- - 1 21.00000000 2.00000000 2.00000000 - 2 20.00000000 3.00000000 3.00000000 - 3 19.00000000 4.00000000 4.00000000 - 4 18.00000000 5.00000000 5.00000000 - 5 17.00000000 6.00000000 6.00000000 - 6 16.00000000 7.00000000 7.00000000 - - [sh] funhist test.fits x 2:7:2 - # data file: /home/eric/data/test.fits - # column: X - # min,max,bins: 2 7 2 - - bin value lo_bin hi_bin - ------ --------------------- --------------------- --------------------- - 1 60.00000000 2.00000000 4.00000000 - 2 51.00000000 5.00000000 7.00000000 -</PRE> - -<P> -You can use gnuplot or other plotting programs to graph the -results, using a script such as: -<PRE> - #!/bin/sh - sed -e '1,/---- .*/d - /^$/,$d' | \ - awk '\ - BEGIN{print "set nokey; set title \"funhist\"; set xlabel \"bin\"; set ylabel \"counts\"; plot \"-\" with boxes"} \ - {print $3, $2, $4-$3}' | \ - gnuplot -persist - 1>/dev/null 2>&1 -</PRE> - -Similar plot commands are supplied in the script <B>funhist.plot</B>: -<PRE> - funhist test.ev pha ... | funhist.plot gnuplot -</PRE> - -<!-- =defdoc funimage funimage 1 --> - -<!-- =section funimage NAME --> -<H2><A NAME="funimage">funimage - create a FITS image from a Funtools data file</A></H2> - -<!-- =section funimage SYNOPSIS --> -<B> -<PRE> -funimage [-a] <iname> <oname> [bitpix=n] -funimage [-l] <iname> <oname> <xcol:xdims> <ycol:ydims> <vcol> [bitpix=n] -funimage [-p x|y] <iname> <oname> [bitpix=n] -</PRE> -</B> - -<!-- =section funimage OPTIONS --> -<P> -<PRE> - -a # append to existing output file as an image extension - -l # input is a list file containing xcol, ycol, value - -p [x|y] # project along x or y axis to create a 1D image -</PRE> - -<!-- =section funimage DESCRIPTION --> -<P> -<B>funimage</B> creates a primary FITS image from the specified -<A HREF="./files.html">FITS Extension</A> -and/or -<A HREF="./files.html#sections">Image Section</A> -of a FITS file, or from an -<A HREF="./files.html#sections">Image Section</A> -of a non-FITS array, or from a raw event file. -<P> -The first argument to the program specifies the FITS input image, -array, or raw event file to process. If "stdin" is specified, data are -read from the standard input. Use <A HREF="./files.html">Funtools -Bracket Notation</A> to specify FITS extensions, image sections, and -filters. The second argument is the output FITS file. If "stdout" is -specified, the FITS image is written to the standard output. By -default, the output pixel values are of the same data type as those of the -input file (or type "int" when binning a table), but this can be -overridden using an optional third argument of the form: -<PRE> - bitpix=n -</PRE> -where n is 8,16,32,-32,-64, for unsigned char, short, int, float and double, -respectively. - -<P> -If the input data are of type image, the appropriate section is -extracted and blocked (based on how the -<A HREF="./files.html#sections">Image Section</A> is specified), and -the result is written to the FITS primary image. When an integer -image containing the BSCALE and BZERO keywords is converted to float, -the pixel values are scaled and the scaling keywords are deleted from the -output header. When converting integer scaled data to integer -(possibly of a different size), the pixels are not scaled and the -scaling keywords are retained. - -<P> -If the input data is a binary table or raw event file, these are -binned into an image, from which a section is extracted and blocked, -and written to a primary FITS image. In this case, it is necessary to -specify the two columns that will be used in the 2D binning. This can -be done on the command line using the <B>bincols=(x,y)</B> keyword: -<PRE> - funcnts "foo.ev[EVENTS,bincols=(detx,dety)]" -</PRE> -The full form of the <B>bincols=</B> specifier is: -<PRE> - bincols=([xname[:tlmin[:tlmax:[binsiz]]]],[yname[:tlmin[:tlmax[:binsiz]]]]) -</PRE> -where the tlmin, tlmax, and binsiz specifiers determine the image binning -dimensions: -<PRE> - dim = (tlmax - tlmin)/binsiz (floating point data) - dim = (tlmax - tlmin)/binsiz + 1 (integer data) -</PRE> -Using this syntax, it is possible to bin any two columns of a binary -table at any bin size. Note that the tlmin, tlmax, and binsiz -specifiers can be omitted if TLMIN, TLMAX, and TDBIN header parameters -(respectively) are present in the FITS binary table header for the -column in question. Note also that if only one parameter is specified, -it is assumed to be tlmax, and tlmin defaults to 1. If two parameters -are specified, they are assumed to be tlmin and tlmax. -See <A HREF="./files.html#binning">Binning FITS Binary Tables and Non-FITS -Event Files</A> for more information about binning parameters. - -<p> -By default, a new 2D FITS image file is created and the image is written -to the primary HDU. If the <B>-a</B> (append) switch is specified, -the image is appended to an existing FITS file as an IMAGE extension. -(If the output file does not exist, the switch is effectively ignored -and the image is written to the primary HDU.) This can be useful in a -shell programming environment when processing multiple FITS images -that you want to combine into a single final FITS file. - -<P> -<B>funimage</B> also can take input from a table containing columns of -x, y, and value (e.g., the output from <B>fundisp -l</B> which -displays each image x and y and the number of counts at that -position.) When the <B>-l</B> (list) switch is used, the input file is -taken to be a FITS or ASCII table containing (at least) three columns -that specify the x and y image coordinates and the value of that -image pixel. In this case, <B>funimage</B> requires four extra -arguments: xcolumn:xdims, ycolumn:ydims, vcolumn and bitpix=n. The x -and y col:dim information takes the form: -<PRE> - name:dim # values range from 1 to dim - name:min:max # values range from min to max - name:min:max:binsiz # dimensions scaled by binsize -</PRE> -In particular, the min value should be used whenever the -minimum coordinate value is something other than one. For example: -<PRE> - funimage -l foo.lst foo.fits xcol:0:512 ycol:0:512 value bitpix=-32 -</PRE> - -<P> -The list feature also can be used to read unnamed columns from standard -input: simply replace the column name with a null string. Note -that the dimension information is still required: -<PRE> - funimage -l stdin foo.fits "":0:512 "":0:512 "" bitpix=-32 - 240 250 1 - 255 256 2 - ... - ^D -</PRE> - -<P> -The list feature provides a simple way to generate a blank image. -If you pass a <A HREF="./text.html">Column-based Text File</A> -to funimage in which the text header contains the required image -information, then funimage will correctly make a blank image. For -example, consider the following text file (called foo.txt): -<PRE> - x:I:1:10 y:I:1:10 - ------ ------ - 0 0 -</PRE> -This text file defines two columns, x and y, each of data type 32-bit int and -image dimension 10. The command: -<PRE> - funimage foo.txt foo.fits bitpix=8 -</PRE> -will create an empty FITS image called foo.fits containing a 10x10 -image of unsigned char: -<PRE> - fundisp foo.fits - 1 2 3 4 5 6 7 8 9 10 - ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ - 10: 0 0 0 0 0 0 0 0 0 0 - 9: 0 0 0 0 0 0 0 0 0 0 - 8: 0 0 0 0 0 0 0 0 0 0 - 7: 0 0 0 0 0 0 0 0 0 0 - 6: 0 0 0 0 0 0 0 0 0 0 - 5: 0 0 0 0 0 0 0 0 0 0 - 4: 0 0 0 0 0 0 0 0 0 0 - 3: 0 0 0 0 0 0 0 0 0 0 - 2: 0 0 0 0 0 0 0 0 0 0 - 1: 1 0 0 0 0 0 0 0 0 0 - -</PRE> - -Note that the text file must contain at least -one row of data. However, in the present example, event position 0,0 is -outside the limits of the image and will be ignored. (You can, of course, -use real x,y values to seed the image with data.) - -<P> -Furthermore, you can use the TEXT filter specification to obviate the need for -an input text file altogether. The following command will create the same -10x10 char image without an actual input file: -<PRE> - funimage stdin'[TEXT(x:I:10,y:I:10)]' foo.fits bitpix=8 < /dev/null -or - funimage /dev/null'[TEXT(x:I:10,y:I:10)]' foo.fits bitpix=8 -</PRE> - -<P> -You also can use either of these methods to generate a region mask simply -by appending a region inside the filter brackets and specfying <B>mask=all</B> -along with the bitpix. For example, the following command will generate a -10x10 char mask using 3 regions: -<PRE> - funimage stdin'[TEXT(x:I:10,y:I:10),cir(5,5,4),point(10,1),-cir(5,5,2)]' \ - foo.fits bitpix=8,mask=all < /dev/null -</PRE> -The resulting mask looks like this: -<PRE> - fundisp foo.fits - 1 2 3 4 5 6 7 8 9 10 - ------ ------ ------ ------ ------ ------ ------ ------ ------ ------ - 10: 0 0 0 0 0 0 0 0 0 0 - 9: 0 0 0 0 0 0 0 0 0 0 - 8: 0 0 1 1 1 1 1 0 0 0 - 7: 0 1 1 1 1 1 1 1 0 0 - 6: 0 1 1 0 0 0 1 1 0 0 - 5: 0 1 1 0 0 0 1 1 0 0 - 4: 0 1 1 0 0 0 1 1 0 0 - 3: 0 1 1 1 1 1 1 1 0 0 - 2: 0 0 1 1 1 1 1 0 0 0 - 1: 0 0 0 0 0 0 0 0 0 2 -</PRE> - -<P> -You can use <B>funimage</B> to create 1D image projections along the x -or y axis using the <b>-p [x|y]</b> switch. This capability works for -both images and tables. For example consider a FITS table named ev.fits -containing the following rows: -<PRE> - X Y - -------- -------- - 1 1 - 1 2 - 1 3 - 1 4 - 1 5 - 2 2 - 2 3 - 2 4 - 2 5 - 3 3 - 3 4 - 3 5 - 4 4 - 4 5 - 5 5 - -</PRE> -A corresponding 5x5 image, called dim2.fits, would therefore contain: -<PRE> - 1 2 3 4 5 - ---------- ---------- ---------- ---------- ---------- - 5: 1 1 1 1 1 - 4: 1 1 1 1 0 - 3: 1 1 1 0 0 - 2: 1 1 0 0 0 - 1: 1 0 0 0 0 -</PRE> -A projection along the y axis can be performed on either the table or -the image: -<PRE> - funimage -p y ev.fits stdout | fundisp stdin - 1 2 3 4 5 - ---------- ---------- ---------- ---------- ---------- - 1: 1 2 3 4 5 - - funimage -p y dim2.fits stdout | fundisp stdin - 1 2 3 4 5 - ---------- ---------- ---------- ---------- ---------- - 1: 1 2 3 4 5 -</PRE> - -<P> -Furthermore, you can create a 1D image projection along any column of -a table by using the <b>bincols=[column]</b> filter specification and -specifying a single column. For example, the following command -projects the same 1D image along the y axis of a table as use of -the <b>-p y</b> switch: -<PRE> - funimage ev.fits'[bincols=y]' stdout | fundisp stdin - 1 2 3 4 5 - ---------- ---------- ---------- ---------- ---------- - 1: 1 2 3 4 5 -</PRE> - -<P> -Examples: -<P> -Create a FITS image from a FITS binary table: -<PRE> - [sh] funimage test.ev test.fits -</PRE> - -<P> -Display the FITS image generated from a blocked section of FITS binary table: -<PRE> - [sh] funimage "test.ev[2:8,3:7,2]" stdout | fundisp stdin - 1 2 3 - --------- --------- --------- - 1: 20 28 36 - 2: 28 36 44 -</PRE> - -<!-- =defdoc funindex funindex 1 --> - -<!-- =section funindex NAME --> -<H2><A NAME="funindex">funindex - create an index for a column of a FITS binary table</A></H2> - -<!-- =section funindex SYNOPSIS --> -<B> -<PRE> -funindex <switches> <iname> <key> [oname] -</PRE> -</B> - -<!-- =section funindex OPTIONS --> -<P> -<PRE> - NB: these options are not compatible with Funtools processing. Please - use the defaults instead. - -c # compress output using gzip" - -a # ASCII output, ignore -c (default: FITS table)" - -f # FITS table output (default: FITS table)" - -l # long output, i.e. with key value(s) (default: long)" - -s # short output, i.e. no key value(s) (default: long)" -</PRE> - -<!-- =section funindex DESCRIPTION --> -<P> -The funindex script creates an index for the specified column (key) by -running funtable -s (sort) and then saving the column value and the -record number for each sorted row. This index will be used automatically - by funtools filtering of that column, provided the index file's modification -date is later than that of the data file. - -<p> -The first required argument is the name of the FITS binary table -to index. Please note that text files cannot be indexed at this time. -The second required argument is the column (key) name to index. While -multiple keys can be specified in principle, the funtools index processing -assume a single key and will not recognize files containing multiple keys. - -<P> -By default, the output index file name is [root]_[key].idx, where [root] -is the root of the input file. Funtools looks for this specific file name -when deciding whether to use an index for faster filtering. Therefore, the -optional third argument (output file name) should not be used for funtools -processing. - -<P> -For example, to create an index on column Y for a given FITS file, use: -<PRE> - funindex foo.fits Y -</PRE> -This will generate an index named foo_y.idx, which will be used by funtools -for filters involving the Y column. - -<!-- =defdoc funjoin funjoin 1 --> - -<!-- =section funjoin NAME --> -<H2><A NAME="funjoin">funjoin - join two or more FITS binary tables on specified columns</A></H2> - -<!-- =section funjoin SYNOPSIS --> -<B> -<PRE> -funjoin [switches] <ifile1> <ifile2> ... <ifilen> <ofile> -</PRE> -</B> - -<!-- =section funjoin OPTIONS --> -<P> -<PRE> - -a cols # columns to activate in all files - -a1 cols ... an cols # columns to activate in each file - -b 'c1:bvl,c2:bv2' # blank values for common columns in all files - -bn 'c1:bv1,c2:bv2' # blank values for columns in specific files - -j col # column to join in all files - -j1 col ... jn col # column to join in each file - -m min # min matches to output a row - -M max # max matches to output a row - -s # add 'jfiles' status column - -S col # add col as status column - -t tol # tolerance for joining numeric cols [2 files only] -</PRE> - -<!-- =section funjoin DESCRIPTION --> -<B>funjoin</B> joins rows from two or more (up to 32) -<A HREF="./files.html">FITS Binary Table files</A>, based on the values -of specified join columns in each file. NB: the join columns must have -an index file associated with it. These files are generated using the -<B>funindex</B> program. - -<P> -The first argument to the program specifies the first input FITS table -or raw event file. If "stdin" is specified, data are read from the -standard input. Subsequent arguments specify additional event files -and tables to join. The last argument is the output FITS file. - -<P> -NB: Do <B>not</B> use <A HREF="./files.html">Funtools Bracket -Notation</A> to specify FITS extensions and row filters when running -funjoin or you will get wrong results. Rows are accessed and joined -using the index files directly, and this bypasses all filtering. - -<P> -The join columns are specified using the <B>-j col</B> switch (which -specifies a column name to use for all files) or with <B>-j1 col1</B>, -<B>-j2 col2</B>, ... <B>-jn coln</B> switches (which specify a column -name to use for each file). A join column must be specified for each file. -If both <B>-j col</B> and <B>-jn coln</B> are specified for a given -file, then the latter is used. Join columns must either be of type -string or type numeric; it is illegal to mix numeric and string -columns in a given join. For example, to join three files using the -same key column for each file, use: -<PRE> - funjoin -j key in1.fits in2.fits in3.fits out.fits -</PRE> -A different key can be specified for the third file in this way: -<PRE> - funjoin -j key -j3 otherkey in1.fits in2.fits in3.fits out.fits -</PRE> - -<P> -The <B>-a "cols"</B> switch (and <B>-a1 "col1"</B>, -<B>-a2 "cols2"</B> counterparts) can be used to specify columns to -activate (i.e. write to the output file) for each input file. By -default, all columns are output. - -<P> -If two or more columns from separate files have the same name, the -second (and subsequent) columns are renamed to have an underscore -and a numeric value appended. - -<P> -The <B>-m min</B> and <B>-M max</B> switches specify the minimum -and maximum number of joins required to write out a row. The default -minimum is 0 joins (i.e. all rows are written out) and the default maximum -is 63 (the maximum number of possible joins with a limit of 32 input files). -For example, to write out only those rows in which exactly two files -have columns that match (i.e. one join): -<PRE> - funjoin -j key -m 1 -M 1 in1.fits in2.fits in3.fits ... out.fits -</PRE> - -<P> -A given row can have the requisite number of joins without all of the -files being joined (e.g. three files are being joined but only two -have a given join key value). In this case, all of the columns of the -non-joined file are written out, by default, using blanks (zeros or NULLs). -The <B>-b c1:bv1,c2:bv2</B> and -<B>-b1 'c1:bv1,c2:bv2' -b2 'c1:bv1,c2:bv2' ...</B> -switches can be used to set the blank value for columns common to all -files and/or columns in a specified file, respectively. Each blank value -string contains a comma-separated list of column:blank_val specifiers. -For floating point values (single or double), a case-insensitive string -value of "nan" means that the IEEE NaN (not-a-number) should be -used. Thus, for example: -<PRE> - funjoin -b "AKEY:???" -b1 "A:-1" -b3 "G:NaN,E:-1,F:-100" ... -</PRE> -means that a non-joined AKEY column in any file will contain the -string "???", the non-joined A column of file 1 will contain a value -of -1, the non-joined G column of file 3 will contain IEEE NaNs, while -the non-joined E and F columns of the same file will contain values -1 -and -100, respectively. Of course, where common and specific blank values -are specified for the same column, the specific blank value is used. - -<P> -To distinguish which files are non-blank components of a given row, -the <B>-s</B> (status) switch can be used to add a bitmask column named -"JFILES" to the output file. In this column, a bit is set for each -non-blank file composing the given row, with bit 0 corresponds to the -first file, bit 1 to the second file, and so on. The file names -themselves are stored in the FITS header as parameters named JFILE1, -JFILE2, etc. The <B>-S col</B> switch allows you to change the name -of the status column from the default "JFILES". - -<P> -A join between rows is the Cartesian product of all rows in one file -having a given join column value with all rows in a second file having -the same value for its join column and so on. Thus, if file1 has 2 -rows with join column value 100, file2 has 3 rows with the same value, -and file3 has 4 rows, then the join results in 2*3*4=24 rows being output. - -<P> -The join algorithm directly processes the index file associated with -the join column of each file. The smallest value of all the current -columns is selected as a base, and this value is used to join -equal-valued columns in the other files. In this way, the index files -are traversed exactly once. - -<P> -The <B>-t tol</B> switch specifies a tolerance value for numeric -columns. At present, a tolerance value can join only two files at a -time. (A completely different algorithm is required to join more than -two files using a tolerance, somethng we might consider implementing -in the future.) - -<P> -The following example shows many of the features of funjoin. The input files -t1.fits, t2.fits, and t3.fits contain the following columns: -<PRE> - [sh] fundisp t1.fits - AKEY KEY A B - ----------- ------ ------ ------ - aaa 0 0 1 - bbb 1 3 4 - ccc 2 6 7 - ddd 3 9 10 - eee 4 12 13 - fff 5 15 16 - ggg 6 18 19 - hhh 7 21 22 - -fundisp t2.fits - AKEY KEY C D - ----------- ------ ------ ------ - iii 8 24 25 - ggg 6 18 19 - eee 4 12 13 - ccc 2 6 7 - aaa 0 0 1 - -fundisp t3.fits - AKEY KEY E F G ------------- ------ -------- -------- ----------- - ggg 6 18 19 100.10 - jjj 9 27 28 200.20 - aaa 0 0 1 300.30 - ddd 3 9 10 400.40 -</PRE> - -<P> -Given these input files, the following funjoin command: -<PRE> - - funjoin -s -a1 "-B" -a2 "-D" -a3 "-E" -b \ - "AKEY:???" -b1 "AKEY:XXX,A:255" -b3 "G:NaN,E:-1,F:-100" \ - -j key t1.fits t2.fits t3.fits foo.fits -</PRE> -will join the files on the KEY column, outputting all columns except B -(in t1.fits), D (in t2.fits) and E (in t3.fits), and setting blank -values for AKEY (globally, but overridden for t1.fits) and A (in file -1) and G, E, and F (in file 3). A JFILES column will be output to -flag which files were used in each row: -<PRE> - - AKEY KEY A AKEY_2 KEY_2 C AKEY_3 KEY_3 F G JFILES - ------------ ------ ------ ------------ ------ ------ ------------ ------ -------- ----------- -------- - aaa 0 0 aaa 0 0 aaa 0 1 300.30 7 - bbb 1 3 ??? 0 0 ??? 0 -100 nan 1 - ccc 2 6 ccc 2 6 ??? 0 -100 nan 3 - ddd 3 9 ??? 0 0 ddd 3 10 400.40 5 - eee 4 12 eee 4 12 ??? 0 -100 nan 3 - fff 5 15 ??? 0 0 ??? 0 -100 nan 1 - ggg 6 18 ggg 6 18 ggg 6 19 100.10 7 - hhh 7 21 ??? 0 0 ??? 0 -100 nan 1 - XXX 0 255 iii 8 24 ??? 0 -100 nan 2 - XXX 0 255 ??? 0 0 jjj 9 28 200.20 4 - -</PRE> -<!-- =defdoc funmerge funmerge 1 --> - -<!-- =section funmerge NAME --> -<H2><A NAME="funmerge">funmerge - merge one or more Funtools table files</A></H2> - -<!-- =section funmerge SYNOPSIS --> -<B> -<PRE> -funmerge [-w|-x] -f [colname] <iname1> <iname2> ... <oname> -</PRE> -</B> - -<!-- =section funmerge OPTIONS --> -<P> -<PRE> - -f # output a column specifying file from which this event came - -w # adjust position values using WCS info - -x # adjust position values using WCS info and save old values -</PRE> - -<!-- =section funmerge DESCRIPTION --> -<P> -<B>funmerge</B> merges FITS data from one or more -<A HREF="./files.html">FITS Binary Table files</A> -or raw event files. -<P> -The first argument to the program specifies the first input FITS table -or raw event file. If "stdin" is specified, data are read from the -standard input. Use <A HREF="./files.html">Funtools Bracket -Notation</A> to specify FITS extensions and row filters. Subsequent -arguments specify additional event files and tables to merge. (NB: Stdin -cannot not be used for any of these additional input file arguments.) -The last argument is the output FITS file. The columns in each input table -must be identical. - -<P> -If an input file begins with the '@' character, it is processed as an -include file, i.e., as a text file containing event file names (as -well as blank lines and/or comment lines starting with the '#' sign). -If standard input is specified as an include file ('@stdin'), then -file names are read from the standard input until EOF (^D). Event -files and include files can be mixed on a command line. - -<P> -Rows from each table are written sequentially to the output -file. If the switch <B>-f [colname]</B> is specified on the command -line, an additional column is added to each row containing the number -of the file from which that row was taken (starting from one). In -this case, the corresponding file names are stored in the header -parameters having the prefix <B>FUNFIL</B>, i.e., FUNFIL01, -FUNFIL02, etc. - -<P> -Using the <B>-w</B> switch (or <B>-x</B> switch as described -below), <B>funmerge</B> also can adjust the position column values -using the WCS information in each file. (By position columns, we mean -the columns that the table is binned on, i.e., those columns defined -by the <B>bincols=</B> switch, or (X,Y) by default.) To perform WCS -alignment, the WCS of the first file is taken as the base WCS. Each -position in subsequent files is adjusted by first converting it to the -sky coordinate in its own WCS coordinate system, then by converting -this sky position to the sky position of the base WCS, and finally -converting back to a pixel position in the base system. Note that in -order to perform WCS alignment, the appropriate WCS and TLMIN/TLMAX -keywords must already exist in each FITS file. -<P> -When performing WCS alignment, you can save the original positions in -the output file by using the <B>-x</B> (for "xtra") switch instead -of the <B>-w</B> switch (i.e., using this switch also implies using -<B>-w</B>) The old positions are saved in columns having the same -name as the original positional columns, with the added prefix "OLD_". -<P> -Examples: - -<P> -Merge two tables, and preserve the originating file number for -each row in the column called "FILE" (along with the corresponding -file name in the header): -<PRE> - [sh] funmerge -f "FILE" test.ev test2.ev merge.ev -</PRE> - -<P> -Merge two tables with WCS alignment, saving the old position values in -2 additional columns: -<PRE> - [sh] funmerge -x test.ev test2.ev merge.ev -</PRE> - -<P> -This program only works on raw event files and binary tables. We have -not yet implemented image and array merging. - -<!-- =defdoc funsky funsky 1 --> - -<!-- =section funsky NAME --> -<H2><A NAME="funsky">funsky - convert between image and sky coordinates</A></H2> - -<!-- =section funsky SYNOPSIS --> -<B> -<PRE> - funsky iname[ext] # RA,Dec (deg) or image pix from stdin - funsky iname[ext] [lname] # RA, Dec (deg) or image pix from list - funsky iname[ext] [col1] [col2] # named cols:units from stdin - funsky iname[ext] [lname] [col1] [col2] # named cols:units from list -</PRE> -</B> - -<!-- =section funsky OPTIONS --> -<P> -<PRE> - -d # always use integer tlmin conversion (as ds9 does) - -r # convert x,y to RA,Dec (default: convert RA,Dec to x,y) - -o # include offset from the nominal target position (in arcsec) - -v # display input values also (default: display output only) - -T # output display in rdb format (w/header,tab delimiters) -</PRE> - -<!-- =section funsky DESCRIPTION --> -<P> -Funsky converts input sky coordinates (RA, Dec) to image coordinates (or vice -versa) using the WCS information contained in the specified FITS file. Several -calling sequences are supported in order to make it easy to specify -coordinate positions in different ways. - -<P> -The first required argument is always the input FITS file (or -extension) containing the WCS information in an extension header. Note -that the data from this file is not used. By default, the program -converts input RA and Dec values to X and Y using this WCS -information. If the WCS is associated with a FITS image, then the X,Y -values are image values. If the WCS is associated with a binary table, -then the X, Y values are physical values. To convert X,Y to RA and -Dec, use the <B>-r</B> (reverse) switch. - -<P> -If no other command arguments are supplied, then the input positions -are read from the standard input. Each line is assumed to contain a -single coordinate position consisting of an RA in degrees (or X in -pixels) followed by a Dec in degrees (or Y in pixels). The usual -delimiters are supported (spaces, commas, tabs). For example: -<PRE> - # read from stdin, default column names and units - [sh] funsky snr.ev - 22.982695 58.606523 # input RA (hrs), Dec(deg) - 510.00 510.00 - 22.982127 58.607634 # input - 512.00 510.50 - 22.981700 58.614301 # input - 513.50 513.50 - ^D # end of input -</PRE> - -<p> -If a second argument is supplied, this argument is assumed to be -a file containing RA (X) and Dec (Y) positions. The file can either be -an ASCII table or a FITS binary table. The order of columns is -unimportant, if the table has a column header. In this case, the -names of the columns must be one of "RA", "DEC", or "X", "Y" for sky -to image and image to sky conversions, respectively. If the table has -no header, then once again, RA (X) is assumed to first, followed -by DEC (Y). -For example: -<PRE> - # read from file, default column names and units - [sh] cat hd.in - RA DEC - --------- --------- - 22.982695 58.606523 - 22.982127 58.607634 - 22.981700 58.614301 - - [sh] funsky snr.ev hd.in - 510.00 510.00 - 512.00 510.50 - 513.50 513.50 -</PRE> - -<P> -If three arguments are supplied, then the input positions again are -read from the standard input. Each line is assumed to contain a single -coordinate position consisting of an RA (or X in pixels) followed by a -Dec (or Y in pixels), with the usual delimiters supported. However, -the second and third arguments now specify the column names and/or -sky units using a colon-delimited syntax: -<PRE> - [colname]:[h|d|r] -</PRE> -If the colname is omitted, the names default to "RA", "DEC", "X", "Y", -"COL1", or "COL2" as above. If the units are omitted, the default is degrees -for both RA and Dec. When the -r switch is used (convert from image -to sky) the units are applied to the output instead of the input. The following -examples will serve to illustrate the options: -<PRE> - # read from stdin, specifying column names (def. units: degrees) - [sh] cat hd.in - MYRA MYDEC - --------- --------- - 22.982695 58.606523 - 22.982127 58.607634 - 22.981700 58.614301 - - [sh] funsky snr.ev MYRA MYDEC < hd.in - 510.00 510.00 - 512.00 510.50 - 513.50 513.50 - - # read from stdin, specifying column names and units - [sh] cat dd.in - MYRA MYDEC - --------- --------- - 344.740432 58.606523 - 344.731900 58.607634 - 344.725500 58.614301 - - [sh] funsky snr.ev MYRA:d MYDEC:d < dd.in - 510.00 510.00 - 512.00 510.50 - 513.50 513.50 - - # read stdin, convert image to sky, specifying output sky units - [sh] cat im.in - 510.00 510.00 - 512.00 510.50 - 513.50 513.50 - - [sh] cat im.in | funsky -r snr.ev :d :d - 344.740432 58.606523 - 344.731900 58.607634 - 344.725500 58.614301 -</PRE> - -<P> -Finally, four command arguments specify both and input file and column names -and/or units: -<PRE> - [sh] cat dd.in - MYRA MYDEC - --------- --------- - 344.740432 58.606523 - 344.731900 58.607634 - 344.725500 58.614301 - - [sh] funsky snr.ev dd.in MYRA:d MYDEC:d - 510.00 510.00 - 512.00 510.50 - 513.50 513.50 - - # read file, convert image to sky, specifying output sky units - [sh] cat im.in - 510.00 510.00 - 512.00 510.50 - 513.50 513.50 - - [sh] funsky -r snr.ev im.in :d :d - 344.740432 58.606523 - 344.731900 58.607634 - 344.725500 58.614301 -</PRE> - -<P> -By default, the output of funsky consists only of the converted coordinate -position(s), one per output line. This makes parsing in shell scripts easy. -Use the <B>-v</B> (verbose) switch to specify that the input -coordinates should be pre-pended to each line. For example: -<PRE> - [sh] cat dd.in - MYRA MYDEC - --------- --------- - 344.740432 58.606523 - 344.731900 58.607634 - 344.725500 58.614301 - - [sh] funsky snr.ev dd.in MYRA:d MYDEC:d - 510.00 510.00 - 512.00 510.50 - 513.50 513.50 - - [sh] funsky -v snr.ev dd.in MYRA:d MYDEC:d - 344.740432 58.606523 510.00 510.00 - 344.731900 58.607634 512.00 510.50 - 344.725500 58.614301 513.50 513.50 -</PRE> - -<P> -In addition, a full starbase table can be output using the <B>-T</B> -(table) switch. This switch can be used with or without the -v -switch. If the -T and -v are both specified, then a descriptive header -parameters are output before the table (mainly to remind you of the -sky units): -<PRE> - # output table in non-verbose mode - [sh] funsky -T snr.ev dd.in MYRA:d MYDEC:d - X Y - ------------ ------------ - 510.00 510.00 - 512.00 510.50 - 513.50 513.50 - - # output table in verbose mode - [sh] funsky -T -v snr.ev dd.in MYRA:d MYDEC:d - # IFILE = /Users/eric/data/snr.ev - # ICOL1 = MYRA - # ICOL2 = MYDEC - # IUNITS1 = d - # IUNITS2 = d - # OCOL1 = X - # OCOL2 = Y - - MYRA MYDEC X Y - ------------ ------------ ------------ ------------ - 344.740432 58.606523 510.00 510.00 - 344.731900 58.607634 512.00 510.50 - 344.725500 58.614301 513.50 513.50 -</PRE> - -<P> -Finally, the <B>-d</B> (ds9) switch mimicks ds9's use of integer TLMIN -and TLMAX values for all coordinate transformations. FITS conventions -seem to call for use of floating point TLMIN and TLMAX when the data are -floats. This convention is followed by funsky but results in a -small discrepancy with ds9's converted values for floating point -data. We will remedy this conflict in the future, maybe. - -<!-- =defdoc funtable funtable 1 --> - -<!-- =section funtable NAME --> -<H2><A NAME="funtable">funtable - copy selected rows from a Funtools file to a FITS binary table</A></H2> - -<!-- =section funtable SYNOPSIS --> -<B> -<PRE> -funtable [-a] [-i|-z] [-m] [-s cols] <iname> <oname> [columns] -</PRE> -</B> - -<!-- =section funtable OPTIONS --> -<P> -<PRE> - -a # append to existing output file as a table extension - -i # for image data, only generate X and Y columns - -m # for tables, write a separate file for each region - -s "col1 ..." # columns on which to sort - -z # for image data, output zero-valued pixels -</PRE> - -<!-- =section funtable DESCRIPTION --> -<P> -<B>funtable</B> selects rows from the specified -<A HREF="./files.html">FITS Extension</A> -(binary table only) of a FITS file, or from a non-FITS raw event -file, and writes those rows to a FITS binary table file. It also -will create a FITS binary table from an image or a raw array file. - -<P> -The first argument to the program specifies the FITS file, raw event -file, or raw array file. If "stdin" is specified, data are read from -the standard input. Use <A HREF="./files.html">Funtools Bracket -Notation</A> to specify FITS extensions, and filters. The second -argument is the output FITS file. If "stdout" is specified, the FITS -binary table is written to the standard output. By default, all -columns of the input file are copied to the output file. Selected -columns can be output using an optional third argument in the form: -<PRE> - "column1 column1 ... columnN" -</PRE> - -<P> -The <B>funtable</B> program generally is used to select rows from a -FITS binary table using -<A HREF="./filters.html">Table Filters</A> -and/or -<A HREF="./regions.html">Spatial Region Filters</A>. -For example, you can copy only selected rows (and output only selected -columns) by executing in a command such as: -<PRE> - [sh] funtable "test.ev[pha==1&&pi==10]" stdout "x y pi pha" | fundisp stdin - X Y PHA PI - ------- ------- ------- --------- - 1 10 1 10 - 1 10 1 10 - 1 10 1 10 - 1 10 1 10 - 1 10 1 10 - 1 10 1 10 - 1 10 1 10 - 1 10 1 10 - 1 10 1 10 - 1 10 1 10 -</PRE> -<P> -The special column <B>$REGION</B> can be specified to write the -region id of each row: -<PRE> - [sh $] funtable "test.ev[time-(int)time>=.99&&annulus(0 0 0 10 n=3)]" stdout 'x y time $REGION' | fundisp stdin - X Y TIME REGION - -------- -------- --------------------- ---------- - 5 -6 40.99000000 3 - 4 -5 59.99000000 2 - -1 0 154.99000000 1 - -2 1 168.99000000 1 - -3 2 183.99000000 2 - -4 3 199.99000000 2 - -5 4 216.99000000 2 - -6 5 234.99000000 3 - -7 6 253.99000000 3 -</PRE> -<P> -Here only rows with the proper fractional time and whose position also is -within one of the three annuli are written. -<P> -Columns can be excluded from display using a minus sign before the -column: -<PRE> - [sh $] funtable "test.ev[time-(int)time>=.99]" stdout "-time" | fundisp stdin - X Y PHA PI DX DY - -------- -------- -------- ---------- ----------- ----------- - 5 -6 5 -6 5.50 -6.50 - 4 -5 4 -5 4.50 -5.50 - -1 0 -1 0 -1.50 0.50 - -2 1 -2 1 -2.50 1.50 - -3 2 -3 2 -3.50 2.50 - -4 3 -4 3 -4.50 3.50 - -5 4 -5 4 -5.50 4.50 - -6 5 -6 5 -6.50 5.50 - -7 6 -7 6 -7.50 6.50 -</PRE> -All columns except the time column are written. -<P> -In general, the rules for activating and de-activating columns are: -<UL> -<LI> If only exclude columns are specified, then all columns but -the exclude columns will be activated. -<LI> If only include columns are specified, then only the specified columns -are activated. -<LI> If a mixture of include and exclude columns are specified, then -all but the exclude columns will be active; this last case -is ambiguous and the rule is arbitrary. -</UL> -In addition to specifying columns names explicitly, the special -symbols <EM>+</EM> and <EM>-</EM> can be used to activate and -de-activate <EM>all</EM> columns. This is useful if you want to -activate the $REGION column along with all other columns. According -to the rules, the syntax "$REGION" only activates the region column -and de-activates the rest. Use "+ $REGION" to activate all -columns as well as the region column. - -<P> -Ordinarily, only the selected table is copied to the output file. In -a FITS binary table, it sometimes is desirable to copy all of the -other FITS extensions to the output file as well. This can be done by -appending a '+' sign to the name of the extension in the input file -name. For example, the first command below copies only the EVENT table, -while the second command copies other extensions as well: -<PRE> - [sh] funtable "/proj/rd/data/snr.ev[EVENTS]" events.ev - [sh] funtable "/proj/rd/data/snr.ev[EVENTS+]" eventsandmore.ev -</PRE> - -<P> -If the input file is an image or a raw array file, then -<B>funtable</B> will generate a FITS binary table from the pixel -values in the image. Note that it is not possible to specify the -columns to output (using command-line argument 3). Instead, there are -two ways to create such a binary table from an image. By default, a -3-column table is generated, where the columns are "X", "Y", and -"VALUE". For each pixel in the image, a single row (event) is -generated with the "X" and "Y" columns assigned the dim1 and dim2 -values of the image pixel, respectively and the "VALUE" column -assigned the value of the pixel. With sort of table, running -<B>funhist</B> on the "VALUE" column will give the same results as -running <B>funhist</B> on the original image. - -<P> -If the <B>-i</B> ("individual" rows) switch is specified, then only -the "X" and "Y" columns are generated. In this case, each positive -pixel value in the image generates n rows (events), where n is equal -to the integerized value of that pixel (plus 0.5, for floating point -data). In effect, <B>-i</B> approximately recreates the rows of a -table that would have been binned into the input image. (Of course, -this is only approximately correct, since the resulting x,y positions -are integerized.) - -<P> -If the <B>-s [col1 col2 ... coln]</B> ("sort") switch is specified, -the output rows of a binary table will be sorted using the -specified columns as sort keys. The sort keys must be scalar columns -and also must be part of the output file (i.e. you cannot sort on a -column but not include it in the output). This facility uses the -<B>_sort</B> program (included with funtools), which must be accessible -via your path. - -<p> -For binary tables, the <B>-m</B> ("multiple files") switch will -generate a separate file for each region in the filter specification -i.e. each file contains only the rows from that region. Rows -which pass the filter but are not in any region also are put in a -separate file. - -<P> -The separate output file names generated by the <B>-m</B> switch are -produced automatically from the root output file to contain the region id of -the associated region. (Note that region ids start at 1, so that the -file name associated with id 0 contains rows that pass the filter but -are not in any given region.) Output file names are generated as follows: - -<UL> -<LI> A $n specification can be used anywhere in the root file name (suitably -quoted to protect it from the shell) and will be expanded to be the id -number of the associated region. For example: -<PRE> - funtable -m input.fits'[cir(512,512,1);cir(520,520,1)...]' 'foo.goo_$n.fits' -</PRE> -will generate files named foo.goo_0.fits (for rows not in any region but -still passing the filter), foo.goo_1.fits (rows in region id #1, the first -region), foo.goo_2.fits (rows in region id #2), etc. Note that single quotes -in the output root are required to protect the '$' from the shell. - -<LI> If $n is not specified, then the region id will be placed before -the first dot (.) in the filename. Thus: -<PRE> - funtable -m input.fits'[cir(512,512,1);cir(520,520,1)...]' foo.evt.fits -</PRE> -will generate files named foo0.evt.fits (for rows not in any region but -still passing the filter), foo1.evt.fits (rows in region id #1), -foo2.evt.fits (rows in region id #2), etc. - -<LI> If no dot is specified in the root output file name, then -the region id will be appended to the filename. Thus: -<PRE> - funtable -m input.fits'[cir(512,512,1);cir(520,520,1)...]' 'foo_evt' -</PRE> -will generate files named foo_evt0 (for rows not in any region but -still passing the filter), foo_evt1 (rows in region id #1), -foo_evt2 (rows in region id #2), etc. -</UL> -The multiple file mechanism provide a simple way to generate -individual source data files with a single pass through the data. - -<p> -By default, a new FITS file is created and the binary table is written -to the first extension. If the <B>-a</B> (append) switch is specified, -the table is appended to an existing FITS file as a BINTABLE extension. -Note that the output FITS file must already exist. - -<P> -If the <B>-z</B> ("zero" pixel values) switch is specified and -<B>-i</B> is not specified, then pixels having a zero value will -be output with their "VALUE" column set to zero. Obviously, this -switch does not make sense when individual events are output. - -<!-- =defdoc funtbl funtbl 1 --> - -<!-- =section funtbl NAME --> -<H2><A NAME="funtbl">funtbl - extract a table from Funtools ASCII output</A></H2> - -<!-- =section funtbl SYNOPSIS --> -<B> -<PRE> -funtable [-c cols] [-h] [-n table] [-p prog] [-s sep] <iname> -</PRE> -</B> - -<!-- =section funtbl DESCRIPTION --> -<P> -[NB: This program has been deprecated in favor of the ASCII text processing -support in funtools. You can now perform fundisp on funtools ASCII output -files (specifying the table using bracket notation) to extract tables -and columns.] - -The <B>funtbl</B> script extracts a specified table (without the -header and comments) from a funtools ASCII output file and writes the -result to the standard output. The first non-switch argument is the -ASCII input file name (i.e. the saved output from funcnts, fundisp, -funhist, etc.). If no filename is specified, stdin is read. The --n switch specifies which table (starting from 1) to extract. The -default is to extract the first table. The -c switch is a -space-delimited list of column numbers to output, e.g. -c "1 3 5" -will extract the first three odd-numbered columns. The default is to -extract all columns. The -s switch specifies the separator string to -put between columns. The default is a single space. The -h switch -specifies that column names should be added in a header line before -the data is output. Without the switch, no header is prepended. The --p program switch allows you to specify an awk-like program to run -instead of the default (which is host-specific and is determined at -build time). The -T switch will output the data in rdb format (i.e., -with a 2-row header of column names and dashes, and with data columns -separated by tabs). The -help switch will print out a message -describing program usage. - -<P> -For example, consider the output from the following funcnts command: -<PRE> - [sh] funcnts -sr snr.ev "ann 512 512 0 9 n=3" - # source - # data file: /proj/rd/data/snr.ev - # arcsec/pixel: 8 - # background - # constant value: 0.000000 - # column units - # area: arcsec**2 - # surf_bri: cnts/arcsec**2 - # surf_err: cnts/arcsec**2 - - # summed background-subtracted results - upto net_counts error background berror area surf_bri surf_err - ---- ------------ --------- ------------ --------- --------- --------- --------- - 1 147.000 12.124 0.000 0.000 1600.00 0.092 0.008 - 2 625.000 25.000 0.000 0.000 6976.00 0.090 0.004 - 3 1442.000 37.974 0.000 0.000 15936.00 0.090 0.002 - - - # background-subtracted results - reg net_counts error background berror area surf_bri surf_err - ---- ------------ --------- ------------ --------- --------- --------- --------- - 1 147.000 12.124 0.000 0.000 1600.00 0.092 0.008 - 2 478.000 21.863 0.000 0.000 5376.00 0.089 0.004 - 3 817.000 28.583 0.000 0.000 8960.00 0.091 0.003 - - - # the following source and background components were used: - source_region(s) - ---------------- - ann 512 512 0 9 n=3 - - reg counts pixels sumcnts sumpix - ---- ------------ --------- ------------ --------- - 1 147.000 25 147.000 25 - 2 478.000 84 625.000 109 - 3 817.000 140 1442.000 249 -</PRE> -<P> -There are four tables in this output. To extract the last one, you -can execute: -<PRE> - [sh] funcnts -s snr.ev "ann 512 512 0 9 n=3" | funtbl -n 4 - 1 147.000 25 147.000 25 - 2 478.000 84 625.000 109 - 3 817.000 140 1442.000 249 -</PRE> -Note that the output has been re-formatted so that only a single space -separates each column, with no extraneous header or comment information. - -<P> -To extract only columns 1,2, and 4 from the last example (but with a header -prepended and tabs between columns), you can execute: -<PRE> - [sh] funcnts -s snr.ev "ann 512 512 0 9 n=3" | funtbl -c "1 2 4" -h -n 4 -s "\t" - #reg counts sumcnts - 1 147.000 147.000 - 2 478.000 625.000 - 3 817.000 1442.000 -</PRE> -<P> -Of course, if the output has previously been saved in a file named -foo.out, the same result can be obtained by executing: -<PRE> - [sh] funtbl -c "1 2 4" -h -n 4 -s "\t" foo.out - #reg counts sumcnts - 1 147.000 147.000 - 2 478.000 625.000 - 3 817.000 1442.000 -</PRE> - -<!-- =section funcalc SEE ALSO --> -<!-- =text See funtools(n) for a list of Funtools help pages --> -<!-- =section funcen SEE ALSO --> -<!-- =text See funtools(n) for a list of Funtools help pages --> -<!-- =section funcnts SEE ALSO --> -<!-- =text See funtools(n) for a list of Funtools help pages --> -<!-- =section funcone SEE ALSO --> -<!-- =text See funtools(n) for a list of Funtools help pages --> -<!-- =section fundisp SEE ALSO --> -<!-- =text See funtools(n) for a list of Funtools help pages --> -<!-- =section funhead SEE ALSO --> -<!-- =text See funtools(n) for a list of Funtools help pages --> -<!-- =section funhist SEE ALSO --> -<!-- =text See funtools(n) for a list of Funtools help pages --> -<!-- =section funimage SEE ALSO --> -<!-- =text See funtools(n) for a list of Funtools help pages --> -<!-- =section funindex SEE ALSO --> -<!-- =text See funtools(n) for a list of Funtools help pages --> -<!-- =section funjoin SEE ALSO --> -<!-- =text See funtools(n) for a list of Funtools help pages --> -<!-- =section funmerge SEE ALSO --> -<!-- =text See funtools(n) for a list of Funtools help pages --> -<!-- =section funsky SEE ALSO --> -<!-- =text See funtools(n) for a list of Funtools help pages --> -<!-- =section funtable SEE ALSO --> -<!-- =text See funtools(n) for a list of Funtools help pages --> -<!-- =section funtbl SEE ALSO --> -<!-- =text See funtools(n) for a list of Funtools help pages --> -<!-- =stop --> - -<P> -<A HREF="./help.html">Go to Funtools Help Index</A> - -<H5>Last updated: April 1, 2007</H5> - -</BODY> -</HTML> |