1funcone(1) SAORD Documentation funcone(1)
2
6 funcone - cone search of a binary table containing RA, Dec columns
7
9 funcone <switches> <iname> <oname> <ra[hdr]> <dec[hdr]> <radius[dr'"]>
10 [columns]
11
13 -d deccol:[hdr] # Dec column name, units (def: DEC:d)
14 -j # join columns from list file
15 -J # join columns from list file, output all rows
16 -l listfile # read centers and radii from a list
17 -L listfile # read centers and radii from a list, output list rows
18 -n # don't use cone limits as a filter
19 -r racol:[hdr] # RA column name, units (def: RA:h)
20 -x # append RA_CEN, DEC_CEN, RAD_CEN, CONE_KEY cols
21 -X # append RA_CEN, DEC_CEN, RAD_CEN, CONE_KEY cols, output all rows
22
24 Funcone performs a cone search on the RA and Dec columns of a FITS
25 binary table. The distance from the center RA, Dec position to the RA,
26 Dec in each row in the table is calculated. Rows whose distance is less
27 than the specified radius are output.
28 The first argument to the program specifies the FITS file, raw event
30 file, or raw array file. If "stdin" is specified, data are read from
31 the standard input. Use Funtools Bracket Notation to specify FITS
32 extensions, and filters. The second argument is the output FITS file.
33 If "stdout" is specified, the FITS binary table is written to the stan‐
34 dard output.
35 The third and fourth required arguments are the RA and Dec center posi‐
37 tion. By default, RA is specified in hours while Dec is specified in
38 degrees. You can change the units of either of these by appending the
39 character "d" (degrees), "h" (hours) or "r" (radians). Sexagesimal
40 notation is supported, with colons or spaces separating hms and dms.
41 (When using spaces, please ensure that the entire string is quoted.)
42 The fifth required argument is the radius of the cone search. By
44 default, the radius value is given in degrees. The units can be changed
45 by appending the character "d" (degrees), "r" (radians), "'" (arc min‐
46 utes) or '"' (arc seconds).
47 By default, all columns of the input file are copied to the output
49 file. Selected columns can be output using an optional sixth argument
50 in the form:
51 "column1 column1 ... columnN"
53 A seventh argument allows you to output selected columns from the list
55 file when -j switch is used. Note that the RA and Dec columns used in
56 the cone calculation must not be de-selected.
57 Also by default, the RA and Dec column names are named "RA" and "Dec",
59 and are given in units of hours and degrees respectively. You can
60 change both the name and the units using the -r [RA] and/or -d [Dec]
61 switches. Once again, one of "h", "d", or "r" is appended to the column
62 name to specify units but in this case, there must be a colon ":"
63 between the name and the unit specification.
64 If the -l [listfile] switch is used, then one or more of the center RA,
66 center Dec, and radius can be taken from a list file (which can be a
67 FITS table or an ASCII column text file). In this case, the third (cen‐
68 ter RA), fourth (center Dec), and fifth (radius) command line arguments
69 can either be a column name in the list file (if that parameter varies)
70 or else a numeric value (if that parameter is static). When a column
71 name is specified for the RA, Dec, or radius, you can append a colon
72 followed by "h", "d", or "r" to specify units (also ' and " for
73 radius). The cone search algorithm is run once for each row in the
74 list, taking RA, Dec, and radius values from the specified columns or
75 from static numeric values specified on the command line.
76 When using a list, all valid rows from each iteration are written to a
78 single output file. Use the -x switch to help delineate which line of
79 the list file was used to produce the given output row(s). This switch
80 causes the values for the center RA, Dec, radius, and row number to be
81 appended to the output file, in columns called RA_CEN, DEC_CEN, RAD_CEN
82 and CONE_KEY, respectively. Alternatively, the -j (join) switch will
83 append all columns from the list row to the output row (essentially a
84 join of the list row and input row), along with the CONE_KEY row num‐
85 ber. These two switches are mutually exclusive.
86 The -X and -J switches write out the same data as their lower case
88 counterparts for each row satisfying a cone search. In addition, these
89 switches also write out rows from the event file that do not satisfy
90 any cone search. In such cases, that CONE_KEY column will be given a
91 value of -1 and the center and list position information will be set to
92 zero for the given row. Thus, all rows of the input event file are
93 guaranteed to be output, with rows satisfying at least one cone search
94 having additional search information.
95 The -L switch acts similarly to the -l switch in that it takes centers
97 from a list file. However, it also implicitly sets the -j switch, so
98 that output rows are the join of the input event row and the center
99 position row. In addition, this switch also writes out all center
100 position rows for which no event satisfies the cone search criteria of
101 that row. The CONE_KEY column will be given a value of -2 for center
102 rows that were not close to any data row and the event columns will be
103 zeroed out for such rows. In this way, all centers rows are guaranteed
104 to be output at least once.
105 If any of "all row" switches (-X, -J, or -L) are specified, then a new
107 column named JSTAT is added to the output table. The positive values
108 in this column indicate the center position row number (starting from
109 1) in the list file that this data row successful matched in a cone
110 search. A value of -1 means that the data row did not match any center
111 position. A value of -2 means that the center position was not matched
112 by any data row.
113 Given a center position and radius, the cone search algorithm calcu‐
115 lates limit parameters for a box enclosing the specified cone, and only
116 tests rows whose positions values lie within those limits. For small
117 files, the overhead associated with this cone limit filtering can cause
118 the program to run more slowly than if all events were tested. You can
119 turn off cone limit filtering using the -n switch to see if this speeds
120 up the processing (especially useful when processing a large list of
121 positions).
122 For example, the default cone search uses columns "RA" and "Dec" in
124 hours and degrees (respectively) and RA position in hours, Dec and
125 radius in degrees:
126 funone in.fits out.fits 23.45 34.56 0.01
128 To specify the RA position in degrees:
130 funcone in.fits out.fits 23.45d 34.56 0.01
132 To get RA and Dec from a list but use a static value for radius (and
134 also write identifying info for each row in the list):
135 funcone -x -l list.txt in.fits out.fits MYRA MYDec 0.01
137 User specified columns in degrees, RA position in hours (sexagesimal
139 notation), Dec position in degrees (sexagesimal notation) and radius in
140 arc minutes:
141 funcone -r myRa:d -d myDec in.fits out.fits 12:30:15.5 30:12 15'
143
145 See funtools(n) for a list of Funtools help pages
146version 1.4.2 January 2, 2008 funcone(1)