funcone(1)

🌸 funcone(1) — cone search of a binary table containing RA, Dec columns 🌸

okay so bestie, welcome to the SAORD Documentation corner of the man pages, section 1, and this one is genuinely iconic 🫶 it's funcone, and it does exactly one thing and does it gorgeously: it finds the rows of a binary table that live inside a cone on the sky. no cap. let's get into it 💅

---

✨ NAME ✨

funcone — cone search of a binary table containing RA, Dec columns

like, that's the whole job description and she ate 🌟

---

🎀 SYNOPSIS 🎀

funcone <switches>  <iname> <oname> <ra[hdr]> <dec[hdr]> <radius[dr'"]>
[columns]

---

💖 OPTIONS 💖

• -d deccol:[hdr] — the Dec column name, plus units (default is DEC:d)
• -j — join columns from the list file 🫶
• -J — same join energy as -j, but output all the rows
• -l listfile — read the centers and radii from a list file
• -L listfile — read centers and radii from a list file, and output the list rows too
• -n — don't use the cone limits as a filter (we'll explain why you'd do this, promise)
• -r racol:[hdr] — the RA column name, plus units (default is RA:h)
• -x — append the RA_CEN, DEC_CEN, RAD_CEN, CONE_KEY cols
• -X — append RA_CEN, DEC_CEN, RAD_CEN, CONE_KEY cols, and output all rows

---

🦋 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. that's it, that's the vibe ✨

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.) quote your strings bestie, the shell will absolutely humble you otherwise 💀

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 -j switch is used. Note that the RA and Dec columns used in the cone calculation must not be de-selected. not me de-selecting the very columns doing the math 😭 don't do that.

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 -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. so many cones, so little time 🍓

When using a list, all valid rows from each iteration are written to a single output file. Use the -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 -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. 🚫 pick one, bestie, they cannot both be main character

The -X and -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. nobody gets left out of the party 💜

The -L switch acts similarly to the -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 (-X, -J, or -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 -n switch to see if this speeds up the processing (especially useful when processing a large list of positions). it's giving "is the shortcut slower than the long way" and honestly sometimes yes 💅

---

🌈 EXAMPLES 🌈

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

ngl bestie, that's spelled funone in the original and we are not touching it — verbatim is verbatim 🫶

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'

---

💫 SEE ALSO 💫

See funtools(7) for a list of Funtools help pages 📚

---

and that's the whole page, bestie — version 1.4.5, April 14, 2011, straight from the SAORD Documentation era, still serving looks in section 1 of the manual. go forth and cone search, you absolute icon 🌟💖🦋