Commit 3fa4ed00 authored by Emmanuel Bertin's avatar Emmanuel Bertin
Browse files

Doc: some refactoring.

parent 9d813987
.. File Config.rst
.. include:: global.rst
The configuration file
======================
Each time it is run, |SExtractor| looks for a configuration file. If no
configuration file is specified in the command-line, it is assumed to be
called :file:`default.sex` and to reside in the current directory. If no
configuration file is found, |SExtractor| will use its own internal
default configuration.
Each time it is run, |SExtractor| looks for a configuration file.
If no configuration file is specified in the command-line, it is assumed to be called :file:`default.sex` and to reside in the current directory.
If no configuration file is found, |SExtractor| will use its own internal default configuration.
Creating a configuration file
-----------------------------
SExtractor can generate an ASCII dump of its internal default
configuration, using the ``-d`` option. By redirecting the standard output
of SExtractor to a file, one creates a configuration file that can
easily be modified afterwards:
SExtractor can generate an ASCII dump of its internal default configuration, using the ``-d`` option.
By redirecting the standard output of SExtractor to a file, one creates a configuration file that can easily be modified afterwards:
.. code-block:: console
$ sex -d > default.sex
A more extensive dump with less commonly used parameters can be
generated by using the ``-dd`` option.
A more extensive dump with less commonly used parameters can be generated by using the ``-dd`` option.
Format of the configuration file
--------------------------------
The format is ASCII. There must be only one parameter set per line,
following the form::
The format is ASCII. There must be only one parameter set per line, following the form::
Config-parameter      Value(s)
Extra spaces or linefeeds are ignored. Comments must begin with a ``#``
and end with a linefeed. Values can be of different types: strings (can
be enclosed between double quotes), floats, integers, keywords or
Boolean (`Y`/`y` or `N`/`n`). Some parameters accept zero or several values,
which must then be separated by commas. Integers can be given as
decimals, in octal form (preceded by digit O), or in hexadecimal
(preceded by `0x`). The hexadecimal format is particularly convenient for
writing multiplexed bit values such as binary masks. Environment
variables, written as ``$HOME`` or ``${HOME}`` are expanded.
Extra spaces or linefeeds are ignored.
Comments must begin with a ``#`` and end with a linefeed.
Values can be of different types: strings (can be enclosed between double quotes), floats, integers, keywords or Boolean (`Y`/`y` or `N`/`n`).
Some parameters accept zero or several values, which must then be separated by commas.
Integers can be given as decimals, in octal form (preceded by digit O), or in hexadecimal (preceded by `0x`).
The hexadecimal format is particularly convenient for writing multiplexed bit values such as binary masks.
Environment variables, written as ``$HOME`` or ``${HOME}`` are expanded.
.. _param_list:
Configuration parameter list
----------------------------
Here is a complete list of all the configuration parameters known to
|SExtractor|. Please refer to the next sections for a detailed description
of their meaning.
Here is a complete list of all the configuration parameters known to |SExtractor|.
Please refer to the next sections for a detailed description of their meaning.
.. include:: keys.rst
.. File Installing.rst
.. include:: global.rst
***********************
Installing the software
***********************
......@@ -12,95 +14,68 @@ is not necessary to operate the software.
Memory requirements depend on the size of the images to be processed.
Processing a single image should typically require about 100MB of memory.
For large images (hundreds of Mpixels or more), or in double-image / weighted
mode, |SExtractor|'s memory footprint should be around 500MB, and up to 2GB in
the worst cases. Swap-space can be put to contribution, although a strong
performance hit is to be expected.
For large images (hundreds of Mpixels or more), or in double-image / weighted mode, |SExtractor|'s memory footprint should be around 500MB, and up to 2GB in the worst cases.
Swap-space can be put to contribution, although a strong performance hit is to be expected.
Obtaining |SExtractor|
----------------------
For Linux users, the simplest way to have |SExtractor| up and running is to
install the standard binary package the comes with your Linux distribution.
Run, e.g., ``apt-get sextractor`` (on Debian) or ``dnf sextractor`` (Fedora) as
root and |SExtractor|, as well as all its dependencies, will automatically be
installed. If you decided to install the package this way you may skip the
following and move straight to the :ref:`next section <Using Sextractor>`.
However if |SExtractor| is not available in your distribution, or to obtain the
most recent version, the |SExtractor| source package can be downloaded from
`the official GitHub repository <https://github.com/astromatic/sextractor>`_ .
One may choose `one of the stable releases
<https://github.com/astromatic/sextractor/releases>`_, or for the fearless,
`a copy of the current master development branch
<https://github.com/astromatic/sextractor/archive/master.zip>`_.
For Linux users, the simplest way to have |SExtractor| up and running is to install the standard binary package the comes with your Linux distribution.
Run, e.g., ``apt-get sextractor`` (on Debian) or ``dnf sextractor`` (Fedora) as root and |SExtractor|, as well as all its dependencies, will automatically be installed.
If you decided to install the package this way you may skip the following and move straight to the :ref:`next section <Using Sextractor>`.
However if |SExtractor| is not available in your distribution, or to obtain the most recent version, the |SExtractor| source package can be downloaded from `the official GitHub repository <https://github.com/astromatic/sextractor>`_ .
One may choose `one of the stable releases <https://github.com/astromatic/sextractor/releases>`_, or for the fearless, `a copy of the current master development branch <https://github.com/astromatic/sextractor/archive/master.zip>`_.
Software requirements
---------------------
|SExtractor| has been developed on
`GNU/Linux <http://en.wikipedia.org/wiki/Linux>`_ machines and should compile on
any `POSIX <http://en.wikipedia.org/wiki/POSIX>`_-compliant system (this
includes |OSX|_ and `Cygwin <http://www.cygwin.com>`_ on |Windows|_, at the
price of some difficulties with the configuration), provided that the
*development* packages of the following libraries have been installed:
|SExtractor| has been developed on `GNU/Linux <http://en.wikipedia.org/wiki/Linux>`_ machines and should compile on any `POSIX <http://en.wikipedia.org/wiki/POSIX>`_-compliant system (this includes |OSX|_ and `Cygwin <http://www.cygwin.com>`_ on |Windows|_, at the price of some difficulties with the configuration), provided that the *development* packages of the following libraries have been installed:
* |ATLAS|_ V3.6 and above [#atlas_install]_,
* |FFTw|_ V3.0 and above [#fftw_install]_,
On Fedora/Redhat distributions for instance, the development packages above are
available as ``atlas-devel`` and ``fftw-devel``. Note that |ATLAS| and |FFTw|
are not necessary if |SExtractor| is linked with |Intel|'s |MKL|_ library.
On Fedora/Redhat distributions for instance, the development packages above are available as ``atlas-devel`` and ``fftw-devel``.
Note that |ATLAS| and |FFTw| are not necessary if |SExtractor| is linked with |Intel|'s |MKL|_ library.
Installation
------------
To install from the |GitHub| source package, you must first uncompress the
archive:
To install from the |GitHub| source package, you must first uncompress the archive:
.. code-block:: console
$ unzip sextractor-<version>.zip
A new directory called :file:`sextractor-<version>` should now appear at the
current location on your disk. Enter the directory and generate the files
required by the `autotools <http://en.wikipedia.org/wiki/GNU_Build_System>`_,
which the package relies on:
A new directory called :file:`sextractor-<version>` should now appear at the current location on your disk.
Enter the directory and generate the files required by the `autotools <http://en.wikipedia.org/wiki/GNU_Build_System>`_, which the package relies on:
.. code-block:: console
$ cd sextractor-<version>
$ sh autogen.sh
A :program:`configure` script is created. This script has many options, which
may be listed with the ``--help`` option:
A :program:`configure` script is created.
This script has many options, which may be listed with the ``--help`` option:
.. code-block:: console
$ ./configure --help
No options are required for compiling with the default GNU C compiler
(:program:`gcc`) if all the required libraries are installed at their default
locations:
No options are required for compiling with the default GNU C compiler (:program:`gcc`) if all the required libraries are installed at their default locations:
.. code-block:: console
$ ./configure
Compared to :program:`gcc` and the librairies above, the combination of the
|Intel| compiler (:program:`icc`) and the |MKL|_ libraries can give the
|SExtractor| executable a strong boost in performance, thanks to better
vectorized code. If :program:`icc` and the |MKL| are installed on your system
[#geticc]_ , you can take advantage of them using
Compared to :program:`gcc` and the librairies above, the combination of the |Intel| compiler (:program:`icc`) and the |MKL|_ libraries can give the |SExtractor| executable a strong boost in performance, thanks to better vectorized code.
If :program:`icc` and the |MKL| are installed on your system [#geticc]_ , you can take advantage of them using
.. code-block:: console
$ ./configure --enable-mkl
Additionally, if the |SExtractor| binary is to be run on a different machine
that does not have :program:`icc` and the |MKL| installed (e.g., a cluster
computing node), you must configure a partially statically linked executable
using
Additionally, if the |SExtractor| binary is to be run on a different machine that does not have :program:`icc` and the |MKL| installed (e.g., a cluster computing node), you must configure a partially statically linked executable using
.. code-block:: console
......@@ -112,34 +87,22 @@ In all cases, |SExtractor| can now be compiled with
$ make -j
An :file:`src/sex` executable is created. For system-wide installation, run
the usual
An :file:`src/sex` executable is created. For system-wide installation, run the usual
.. code-block:: console
$ sudo make install
You may now check that the software is properly installed by simply
typing in your shell:
You may now check that the software is properly installed by simply typing in your shell:
.. code-block:: console
$ sex
which will return the version number and other basic information (note that
some shells require the :program:`rehash` command to be run before making a
freshly installed executable accessible in the execution path).
which will return the version number and other basic information (note that some shells require the :program:`rehash` command to be run before making a freshly installed executable accessible in the execution path).
.. [#mac_install] Mac OS X |.dmg|_ packages should be available soon.
.. [#atlas_install] Use the ``--with-atlas`` and/or
``--with-atlas-incdir`` options of the |SExtractor| :command:`configure`
script to specify the |ATLAS| library and include paths if |ATLAS| files are
installed at unusual locations.
.. [#fftw_install] Make sure that |FFTW| has been compiled with
:command:`configure` options ``--enable-threads --enable-float``.
.. [#geticc] The Linux versions of the |Intel| compiler and |MKL| are
`available for free to academic researchers, students, educators and open
source contributors <http://software.intel.com/qualify-for-free-software>`_.
.. include:: keys.rst
.. [#atlas_install] Use the ``--with-atlas`` and/or ``--with-atlas-incdir`` options of the |SExtractor| :command:`configure` script to specify the |ATLAS| library and include paths if |ATLAS| files are installed at unusual locations.
.. [#fftw_install] Make sure that |FFTW| has been compiled with :command:`configure` options ``--enable-threads --enable-float``.
.. [#geticc] The Linux versions of the |Intel| compiler and |MKL| are `available for free to academic researchers, students, educators and open source contributors <http://software.intel.com/qualify-for-free-software>`_.
.. File Introduction.rst
.. include:: global.rst
Introduction
============
|SExtractor|_ (Source-Extractor) is a program that builds a catalog
of objects from an astronomical image. It is particularly oriented
towards the reduction of large scale galaxy-survey data, but it also performs
well on moderately crowded star fields. Its main features are:
|SExtractor|_ (Source-Extractor) is a program that builds a catalog of objects from an astronomical image. It is particularly oriented towards the reduction of large scale galaxy-survey data, but it also performs well on moderately crowded star fields. Its main features are:
* Support for multi-extension FITS (|MEF|_)
* Speed: up to about 50 Mpixel/s or 10,000 sources/s with a 3 GHz processor
......@@ -22,8 +21,5 @@ well on moderately crowded star fields. Its main features are:
* Built-in catalog cross-identification.
* Special mode for photographic scans.
* |XML|_ |VOTable|_-compliant catalog output.
* |XSLT|_ filter sheet provided for convenient access to metadata from a
regular web browser.
.. include:: keys.rst
* |XSLT|_ filter sheet provided for convenient access to metadata from a regular web browser.
.. File License.rst
.. include:: global.rst
License
=======
|SExtractor|_ *is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your
option) any later version.* |SExtractor| *is distributed in the hope that it will
be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details. You should have received a copy
of the GNU General Public License along with* |SExtractor|. *If not, see*
`www.gnu.org/licenses/ <http://www.gnu.org/licences/>`_.
|SExtractor|_ *is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.*
|SExtractor| *is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with* |SExtractor|. *If not, see* `www.gnu.org/licenses/ <http://www.gnu.org/licences/>`_.
.. include:: keys.rst
Measurements
============
Once sources have been detected and deblended, they enter the measurement phase. |SExtractor| performs three categories of measurements: isophotal, full, and model-fitting.
.. include:: global.rst
Once sources have been detected and deblended, they enter the measurement phase.
|SExtractor| performs three categories of measurements: isophotal, full, and model-fitting.
.. _isophotal_measurements:
Isophotal
Measurements are made on the isophotal object footprints, which are defined on the filtered detection image. Only pixels with values above the threshold set with ``ANALYSIS_THRESH`` are considered [#thresh]_, which makes the analysis extremely fast, but obviously strongly dependent on the threshold itself. This is an issue particularly when the amplitude of the bakground noise varies over the image. Many of the isophotal measurements (e.g., ``X_IMAGE``, ``Y_IMAGE``, ``FLUX_ISO``) are necessary for the internal operations of |SExtractor| and are therefore executed even if they are not requested.
Measurements are made on the isophotal object footprints, which are defined on the filtered detection image. Only pixels with values above the threshold set with ``ANALYSIS_THRESH`` are considered [#thresh]_, which makes the analysis extremely fast, but obviously strongly dependent on the threshold itself. This is an issue particularly when the amplitude of the bakground noise varies over the image. Many of the isophotal measurements (e.g., :param:`X_IMAGE`, :param:`Y_IMAGE`, :param:`FLUX_ISO`) are necessary for the internal operations of |SExtractor| and are therefore executed even if they are not requested.
Full
Measurements have access to all pixels of the image. These measurements are generally more sophisticated, less affected by variable biases induced by the detection threshold, and still reasonably fast. They are done at a later stage of the processing, after CLEANing and MASKing.
......@@ -23,5 +26,4 @@ Model-fitting
.. [#thresh] Pixel values also have to exceed the local detection threshold set with ``DETECT_THRESH``.
.. [#psf_models] PSF models be computed using the |PSFEx|_ package.
.. include:: keys.rst
This diff is collapsed.
.. File PositionWin.rst
.. include:: global.rst
Windowed positional parameters
==============================
Measurements performed through a *window* function (an *envelope*) do not have many of the drawbacks of isophotal measurements. |SExtractor| implements “windowed” versions for most
of the measurements described in the :ref:`previous section<position_iso>`:
of the measurements described in the :ref:`previous section<position_iso_def>`:
.. note::
Unless otherwise noted, all parameter names given below are only prefixes. They must be followed by _IMAGE if the results shall be expressed in pixel coordinates or _WORLD, _SKY, _J2000 or _B1950 for |WCS|_ coordinates (see :ref:`coord_suffix`).
+----------------------+-------------------------------+
| Isophotal parameters | Equivalent windowed parameters|
+======================+===============================+
| X, Y | XWIN, YWIN |
+----------------------+-------------------------------+
| ERRA, ERRB, ERRTHETA | ERRAWIN, ERRBWIN, ERRTHETAWIN |
+----------------------+-------------------------------+
| A, B, THETA | AWIN, BWIN, THETAWIN |
+----------------------+-------------------------------+
| X2, Y2, XY | X2WIN, Y2WIN, XYWIN |
+----------------------+-------------------------------+
| CXX, CYY, CXY | CXXWIN, CYYWIN, CXYWIN |
+----------------------+-------------------------------+
The computations involved are roughly the same except that the pixel
values are integrated within a circular Gaussian window as opposed to
the object’s isophotal footprint. The Gaussian window is scaled to each
object; its FWHM is the diameter of the disk that contains half of the
object flux (:math:`d_{50}`). Note that in double-image mode
(§[chap:using]) the window is scaled based on the *measurement* image.
Unless otherwise noted, all parameter names given below are only prefixes. They must be followed by _IMAGE if the results shall be expressed in pixel coordinates or :param:`_WORLD`, :param:`_SKY`, :param:`_J2000` or :param:`_B1950` for |WCS|_ coordinates (see :ref:`coord_suffix`).
+-------------------------------------------------+----------------------------------------------------------+
| Isophotal parameters | Equivalent windowed parameters |
+=================================================+==========================================================+
| :param:`X`, :param:`Y` | :param:`XWIN`, :param:`YWIN` |
+-------------------------------------------------+----------------------------------------------------------+
| :param:`ERRA`, :param:`ERRB`, :param:`ERRTHETA` | :param:`ERRAWIN`, :param:`ERRBWIN`, :param:`ERRTHETAWIN` |
+-------------------------------------------------+----------------------------------------------------------+
| :param:`A`, :param:`B`, :param:`THETA` | :param:`AWIN`, :param:`BWIN`, :param:`THETAWIN` |
+-------------------------------------------------+----------------------------------------------------------+
| :param:`X2`, :param:`Y2`, :param:`XY` | :param:`X2WIN`, :param:`Y2WIN`, :param:`XYWIN` |
+-------------------------------------------------+----------------------------------------------------------+
| :param:`CXX`, :param:`CYY`, :param:`CXY` | :param:`CXXWIN`, :param:`CYYWIN`, :param:`CXYWIN` |
+-------------------------------------------------+----------------------------------------------------------+
The computations involved are roughly the same except that the pixel values are integrated within a circular Gaussian window as opposed to
the object’s isophotal footprint.
The Gaussian window is scaled to each object; the Gaussian FWHM is the diameter of the disk that contains half of the object flux (:math:`d_{50}`).
Note that in double-image mode (§[chap:using]) the window is scaled based on the *measurement* image.
.. _xywin:
Windowed centroid: XWIN, YWIN
-----------------------------
Windowed centroid: :param:`XWIN`, :param:`YWIN`
-----------------------------------------------
This is an iterative process. The computation starts by initializing the
windowed centroid coordinates :math:`\overline{x_{\tt WIN}}^{(0)}` and
:math:`\overline{y_{\tt WIN}}^{(0)}` to their basic :math:`\overline{x}`
and :math:`\overline{y}` isophotal equivalents, respectively. Then at
each iteration :math:`t`, :math:`\overline{x_{\tt WIN}}` and
:math:`\overline{y_{\tt WIN}}` are refined using:
This is an iterative process.
Computation starts by initializing the windowed centroid coordinates :math:`\overline{x_{\tt WIN}}^{(0)}` and :math:`\overline{y_{\tt WIN}}^{(0)}` to their basic :math:`\overline{x}` and :math:`\overline{y}` isophotal equivalents, respectively.
Then at each iteration :math:`t`, :math:`\overline{x_{\tt WIN}}` and :math:`\overline{y_{\tt WIN}}` are refined using:
.. math::
:label: xywin
......@@ -54,7 +51,8 @@ each iteration :math:`t`, :math:`\overline{x_{\tt WIN}}` and
{\tt YWIN}^{(t+1)} & = & \overline{y_{\tt WIN}}^{(t+1)}
= \overline{y_{\tt WIN}}^{(t)} + 2\,\frac{\sum_{r_i^{(t)} < r_{\rm max}}
w_i^{(t)} I_i\ (y_i - \overline{y_{\tt WIN}}^{(t)})}
{\sum_{r_i^{(t)} < r_{\rm max}} w_i^{(t)} I_i},\end{aligned}
{\sum_{r_i^{(t)} < r_{\rm max}} w_i^{(t)} I_i},
\end{aligned}
where
......@@ -71,20 +69,12 @@ with
r_i^{(t)} = \sqrt{\left(x_i - \overline{x_{\tt WIN}}^{(t)}\right)^2 + \left(y_i
- \overline{y_{\tt WIN}}^{(t)}\right)^2}
and :math:`s_{\tt WIN} = d_{50} / \sqrt{8 \ln 2}`. The process stops
when the change in position between two iterations is less than
:math:`2\times10^{-4}` pixel, a condition which is generally achieved in
about 3 to 5 iterations.
Although the iterative nature of the processing slows down the
processing , it is recommended to use whenever possible windowed
parameters instead of their isophotal equivalents, since the
measurements they provide are much more precise (:numref:`fig_xwinprec`).
The precision in centroiding offered by XWIN_IMAGE and YWIN_IMAGE is
actually very close to that of PSF-fitting on focused and properly
sampled star images, and can also be applied to galaxies. It has been
verified that for isolated, Gaussian-like PSFs, its accuracy is close to
the theoretical limit set by image noise [#win_accuracy]_.
and :math:`s_{\tt WIN} = d_{50} / \sqrt{8 \ln 2}`.
Process stops when the change in position between two iterations is less than :math:`2\times10^{-4}` pixel, a condition which is achieved in about 3 to 5 iterations in practice.
Although they are slower, it is recommended to use whenever possible windowed position parameters instead of their isophotal equivalents; the measurements they provide are generally much more accurate (:numref:`fig_xwinprec`).
The centroiding accuracy of :param:`XWIN_IMAGE` and :param:`YWIN_IMAGE` is actually very close to that of PSF-fitting on focused and properly sampled star images. Windowed measurements can also be applied to galaxies.
It has been verified that for isolated objects with Gaussian-like profiles, their accuracy is close to the theoretical limit set by image noise [#win_accuracy]_.
.. _fig_xwinprec:
......@@ -92,15 +82,12 @@ the theoretical limit set by image noise [#win_accuracy]_.
:figwidth: 100%
:align: center
Comparison between isophotal and windowed centroid measurement residuals on
simulated, background noise-limited images.
*Left*: histogram of the difference between X_IMAGE and the true centroid
in x.
*Right*: histogram of the difference between XWIN_IMAGE and the true centroid
in x.
Comparison between isophotal and windowed centroid measurement residuals on simulated, background noise-limited images.
*Left*: histogram of the difference between :param:`X_IMAGE` and the true centroid in x.
*Right*: histogram of the difference between :param:`XWIN_IMAGE` and the true centroid in x.
Windowed 2nd order moments: X2, Y2, XY
--------------------------------------
Windowed 2nd order moments: :param:`X2`, :param:`Y2`, :param:`XY`
-----------------------------------------------------------------
Windowed second-order moments are computed on the image data once the :ref:`centering process <xywin>` has converged:
......@@ -119,14 +106,13 @@ Windowed second-order moments are computed on the image data once the :ref:`cent
(y_i - \overline{y_{\tt WIN}})}
{\sum_{r_i < r_{\rm max}} w_i I_i}.\end{aligned}
Windowed second-order moments are typically twice smaller than their
isophotal equivalent.
Windowed second-order moments are typically twice smaller than their isophotal equivalent.
Windowed shape parameters: AWIN, BWIN, THETAWIN
-----------------------------------------------
Windowed shape parameters: :param:`AWIN`, :param:`BWIN`, :param:`THETAWIN`
--------------------------------------------------------------------------
They are computed from the windowed 2nd order moments exactly the same
way as in :eq:`theta0_3` and :eq:`aimage_2` from the :ref:`isophotal shape parameter<shape_iso>` section:
way as in :eq:`theta0_3` and :eq:`aimage_2` from the :ref:`isophotal shape parameter<shape_iso_def>` section:
.. math::
:label: shapewin
......@@ -140,11 +126,10 @@ way as in :eq:`theta0_3` and :eq:`aimage_2` from the :ref:`isophotal shape param
\end{aligned}
Windowed ellipse parameters: CXXWIN, CYYWIN, CXYWIN
---------------------------------------------------
Windowed ellipse parameters: :param:`CXXWIN`, :param:`CYYWIN`, :param:`CXYWIN`
------------------------------------------------------------------------------
They are computed from the windowed 2nd order moments exactly the same
way as in :eq:`ellipse_2` describing the :ref:`isophotal ellipse parameters<ellipse_iso>`:
Ellipse parameters are computed from the windowed 2nd order moments exactly the same way as in :eq:`ellipse_2` describing the :ref:`isophotal ellipse parameters<ellipse_iso_def>`:
.. math::
:label: ellipsewin_2
......@@ -158,15 +143,14 @@ way as in :eq:`ellipse_2` describing the :ref:`isophotal ellipse parameters<elli
\frac{\overline{x_{\tt WIN}^2}}{\overline{x_{\tt WIN}^2} \overline{y_{\tt WIN}^2} - \overline{xy_{\tt WIN}}^2}\\
{\tt CXYWIN} & = & 2 \,\cos {\tt THETAWIN}\,\sin {\tt
THETAWIN} \left( \frac{1}{{\tt AWIN}^2} - \frac{1}{{\tt BWIN}^2}\right) = -2\,
\frac{\overline{xy_{\tt WIN}}}{\overline{x_{\tt WIN}^2} \overline{y_{\tt WIN}^2} - \overline{xy_{\tt WIN}}^2}\end{aligned}
\frac{\overline{xy_{\tt WIN}}}{\overline{x_{\tt WIN}^2} \overline{y_{\tt WIN}^2} - \overline{xy_{\tt WIN}}^2}.
\end{aligned}
Windowed position uncertainties: ERRX2WIN, ERRY2WIN, ERRXYWIN, ERRAWIN, ERRBWIN, ERRTHETAWIN, ERRCXXWIN, ERRCYYWIN, ERRCXYWIN
-----------------------------------------------------------------------------------------------------------------------------
Windowed position uncertainties: :param:`ERRX2WIN`, :param:`ERRY2WIN`, :param:`ERRXYWIN`, :param:`ERRAWIN`, :param:`ERRBWIN`, :param:`ERRTHETAWIN`, :param:`ERRCXXWIN`, :param:`ERRCYYWIN`, :param:`ERRCXYWIN`
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Windowed position uncertainties are computed on the image data once the
centering process of the :ref:`windowed centroid <xywin>` has converged. Assuming that
noise is uncorrelated among pixels, standard error propagation applied
to :eq:`xywin` writes:
Windowed position uncertainties are computed on the image data once the centering process of the :ref:`windowed centroid <xywin>` has converged.
Assuming that noise is uncorrelated among pixels, standard error propagation applied to :eq:`xywin` writes:
.. math::
:label: errwin
......@@ -181,15 +165,10 @@ to :eq:`xywin` writes:
{\tt ERRXYWIN} & = {\rm cov}(\overline{x_{\tt WIN}},\overline{y_{\tt WIN}})
= & 4\,\frac{\sum_{r_i < r_{\rm max}}
w_i^2 \sigma^2_i (x_i-\overline{x_{\tt WIN}})(y_i-\overline{y_{\tt WIN}})}
{\left(\sum_{r_i < r_{\rm max}} w_i I_i\right)^2}.\end{aligned}
{\left(\sum_{r_i < r_{\rm max}} w_i I_i\right)^2}.
\end{aligned}
The semi-major axis ERRAWIN, semi-minor axis ERRBWIN, and position angle
ERRTHETAWIN of the :math:`1\sigma` position error ellipse are computed
from the covariance matrix elements
:math:`{\rm var}(\overline{x_{\tt WIN}})`,
:math:`{\rm var}(\overline{y_{\tt WIN}})`,
:math:`{\rm cov}(\overline{x_{\tt WIN}},\overline{y_{\tt WIN}})`,
similarly to the :ref:`isophotal error ellipse <poserr>`:
Semi-major axis :param:`ERRAWIN`, semi-minor axis :param:`ERRBWIN`, and position angle :param:`ERRTHETAWIN` of the :math:`1\sigma` position error ellipse are computed from the covariance matrix elements :math:`{\rm var}(\overline{x_{\tt WIN}})`, :math:`{\rm var}(\overline{y_{\tt WIN}})`, :math:`{\rm cov}(\overline{x_{\tt WIN}},\overline{y_{\tt WIN}})`, similarly to the :ref:`isophotal error ellipse <poserr>`:
.. math::
:label: errabthetawin
......@@ -205,7 +184,7 @@ similarly to the :ref:`isophotal error ellipse <poserr>`:
{{\rm var}(\overline{x_{\tt WIN}}) - {\rm var}(\overline{y_{\tt WIN}})}.
\end{aligned}
And the error ellipse parameters are:
The error ellipse parameters are:
.. math::
:label: errellipsewin
......@@ -230,5 +209,3 @@ And the error ellipse parameters are:
.. [#win_accuracy] See http://www.astromatic.net/forum/showthread.php?tid=581 .
.. include:: keys.rst
.. File Using.rst
.. include:: global.rst
.. _using-sextractor:
Using SExtractor
......@@ -39,5 +41,4 @@ about the source extraction process:
remote web server), alternative |XSLT| translation URLs may be specified
using the ``XSL_URL`` configuration parameter.
.. include:: keys.rst
.. File Weighting.rst
.. include:: global.rst
Weighting
=========
The noise level in astronomical images is often fairly constant, that is, constant values for the gain,
the background noise and the detection thresholds can be used over the whole frame.
Unfortunately in some cases, like strongly vignetted or composited images, this approximation
is no longer good enough.
This leads to detecting clusters of detected noise peaks in the noisiest parts of the image,
or missing obvious objects in the most sensitive ones.
The noise level in astronomical images is often fairly constant, that is, constant values for the gain, the background noise and the detection thresholds can be used over the whole frame.
Unfortunately in some cases, like strongly vignetted or composited images, this approximation is no longer good enough.
This leads to detecting clusters of detected noise peaks in the noisiest parts of the image, or missing obvious objects in the most sensitive ones.
|SExtractor| is able to handle images with variable noise.
It does it through *weight maps*, which are frames having the same size as the images where objects are detected or
measured, and which describe the noise intensity at each pixel.
It does it through *weight maps*, which are frames having the same size as the images where objects are detected or measured, and which describe the noise intensity at each pixel.
These maps are internally stored in units of *absolute variance* (in :math:`ADU^2`)
We employ the generic term *weight map* because these maps can also be interpreted as quality index maps:
infinite variance (:math:`\ge 10^{30}` by definition in |SExtractor|) means that the related pixel in the science frame is totally unreliable and should be ignored.
We employ the generic term *weight map* because these maps can also be interpreted as quality index maps: infinite variance (:math:`\ge 10^{30}` by definition in |SExtractor|) means that the related pixel in the science frame is totally unreliable and should be ignored.
The variance format was adopted as it linearizes most of the operations done over weight maps (see below).
This means that the noise covariances between pixels are ignored.
Although raw CCD images have essentially white noise, this is not the case for warped images, for which resampling may
induce a strong correlation between neighbouring pixels.
In theory, all non-zero covariances within the geometrical limits of the analysed patterns should be taken into account to derive
thresholds or error estimates.
Fortunately, the correlation length of the noise is often smaller than the patterns to be detected or measured,
and constant over the image. In that case one can apply a simple *fudge factor* to the estimated variance to account for
correlations on small scales. This proves to be a good approximation in general, although it certainly leads to
underestimations for the smallest patterns.
This means that the noise covariances between pixels are ignored. Although raw CCD images have essentially white noise, this is not the case for warped images, for which resampling may induce a strong correlation between neighboring pixels.
In theory, all non-zero covariances within the geometrical limits of the analysed patterns should be taken into account to derive thresholds or error estimates.
Fortunately, the correlation length of the noise is often smaller than the patterns to be detected or measured, and constant over the image.
In that case one can apply a simple *fudge factor* to the estimated variance to account for correlations on small scales.
This proves to be a good approximation in general, although it certainly leads to underestimations for the smallest patterns.
.. _weigth-map-format:
......@@ -34,41 +27,34 @@ Weight-map formats
|SExtractor| accepts in input, and converts to its internal variance format, several types of weight-maps.
This is controlled through the ``WEIGHT_TYPE`` configuration keyword.
Those weight-maps can either be read from a FITS file, whose name is specified by the ``WEIGHT_IMAGE`` keyword,
or computed internally.
Those weight-maps can either be read from a FITS file, whose name is specified by the ``WEIGHT_IMAGE`` keyword, or computed internally.
Valid ``WEIGHT_TYPE`` values are:
* ``NONE`` :
No weighting is applied. The related ``WEIGHT_IMAGE`` and ``WEIGHT_THRESH`` (see below) parameters are ignored.
No weighting is applied.
The related ``WEIGHT_IMAGE`` and ``WEIGHT_THRESH`` (see below) parameters are ignored.
* ``BACKGROUND`` :
the science image itself is used to compute internally a variance map (the related ``WEIGHT_IMAGE``
parameter is ignored). Robust (:math:`3\sigma`-clipped) variance estimates are first computed within the same
background meshes as those described in ?? [#f1].
The resulting low-resolution variance map is then bicubic-spline-interpolated on the fly to produce
the actual full-size variance map.
The science image itself is used to compute internally a variance map (the related ``WEIGHT_IMAGE`` parameter is ignored).
Robust (:math:`3\sigma`-clipped) variance estimates are first computed within the same background meshes as those described in ?? [#f1]_.
The resulting low-resolution variance map is then bicubic-spline-interpolated on the fly to produce the actual full-size variance map.
A check-image with ``CHECKIMAGE_TYPE`` ``MINIBACK_RMS`` can be requested to examine the low-resolution variance map.
* ``MAP_RMS`` :
the FITS image specified by the ``WEIGHT_IMAGE`` file name must contain a weight-map in units of
absolute standard deviations (in ADUs per pixel).
The FITS image specified by the ``WEIGHT_IMAGE`` file name must contain a weight-map in units of absolute standard deviations (in ADUs per pixel).
* ``MAP_VAR`` :
the FITS image specified by the ``WEIGHT_IMAGE`` file name must contain a weight-map in units of
relative variance. A robust scaling to the appropriate absolute level is then performed by comparing this
variance map to an internal, low-resolution, absolute variance map built from the science image itself.
The FITS image specified by the ``WEIGHT_IMAGE`` file name must contain a weight-map in units of relative variance.
A robust scaling to the appropriate absolute level is then performed by comparing this variance map to an internal, low-resolution, absolute variance map built from the science image itself.
* ``MAP_WEIGHT`` :
the FITS image specified by the ``WEIGHT_IMAGE`` file name must contain a weight-map in units of
relative weights.
The data are converted to variance units (by definition variance :math:`\propto\frac{1}{weight}`),
and scaled as for ``MAP_VAR``.
``MAP_WEIGHT`` is the most commonly used type of weight-map: a flat-field, for example, is generally
a good approximation to a perfect weight-map.
The FITS image specified by the ``WEIGHT_IMAGE`` file name must contain a weight-map in units of relative weights.
The data are converted to variance units (by definition variance :math:`\propto\frac{1}{weight}`), and scaled as for ``MAP_VAR``.
``MAP_WEIGHT`` is the most commonly used type of weight-map: a flat-field, for example, is generally a good approximation to a perfect weight-map.
.. _effect_of_weighting:
......@@ -78,12 +64,9 @@ Effect of weighting
Weight-maps modify the working of |SExtractor| in the following respects:
#. Bad pixels are discarded from the background statistics.
If more than :math:`50\%` of the pixels in a background mesh are bad, the local background value and
its standard deviation are replaced by interpolation of the nearest valid meshes.
If more than :math:`50\%` of the pixels in a background mesh are bad, the local background value and the background standard deviation are replaced by interpolation of the nearest valid meshes.
#. The detection threshold *t* above the local sky background is adjusted for each pixel *i*
with variance :math:`\sigma^2_i` : :math:`t_i=DETECT\_THRESH\times\sqrt{\sigma^2_i}`, where
``DETECT_THRESH`` is expressed in units of standard deviations of the background noise.
#. The detection threshold *t* above the local sky background is adjusted for each pixel *i* with variance :math:`\sigma^2_i` : :math:`t_i=DETECT\_THRESH\times\sqrt{\sigma^2_i}`, where ``DETECT_THRESH`` is expressed in units of standard deviations of the background noise.
Pixels with variance above the threshold set with the ``WEIGHT_THRESH`` parameter are therefore simply not detected.
This may result in splitting objects crossed by a group of bad pixels.
Interpolation (see ???) should be used to avoid this problem.
......@@ -91,34 +74,28 @@ Weight-maps modify the working of |SExtractor| in the following respects:
This yields optimum scaling of the detection threshold in the case where noise is uncorrelated from pixel to pixel.
Non-linear filtering operations (like those offered by artificial retinae) are not affected.
#. The cleaning process (??) takes into account the exact individual thresholds assigned to each pixel for
deciding about the fate of faint detections.
#. The cleaning process (??) takes into account the exact individual thresholds assigned to each pixel for deciding about the fate of faint detections.
#. Error estimates like ``FLUXISO_ERR`` , ``ERRA_IMAGE`` , etc., make use of individual variances too.
#. Error estimates like ``FLUXISO_ERR`` , ``ERRA_IMAGE`` , etc. also make use of individual variances.
Local background-noise standard deviation is simply set to :math:`\sqrt{\sigma^2_i}`.
In addition, if the ``WEIGHT_GAIN`` parameter is set to ``Y`` (which is the default), it is assumed that the
local pixel gain (i.e., the conversion factor from photo-electrons to ADUs) is inversely proportional to
:math:`\sigma^2_i`, its median value over the image being set by the ``GAIN`` configuration parameter.
In addition, if the ``WEIGHT_GAIN`` parameter is set to ``Y`` (which is the default), it is assumed that the local pixel gain (i.e., the conversion factor from photo-electrons to ADUs) is inversely proportional to :math:`\sigma^2_i`, the median value over the image being set by the ``GAIN`` configuration parameter.
In other words, it is then supposed that the changes in noise intensities seen over the images are due to gain changes.
This is the most common case: correction for vignetting, or coverage depth.
When this is not the case, for instance when changes are purely dominated by those of the read-out noise,
``WEIGHT_GAIN`` shall be set to ``N``.
When this is not the case, for instance when changes are purely dominated by those of the read-out noise, ``WEIGHT_GAIN`` shall be set to ``N``.
#. Finally, pixels with weights beyond ``WEIGHT_THRESH`` are treated just like pixels discarded by the masking process (??).
Combining weight maps
---------------------
All the weighting options listed in :ref:`weigth-map-format` can be applied separately to detection and measurement images
(:ref:`using-sextractor`), even if some combinations may not always make sense.
All the weighting options listed in :ref:`weigth-map-format` can be applied separately to detection and measurement images (:ref:`using-sextractor`), even if some combinations may not always make sense.
For instance, the following set of configuration lines:
``WEIGHT_IMAGE`` *rms.fits*, *weight.fits*
``WEIGHT_TYPE`` ``MAP_RMS``, ``MAP_WEIGHT``
will load the FITS file *rms.fits* and use it as an RMS map for adjusting the detection threshold and cleaning,
while the *weight.fits* weight map will only be used for scaling the error estimates on measurements.
will load the FITS file *rms.fits* and use it as an RMS map for adjusting the detection threshold and cleaning, while the *weight.fits* weight map will only be used for scaling the error estimates on measurements.
This can be done in single- as well as in dual-image mode (:ref:`using-sextractor`).
``WEIGHT_IMAGE`` can be ignored for ``BACKGROUND`` ``WEIGHT_TYPE``.
It is of course possible to use weight-maps for detection or for measurement only.
......@@ -134,5 +111,4 @@ will apply weighting only for measurements; detection and cleaning operations wi
.. [#f1] The mesh-filtering procedures act on the variance map, too.
.. include:: keys.rst
......@@ -156,7 +156,7 @@ booktitle = {Conference on Applications of Digital Image Processing to Astronomy
@PHDTHESIS{1996PhDT_68B,
author = {{Bertin}, E.},
title = "{Photom\'etrie automatique de galaxies et contraintes sur leur \'evolution r\'ecente}",
school = {PhD Thesis.~Universit{\'e} Paris VI., (1996)},
school = {Universit{\'e} Paris VI},
year = 1996,
month = jun,
adsurl = {http://adsabs.harvard.edu/abs/1996PhDT........68B},
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment