public documents.sextractor_doc

\chapter{Cross-identification within {\sc SExtractor}}
{\sc SExtractor} allows one to perform on-line cross-identification of
each detection with an {\tt ASCII} list. Although the
cross-identification algorithm is not very sophisticated --- it works
in pixel-coordinates only ---, it is particularly convenient for
assessing {\sc SExtractor} performances, on image simulations from
instance. Configuration parameters related to cross-identification are
prefixed with {\tt ASSOC}.
 
\section{The {\tt ASSOC} list}
The {\tt ASSOC} process is initiated by requesting in the parameter
file at least one of the {\tt ASSOC} catalogue parameters: {\tt
VECTOR\_ASSOC} and {\tt NUMBER\_ASSOC}. Then {\sc SExtractor} looks
for an {\tt ASCII} file (let's call it the {\tt ASSOC} list) whose
file name has to be specified by the {\tt ASSOC\_NAME} configuration
keyword. The {\tt ASSOC} list must contain columns of numbers
separated by spaces or tabs. Each line describes a source that will
enter the cross-identification process. Lines with zero characters, or
beginning with ``{\tt \#}'' (for comments) are ignored. This means you
may use any {\tt ASCII} catalogue generated by a previous {\sc
SExtractor} run as an {\tt ASSOC} list.
 
To perform the cross-identification, {\sc SExtractor} needs to know
which are the columns that contain the $x$ and $y$
coordinates\footnote{The $x$ and $y$ coordinates must comply with the
FITS (and {\sc SExtractor}) convention: by definition, the center of
the first pixel in the image array has pixel-coordinates (1.0,1.0).}
in the {\tt ASSOC} list. These shall be specified using the {\tt
ASSOC\_PARAMS} configuration parameter. The syntax is: ``{\tt
ASSOC\_PARAMS}~$c_x$,$c_y[$,$c_Z]$'', where $c_x$ and $c_y$ are the
positions of the columns containing the $x$ and $y$ coordinates (the
first column has position 1). $c_Z$ (optional) specifies an extra
column containing some ``$Z$'' parameter that may be used for
controlling or weighting the {\tt ASSOC} process. $Z$ will typically
be a flux estimate. $c_Z$ is required if {\tt ASSOC\_TYPE} is {\tt
MIN}, {\tt MAX}, {\tt MEAN} or {\tt MAG\_MEAN} (see \S\ref{assoc} below).
 
\section{Controlling the {\tt ASSOC} process}
\label{assoc}
Two configuration parameters control the {\tt ASSOC} process. The
first one, {\tt ASSOC\_RADIUS}, accepts a decimal number which
represents the maximum distance (in pixels) one should have between
the barycenter \gam{{\tt X}, {\tt Y} or {\tt XWIN}, {\tt YWIN}?}
of the current {\sc SExtractor} detection and an {\tt
ASSOC}-list member to consider a match. This number must of course
account for positional uncertainties in both catalogues. In most cases,
a value of a few pixels will do just fine. The second configuration
parameter, {\tt ASSOC\_TYPE}, accepts a keyword as argument and
selects the kind of identification procedure one wants to operate:
\begin{itemize}
\item {\tt FIRST}: this is the simplest way of performing a
cross-identification. It does not require the $c_Z$ column in {\tt
ASSOC\_PARAMS}. The first geometrical match encountered while scanning
the {\tt ASSOC} list is retained as the actual match. This can used
for catalogues with low spatial density.
\item {\tt NEAREST}: this option does not require the $c_Z$ column in
{\tt ASSOC\_PARAMS}. The match is performed with the {\tt ASSOC}-list
member the closest (in position) to the current detection, provided
that it lies within the {\tt ASSOC\_RADIUS}.
\item {\tt SUM}: all parameters issued from {\tt ASSOC}-list members
which geometrically match the current detection are summed. $c_Z$ is
not required.
\item {\tt MAG\_SUM}: all parameters $c_i$ issued from {\tt
ASSOC}-list members which geometrically match the current detection
are combined using the following law: $-2.5\log(\sum_i 10^{-0.4c_i})$.
This option allows one to sum flux contributions from magnitude data.
$c_Z$ is not required.
\item {\tt MIN}: among all geometrical matches, retains the {\tt
ASSOC}-list member which has the smallest $Z$ parameter.
\item {\tt MAX}: among all geometrical matches, retains the {\tt
ASSOC}-list member which has the largest $Z$ parameter.
\item {\tt MEAN}: all parameters issued from {\tt ASSOC}-list members
which geometrically match the current detection are weighted-averaged,
using the $Z$ parameter as the weight.
\item {\tt MAG\_MEAN}: all parameters issued from {\tt ASSOC}-list
members which geometrically match the current detection are
weighted-averaged, using $10^{-0.4Z}$ as the weight. This option is
useful for weighting catalogue sources with magnitudes.
\end{itemize}
 
\section{Output from {\tt ASSOC}}
Now that we have described the cross-identification process, let's see
how informations coming from the matching with the {\tt ASSOC} list
are propagated to the output {\sc SExtractor} catalogue.
 
The output of {\tt ASSOC} data in {\sc SExtractor} catalogue is done
through the {\tt VECTOR\_ASSOC()} catalogue parameter. {\tt
VECTOR\_ASSOC()} is a vector, each element of which refers to a column
from the input {\tt ASSOC} list. {\tt VECTOR\_ASSOC()} contains either
{\tt ASSOC}-list member data from the best match (if {\tt ASSOC\_TYPE}
is {\tt FIRST}, {\tt NEAREST}, {\tt MIN} or {\tt MAX}), or a
combination of {\tt ASSOC}-list member data (if {\tt ASSOC\_TYPE} is
{\tt MEAN}, {\tt MAG\_MEAN}, {\tt SUM} or {\tt MAG\_SUM}). If no match
has been found, it just contains zeros. The {\tt NUMBER\_ASSOC}
contains the number of {\tt ASSOC}-list members that geometrically
match the current {\sc SExtractor} detection, and obviously, if
different from zero, indicates that {\tt VECTOR\_ASSOC()} has a
meaningful content.
 
The {\tt ASSOC\_DATA} configuration parameter is used to tell {\sc
SExtractor} to which column refers each element of {\tt
VECTOR\_ASSOC()}. The syntax of {\tt ASSOC\_DATA} is similar to that
of {\tt ASSOC\_PARAMS}: ``{\tt ASSOC\_DATA} $c_1$,$c_2$,$c_3$,...''
where the $c_i$ are the column positions in the {\tt ASSOC} list. The
special case ``{\tt ASSOC\_DATA} 0'' tells {\sc SExtractor} to
propagate all columns from the {\tt ASSOC} file to the output catalogue.
 
There are situations where it might be desirable to keep in the output
{\sc SExtractor} catalogue only those detections that were matched with
some {\tt ASSOC}-list member. Such a feature is controlled by the {\tt
ASSOCSELEC\_TYPE} configuration parameter, which accepts one of the
three following keywords:
\begin{itemize}
\item {\tt ALL}: keep all {\sc SExtractor} detections, regardless of
matching. This is the default.
\item {\tt MATCHED}: keep only {\sc SExtractor} detections that were
matched with at least one {\tt ASSOC}-list member.
\item {\tt -MATCHED}: keep only {\sc SExtractor} detections that were
not matched with any {\tt ASSOC}-list member.
\end{itemize}