Merge commit '23c7930d27fe11c4655e1291a07a821dbbaba78d' as 'funtools'

10 files changed, 1005 insertions, 0 deletions

diff --git a/funtools/faq/Makefile.in b/funtools/faq/Makefile.in
new file mode 100644
index 0000000..09900f5
--- /dev/null
+++ b/funtools/faq/Makefile.in
@@ -0,0 +1,135 @@
+#
+# This is a Makefile for the Funtools testing. If it has the name "Makefile.in"
+# then it is a template for a Makefile;  to generate the actual Makefile,
+# run "./configure", which is a configuration script generated by the
+# "autoconf" program (constructs like "@foo@" will get replaced in the
+# actual Makefile.
+#
+
+#----------------------------------------------------------------
+# Things you can change to personalize the Makefile for your own
+# site (you can make these changes in either Makefile.in or
+# Makefile, but changes to Makefile will get lost if you re-run
+# the configuration script).
+#----------------------------------------------------------------
+
+# Default top-level directories in which to install architecture-
+# specific files (exec_prefix) and machine-independent files such
+# as scripts (prefix).  The values specified here may be overridden
+# at configure-time with the --exec-prefix and --prefix options
+# to the "configure" script.
+
+prefix =		@prefix@
+exec_prefix =		@exec_prefix@
+
+# The following definition can be set to non-null for special systems
+# like AFS with replication.  It allows the pathnames used for installation
+# to be different than those used for actually reference files at
+# run-time.  INSTALL_ROOT is prepended to $prefix and $exec_prefix
+# when installing files.
+INSTALL_ROOT =
+
+# extra includes for compiling
+INCLUDES = -I. -I$(prefix)/include
+
+# extra libs
+EXTRA_LIBS	= @EXTRA_LIBS@
+
+# the full set of libraries for linking
+LIBS	= -L.. -lfuntools $(EXTRA_LIBS) -lm
+
+# To change the compiler switches, for example to change from -O
+# to -g, change the following line:
+CFLAGS = 		@CFLAGS@
+
+# To add ld switches, change the following line:
+LDFLAGS =		@LDFLAGS@
+
+# Some versions of make, like SGI's, use the following variable to
+# determine which shell to use for executing commands:
+SHELL =			/bin/sh
+
+# extra modules added by configure.in to fix OS bugs
+EXTRA_OBJS = 		@EXTRA_OBJS@
+
+# There are just too many different versions of "install" around;
+# better to use the install-sh script that comes with the distribution,
+# which is slower but guaranteed to work.
+
+INSTALL = 		@srcdir@/install-sh -c
+INSTALL_PROGRAM =	${INSTALL}
+INSTALL_DATA =		${INSTALL} -m 644
+
+#----------------------------------------------------------------
+# The information below is modified by the configure script when
+# Makefile is generated from Makefile.in.  You shouldn't normally
+# modify any of this stuff by hand.
+#----------------------------------------------------------------
+
+AC_FLAGS =		@DEFS@
+RANLIB =		@RANLIB@
+
+# web site for installation
+WEBDIR =	/proj/rd/www/funtools
+
+#----------------------------------------------------------------
+# The information below should be usable as is.  The configure
+# script won't modify it and you shouldn't need to modify it
+# either.
+#----------------------------------------------------------------
+
+CC =		@CC@
+
+CC_SWITCHES =	${CFLAGS} ${INCLUDES} ${AC_FLAGS}
+
+DEPEND_SWITCHES = ${CFLAGS} ${INCLUDES} ${AC_FLAGS}
+
+PROGS =		tev tim
+
+all:		$(PROGS)
+
+tev:		tev.o
+		$(CC) $(LDFLAGS) tev.o -o tev $(LIBS)
+
+tim:		tim.o
+		$(CC) $(LDFLAGS) tim.o -o tim $(LIBS)
+
+Makefile:	Makefile.in
+		$(SHELL) config.status
+
+RM = 		rm -f
+
+clean:
+		$(RM) *.a *.so *.o *.exe core errs *pure* .nfs* \
+			foo* *~ *.log \#* TAGS *.E a.out errors \
+			$(PROGS) $(TESTPROGS) \
+			gmon.out *.pg *.bak \
+			config.info config.log \
+			*fun*.out doc/*~ 
+		$(RM) -r autom4te.cache
+
+distclean:	clean
+		$(RM) Makefile config.status config.cache config.log
+
+install:
+		@echo "Nothing to install in faq"
+
+www:
+		-@( if [ -d ${WEBDIR} ]; then \
+			  echo "installing in Web site: ${WEBDIR}"; \
+			  mkdir -p ${WEBDIR}/faq; \
+			  cp -p *.html ${WEBDIR}/faq/.; \
+		    else \
+			  echo "Web site not available for install"; \
+		    fi;)
+
+pclean:
+		$(RM) $(PROGS)
+
+depend:
+		makedepend -- $(DEPEND_SWITCHES) -- $(SRCS)
+
+evread.o:	evread.c
+		$(CC) -c $(CC_SWITCHES) evread.c
+
+# DO NOT DELETE THIS LINE -- make depend depends on it.
diff --git a/funtools/faq/faq.html b/funtools/faq/faq.html
new file mode 100644
index 0000000..d89d723
--- /dev/null
+++ b/funtools/faq/faq.html
@@ -0,0 +1,49 @@
+<html><head><title>Funtools FAQ</title></head>
+
+<p>
+Welcome to the Funtools FAQ
+<p>
+The primary home page for this FAQ is
+<a href="http://hea-www.harvard.edu/saord/funtools/faq/faq.html">http://hea-www.harvard.edu/saord/funtools/faq/faq.html</a>. 
+
+<ol>
+
+<li>Retrieving and Installing Funtools
+<ol>
+<li><a href="faq1.html#faq1">Where can I get funtools?</a>
+<li><a href="faq1.html#faq2">How do I build funtools?</a>
+<li><a href="faq1.html#faq3">What secondary build options might be useful?</a>
+</ol>
+
+<li>Programming with Funtools
+<ol>
+<li><a href="faq2.html#faq1">What are the compile/link commands for various platforms?</a>
+<li><a href="faq2.html#faq2">What is the simplest possible program?</a>
+<li>Working with Binary Tables (Event Files)
+<ol>
+<li><a href="faq2.html#faq1.1">How do I read and display events?</a>
+<li><a href="faq2.html#faq1.2">How do I change the values of a single column for all events?</a>
+<li><a href="faq2.html#faq1.3">How do I process events based on the region each is in?</a>
+<li><a href="faq2.html#faq1.4">How do I make a FITS event file from a non-FITS source (and add my own params)?</a>
+</ol>
+<li>Working with Images
+<ol>
+<li><a href="faq2.html#faq2.1">How do I process an image in double float format?</a>
+<li><a href="faq2.html#faq2.1">How do I process an image in its native format?</a>
+</ol>
+</ol>
+
+<li>Funtools Analysis Programs
+<ol>
+<li><a href="faq3.html#faq1">What programs are available and what do they do?</a>
+</ol>
+
+<li>Using Filters and Regions
+<ol>
+<li><a href="faq4.html#faq1">Please show how to use column and regions filters</a>
+</ol>
+
+</ol>
+
+
+
diff --git a/funtools/faq/faq1.html b/funtools/faq/faq1.html
new file mode 100644
index 0000000..d4f1fd8
--- /dev/null
+++ b/funtools/faq/faq1.html
@@ -0,0 +1,39 @@
+<html><head><title>Funtools FAQ: Installing</title></head>
+
+<ol>
+
+<li> <a name="faq1"><b>Where can I get funtools?</b><p>
+Funtools is available at:
+<a href="http://hea-www.harvard.edu/saord/funtools">http://hea-www.harvard.edu/saord/funtools</a>.
+
+<li> <a name="faq2"><b>How do I build funtools?</b><p>
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+./configure --prefix="install_root"	# site-specific configuration
+make			                # build the software
+make install		                # install it
+make clean		                # clean up unneeded temp files
+</PRE>
+</CODE></BLOCKQUOTE>
+
+<li><a name=faq3"><b>What secondary build options might be useful?</b></a>
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+# specify root dir to install funtools executables, libraries, man pages, etc.
+# default is to install in /usr/local
+configure --prefix="install_root"
+
+# create funtools as a shared library
+configure --enable-shared=yes
+
+# create funtools as a shared library and use it to link funtools itself
+configure --enable-shared=link
+
+# gcc: enable support for files larger than 2 Gb
+configure CFLAGS="-D_LARGEFILE64_SOURCE -D_FILE_OFFSET_BITS=64"
+</PRE>
+</CODE></BLOCKQUOTE>
+
+</ol>
diff --git a/funtools/faq/faq2.html b/funtools/faq/faq2.html
new file mode 100644
index 0000000..f5b424b
--- /dev/null
+++ b/funtools/faq/faq2.html
@@ -0,0 +1,381 @@
+<html><head><title>Funtools FAQ: Programming</title></head>
+
+<ol>
+<li><a name="faq1"><b>What are the compile/link commands for various platforms?</b></a>
+<P>
+Assuming, for example, that funtools is installed in /soft/saord and that
+gcc is the compiler being used:
+<ol>
+<li> Linux:
+<BLOCKQUOTE><CODE>
+<PRE>
+gcc -g -I/soft/saord/include -c -o foo.o foo.c
+gcc -g foo.o -o foo -L/soft/saord/lib -lfuntools -ldl -lm
+</PRE>
+</CODE></BLOCKQUOTE>
+<li> Apple OS X:
+<BLOCKQUOTE><CODE>
+<PRE>
+gcc -g -no-cpp-precomp -fno-common -I/soft/saord/include -c -o foo.o foo.c
+gcc -g foo.o -o foo -L/soft/saord/lib -lfuntools -lm
+</PRE>
+</CODE></BLOCKQUOTE>
+<li> Sun Solaris:
+<BLOCKQUOTE><CODE>
+<PRE>
+gcc -g -no-cpp-precomp -fno-common -I/soft/saord/include -c -o foo.o foo.c
+gcc -g foo.o -o foo -L/soft/saord/lib -lfuntools -lsocket -lnsl -ldl -lm
+</PRE>
+</CODE></BLOCKQUOTE>
+
+</ol>
+
+<li><a name="faq2"><b>What is the simplest possible program?</b></a>
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+#include &lt;stdlib.h&gt;
+#include &lt;funtools.h&gt;
+
+int main(int argc, char **argv)
+{
+  Fun fun;
+
+  /* sanity check */
+  if( argc &lt; 2 ) return 1;
+  /* open file for reading */
+  if( !(fun=FunOpen(argv[1], "r", NULL)) ){
+    fprintf(stderr, "ERROR: can't open funtools file: %s\n", argv[1]);
+    return 1;
+  }
+  /* close file */
+  FunClose(fun);
+  return 0;
+}
+</PRE>
+</CODE></BLOCKQUOTE>
+
+<li><a name="faq1.1"><b>How do I read and display events?</b></a>
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>#
+#include &lt;stdlib.h&gt;
+#include &lt;funtools.h&gt;
+
+typedef struct evstruct{
+  double x, y;
+  int pi, pha;
+} *Ev, EvRec;
+
+int main(int argc, char **argv)
+{
+  int i, got;
+  int maxrow=1024;
+  Ev ev, ebuf=NULL;
+  Fun fun;
+
+  /* sanity check */
+  if( argc &lt; 2 ) return 1;
+  /* open file for reading */
+  if( !(fun=FunOpen(argv[1], "r", NULL)) ){
+    fprintf(stderr, "ERROR: can't open funtools file: %s\n", argv[1]);
+    return 1;
+  }
+  /* select columns to read (and data types to convert to) */
+  got = FunColumnSelect(fun, sizeof(EvRec), NULL,
+			"x",       "D", "r", FUN_OFFSET(Ev, x),
+			"y",       "D", "r", FUN_OFFSET(Ev, y),
+			"pha",     "J", "r", FUN_OFFSET(Ev, pha),
+			"pi",      "J", "r", FUN_OFFSET(Ev, pi),
+			NULL);
+  /* read and process events */
+  while( (ebuf=(void *)FunTableRowGet(fun, NULL, maxrow, NULL, &got)) && got ){
+    for(i=0; i&lt;got; i++){
+      ev = (Ev)ebuf+i;
+      fprintf(stdout, "%.1f %.1f %d %d\n", ev->x, ev->y, ev->pha, ev->pi);
+    }
+    if( ebuf) free(ebuf);
+  }
+  /* close file */
+  FunClose(fun);
+  return 0;
+}
+</PRE>
+</CODE></BLOCKQUOTE>
+
+<li><a name="faq1.2"><b>How do I change the value of a single column in all events?</b></a>
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+#include &lt;stdlib.h&gt;
+#include &lt;funtools.h&gt;
+
+typedef struct evstruct{
+  int pi;
+} *Ev, EvRec;
+
+int main(int argc, char **argv)
+{
+  int i, got;
+  int maxrow=1024;
+  Ev ev, ebuf=NULL;
+  Fun fun, ofun;
+
+  /* sanity check */
+  if( argc &lt; 3 ) return 1;
+  /* open file for reading */
+  if( !(fun=FunOpen(argv[1], "r", NULL)) ){
+    fprintf(stderr, "ERROR: can't open input funtools file: %s\n", argv[1]);
+    return 1;
+  }
+  /* open output file and inherit header params, columns, etc. from input */
+  if( !(ofun=FunOpen(argv[2], "w", fun)) ){
+    fprintf(stderr, "ERROR: can't open output funtools file: %s\n", argv[2]);
+    return 1;
+  }
+  /* select columns to read (and data types to convert to) */
+  /* use "merge=update" to change value while keeping original data type */
+  /* use "merge=replace" to change boh the value and data type */
+  got = FunColumnSelect(fun, sizeof(EvRec), "merge=update",
+			"pi",     "J", "rw", FUN_OFFSET(Ev, pi),
+			NULL);
+  /* read and process events */
+  while( (ebuf=(void *)FunTableRowGet(fun, NULL, maxrow, NULL, &got)) && got ){
+    for(i=0; i&lt;got; i++){
+      ev = (Ev)ebuf+i;
+      ev->pi = ev->pi + 1;
+    }
+    /* write rows to output file */
+    if( FunTableRowPut(ofun, ebuf, got, 0, NULL) != got ){
+      fprintf(stderr, "ERROR: writing to funtools file: %s\n", argv[2]);
+      return 1;
+    }
+    if( ebuf) free(ebuf);
+  }
+  /* close files */
+  FunClose(ofun);
+  FunClose(fun);
+  return 0;
+}
+</PRE>
+</CODE></BLOCKQUOTE>
+
+<li><a name="faq1.3"><b>How do I process events based on the region each is in?</b></a>
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+#include &lt;stdlib.h&gt;
+#include &lt;funtools.h&gt;
+
+typedef struct evstruct{
+  int x, y;
+  int pi, pha;
+  int region;
+} *Ev, EvRec;
+
+int main(int argc, char **argv)
+{
+  int i, got;
+  int maxrow=1024;
+  Ev ev, ebuf=NULL;
+  Fun fun;
+
+  /* sanity check */
+  if( argc &lt; 2 ) return 1;
+  /* open file for reading */
+  if( !(fun=FunOpen(argv[1], "r", NULL)) ){
+    fprintf(stderr, "ERROR: can't open funtools file: %s\n", argv[1]);
+    return 1;
+  }
+  /* select columns to read (and data types to convert to) */
+  /* specifying $REGION will retrieve the one-indexed region number */
+  /* events passing the filter but not in a region will have value -1 */
+  got = FunColumnSelect(fun, sizeof(EvRec), NULL,
+			"x",       "J", "r", FUN_OFFSET(Ev, x),
+			"y",       "J", "r", FUN_OFFSET(Ev, y),
+			"pha",     "J", "r", FUN_OFFSET(Ev, pha),
+			"pi",      "J", "r", FUN_OFFSET(Ev, pi),
+			"$REGION", "J", "r", FUN_OFFSET(Ev, region),
+			NULL);
+  /* read and process events */
+  while( (ebuf=(void *)FunTableRowGet(fun, NULL, maxrow, NULL, &got)) && got ){
+    for(i=0; i&lt;got; i++){
+      ev = (Ev)ebuf+i;
+      fprintf(stdout, "%4d %4d %3d %3d %4d\n", 
+	      ev->x, ev->y, ev->pha, ev->pi, ev->region);
+    }
+    if( ebuf) free(ebuf);
+  }
+  /* close file */
+  FunClose(fun);
+  return 0;
+}
+</PRE>
+</CODE></BLOCKQUOTE>
+
+<li><a name="faq1.4"><b>How do I make a FITS event file from a non-FITS source (and add my own params)?</b></a>
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+#include &lt;stdlib.h&gt;
+#include &lt;funtools.h&gt;
+
+typedef struct evstruct{
+  int x, y;
+  int pha;
+  float pi;
+} *Ev, EvRec;
+
+int main(int argc, char **argv)
+{
+  int i, nev;
+  int pmod=16, put=1;
+  double pinc=0.1234;
+  char xbuf[32], ybuf[32];
+  Ev ev;
+  Fun ofun;
+
+  /* sanity check */
+  if( argc &lt; 3 ) return 1;
+  /* open new file for writing */
+  if( !(ofun=FunOpen(argv[1], "w", NULL)) ){
+    fprintf(stderr, "ERROR: can't open funtools file: %s\n", argv[1]);
+    return 1;
+  }
+  if( (nev = atoi(argv[2])) <=0 ) return 1;
+  ev = (Ev)calloc(1, sizeof(EvRec));
+  /* The pair of numeric values specify the data value range, used to bin
+     x, y into an image. They are permitted but not needed for pi and pha */
+  sprintf(xbuf, "J:1:%d", nev);
+  sprintf(ybuf, "J:1:%d", nev);
+  /* select columns to write */
+  FunColumnSelect(ofun, sizeof(EvRec), NULL,
+		  "x",   xbuf,      "w", FUN_OFFSET(Ev, x),
+		  "y",   ybuf,      "w", FUN_OFFSET(Ev, y),
+		  "pha", "J:1:16",  "w", FUN_OFFSET(Ev, pha),
+		  "pi",  "E",       "w", FUN_OFFSET(Ev, pi),
+		  NULL);
+  /* write params to header; generally added before first event is written */
+  FunParamPuti(ofun, "PMOD",  0, pmod,  "modulus for pha generation", 1);
+  FunParamPutd(ofun, "PINC",  0, pinc,  7, "increment for pi generation", 1);
+  /* make up events */
+  for(i=1; i<=nev; i++){
+    ev->x = i; ev->y = nev-i+1; ev->pha = i % pmod; ev->pi = ev->pha + pinc;
+    /* write rows to output file -- this can be done in batches, of course */
+    if( FunTableRowPut(ofun, ev, put, 0, NULL) != put ){
+      fprintf(stderr, "ERROR: writing to funtools file: %s\n", argv[1]);
+      return 1;
+    }
+  }
+  if( ev) free(ev);
+  /* close file */
+  FunClose(ofun);
+  return 0;
+}
+</PRE>
+</CODE></BLOCKQUOTE>
+
+<li><a name="faq2.1"><b>How do I process an image in double float format?</b></a>
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+#include &lt;stdlib.h&gt;
+#include &lt;funtools.h&gt;
+
+int main(int argc, char **argv)
+{
+  int i, j, dim1, dim2;
+  double *buf;
+  Fun fun;
+
+  /* sanity check */
+  if( argc &lt; 2 ) return 1;
+  /* open file for reading */
+  if( !(fun=FunOpen(argv[1], "r", NULL)) ){
+    fprintf(stderr, "ERROR: can't open funtools file: %s\n", argv[1]);
+    return 1;
+  }
+  /* extract (and bin, if necessary) data into a double prec. image buffer */
+  if( !(buf = FunImageGet(fun, NULL, "bitpix=-64")) ){
+    fprintf(stderr, "ERROR: can't get image: %s\n", argv[1]);
+    return 1;
+  }
+  /* get image dimensions after FunImageGet, in case an image section
+     was specified on the command line, which changes image dimensions */
+  FunInfoGet(fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0);
+  /* loop through image */
+  for(i=0; i&lt;dim2; i++){
+    for(j=0; j&lt;dim1; j++){
+      fprintf(stdout, "%.1f ", buf[i*dim1+j]);
+    }
+    fprintf(stdout, "\n");
+  }
+  /* close file */
+  FunClose(fun);
+  return 0;
+}
+</PRE>
+</CODE></BLOCKQUOTE>
+
+<li><a name="faq2.1"><b>How do I process an image in its native format?</b></a>
+<BLOCKQUOTE><CODE>
+<PRE>
+#include &lt;funtools.h&gt;
+
+int main(int argc, char **argv)
+{
+  int i, j, bitpix, dim1, dim2;
+  double *buf;
+  unsigned char *cbuf;
+  short *sbuf;
+  int *ibuf;
+  float *fbuf;
+  double *dbuf;
+  Fun fun;
+
+  /* sanity check */
+  if( argc &lt; 2 ) return 1;
+  /* open file for reading */
+  if( !(fun=FunOpen(argv[1], "r", NULL)) ){
+    fprintf(stderr, "ERROR: can't open funtools file: %s\n", argv[1]);
+    return 1;
+  }
+  /* extract (and bin, if necessary) data into a buffer whose
+     data type is not specified and therefore is that of the file */
+  if( !(buf = FunImageGet(fun, NULL, NULL)) ){
+    fprintf(stderr, "ERROR: can't get image: %s\n", argv[1]);
+    return 1;
+  }
+  /* get image dimensions after FunImageGet, in case an image section
+     was specified on the command line, which changes image dimensions */
+  FunInfoGet(fun, FUN_SECT_BITPIX, &bitpix, 
+	     FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0);
+  /* set appropriate data type buffer to point to image buffer */
+  switch(bitpix){
+    case 8:   cbuf = (unsigned char *)buf; break;
+    case 16:  sbuf = (short *)buf;         break;
+    case 32:  ibuf = (int *)buf;           break;
+    case -32: fbuf = (float *)buf;         break;
+    case -64: dbuf = (double *)buf;        break;
+  }
+  /* loop through image */
+  for(i=0; i&lt;dim2; i++){
+    for(j=0; j&lt;dim1; j++){
+      switch(bitpix){
+        case 8:   fprintf(stdout, "%4d ",  cbuf[i*dim1+j]);  break;
+        case 16:  fprintf(stdout, "%6d ",  sbuf[i*dim1+j]);  break;
+        case 32:  fprintf(stdout, "%9d ",  ibuf[i*dim1+j]);  break;
+        case -32: fprintf(stdout, "%.2f ", fbuf[i*dim1+j]);  break;
+        case -64: fprintf(stdout, "%.6f ", dbuf[i*dim1+j]);  break;
+      }
+    }
+    fprintf(stdout, "\n");
+  }
+  /* close file */
+  FunClose(fun);
+  return 0;
+}
+</PRE>
+</CODE></BLOCKQUOTE>
+
+</ol>
diff --git a/funtools/faq/faq3.html b/funtools/faq/faq3.html
new file mode 100644
index 0000000..e55a4d0
--- /dev/null
+++ b/funtools/faq/faq3.html
@@ -0,0 +1,23 @@
+<html><head><title>Funtools FAQ: Programs</title></head>
+
+<ol>
+<li><a name=faq1"><b>What programs are available and what do they do?</b></a>
+<P>
+<ol>
+<LI>funcalc: funtools calculator (for binary tables)
+<LI>funcen: find centroid (for binary tables)
+<LI>funcnts: count photons in specified regions with background subtraction
+<LI>funcone: cone search on RA, Dec columns
+<LI>fundisp: display data in a funtools data file
+<LI>funhead: display a header in a funtools file
+<LI>funhist: create a 1D histogram of a column
+<LI>funimage: create a FITS image from a funtools data file
+<LI>funindex: create a index on a column in a binary table
+<LI>funjoin: join two or more FITS binary tables on specified columns
+<LI>funmerge: merge one or more funtools table files
+<LI>funsky: convert between image and sky coodinates, using WCS info from a FITS header
+<LI>funtable: copy selected rows from a funtools file to a FITS binary table
+<LI>funtbl: extract a table (obsolete)
+</ol>
+
+</ol>
diff --git a/funtools/faq/faq4.html b/funtools/faq/faq4.html
new file mode 100644
index 0000000..7e384a7
--- /dev/null
+++ b/funtools/faq/faq4.html
@@ -0,0 +1,211 @@
+<html><head><title>Funtools FAQ: Filtering</title></head>
+<p>
+NB: column filters work on tables only. Regions work on tables and images.
+
+<p>
+<ol>
+<li><a name="faq1"><b>Please show how to use column and regions filters</b></a>
+
+<p>
+<ol>
+<li> Filter events through a circular region using physical pixels
+<BLOCKQUOTE><CODE>
+<PRE>
+fundisp foo.fits'[circle(512,512,.5)]'
+ 
+   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
+</PRE>
+</CODE></BLOCKQUOTE>
+
+<li> Filter events through a circular region, for a single value of pha
+<BLOCKQUOTE><CODE>
+<PRE>
+fundisp foo.fits'[circle 512 512 .5 && pha==5]'
+ 
+   X    Y PHA  PI                  TIME   DX   DY
+---- ---- --- --- --------------------- ---- ----
+ 512  512   5   6     79493631.03866175  578  575
+ 512  512   5   5     79493290.86521725  578  575
+</PRE>
+</CODE></BLOCKQUOTE>
+
+<li> Filter events through a circular region, including a range of pha values
+<BLOCKQUOTE><CODE>
+<PRE>
+fundisp foo.fits'[circle(512,512,.5)&&pha=5:6]'
+ 
+   X    Y PHA  PI                  TIME   DX   DY
+---- ---- --- --- --------------------- ---- ----
+ 512  512   6   7     79493997.45854475  578  574
+ 512  512   5   6     79493631.03866175  578  575
+ 512  512   5   5     79493290.86521725  578  575
+</PRE>
+</CODE></BLOCKQUOTE>
+
+<li> Filter events through a circular region, excluding a range of pha values
+<BLOCKQUOTE><CODE>
+<PRE>
+fundisp foo.fits'[circle(512,512,.5)&&\!pha=5:6]'
+ 
+   X    Y PHA  PI                  TIME   DX   DY
+---- ---- --- --- --------------------- ---- ----
+ 512  512   8   9     79494575.58943175  579  573
+ 512  512   8   9     79493432.00990875  579  573
+</PRE>
+</CODE></BLOCKQUOTE>
+
+<li> Filter events through two circular regions
+<BLOCKQUOTE><CODE>
+<PRE>
+fundisp foo.fits'[circle(512,512,.5); circle 500 500 .1]'
+ 
+   X    Y PHA  PI                  TIME   DX   DY
+---- ---- --- --- --------------------- ---- ----
+ 500  500   5   5     79493733.05197725  600  577
+ 500  500   9   9     79488217.13936825  600  576
+ 500  500   2   2     79487590.99904275  599  581
+ 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
+</PRE>
+</CODE></BLOCKQUOTE>
+
+<li> Filter events through a circular region, selecting a single time value
+<BLOCKQUOTE><CODE>
+<PRE>
+fundisp foo.fits'[circle(512,512,.5)&&time==79493631.03866175]'
+ 
+   X    Y PHA  PI                  TIME   DX   DY
+---- ---- --- --- --------------------- ---- ----
+ 512  512   5   6     79493631.03866175  578  575
+</PRE>
+</CODE></BLOCKQUOTE>
+
+<li> Filter events through a circular region, selecting a single time value
+(but using feq to avoid possible precision problems)
+<BLOCKQUOTE><CODE>
+<PRE>
+fundisp foo.fits'[circle(512,512,.5)&&feq(time,79493631.03866175)]'
+ 
+   X    Y PHA  PI                  TIME   DX   DY
+---- ---- --- --- --------------------- ---- ----
+ 512  512   5   6     79493631.03866175  578  575
+</PRE>
+</CODE></BLOCKQUOTE>
+
+<li> Filter events through a circular region, while excluding an inner circle
+<BLOCKQUOTE><CODE>
+<PRE>
+fundisp foo.fits'[circle(512,512,1);-cir 512 512 .5]'
+ 
+   X    Y PHA  PI                  TIME   DX   DY
+---- ---- --- --- --------------------- ---- ----
+ 512  511   9   9     79492909.11908525  580  572
+ 512  511   6   7     79492607.35239075  580  573
+ 512  511   6   7     79493574.08603576  580  573
+ 512  511   7   8     79488537.75487424  579  572
+ 511  512   5   5     79488781.64644176  579  576
+ 511  512   5   6     79492586.05470325  579  576
+ 511  512  10  10     79494397.55842775  580  574
+ 511  512   1   2     79493697.87522624  577  582
+ 511  512   6   7     79493997.75123225  579  575
+ 511  512  10  11     79487417.67703976  579  574
+ 513  512   6   6     79493306.47509325  578  573
+ 513  512   8   8     79487909.39373726  578  572
+ 512  513   4   4     79487403.52010125  576  577
+ 512  513   8   9     79492536.31151475  577  574
+ 512  513  10  10     79492589.71195325  578  574
+ 512  513   5   5     79488335.19512025  576  575
+ 512  513   8   8     79493661.25728776  578  574
+ 512  513   8   9     79487914.98186225  577  574
+ 512  513   5   5     79487392.91247626  577  576
+ 512  513   4   4     79492808.24789475  577  576
+ 512  513   7   8     79493236.90765475  577  574
+ 512  513   6   7     79493667.65710025  578  574
+</PRE>
+</CODE></BLOCKQUOTE>
+
+<li> Filter events through a circular region for a range of pha, while excluding an inner circle
+<BLOCKQUOTE><CODE>
+<PRE>
+fundisp foo.fits'[circle(512,512,1)&&pha=6:7;-cir 512 512 .5]'
+ 
+   X    Y PHA  PI                  TIME   DX   DY
+---- ---- --- --- --------------------- ---- ----
+ 512  511   6   7     79492607.35239075  580  573
+ 512  511   6   7     79493574.08603576  580  573
+ 512  511   7   8     79488537.75487424  579  572
+ 511  512   6   7     79493997.75123225  579  575
+ 513  512   6   6     79493306.47509325  578  573
+ 512  513   7   8     79493236.90765475  577  574
+ 512  513   6   7     79493667.65710025  578  574
+</PRE>
+</CODE></BLOCKQUOTE>
+
+<li> Filter events through a circular region for ranges of pha and pi, while excluding an inner circle
+<BLOCKQUOTE><CODE>
+<PRE>
+fundisp foo.fits'[circle(512,512,1)&&pha=5:7 && pi=6:8;-cir 512 512 .5]'
+ 
+   X    Y PHA  PI                  TIME   DX   DY
+---- ---- --- --- --------------------- ---- ----
+ 512  511   6   7     79492607.35239075  580  573
+ 512  511   6   7     79493574.08603576  580  573
+ 512  511   7   8     79488537.75487424  579  572
+ 511  512   5   6     79492586.05470325  579  576
+ 511  512   6   7     79493997.75123225  579  575
+ 513  512   6   6     79493306.47509325  578  573
+ 512  513   7   8     79493236.90765475  577  574
+ 512  513   6   7     79493667.65710025  578  574
+</PRE>
+</CODE></BLOCKQUOTE>
+
+<li> Filter events through a circular region in fk5 coords (degrees)
+<BLOCKQUOTE><CODE>
+<PRE>
+fundisp foo.fits'[fk5;circle(345.25391,58.879774,3.9999997")]'
+ 
+   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
+</PRE>
+</CODE></BLOCKQUOTE>
+
+<li> Filter events through a circular region retrieved from ds9
+<BLOCKQUOTE><CODE>
+<PRE>
+cat foo.reg
+# Region file format: DS9 version 4.0
+# Filename: foo.fits'[EVENTS]'
+global color=green font="helvetica 10 normal" select=1 highlite=1 edit=1 move=1 delete=1 include=1 fixed=0 source
+fk5
+circle(345.25391,58.879774,3.9999997")
+
+fundisp foo.fits'[@foo.reg]'
+ 
+   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
+
+</PRE>
+</CODE></BLOCKQUOTE>
+
+</ol>
+
+</ol>
diff --git a/funtools/faq/tdisp b/funtools/faq/tdisp
new file mode 100755
index 0000000..e2ee633
--- /dev/null
+++ b/funtools/faq/tdisp
@@ -0,0 +1,15 @@
+#!/bin/sh
+
+if [ ! -r foo.fits ]; then
+  ln -s $HOME/data/snr.ev foo.fits
+fi
+
+FUN_FORMAT='x=%4d y=%4d pha=%3d pi=%3d dx=%4d dy=%4d'
+export FUN_FORMAT
+
+echo fundisp foo.fits"'[$1]'" | tee foo.log
+echo " " | tee -a foo.log
+../fundisp foo.fits"[$1]" | tee -a foo.log
+
+
+
diff --git a/funtools/faq/tev.c b/funtools/faq/tev.c
new file mode 100644
index 0000000..9f9cf59
--- /dev/null
+++ b/funtools/faq/tev.c
@@ -0,0 +1,56 @@
+#include <stdlib.h>
+#include <funtools.h>
+
+typedef struct evstruct{
+  int x, y;
+  int pha;
+  float pi;
+  int region;
+} *Ev, EvRec;
+
+int main(int argc, char **argv)
+{
+  int i, nev;
+  int pmod=16, put=1;
+  double pinc=0.1234;
+  char xbuf[32], ybuf[32];
+  Ev ev;
+  Fun ofun;
+
+  /* sanity check */
+  if( argc < 3 ) return 1;
+  /* open new file for writing */
+  if( !(ofun=FunOpen(argv[1], "w", NULL)) ){
+    fprintf(stderr, "ERROR: can't open funtools file: %s\n", argv[1]);
+    return 1;
+  }
+  if( (nev = atoi(argv[2])) <=0 ) return 1;
+  ev = (Ev)calloc(1, sizeof(EvRec));
+  /* The pair of numeric values specify the data value range, used to bin
+     x, y into an image. They are permitted but not needed for pi and pha */
+  sprintf(xbuf, "J:1:%d", nev);
+  sprintf(ybuf, "J:1:%d", nev);
+  /* select columns to write */
+  FunColumnSelect(ofun, sizeof(EvRec), NULL,
+		  "x",   xbuf,      "w", FUN_OFFSET(Ev, x),
+		  "y",   ybuf,      "w", FUN_OFFSET(Ev, y),
+		  "pha", "J:1:16",  "w", FUN_OFFSET(Ev, pha),
+		  "pi",  "E",       "w", FUN_OFFSET(Ev, pi),
+		  NULL);
+  /* write params to header; generally added before first event is written */
+  FunParamPuti(ofun, "PMOD",  0, pmod,  "modulus for pha generation", 1);
+  FunParamPutd(ofun, "PINC",  0, pinc,  7, "increment for pi generation", 1);
+  /* make up events */
+  for(i=1; i<=nev; i++){
+    ev->x = i; ev->y = nev-i+1; ev->pha = i % pmod; ev->pi = ev->pha + pinc;
+    /* write rows to output file -- this can be done in batches, of course */
+    if( FunTableRowPut(ofun, ev, put, 0, NULL) != put ){
+      fprintf(stderr, "ERROR: writing to funtools file: %s\n", argv[1]);
+      return 1;
+    }
+  }
+  if( ev) free(ev);
+  /* close file */
+  FunClose(ofun);
+  return 0;
+}
diff --git a/funtools/faq/tfaq.c b/funtools/faq/tfaq.c
new file mode 100644
index 0000000..8913f44
--- /dev/null
+++ b/funtools/faq/tfaq.c
@@ -0,0 +1,41 @@
+#include <funtools.h>
+
+typedef struct evstruct{
+  int pi;
+} *Ev, EvRec;
+
+int main(int argc, char **argv)
+{
+  int i, got;
+  int maxrow=1024;
+  Ev ev, ebuf=NULL;
+  Fun fun, ofun;
+  /* open file for reading */
+  if( !(fun=FunOpen(argv[1], "r", NULL)) ){
+    fprintf(stderr, "ERROR: can't open input funtools file: %s\n", argv[1]);
+    return 1;
+  }
+  if( !(ofun=FunOpen(argv[2], "w", fun)) ){
+    fprintf(stderr, "ERROR: can't open output funtools file: %s\n", argv[2]);
+    return 1;
+  }
+  /* select columns to read (and data types to convert to) */
+  got = FunColumnSelect(fun, sizeof(EvRec), "merge=update",
+			"pi",     "J", "rw", FUN_OFFSET(Ev, pi),
+			NULL);
+  /* read and process events */
+  while(ebuf=(void *)FunTableRowGet(fun, NULL, maxrow, NULL, &got) ){
+    for(i=0; i<got; i++){
+      ev = (Ev)ebuf+i;
+      ev->pi = ev->pi + 1;
+    }
+    if( FunTableRowPut(ofun, ebuf, got, 0, NULL) != got ){
+      fprintf(stderr, "ERROR: writing to funtools file: %s\n", argv[2]);
+      return 1;
+    }
+    if( ebuf) free(ebuf);
+  }
+  /* close files */
+  FunClose(ofun);
+  FunClose(fun);
+}
diff --git a/funtools/faq/tim.c b/funtools/faq/tim.c
new file mode 100644
index 0000000..5b0aa98
--- /dev/null
+++ b/funtools/faq/tim.c
@@ -0,0 +1,55 @@
+#include <funtools.h>
+
+int main(int argc, char **argv)
+{
+  int i, j, bitpix, dim1, dim2;
+  double *buf;
+  unsigned char *cbuf;
+  short *sbuf;
+  int *ibuf;
+  float *fbuf;
+  double *dbuf;
+  Fun fun;
+
+  /* sanity check */
+  if( argc < 2 ) return 1;
+  /* open file for reading */
+  if( !(fun=FunOpen(argv[1], "r", NULL)) ){
+    fprintf(stderr, "ERROR: can't open funtools file: %s\n", argv[1]);
+    return 1;
+  }
+  /* extract (and bin, if necessary) data into a double prec. image buffer */
+  /* data type is not specified and therefore is that of the file */
+  if( !(buf = FunImageGet(fun, NULL, NULL)) ){
+    fprintf(stderr, "ERROR: can't get image: %s\n", argv[1]);
+    return 1;
+  }
+  /* get image dimensions after FunImageGet, in case an image section
+     was specified on the command line, which changes image dimensions */
+  FunInfoGet(fun, FUN_SECT_BITPIX, &bitpix, 
+	     FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0);
+  /* set appropriate data type buffer to point to image buffer */
+  switch(bitpix){
+    case 8:   cbuf = (unsigned char *)buf; break;
+    case 16:  sbuf = (short *)buf;         break;
+    case 32:  ibuf = (int *)buf;           break;
+    case -32: fbuf = (float *)buf;         break;
+    case -64: dbuf = (double *)buf;        break;
+  }
+  /* loop through image */
+  for(i=0; i<dim2; i++){
+    for(j=0; j<dim1; j++){
+      switch(bitpix){
+        case 8:   fprintf(stdout, "%4d ",  cbuf[i*dim1+j]);  break;
+        case 16:  fprintf(stdout, "%6d ",  sbuf[i*dim1+j]);  break;
+        case 32:  fprintf(stdout, "%9d ",  ibuf[i*dim1+j]);  break;
+        case -32: fprintf(stdout, "%.2f ", fbuf[i*dim1+j]);  break;
+        case -64: fprintf(stdout, "%.6f ", dbuf[i*dim1+j]);  break;
+      }
+    }
+    fprintf(stdout, "\n");
+  }
+  /* close file */
+  FunClose(fun);
+  return 0;
+}