funcalc [-n] [-e expr] [-f file] [-l link] <iname> [oname [columns]] funcnts [switches] <source_file> [source_region] [bkgd_file] [bkgd_region|bkgd_cnts] fundisp [-f format] [-l] [-T] <iname> [columns|bitpix=n] funhead [-a] [-s] <iname> funhist [-n|-w] <iname> [column] [[lo_edge:hi_edge:]bins] funimage <iname> <oname> [bitpix=n] funmerge <iname1> <iname2> ... <oname> funtable [-i|-z] <iname> <oname> [columns]
funcalc [-n] [-e expr] [-f file] [-l link] <iname> [oname [columns]]funcalc 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. funcalc expressions are C statements, although some important simplifications (such as automatic declaration of variables) are supported.
funcalc expressions can be specified in three ways: on the command line using the -e [expression] switch, in a file using the -f [file] switch, or from stdin (if neither -e nor -f is specified). Of course a file containing funcalc expressions can be read from stdin.
Each invocation of funcalc 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 funcalc 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 FunColumnActivate()). Note that funcalc determines whether or not to generate code for writing an output file based on the presence or absence of an output file argument.
A funcalc 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 current row using the C struct syntax cur->[colname], 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 funcalc (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 funcalc expressions:
double temp; temp = cur->x; cur->x = cur->y; cur->y = temp;or:
temp = cur->x; cur->x = cur->y; cur->y = temp;When this expression is executed using a command such as:
funcalc -f swap.expr itest.ev otest.evthe resulting file will have values of the x and y columns swapped.
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:
temp = cur->x:D; cur->x = cur->y:D; cur->y = temp;Data type specifiers follow standard FITS table syntax for defining columns using TFORM:
Of course, it is important to handle the data type of the columns correctly. One of the most frequent cause of error in funcalc programming is the implicit use of the wrong data type for a column in expression. For example, the calculation:
dx = (cur->x - cur->y)/(cur->x + cur->y);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:
dx = (cur->x:D - cur->y:D)/(cur->x + cur->y);Alternatively, it can be done using C type-casting in the expression:
dx = ((double)cur->x - (double)cur->y)/((double)cur->x + (double)cur->y);
In addition to accessing columns in the current row, reference also can be made to the previous row using prev->[colname], and to the next row using next->[colname]. Note that if prev->[colname] is specified in the funcalc expression, the very first row is not processed. If next->[colname] is specified in the funcalc expression, the very last row is not processed. In this way, prev and next 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 funcalc expression:
fprintf(stdout, "%d %d\n", cur->x, prev->y);
New columns can be specified using the same cur->[colname] 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.
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:
cur->avg:D = (cur->x + cur->y)/2.0Note that the final ';' is not required for single-line expressions.
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 funcalc expression, after which it can be used without re-specifying the type. This includes reference to elements of a column array:
cur->avg[0]:2D = (cur->x + cur->y)/2.0; cur->avg[1] = (cur->x - cur->y)/2.0;
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:
cur->stat[0]:16X = 1; cur->stat[1] = 2;Here, a 16-bit column is created with the MSB is set to 1 and the LSB set to 2.
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 funcalc 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:
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;
If no output file argument is specified on the funcalc 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:
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);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.
When an output file is specified, the selected input table is processed and output rows are 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. See funtable for a related example.
funcalc works by integrating the user-specified expression into a template C program called tabcalc.c. The completed program then is compiled and executed. Variable declarations that begin the funcalc 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 FunColumnSelect() and used in FunTableRowGet(). 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.
Normally, funcalc expression code is added to funcalc 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:
[directive name]
... code goes here ...
end
The directives are:
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
Routines such as init() and finish() above are passed to the generated
program for linking using the -l [link directives ...]
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:
funcalc -l "-L/opt/special/lib -lmysubs" ...
If the -n 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.)
As mentioned previously, funcalc 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 funcalc.sed, 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.
In order to keep the lexical analysis of funcalc 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 local...end block) will usually end up in the inner loop, not with the local declarations:
/* 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;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.
Because funcalc 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: funcalc cannot be used as a filter. We will consider removing this restriction at a later time.
Along with C comments, funcalc expressions can have one-line internal comments that are not passed on to the generated C program. These internal comment start with the # character and continue up to the new-line:
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;
Finally, note that funcalc 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.
funcnts [switches] <source_file> [source_region] [bkgd_file] [bkgd_region|bkgd_value]
optional switches:
-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)
-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
-T # output in starbase/rdb format
-z # output regions with zero area
funcnts counts photons in the specified source regions and reports the results for each region. Regions are specified using the Spatial Region Filtering 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.
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 Funtools Bracket Notation to specify FITS extensions, image sections, and filters. The optional second argument is the source region descriptor. If no region is specified, the entire field is used.
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).
In summary, the following command arguments are valid:
[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
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:
[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 23572The 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 -p 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 -z switch.
Note that a simple sed command will extract the background-subtracted results for further analysis:
[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
If separate source and background files are specified, funcnts 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.
Normally, if more than one background region is specified, funcnts will combine them all into a single region and use this background region to produce the background-subtracted results for each source region. The -m (match multiple backgrounds) switch tells funcnts 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:
[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 23572Note that the basic region filter rule "each photon is counted once and no photon is counted more than once" still applies when using The -m 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, then the first will get all the counts and area and the second will get none.
Using the -m switch causes funcnts to use each of the two background regions independently with each of the two source regions:
[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
Note that most floating point quantities are displayed using "f" format. You can change this to "g" format using the -g 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 -G, which outputs all floating values as %.14g.
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 -r switch will add radii and angle columns to the output table:
[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
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 funcnts.plot 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:
#!/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
Thus, to run funcnts and plot the results using gnuplot (version 3.7
or above), use:
funcnts -r snr.ev "annulus(502,512,0,50,n=5)" ... | funcnts.plot gnuplot
The -s (sum) switch causes funcnts to produce an additional table of summed (integrated) background subtracted values, along with the default table of individual values:
[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
The -t and -e 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:
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 mapThen, Net Counts in Source region is
Net = C - B * (Ac*Tc*Ec)/(Ab*Tb*Eb)with the standard propagation of errors for the Error on Net. The net rate would then be
Net Rate = Net/(Ac*Tc*Ec)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 funcnts will deal with the blocking automatically. Using the -e 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, funcnts 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.
NB: The -e switch assumes that the exposure map overlays the image file exactly, 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, do not use the -e exposure correction. In this case, it still is possible to perform exposure correction if both the image and the exposure map have valid WCS information: use the -w 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 -w can increase the time required to process the exposure correction considerably.
A time correction can be applied to both source and background data using the -t 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:
[sh]$ funcnts -t 23.4 ... # number for source [sh]$ funcnts -t "LIVETIME;23.4" ... # param for source, numeric for bkgdWhen 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.
If the -T (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.
Finally, note that funcnts 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 funcnts can differ from the number of events found using row-filter programs such as fundisp or funtable For more information about these difference, see the discussion of Region Boundaries.
fundisp [-f format] [-l] [-T] <iname> [columns|bitpix=n]
fundisp displays the data in the specified FITS Extension and/or Image Section of a FITS file, or in an Image Section of a non-FITS array or raw event file.
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 Funtools Bracket Notation to specify FITS extensions, image sections, and filters.
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:
[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
[NB: The FITS binary table test file test.ev, as well as the FITS
image test.fits, are contained in the funtools funtest directory.]
When a table is being displayed using fundisp, a second optional argument can be used to specify the columns to display. For example:
[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
The special column $REGION can be specified to display the region id of each row:
[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
Here only rows with the proper fractional time and whose position also is within one of the three annuli are displayed.
Columns can be excluded from display using a minus sign before the column:
[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
All columns except the time column are displayed.
The special column $N can be specified to display the ordinal value of each row. Thus, continuing the previous example:
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
Note that the column specification is enclosed in single quotes to protect
'$n' from begin expanded by the shell.
In general, the rules for activating and de-activating columns are:
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, but this can be overridden using an optional second argument of the form:
bitpix=nwhere n is 8,16,32,-32,-64, for unsigned char, short, int, float and double, respectively.
Of course, running fundisp 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:
[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
Note that is is possible to display a FITS binary table as an image simply by passing the table through funimage first:
[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
If the -l (list) switch is used, then an image is displayed as a
list containing the columns: X, Y, VAL. For example:
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
The fundisp program uses a default set of display formats:
datatype TFORM format -------- ----- -------- double D "%21.8f" float F "%11.2f" int J "%10d" short I "%8d" byte B "%6d" string A "%12.12s" bits X "%8x" logical L "%1x"Thus, the default display of 1 double and 2 shorts gives:
[sh]$ fundisp snr.ev "time x y"
TIME X Y
--------------------- -------- --------
79494546.56818075 546 201
79488769.94469175 548 201
...
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:
[sh]$ fundisp -f "D=%22.11f I=%3d" snr.ev "time x y"
TIME X Y
---------------------- --- ---
79494546.56818075478 546 201
79488769.94469174743 548 201
...
Alternatively, you can change the format of the time and x columns like this:
[sh] fundisp -f "time=%22.11f x=%3d" snr.ev "time x y"
TIME X Y
---------------------- --- --------
79494546.56818075478 546 201
79488769.94469174743 548 201
...
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:
[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
...
As a rule, therefore, it is best always to specify the column name in
lower case and TFORM data types in upper case. Please also note that it
is the user's responsibility to match the format specifier to the column
data type correctly.
[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:
double float int short byte string bit.This order of the list is based on the assumption that people generally will want to change the float formats.
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:
[sh]$ fundisp -f "22.11f - - 3d" snr.ev "time x y"
TIME X Y
---------------------- --- ---
79494546.56818075478 546 201
79488769.94469174743 548 201
...
NB: This format is deprecated and will be removed in a future release.]
If the -T (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 -l switch).
Finally, note that fundisp 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:
#!/bin/sh
sed '1,/---- .*/d
/^$/,$d' | awk 'tot>0{printf "||"};{printf "time="$1":"$2; tot++}'
If this script is placed in a file called "mkgti", it can be used in a
command such as:
fundisp foo.fits"[GTI]" | mkgti > gti.filterThe resulting filter file can then be used in various funtools programs:
funcnts foo.fits"[@gti.filter]" ...to process only the events in the good-time intervals.
funhead [-a] [-s] <iname>
funhead displays the FITS header parameters in the specified FITS Extension.
The first argument to the program specifies the Funtools input file to display. If "stdin" is specified, data are read from the standard input. Funtools Bracket Notation 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.
If the -a switch is specified, the header from each FITS extensions in the file is displayed. Note, however, that the -a switch does not work with FITS files input via stdin. We hope to remove this restriction in a future release.
If the -s switch is specified, only 79 characters are output before the new-line. This helps the display on 80 character terminals.
If the -t 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').
For example to display the EVENTS extension (binary table):
[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
To display the third header:
[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
To display the primary header (i.e., extension 0):
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
funhist [-n|-w] <iname> [column] [[lo:hi:]bins]
funhist creates a one-dimensional histogram from the specified columns of a FITS Extension 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.
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 Funtools Bracket Notation to specify FITS extensions, and filters.
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.
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.
For binary table processing, the -w (bin width) switch can be used to specify the width of each bin rather than the number of bins. Thus:
funhist test.ev pha 1:100:5means that 5 bins of width 20 are used in the histogram, while:
funhist -w test.ev pha 1:100:5means that 20 bins of width 5 are used in the histogram.
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:
[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
For a table histogram, the -n(normalize) switch can be used to normalize the bin value by the width of the bin (i.e., hi_edge-lo_edge):
[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
This could used, for example, to produce a light curve with values
having units of counts/second instead of counts.
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:
[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
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.:
[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
You can use gnuplot or other plotting programs to graph the results, using a script such as:
#!/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
Similar plot commands are supplied in the script funhist.plot:
funhist test.ev pha ... | funhist.plot gnuplot
funimage <iname> <oname> [bitpix=n]
funimage creates a primary FITS image from the specified FITS Extension and/or Image Section of a FITS file, or from an Image Section of a non-FITS array, or from a raw event file.
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 Funtools Bracket Notation 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:
bitpix=nwhere n is 8,16,32,-32,-64, for unsigned char, short, int, float and double, respectively.
If the input data are of type image, the appropriate section is extracted and blocked (based on how the Image Section is specified), and the result is written to the FITS primary image.
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 bincols=(x,y) keyword:
funcnts "foo.ev[EVENTS,bincols=(detx,dety)]"The full form of the bincols= specifier is:
bincols=([xname[:tlmin[:tlmax:[binsiz]]]],[yname[:tlmin[:tlmax[:binsiz]]]])where the tlmin, tlmax, and binsiz specifiers determine the image binning dimensions:
dim = (tlmax - tlmin)/binsiz (floating point data) dim = (tlmax - tlmin)/binsiz + 1 (integer data)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 Binning FITS Binary Tables and Non-FITS Event Files for more information about binning parameters.
Examples:
Create a FITS image from a FITS binary table:
[sh]$ funimage test.ev test.fits
Display the FITS image generated from a blocked section of FITS binary table:
[sh]$ funimage "test.ev[2:8,3:7,2]" stdout | fundisp stdin
1 2 3
--------- --------- ---------
1: 20 28 36
2: 28 36 44
funmerge [-w|-x] -f [colname] <iname1> <iname2> ... <oname>
funmerge merges FITS data from one or more FITS Binary Table files or raw event files.
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 Funtools Bracket Notation to specify FITS extensions and row filters. Subsequent arguments specify additional event files and tables to merge. The last argument is the output FITS file. The columns in each input table must be identical.
Rows from each table are written sequentially to the output file. If the switch -f [colname] 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 FUNFIL, i.e., FUNFIL01, FUNFIL02, etc.
Using the -w switch (or -x switch as described below), funmerge 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 bincols= 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.
When performing WCS alignment, you can save the original positions in the output file by using the -x (for "xtra") switch instead of the -w switch (i.e., using this switch also implies using -w) The old positions are saved in columns having the same name as the original positional columns, with the added prefix "OLD_".
Examples:
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):
[sh]$ funmerge -f "FILE" test.ev test2.ev merge.ev
Merge two tables with WCS alignment, saving the old position values in 2 additional columns:
[sh]$ funmerge -x test.ev test2.ev merge.ev
This program only works on raw event files and binary tables. We have not yet implemented image and array merging.
funtable <iname> <oname> [columns]
funtable selects rows from the specified FITS Extension (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.
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 Funtools Bracket Notation 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:
"column1 column1 ... columnN"
The funtable program generally is used to select rows from a FITS binary table by Specifying Table and Region Filters. For example, you can copy only selected rows (and output only selected columns) by executing in a command such as:
[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
The special column $REGION can be specified to write the region id of each row:
[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
Here only rows with the proper fractional time and whose position also is within one of the three annuli are written.
Columns can be excluded from display using a minus sign before the column:
[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
All columns except the time column are written.
In general, the rules for activating and de-activating columns are:
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:
[sh]$ funtable "/proj/rd/data/snr.ev[EVENTS]" events.ev [sh]$ funtable "/proj/rd/data/snr.ev[EVENTS+]" eventsandmore.ev
If the input file is an image or a raw array file, then funtable 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 funhist on the "VALUE" column will give the same results as running funhist on the original image.
If the -i ("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, -i 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.)
If the -s [col1 col2 ... coln] ("sort") switch is specified, then 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 _sort program (included with funtools), which must be accessible via your path.
If the -z ("zero" pixel values) switch is specified and -i 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.