path: root/funtools/man/man1/funcone.1

.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'\-1'\(ga
.    ds D- D\h'\-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "funcone 1"
.TH funcone 1 "April 14, 2011" "version 1.4.5" "SAORD Documentation"
.SH "NAME"
funcone \- cone search of a binary table containing RA, Dec columns
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBfuncone\fR <switches>  <iname> <oname> <ra[hdr]> <dec[hdr]> <radius[dr'"]> [columns]
.SH "OPTIONS"
.IX Header "OPTIONS"
.Vb 9
\&  \-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
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Funcone performs a cone search on the \s-1RA\s0 and Dec columns of a \s-1FITS\s0
binary table. The distance from the center \s-1RA\s0, Dec position to the \s-1RA\s0,
Dec in each row in the table is calculated. Rows whose distance is
less than the specified radius are output.
.PP
The first argument to the program specifies the \s-1FITS\s0 file, raw event
file, or raw array file.  If \*(L"stdin\*(R" is specified, data are read from
the standard input. Use Funtools Bracket
Notation to specify \s-1FITS\s0 extensions, and filters.  The second
argument is the output \s-1FITS\s0 file.  If \*(L"stdout\*(R" is specified, the \s-1FITS\s0
binary table is written to the standard output.  
.PP
The third and fourth required arguments are the \s-1RA\s0 and Dec center
position.  By default, \s-1RA\s0 is specified in hours while Dec is specified
in degrees.  You can change the units of either of these by appending
the character \*(L"d\*(R" (degrees), \*(L"h\*(R" (hours) or \*(L"r\*(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.)
.PP
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 \*(L"d\*(R" (degrees), \*(L"r\*(R" (radians), \*(L"'\*(R" (arc minutes) or
\&'"' (arc seconds).
.PP
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:
.PP
.Vb 1
\&  "column1 column1 ... columnN"
.Ve
.PP
A seventh argument allows you to output selected columns from the list
file when \fB\-j\fR switch is used. Note that the \s-1RA\s0 and Dec columns
used in the cone calculation must not be de\-selected.
.PP
Also by default, the \s-1RA\s0 and Dec column names are named \*(L"\s-1RA\s0\*(R" and \*(L"Dec\*(R",
and are given in units of hours and degrees respectively. You can
change both the name and the units using the \-r [\s-1RA\s0] and/or \-d [Dec]
switches. Once again, one of \*(L"h\*(R", \*(L"d\*(R", or \*(L"r\*(R" is appended to the
column name to specify units but in this case, there must be a colon \*(L":\*(R"
between the name and the unit specification.
.PP
If the \fB\-l [listfile]\fR switch is used, then one or more of the
center \s-1RA\s0, center Dec, and radius can be taken from a list file (which
can be a \s-1FITS\s0 table or an \s-1ASCII\s0 column text file). In this case, the
third (center \s-1RA\s0), 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 \s-1RA\s0, Dec, or radius,
you can append a colon followed by \*(L"h\*(R", \*(L"d\*(R", or \*(L"r\*(R" to specify units
(also ' and " for radius). The cone search algorithm is run once for
each row in the list, taking \s-1RA\s0, Dec, and radius values from the
specified columns or from static numeric values specified on the
command line.
.PP
When using a list, all valid rows from each iteration are written to a
single output file.  Use the \fB\-x\fR 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 \s-1RA\s0, Dec, radius, and row
number to be appended to the output file, in columns called \s-1RA_CEN\s0,
\&\s-1DEC_CEN\s0, \s-1RAD_CEN\s0 and \s-1CONE_KEY\s0, respectively. Alternatively, the
\&\fB\-j\fR (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 \s-1CONE_KEY\s0 row number. These two switches are mutually
exclusive.
.PP
The \fB\-X\fR and \fB\-J\fR 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 \s-1CONE_KEY\s0 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.
.PP
The \fB\-L\fR switch acts similarly to the \fB\-l\fR 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 \s-1CONE_KEY\s0 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.
.PP
If any of \*(L"all row\*(R" switches (\fB\-X\fR, \fB\-J\fR, or \fB\-L\fR) are
specified, then a new column named \s-1JSTAT\s0 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.
.PP
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 \fB\-n\fR
switch to see if this speeds up the processing (especially useful when
processing a large list of positions).
.PP
For example, the default cone search uses columns \*(L"\s-1RA\s0\*(R" and \*(L"Dec\*(R" in hours
and degrees (respectively) and \s-1RA\s0 position in hours, Dec and radius in degrees:
.PP
.Vb 1
\&  funone in.fits out.fits 23.45 34.56 0.01
.Ve
.PP
To specify the \s-1RA\s0 position in degrees:
.PP
.Vb 1
\&  funcone in.fits out.fits 23.45d 34.56 0.01
.Ve
.PP
To get \s-1RA\s0 and Dec from a list but use a static value for radius (and
also write identifying info for each row in the list):
.PP
.Vb 1
\&  funcone \-x \-l list.txt in.fits out.fits MYRA MYDec 0.01
.Ve
.PP
User specified columns in degrees, \s-1RA\s0 position in hours (sexagesimal
notation), Dec position in degrees (sexagesimal notation) and radius
in arc minutes:
.PP
.Vb 1
\&  funcone \-r myRa:d \-d myDec in.fits out.fits 12:30:15.5 30:12 15'
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See funtools(7) for a list of Funtools help pages