# public documents.sextractor_doc

## [/] [crossid.tex] - Rev 32

\chapter{Cross-identification within {\sc SExtractor}}
{\sc SExtractor} allows one to perform on-the-fly \index{cross-identification} cross-identification of
detections with an {\tt ASCII} list provided by the user. \index{cross-identification} Cross-identification
can be done both in pixel or world coordinates. Configuration parameters related
to \index{cross-identification} 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} or {\tt NUMBER\_ASSOC}. Then {\sc SExtractor} looks
for an {\tt ASCII} file (the so-called{\tt ASSOC} list), which must be
specified using the {\tt ASSOC\_NAME} configuration
keyword. The {\tt ASSOC} list should contain columns of numbers
separated by spaces or tabs. Each line describes a source that will
enter the \index{cross-identification} cross-identification process. Lines with
zero characters, or beginning with {\tt \#}'' (for comments) are ignored.
You may therefore use any {\tt ASCII} catalogue generated by a previous
{\sc SExtractor} run as an {\tt ASSOC} list.

In order to perform the \index{cross-identification} cross-identification,
{\sc SExtractor} needs to know which are the columns that contain the
coordinates in the {\tt ASSOC} list. These can be designated using the {\tt
ASSOC\_PARAMS} configuration parameter. The \index{syntax} 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, or world
coordinates such as $\alpha$ and $\delta$. By definition, the position of the
first column is 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}
Three configuration parameters control the {\tt ASSOC} process. The first
one, {\tt ASSOCCOORD\_TYPE}, should be set to {\tt PIXEL} or {\tt WORLD},
depending on what type of coordinates is in the {\tt ASSOC} list. If
{\tt ASSOCCOORD\_TYPE} is set to {\tt PIXEL}, {\sc SExtractor} expects the $x$
and $y$ coordinates to comply with the FITS convention: by definition, the
center of the first pixel in the \index{image} image array has pixel-coordinates
(1.0,1.0). If {\tt ASSOCCOORD\_TYPE} is set to {\tt WORLD}, {\sc SExtractor}
uses the WCS information found in the FITS image header to convert to
pixel coordinates the coordinates read in the {\tt ASSOC} list prior to
making the cross-identification.

{\tt ASSOC\_RADIUS}, accepts a decimal number which
represents the maximum distance (in pixels) one should have between
the \index{barycenter} 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 last 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
\index{cross-identification} 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 \index{cross-identification} 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
\index{mean} 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 \index{syntax} 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}