From 2d5beb61c1920825385cbc68478becad9a828f9a Mon Sep 17 00:00:00 2001
From: Emmanuel Bertin <bertin@localhost.localdomain>
Date: Sun, 21 Jan 2018 19:09:24 +0100
Subject: [PATCH] Doc: Added input image file description and refactored Using
section.
---
doc/src/Config.rst | 10 ++++++----
doc/src/Input.rst | 44 ++++++++++++++++++++++++++++++++++++++++++
doc/src/Output.rst | 32 ++++++++++++++++++++++++++++++
doc/src/Param.rst | 22 ++++++++++++---------
doc/src/Using.rst | 35 ++++++++-------------------------
doc/src/index.rst | 2 --
doc/src/references.bib | 27 ++++++++++++++++++++++++++
7 files changed, 130 insertions(+), 42 deletions(-)
create mode 100644 doc/src/Input.rst
create mode 100644 doc/src/Output.rst
diff --git a/doc/src/Config.rst b/doc/src/Config.rst
index 871afc7..be953db 100644
--- a/doc/src/Config.rst
+++ b/doc/src/Config.rst
@@ -2,15 +2,17 @@
.. include:: global.rst
+.. _config_file:
+
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.
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:
@@ -22,7 +24,7 @@ By redirecting the standard output of SExtractor to a file, one creates a config
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::
@@ -39,7 +41,7 @@ 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.
diff --git a/doc/src/Input.rst b/doc/src/Input.rst
new file mode 100644
index 0000000..fccf40e
--- /dev/null
+++ b/doc/src/Input.rst
@@ -0,0 +1,44 @@
+.. File Input.rst
+
+.. include:: global.rst
+
+.. _input:
+
+Input files
+-----------
+
+|SExtractor| accepts images stored in |FITS|_ :cite:`1981AAS_44_363W`.
+Both "Basic FITS" (one single header and one single body) and |MEF|_
+files are recognized.
+Binary |SExtractor| catalogs produced from |MEF| images are |MEF| files themselves.
+If the catalog output format is set to ASCII, all catalogs from the individual extensions are concatenated in one big file; the :param:`EXT_NUMBER` catalog parameter can be used to tell which extension the detection belongs to.
+
+.. important::
+ Contrary to most other astronomy packages, |SExtractor| does not rely on the `FITSIO <https://heasarc.gsfc.nasa.gov/fitsio/>`_ library and instead uses its own library for managing |FITS| files. As a consequence, some features of |FITS| such as image compression/tiling are not supported at this time.
+
+For images with :math:`{\rm NAXIS} > 2`, only the first data-plane is loaded.
+In |SExtractor|, as in all similar programs, |FITS| axis #1 is traditionally
+referred to as the *x* axis, and |FITS| axis #2 as the *y* axis.
+
+Double image mode
+~~~~~~~~~~~~~~~~~
+
+When the pixel data for a given field are available using the same pixel grid in several photometric channels, it is often best to measure object characteristics, like magnitudes, exactly at the same positions and through the same apertures for the different channels.
+This to derive precise color indices for example.
+|SExtractor| makes this possible by providing a special mode dubbed "double image mode" where detections are made on one image while measurements are carried out on another. Both images must have the exact same dimensions, obviously.
+By repeatedly running |SExtractor| with various "measurement images" while keeping the same "detection image", one ends up with a set of catalogs having the same sources measured through different channels.
+The detection image will generally be chosen in the band where the data are the deepest.
+Alternatively, using a ":math:`\chi2` image" :cite:`1999AJ_117_68S` [#swarpchi2]_ as a detection image, will allow most of the sources present in at least one channel to be detected and measured.
+
+Double image mode is automatically engaged when providing |SExtractor| with two images instead of one:
+
+.. code-block:: console
+
+ $ sex detection.fits,measurement.fits
+
+A space may be used instead of a coma. In the example above, :file:`detection.fits` is used as a detection image, while measurements are carried out on :file:`measurement.fits`.
+
+.. [#swarpchi2]
+ :math:`\chi2` images can easily be generated using the |SWarp|_ package :cite:`2002ASPC_281_228B`.
+
+
diff --git a/doc/src/Output.rst b/doc/src/Output.rst
new file mode 100644
index 0000000..f79dc43
--- /dev/null
+++ b/doc/src/Output.rst
@@ -0,0 +1,32 @@
+.. File Output.rst
+
+.. include:: global.rst
+
+.. _output:
+
+Output files
+------------
+
+Diagnostic files
+~~~~~~~~~~~~~~~~
+
+Two types of files can be generated by |SExtractor|, providing diagnostics
+about the source extraction process:
+
+* "Check-images" are FITS files containing raster images such as maps of the
+ background model, apertures, etc.. The configuration parameters
+ ``CHECKIMAGE_TYPE`` and ``CHECKIMAGE_NAME`` allow the user to provide a list
+ of check-image types and file names, respectively, to be produced by
+ |SExtractor|. A complete list of available check-image types is given in
+ 搂[chap:paramlist].
+* An |XML|_ file providing a processing summary and various statistics in
+ |VOTable|_ format is written if the ``WRITE_XML`` switch is set to ``Y``
+ (the default). The ``XML_NAME`` parameter can be used to change the default
+ file name :file:`sex.xml`. The |XML| file can be displayed with any recent
+ web browser; the |XSLT| stylesheet installed together with |SExtractor| will
+ automatically translate it into a dynamic, user-friendly web-page.
+ For more advanced usages (e.g., access from a
+ remote web server), alternative |XSLT| translation URLs may be specified
+ using the ``XSL_URL`` configuration parameter.
+
+
diff --git a/doc/src/Param.rst b/doc/src/Param.rst
index 9db6552..0a67f67 100644
--- a/doc/src/Param.rst
+++ b/doc/src/Param.rst
@@ -3,7 +3,7 @@
.. include:: global.rst
The measurement (or catalog) parameter file
-===========================================
+-------------------------------------------
In addition to the configuration file detailed above, |SExtractor| requires a file containing the list of measurements ("catalog parameters") that will be listed in the output catalog for every detection. This allows the software to compute only the measurements that are needed. The name of this catalog parameter file is traditionally suffixed with :file:`.param`, and must be specified using the :param:`PARAMETERS_NAME` config parameter. The full set of parameters can be queried with the command
@@ -12,7 +12,7 @@ In addition to the configuration file detailed above, |SExtractor| requires a fi
$ sex -dp
Format
-------
+~~~~~~
The format of the catalog parameter list is ASCII, and there must be
*a single keyword per line*. Presently two kinds of keywords are
@@ -23,7 +23,7 @@ in the output catalog is identical to that of the keywords in the parameter
list. Comments are allowed, they must begin with a :param:`#`.
Variants
---------
+~~~~~~~~
For many catalog parameters, especially those related to flux,
position, or shape, several variants of the same measurement are
@@ -32,7 +32,7 @@ available:
.. _fluxes_and_magnitudes:
Fluxes and magnitudes
-~~~~~~~~~~~~~~~~~~~~~
+"""""""""""""""""""""
Fluxes may be expressed in counts (|ADU|\ s) or as Pogson :cite:`1856MNRAS_17_12P` magnitudes.
Flux measurements in |ADU|\ s are prefixed with :param:`FLUX_`, for example: :param:`FLUX_AUTO`, :param:`FLUX_ISO`, etc.
@@ -48,7 +48,7 @@ The ``MAG_ZEROPOINT`` configuration parameter sets the magnitude zero-point of m
\end{array}\right.
Flux and magnitude uncertainties
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+""""""""""""""""""""""""""""""""
Flux uncertainties (error estimates) follow a scheme similar to that of fluxes.
They are prefixed with :param:`FLUXERR_`, as in :param:`FLUXERR_AUTO` or :param:`FLUXERR_ISO`.
@@ -64,7 +64,7 @@ They are computed using
\end{array}\right.
Pixel values and Surface brightnesses
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"""""""""""""""""""""""""""""""""""""
Pixel values (averaged or not) :math:`p` are expressed in counts (|ADU|\ s).
There is no specific prefix (:param:`THRESHOLD`, :param:`BACKGROUND`, :param:`FLUX_MAX`, etc.).
@@ -84,7 +84,7 @@ Setting ``PIXEL_SCALE`` to 0 instructs |SExtractor| to compute the pixel scale f
.. _coord_suffix:
Positions and shapes
-~~~~~~~~~~~~~~~~~~~~
+""""""""""""""""""""
Positions, distances and position angles are computed in pixel coordinates. They may be expressed in image pixels, world coordinates, or in celestial coordinates, depending on the suffix:
@@ -96,7 +96,7 @@ Positions, distances and position angles are computed in pixel coordinates. They
.. _world_coords:
:param:`_WORLD`
- Measurements are given in so-called 鈥渨orld coordinates鈥�, converted from pixel coordinates using the local Jacobian of the transformation between both systems. This requires |WCS| metadata :cite:`2002AA_395_1061G` to be present in the FITS image header(s). Position angles are counted from the first world axis, positive towards the second world axis.
+ Measurements are given in so-called 鈥渨orld coordinates鈥�, converted from pixel coordinates using the local Jacobian of the transformation between both systems. This requires |WCS|_ metadata :cite:`2002AA_395_1061G` to be present in the FITS image header(s). Position angles are counted from the first world axis, positive towards the second world axis.
.. _sky_coords:
@@ -111,8 +111,12 @@ Positions, distances and position angles are computed in pixel coordinates. They
.. note::
Conversion to :param:`_FOCAL` coordinates is available only for a limited subset of measurements.
+.. important::
+ The |WCS| library currently implemented in |SExtractor| is a customized version of an early implementation (v1.1.1) by Calabretta.
+ Several projections from later versions and alternative astrometric descriptions such as `AST <https://starlink.eao.hawaii.edu/starlink/AST>`_ or `that of original DSS plates <https://archive.stsci.edu/dss/booklet_n.pdf>`_ are not supported at this time.
+
Measurement parameter list
---------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~
Below is an exhaustive list of all the measurement parameters known to
|SExtractor|. Please refer to the next sections for a detailed description
diff --git a/doc/src/Using.rst b/doc/src/Using.rst
index 215b167..953b84e 100644
--- a/doc/src/Using.rst
+++ b/doc/src/Using.rst
@@ -11,34 +11,15 @@ Using SExtractor
.. code-block:: console
- $ sex Image1 [Image2] -c configuration-file [-Parameter1 Value1 -Parameter2 Value2 ...]
+ $ sex Image1 [Image2] -c configuration-file [-Parameter1 Value1 -Parameter2 Value2 ...]
The parts enclosed within brackets are optional.
-Any `-Parameter Value` statement in the command-line overrides the corresponding definition in the configuration-file or any default value (see below).
-
-Output files
-------------
-
-Diagnostic files
-~~~~~~~~~~~~~~~~
-
-Two types of files can be generated by |SExtractor|, providing diagnostics
-about the source extraction process:
-
-* "Check-images" are FITS files containing raster images such as maps of the
- background model, apertures, etc.. The configuration parameters
- ``CHECKIMAGE_TYPE`` and ``CHECKIMAGE_NAME`` allow the user to provide a list
- of check-image types and file names, respectively, to be produced by
- |SExtractor|. A complete list of available check-image types is given in
- 搂[chap:paramlist].
-* An |XML|_ file providing a processing summary and various statistics in
- |VOTable|_ format is written if the ``WRITE_XML`` switch is set to ``Y``
- (the default). The ``XML_NAME`` parameter can be used to change the default
- file name :file:`sex.xml`. The |XML| file can be displayed with any recent
- web browser; the |XSLT| stylesheet installed together with |SExtractor| will
- automatically translate it into a dynamic, user-friendly web-page.
- For more advanced usages (e.g., access from a
- remote web server), alternative |XSLT| translation URLs may be specified
- using the ``XSL_URL`` configuration parameter.
+Any `-Parameter Value` statement in the command-line overrides the corresponding definition in the configuration file or any default value (see :ref:`configuration section<config_file>`).
+.. toctree::
+
+ Input
+ Output
+ Config
+ Param
diff --git a/doc/src/index.rst b/doc/src/index.rst
index 9fba681..9eea3ba 100644
--- a/doc/src/index.rst
+++ b/doc/src/index.rst
@@ -17,8 +17,6 @@ Contents
License
Installing
Using
- Config
- Param
Background
Weighting
Flagging
diff --git a/doc/src/references.bib b/doc/src/references.bib
index 9ff01a2..ddebffb 100644
--- a/doc/src/references.bib
+++ b/doc/src/references.bib
@@ -363,6 +363,33 @@ month={Sep}
adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}
+@ARTICLE{1999AJ_117_68S,
+ author = {{Szalay}, A.~S. and {Connolly}, A.~J. and {Szokoly}, G.~P.},
+ title = "{Simultaneous Multicolor Detection of Faint Galaxies in the Hubble Deep Field}",
+ journal = {AJ},
+ eprint = {astro-ph/9811086},
+ keywords = {COSMOLOGY: OBSERVATIONS, GALAXIES: FUNDAMENTAL PARAMETERS, GALAXIES: PHOTOMETRY, TECHNIQUES: PHOTOMETRIC},
+ year = 1999,
+ month = jan,
+ volume = 117,
+ pages = {68-74},
+ doi = {10.1086/300689},
+ adsurl = {http://adsabs.harvard.edu/abs/1999AJ....117...68S},
+ adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+
+@ARTICLE{1981AAS_44_363W,
+ author = {{Wells}, D.~C. and {Greisen}, E.~W. and {Harten}, R.~H.},
+ title = "{FITS - a Flexible Image Transport System}",
+ journal = {A&AS},
+ year = 1981,
+ month = jun,
+ volume = 44,
+ pages = {363},
+ adsurl = {http://adsabs.harvard.edu/abs/1981A&AS...44..363W},
+ adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+
@ARTICLE{2001AJ_122_1104Y,
author = {{Yasuda}, N. and {Fukugita}, M. and {Narayanan}, V.~K. and {Lupton}, R.~H. and
{Strateva}, I. and {Strauss}, M.~A. and {Ivezi{\'c}}, {\v Z}. and
--
GitLab