diff options
Diffstat (limited to 'funtools/doc/pod/funcone.pod')
-rw-r--r-- | funtools/doc/pod/funcone.pod | 191 |
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 |