1 files changed, 239 insertions, 0 deletions
diff --git a/funtools/doc/pod/funcolumnactivate.pod b/funtools/doc/pod/funcolumnactivate.pod
new file mode 100644
index 0000000..d5f6e3a
--- /dev/null
+++ b/funtools/doc/pod/funcolumnactivate.pod
@@ -0,0 +1,239 @@
+=pod
+
+=head1 NAME
+
+
+
+B<FunColumnActivate - activate Funtools columns>
+
+
+
+=head1 SYNOPSIS
+
+
+
+
+
+  #include <funtools.h>
+
+  void FunColumnActivate(Fun fun, char *s, char *plist)
+
+
+
+
+
+=head1 DESCRIPTION
+
+
+
+
+The B<FunColumnActivate()> routine determines which columns (set up
+by FunColumnSelect())
+ultimately will be read and/or written.  By default, all columns that
+are selected using 
+FunColumnSelect()
+are activated.  The 
+FunColumnActivate()
+routine can be used to turn off/off activation of specific columns.
+
+
+The first argument is the Fun handle associated with this set of
+columns.  The second argument is a space-delimited list of columns to
+activate or de-activate. Columns preceded by "+" are activated and
+columns preceded by a "-" are de-activated. If a column is named
+without "+" or "-", it is activated. The reserved strings "$region"
+and '$n' are used to activate a special columns containing the filter
+region value and row value, respectively, associated with
+this row. For example, if a filter containing two circular regions is
+specified as part of the Funtools file name, this column will contain
+a value of 1 or 2, depending on which region that row was in. The
+reserved strings "$x" and "$y" are used to activate the current
+binning columns. Thus, if the columns DX and DY are specified as
+binning columns:
+
+  [sh $] fundisp foo.fits[bincols=(DX,DY)]
+
+then "$x" and "$y" will refer to these columns in a call to
+FunColumnActivate().
+
+
+In addition, if the activation string contains only columns to be
+activated, then the routine will de-activate all other columns.
+Similarly, if the activation string contains only
+columns to de-activate, then the routine will activate all other columns
+before activating the list.  This makes it simple to change the
+activation state of all columns without having to know all of the
+column names. For example:
+
+
+=over 4
+
+
+
+
+=item *
+
+B<"pi pha time">     # only these three columns will be active
+
+
+=item *
+
+B<"-pi -pha -time">  # all but these columns will be active
+
+
+=item *
+
+B<"pi -pha">         # only pi is active, pha is not, others are not
+
+
+=item *
+
+B<"+pi -pha">        # same as above
+
+
+=item *
+
+B<"pi -pha -time">   # only pi is active, all others are not
+
+
+=item *
+
+B<"pi pha">          # pha and pi are active, all others are not
+
+
+=item *
+
+B<"pi pha -x -y">    # pha and pi are active, all others are not
+
+
+=back
+
+
+
+
+You can use the column activation list to reorder columns, since
+columns are output in the order specified. For example:
+
+  # default output order
+  fundisp 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
+
+  # re-order the output by specifying explicit order
+  fundisp snr.ev'[cir 512 512 .1]' "time x y dy dx pi pha"
+                   TIME        X        Y       DY       DX       PI      PHA
+  --------------------- -------- -------- -------- -------- -------- --------
+      79493997.45854475      512      512      574      578        7        6
+      79494575.58943175      512      512      573      579        9        8
+      79493631.03866175      512      512      575      578        6        5
+      79493290.86521725      512      512      575      578        5        5
+      79493432.00990875      512      512      573      579        9        8
+
+
+
+A "+" sign by itself means to activate all columns, so that you can reorder
+just a few columns without specifying all of them:
+
+  # reorder 3 columns and then output the rest
+  fundisp snr.ev'[cir 512 512 .1]' "time pi pha +"
+                   TIME       PI      PHA        Y        X       DX       DY
+  --------------------- -------- -------- -------- -------- -------- --------
+      79493997.45854475        7        6      512      512      578      574
+      79494575.58943175        9        8      512      512      579      573
+      79493631.03866175        6        5      512      512      578      575
+      79493290.86521725        5        5      512      512      578      575
+      79493432.00990875        9        8      512      512      579      573
+
+The column activation/deactivation is performed in the order of the
+specified column arguments. This means you can mix "+", "-" (which
+de-activates all columns) and specific column names to reorder and
+select columns in one command. For example, consider the following:
+
+  # reorder and de-activate
+  fundisp snr.ev'[cir 512 512 .1]' "time pi pha + -x -y"
+                   TIME       PI      PHA       DX       DY
+  --------------------- -------- -------- -------- --------
+      79493997.45854475        7        6      578      574
+      79494575.58943175        9        8      579      573
+      79493631.03866175        6        5      578      575
+      79493290.86521725        5        5      578      575
+      79493432.00990875        9        8      579      573
+
+We first activate "time", "pi", and "pha" so that they are output first.
+We then activate all of the other columns, and then de-activate "x" and "y".
+Note that this is different from:
+
+  # probably not what you want ...
+  fundisp snr.ev'[cir 512 512 .1]' "time pi pha -x -y +"
+                   TIME       PI      PHA        Y        X       DX       DY
+  --------------------- -------- -------- -------- -------- -------- --------
+      79493997.45854475        7        6      512      512      578      574
+      79494575.58943175        9        8      512      512      579      573
+      79493631.03866175        6        5      512      512      578      575
+      79493290.86521725        5        5      512      512      578      575
+      79493432.00990875        9        8      512      512      579      573
+
+Here, "x" and "y" are de-activated, but then all columns including "x" and
+"y" are again re-activated.
+
+
+Typically, 
+FunColumnActivate() uses a
+list of columns that are passed into the program from the command line.  For
+example, the code for funtable contains the following:
+
+  char *cols=NULL;
+
+  /* open the input FITS file */
+  if( !(fun = FunOpen(argv[1], "rc", NULL)) )
+    gerror(stderr, "could not FunOpen input file: %s\n", argv[1]);
+
+  /* set active flag for specified columns */
+  if( argc >= 4 ) cols = argv[3];
+  FunColumnActivate(fun, cols, NULL);
+
+
+The FunOpen() call sets the
+default columns to be all columns in the input file. The 
+FunColumnActivate() call
+then allows the user to control which columns ultimately will be
+activated (i.e., in this case, written to the new file).  For example:
+
+  funtable test.ev foo.ev "pi pha time"
+
+will process only the three columns mentioned, while:
+
+  funtable test.ev foo.ev "-time"
+
+will process all columns except "time".
+
+
+If FunColumnActivate()
+is called with a null string, then the environment variable
+B<FUN_COLUMNS> will be used to provide a global value, if present.
+This is the reason why we call the routine even if no columns
+are specified on the command line (see example above), instead
+of calling it this way:
+
+  /* set active flag for specified columns */
+  if( argc >= 4 ){
+    FunColumnActivate(fun, argv[3], NULL);
+  }
+
+
+
+
+
+=head1 SEE ALSO
+
+
+
+See funtools(n) for a list of Funtools help pages
+
+
+=cut