1 files changed, 191 insertions, 0 deletions
diff --git a/funtools/doc/pod/funcone.pod b/funtools/doc/pod/funcone.pod
new file mode 100644
index 0000000..a766ca6
--- /dev/null
+++ b/funtools/doc/pod/funcone.pod
@@ -0,0 +1,191 @@
+=pod
+
+=head1 NAME
+
+
+
+B<funcone - cone search of a binary table containing RA, Dec columns>
+
+
+
+=head1 SYNOPSIS
+
+
+
+
+
+funcone <switches>  <iname> <oname> <ra[hdr]> <dec[hdr]> <radius[dr'"]> [columns]
+
+
+
+
+
+=head1 OPTIONS
+
+
+
+
+
+  -d deccol:[hdr]  # Dec column name, units (def: DEC:d)
+  -j               # join columns from list file
+  -J               # join columns from list file, output all rows
+  -l listfile      # read centers and radii from a list
+  -L listfile      # read centers and radii from a list, output list rows
+  -n               # don't use cone limits as a filter
+  -r  racol:[hdr]  # RA column name, units (def: RA:h)
+  -x               # append RA_CEN, DEC_CEN, RAD_CEN, CONE_KEY cols
+  -X               # append RA_CEN, DEC_CEN, RAD_CEN, CONE_KEY cols, output all rows
+
+
+
+
+=head1 DESCRIPTION
+
+
+
+
+Funcone performs a cone search on the RA and Dec columns of a FITS
+binary table. The distance from the center RA, Dec position to the RA,
+Dec in each row in the table is calculated. Rows whose distance is
+less than the specified radius are output.
+
+
+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.  
+
+ 
+The third and fourth required arguments are the RA and Dec center
+position.  By default, RA is specified in hours while Dec is specified
+in degrees.  You can change the units of either of these by appending
+the character "d" (degrees), "h" (hours) or "r" (radians). Sexagesimal
+notation is supported, with colons or spaces separating hms and dms.
+(When using spaces, please ensure that the entire string is quoted.)
+
+
+The fifth required argument is the radius of the cone search. By default,
+the radius value is given in degrees. The units can be changed by appending
+the character "d" (degrees), "r" (radians), "'" (arc minutes) or
+'"' (arc seconds).
+
+
+By default, all
+columns of the input file are copied to the output file.  Selected
+columns can be output using an optional sixth argument in the form:
+
+  "column1 column1 ... columnN"
+
+A seventh argument allows you to output selected columns from the list
+file when B<-j> switch is used. Note that the RA and Dec columns
+used in the cone calculation must not be de-selected.
+
+
+Also by default, the RA and Dec column names are named "RA" and "Dec",
+and are given in units of hours and degrees respectively. You can
+change both the name and the units using the -r [RA] and/or -d [Dec]
+switches. Once again, one of "h", "d", or "r" is appended to the
+column name to specify units but in this case, there must be a colon ":"
+between the name and the unit specification.
+
+
+If the B<-l [listfile]> switch is used, then one or more of the
+center RA, center Dec, and radius can be taken from a list file (which
+can be a FITS table or an ASCII column text file). In this case, the
+third (center RA), fourth (center Dec), and fifth (radius) command
+line arguments can either be a column name in the list file (if that
+parameter varies) or else a numeric value (if that parameter is
+static). When a column name is specified for the RA, Dec, or radius,
+you can append a colon followed by "h", "d", or "r" to specify units
+(also ' and " for radius). The cone search algorithm is run once for
+each row in the list, taking RA, Dec, and radius values from the
+specified columns or from static numeric values specified on the
+command line.
+
+
+When using a list, all valid rows from each iteration are written to a
+single output file.  Use the B<-x> switch to help delineate which
+line of the list file was used to produce the given output row(s).
+This switch causes the values for the center RA, Dec, radius, and row
+number to be appended to the output file, in columns called RA_CEN,
+DEC_CEN, RAD_CEN and CONE_KEY, respectively. Alternatively, the
+B<-j> (join) switch will append all columns from the list row to
+the output row (essentially a join of the list row and input row),
+along with the CONE_KEY row number. These two switches are mutually
+exclusive.
+
+
+The B<-X> and B<-J> switches write out the same data as their
+lower case counterparts for each row satisfying a cone search. In
+addition, these switches also write out rows from the event file that
+do not satisfy any cone search.  In such cases, that CONE_KEY column
+will be given a value of -1 and the center and list position information
+will be set to zero for the given row. Thus, all rows of the input
+event file are guaranteed to be output, with rows satisfying at least
+one cone search having additional search information.
+
+
+The B<-L> switch acts similarly to the B<-l> switch in that it
+takes centers from a list file. However, it also implicitly sets the
+-j switch, so that output rows are the join of the input event row and
+the center position row.  In addition, this switch also writes out all
+center position rows for which no event satisfies the cone search
+criteria of that row.  The CONE_KEY column will be given a value of -2
+for center rows that were not close to any data row and the event
+columns will be zeroed out for such rows. In this way, all centers
+rows are guaranteed to be output at least once.
+
+
+If any of "all row" switches (B<-X>, B<-J>, or B<-L>) are
+specified, then a new column named JSTAT is added to the output table.
+The positive values in this column indicate the center position row number
+(starting from 1) in the list file that this data row successful matched
+in a cone search. A value of -1 means that the data row did not match
+any center position. A value of -2 means that the center position was
+not matched by any data row.
+
+
+Given a center position and radius, the cone search algorithm
+calculates limit parameters for a box enclosing the specified cone,
+and only tests rows whose positions values lie within those limits.
+For small files, the overhead associated with this cone limit
+filtering can cause the program to run more slowly than if all events
+were tested. You can turn off cone limit filtering using the B<-n>
+switch to see if this speeds up the processing (especially useful when
+processing a large list of positions).
+
+
+For example, the default cone search uses columns "RA" and "Dec" in hours
+and degrees (respectively) and RA position in hours, Dec and radius in degrees:
+
+  funone in.fits out.fits 23.45 34.56 0.01
+
+To specify the RA position in degrees:
+
+  funcone in.fits out.fits 23.45d 34.56 0.01
+
+To get RA and Dec from a list but use a static value for radius (and
+also write identifying info for each row in the list):
+
+  funcone -x -l list.txt in.fits out.fits MYRA MYDec 0.01
+
+User specified columns in degrees, RA position in hours (sexagesimal
+notation), Dec position in degrees (sexagesimal notation) and radius
+in arc minutes:
+
+  funcone -r myRa:d -d myDec in.fits out.fits 12:30:15.5 30:12 15'
+
+
+
+
+
+=head1 SEE ALSO
+
+
+
+See funtools(n) for a list of Funtools help pages
+
+
+=cut