Commit eb8119c8 authored by Emmanuel Bertin's avatar Emmanuel Bertin
Browse files

Doc: included in param.rst all currently described measurement parameters.

parent 3fa4ed00
Loading
Loading
Loading
Loading
+64 −8
Original line number Diff line number Diff line
@@ -91,10 +91,66 @@ of their meaning.
  EXT_NUMBER,..., FITS extension number
  _`FLUX_ISO`, count, :ref:`Isophotal flux <flux_iso_def>`
  _`FLUXERR_ISO`, count, :ref:`RMS error estimate for the isophotal flux <flux_iso_def>`
  _`MAG_ISO`, mag, :ref:`Isophotal magnitude<flux_iso_def>`
  _`MAGERR_ISO`, mag, :ref:`RMS error estimate for the isophotal magnitude<flux_iso_def>`
  _`MAG_ISO`, magnitude, :ref:`Isophotal magnitude <flux_iso_def>`
  _`MAGERR_ISO`, magnitude, :ref:`RMS error estimate for the isophotal magnitude <flux_iso_def>`
  _`FLUX_ISOCOR`, count, :ref:`Corrected isophotal flux <mag_isocor_def>`
  _`FLUXERR_ISOCOR`, count, :ref:`RMS error estimate for the corrected isophotal flux <mag_isocor_def>`
  _`MAG_ISOCOR`, mag, :ref:`Corrected isophotal magnitude<mag_isocor_def>`
  _`MAGERR_ISOCOR`, mag, :ref:`RMS error estimate for the corrected isophotal magnitude<mag_isocor_def>`
  _`MAG_ISOCOR`, magnitude, :ref:`Corrected isophotal magnitude <mag_isocor_def>`
  _`MAGERR_ISOCOR`, magnitude, :ref:`RMS error estimate for the corrected isophotal magnitude <mag_isocor_def>`
  _`FLUX_APER`, count, :ref:`Flux(es) within fixed circular aperture(s) <flux_aper_def>`
  _`FLUXERR_APER`, count, :ref:`RMS error estimate(s) for the flux(es) within fixed circular aperture(s) <flux_aper_def>`
  _`MAG_APER`, magnitude, :ref:`Circular aperture magnitude(s) <flux_aper_def>`
  _`MAGERR_APER`, magnitude, :ref:`RMS error estimate(s) for circular aperture magnitude(s) <flux_aper_def>`
  _`FLUX_AUTO`, count, :ref:`Kron-like automated aperture flux <flux_auto_def>`
  _`FLUXERR_AUTO`, count, :ref:`RMS error estimate for Kron-like automated aperture flux <flux_auto_def>`
  _`MAG_AUTO`, magnitude, :ref:`Kron-like automated aperture magnitude <flux_auto_def>`
  _`MAGERR_AUTO`, magnitude, :ref:`RMS error estimate for Kron-like automated aperture magnitude <flux_auto_def>`
  _`X_IMAGE`, pixel, :ref:`Isophotal image centroid along axis 1 (x) <pos_iso_def>`
  _`Y_IMAGE`, pixel, :ref:`Isophotal image centroid along axis 2 (y) <pos_iso_def>`
  _`ERRX2_IMAGE`, pixel\ :sup:`2`, :ref:`Estimated variance of isophotal image centroid x coordinate <poserr_iso_def>`
  _`ERRY2_IMAGE`, pixel\ :sup:`2`, :ref:`Estimated variance of isophotal image centroid y coordinate <poserr_iso_def>`
  _`ERRXY_IMAGE`, pixel\ :sup:`2`, :ref:`Estimated covariance of isophotal image centroid x and y coordinates <poserr_iso_def>`
  _`ERRA_IMAGE`, pixel, :ref:`Major axis of the isophotal image centroid error ellipse <poserr_iso_def>`
  _`ERRB_IMAGE`, pixel, :ref:`Minor axis of the isophotal image centroid error ellipse <poserr_iso_def>`
  _`ERRTHETA_IMAGE`, degree, :ref:`Position angle of the isophotal image centroid ellipse <poserr_iso_def>`
  _`ERRCXX_IMAGE`, pixel\ :sup:`-2`, :ref:`Isophotal image centroid Cxx error ellipse parameter <poserr_iso_def>`
  _`ERRCYY_IMAGE`, pixel\ :sup:`-2`, :ref:`Isophotal image centroid Cyy error ellipse parameter <poserr_iso_def>`
  _`ERRCXY_IMAGE`, pixel\ :sup:`-2`, :ref:`Isophotal image centroid Cxy error ellipse parameter <poserr_iso_def>`
  _`XPEAK_IMAGE`, pixel, :ref:`x coordinate of the brightest pixel <pospeak_def>`
  _`YPEAK_IMAGE`, pixel, :ref:`y coordinate of the brightest pixel <pospeak_def>`
  _`XMIN_IMAGE`, pixel, :ref:`Minimum x coordinate among detected pixels <xyminmax_def>`
  _`YMIN_IMAGE`, pixel, :ref:`Minimum y coordinate among detected pixels <xyminmax_def>`
  _`XMAX_IMAGE`, pixel, :ref:`Maximum x coordinate among detected pixels <xyminmax_def>`
  _`YMAX_IMAGE`, pixel, :ref:`Maximum y coordinate among detected pixels <xyminmax_def>`
  _`XWIN_IMAGE`, pixel, :ref:`x coordinate of windowed image centroid <pos_win_def>`
  _`YWIN_IMAGE`, pixel, :ref:`y coordinate of windowed image centroid <pos_win_def>`
  _`ERRX2WIN_IMAGE`, pixel\ :sup:`2`, :ref:`Estimated variance of windowed image centroid x coordinate <poserr_win_def>`
  _`ERRY2WIN_IMAGE`, pixel\ :sup:`2`, :ref:`Estimated variance of windowed image centroid y coordinate <poserr_win_def>`
  _`ERRXYWIN_IMAGE`, pixel\ :sup:`2`, :ref:`Estimated covariance of windowed image centroid x and y coordinates <poserr_win_def>`
  _`ERRAWIN_IMAGE`, pixel, :ref:`Major axis of the windowed image centroid error ellipse <poserr_win_def>`
  _`ERRBWIN_IMAGE`, pixel, :ref:`Minor axis of the windowed image centroid error ellipse <poserr_win_def>`
  _`ERRTHETAWIN_IMAGE`, degree, :ref:`Position angle of the windowed image centroid ellipse <poserr_win_def>`
  _`ERRCXXWIN_IMAGE`, pixel\ :sup:`-2`, :ref:`Windowed image centroid Cxx error ellipse parameter <poserr_win_def>`
  _`ERRCYYWIN_IMAGE`, pixel\ :sup:`-2`, :ref:`Windowed image centroid Cyy error ellipse parameter <poserr_win_def>`
  _`ERRCXYWIN_IMAGE`, pixel\ :sup:`-2`, :ref:`Windowed image centroid Cxy error ellipse parameter <poserr_win_def>`
  _`X2_IMAGE`, pixel\ :sup:`2`, :ref:`Isophotal image 2nd order central moment in x <moments_iso_def>`
  _`Y2_IMAGE`, pixel\ :sup:`2`, :ref:`Isophotal image 2nd order central moment in y <moments_iso_def>`
  _`XY_IMAGE`, pixel\ :sup:`2`, :ref:`Isophotal image 2nd order central cross-moment in xy <moments_iso_def>`
  _`A_IMAGE`, pixel, :ref:`Isophotal image major axis <shape_iso_def>`
  _`B_IMAGE`, pixel, :ref:`Isophotal image minor axis <shape_iso_def>`
  _`THETA_IMAGE`, degree, :ref:`Isophotal image position angle<shape_iso_def>`
  _`ELONGATION`, ..., :ref:`A_IMAGE / B_IMAGE <elong_iso_def>`
  _`ELLIPTICITY`, ..., :ref:`1 - B_IMAGE / A_IMAGE <elong_iso_def>`
  _`CXX_IMAGE`, pixel\ :sup:`-2`, :ref:`Isophotal image Cxx ellipse parameter <ellipse_iso_def>`
  _`CYY_IMAGE`, pixel\ :sup:`-2`, :ref:`Isophotal image Cyy ellipse parameter <ellipse_iso_def>`
  _`CXY_IMAGE`, pixel\ :sup:`-2`, :ref:`Isophotal image Cxy ellipse parameter <ellipse_iso_def>`
  _`X2WIN_IMAGE`, pixel\ :sup:`2`, :ref:`Windowed image 2nd order central moment in x <moments_win_def>`
  _`Y2WIN_IMAGE`, pixel\ :sup:`2`, :ref:`Windowed image 2nd order central moment in y <moments_win_def>`
  _`XYWIN_IMAGE`, pixel\ :sup:`2`, :ref:`Windowed image 2nd order central cross-moment in xy <moments_win_def>`
  _`CXXWIN_IMAGE`, pixel\ :sup:`-2`, :ref:`Windowed image Cxx ellipse parameter <ellipse_win_def>`
  _`CYYWIN_IMAGE`, pixel\ :sup:`-2`, :ref:`Windowed image Cyy ellipse parameter <ellipse_win_def>`
  _`CXYWIN_IMAGE`, pixel\ :sup:`-2`, :ref:`Windowed image Cxy ellipse parameter <ellipse_win_def>`
  _`AWIN_IMAGE`, pixel, :ref:`Windowed image major axis <shape_win_def>`
  _`BWIN_IMAGE`, pixel, :ref:`Windowed image minor axis <shape_win_def>`
  _`THETAWIN_IMAGE`, degree, :ref:`Windowed image position angle <shape_win_def>`
+24 −14
Original line number Diff line number Diff line
@@ -22,6 +22,7 @@ Magnitude uncertainties (error estimates) are computed using

   {\tt MAGERR} = \frac{2.5}{\ln 10}\frac{\tt FLUXERR}{\tt FLUX}


.. _flux_iso_def:

Isophotal flux
@@ -67,7 +68,8 @@ A “total” magnitude :param:`MAG_ISOCOR` estimate is then

Clearly this cheap correction works best with stars; and although it is shown to give tolerably accurate results with most disk galaxies, it fails with ellipticals because of the broader wings of their profiles.

.. flux_aper_def:

.. _flux_aper_def:

Fixed-aperture flux
-------------------
@@ -80,10 +82,13 @@ before measuring the flux within the aperture. If :param:`FLUX_APER` is provided
vector :param:`FLUX_APER[n]`, at least :math:`n` apertures must be
specified with ``PHOTOM_APERTURES``.

Automatic aperture magnitudes
-----------------------------

:param:`MAG_AUTO` provides an estimate of the “total magnitude” by integrating the source flux within an adaptively scaled aperture.
.. _flux_auto_def:

Automatic aperture flux
-----------------------

:param:`FLUX_AUTO` provides an estimate of the “total flux” by integrating pixel values within an adaptively scaled aperture.
|SExtractor|’s automatic aperture photometry routine is inspired by Kron’s “first moment” algorithm :cite:`1980ApJS_43_305K`.

#. An elliptical aperture is defined whose elongation :math:`\epsilon` and position angle :math:`\theta` are defined by second order moments of the object’s light distribution. The ellipse is scaled to :math:`R_{\rm max}.\sigma_{\rm iso}`
@@ -110,6 +115,7 @@ The user has full control over the parameters :math:`k` and :math:`R_{\rm min}`
   (see text). Only isolated galaxies (no blends) of the simulations
   have been considered. 

.. hint::
  Aperture magnitudes are sensitive to crowding.
  In |SExtractor| v1, :param:`MAG_AUTO` measurements were not very robust in that respect.
  It was therefore suggested to replace the aperture magnitude by the corrected-isophotal one when an object is too close to its neighbors (2 isophotal radii for instance).
@@ -119,9 +125,11 @@ The use of :param:`MAG_BEST` is now deprecated as :param:`MAG_AUTO` measurements
  The first improvement is a crude subtraction of all the neighbors that have been detected around the measured source (``MASK_TYPE BLANK`` option).
  The second improvement is an automatic correction of parts of the aperture that are suspected to be contaminated by a neighbor.
  This is done by mirroring the opposite, cleaner side of the measurement ellipse if available (``MASK_TYPE CORRECT`` option, which is also the default).
Figure [figphot] shows the mean loss of flux measured with isophotal (threshold :math:`= 24.4\ \mbox{\rm magnitude\,arsec}^{-2}`), corrected isophotal and automatic aperture photometries for simulated galaxy :math:`B_J` on a typical Schmidt-survey plate image. 

Figure [figphot] shows the mean loss of flux measured with isophotal (threshold 24.4 magnitude.arsec\ :sup:`-2`), corrected isophotal and automatic aperture photometry for simulated galaxies on a typical Schmidt-survey B\ :sub:`J` plate image.
The automatic adaptive aperture photometry leads to the lowest loss of flux.


Photographic photometry
-----------------------

@@ -140,6 +148,7 @@ where :math:`\gamma` (``MAG_GAMMA``) is the contrast index of the emulsion, :mat

One advantage of using a density-to-intensity transformation relative to the local sky background is that it corrects (to some extent) large-scale inhomogeneities in sensitivity (see :cite:`1996PhDT_68B` for details).


Magnitude uncertainties
-----------------------

@@ -167,6 +176,7 @@ Making the assumption that plate-noise is the major contributor to photometric e
where :math:`I(x,y)` is the contribution of pixel :math:`(x,y)` to the
total flux (Eq. [eq:dtoi]). ``GAIN`` is ignored in ``PHOTO`` mode.


Background
----------

+34 −16
Original line number Diff line number Diff line
@@ -2,8 +2,6 @@

.. include:: global.rst

.. _position_iso_def:

Position and shape parameters derived from the isophotal profile
================================================================

@@ -13,7 +11,11 @@ The following parameters are derived from the spatial distribution :math:`\cal S
  Unless otherwise noted, pixel values :math:`I_i` are taken from the (filtered) detection image.

.. 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 :param:`_WORLD`, :param:`_SKY, :param:`_J2000` or :param:`_B1950` for |WCS|_ coordinates (see :ref:`coord_suffix`).
  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`).


.. _xyminmax_def:

Limits: :param:`XMIN`, :param:`YMIN`, :param:`XMAX`, :param:`YMAX`
------------------------------------------------------------------
@@ -32,6 +34,9 @@ These coordinates define two corners of a rectangle which encloses the detected

where :math:`x_i` and :math:`y_i` are respectively the x-coordinate and y-coordinate of pixel :math:`i`.


.. _pos_iso_def:

Barycenter: :param:`X`, :param:`Y`
----------------------------------

@@ -49,11 +54,17 @@ Barycenter coordinates generally define the position of the “center” of a so

In practice, :math:`x_i` and :math:`y_i` are summed relative to :param:`XMIN` and :param:`YMIN` in order to reduce roundoff errors in the summing.


.. _pospeak_def:

Position of the peak: :param:`XPEAK`, :param:`YPEAK`
----------------------------------------------------

It is sometimes useful to have the position :param:`XPEAK`, :param:`YPEAK` of the pixel with maximum intensity in a detected object, for instance when working with likelihood maps, or when searching for artifacts. For better robustness, PEAK coordinates are computed on *filtered* profiles if available. On symmetrical profiles, PEAK positions and barycenters coincide within a fraction of pixel (:param:`XPEAK` and :param:`YPEAK` coordinates are quantized by steps of 1 pixel, hence :param:`XPEAK_IMAGE` and :param:`YPEAK_IMAGE` are integers). This is no longer true for skewed profiles, therefore a simple comparison between PEAK and barycenter coordinates can be used to identify asymmetrical objects on well-sampled images.


.. _moments_iso_def:

2nd order moments: :param:`X2`, :param:`Y2`, :param:`XY`
--------------------------------------------------------

@@ -76,6 +87,7 @@ These expressions are more subject to roundoff errors than if the 1st-order mome
2nd order moments to be computed in one pass.
Roundoff errors are however kept to a negligible value by measuring all positions relative here again to :param:`XMIN` and :param:`YMIN`.


.. _shape_iso_def:

Basic shape parameters: :param:`A`, :param:`B`, :param:`THETA`
@@ -153,6 +165,23 @@ covariance :math:`\overline{xy}`.
Note that :param:`A` and :param:`B` are exactly halves the :math:`a` and :math:`b` parameters computed by the COSMOS image analyser :cite:`1980SPIE_264_208S`.
Actually, :math:`a` and :math:`b` are defined in :cite:`1980SPIE_264_208S` as the semi-major and semi-minor axes of an elliptical shape with constant surface brightness, which would have the same 2nd-order moments as the analyzed object.


.. _elong_iso_def:

By-products of shape parameters: :param:`ELONGATION` and :param:`ELLIPTICITY`
-----------------------------------------------------------------------------

These parameters [#elongation]_ are directly derived from :param:`A` and :param:`B`:

.. math::
  :label: elongation

   \begin{aligned}
   {\tt ELONGATION} & = & \frac{\tt A}{\tt B}\ \ \ \ \ \mbox{and}\\
   {\tt ELLIPTICITY} & = & 1 - \frac{\tt B}{\tt A}.
   \end{aligned}


.. _ellipse_iso_def:

Ellipse parameters: :param:`CXX`, :param:`CYY`, :param:`CXY`
@@ -197,20 +226,8 @@ parameters can be derived from the 2nd order moments:

   Meaning of shape parameters.

By-products of shape parameters: :param:`ELONGATION` and :param:`ELLIPTICITY`
-----------------------------------------------------------------------------

These parameters [#elongation]_ are directly derived from :param:`A` and :param:`B`:

.. math::
  :label: elongation

   \begin{aligned}
   {\tt ELONGATION} & = & \frac{\tt A}{\tt B}\ \ \ \ \ \mbox{and}\\
   {\tt ELLIPTICITY} & = & 1 - \frac{\tt B}{\tt A}.
   \end{aligned}

.. _poserr:
.. _poserr_iso_def:

Position uncertainties: :param:`ERRX2`, :param:`ERRY2`, :param:`ERRXY`, :param:`ERRA`, :param:`ERRB`, :param:`ERRTHETA`, :param:`ERRCXX`, :param:`ERRCYY`, :param:`ERRCXY`
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------
@@ -276,6 +293,7 @@ And the error ellipse parameters are:
   {\rm cov}^2(\overline{x},\overline{y})}.
   \end{aligned}


Handling of “infinitely thin” detections
----------------------------------------

+13 −5
Original line number Diff line number Diff line
@@ -6,7 +6,7 @@ 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_def>`:
of the measurements described in the :ref:`previous section<pos_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 :param:`_WORLD`, :param:`_SKY`, :param:`_J2000` or :param:`_B1950` for |WCS|_ coordinates (see :ref:`coord_suffix`).
@@ -30,7 +30,7 @@ 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:
.. _pos_win_def:

Windowed centroid: :param:`XWIN`, :param:`YWIN`
-----------------------------------------------
@@ -86,10 +86,12 @@ It has been verified that for isolated objects with Gaussian-like profiles, thei
   *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.

.. _moments_win_def:

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:
Windowed second-order moments are computed on the image data once the :ref:`centering process <pos_win_def>` has converged:

.. math::
  :label: x2y2win
@@ -108,6 +110,8 @@ Windowed second-order moments are computed on the image data once the :ref:`cent

Windowed second-order moments are typically twice smaller than their isophotal equivalent.

.. _shape_win_def:

Windowed shape parameters: :param:`AWIN`, :param:`BWIN`, :param:`THETAWIN`
--------------------------------------------------------------------------

@@ -126,6 +130,8 @@ way as in :eq:`theta0_3` and :eq:`aimage_2` from the :ref:`isophotal shape param
   \end{aligned}


.. _ellipse_win_def:

Windowed ellipse parameters: :param:`CXXWIN`, :param:`CYYWIN`, :param:`CXYWIN`
------------------------------------------------------------------------------

@@ -146,10 +152,12 @@ Ellipse parameters are computed from the windowed 2nd order moments exactly the
   \frac{\overline{xy_{\tt WIN}}}{\overline{x_{\tt WIN}^2} \overline{y_{\tt WIN}^2} - \overline{xy_{\tt WIN}}^2}.
   \end{aligned}

.. _poserr_win_def:

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.
Windowed position uncertainties are computed on the image data once the centering process of the :ref:`windowed centroid <pos_win_def>` has converged.
Assuming that noise is uncorrelated among pixels, standard error propagation applied to :eq:`xywin` writes:

.. math::
@@ -168,7 +176,7 @@ Assuming that noise is uncorrelated among pixels, standard error propagation app
   {\left(\sum_{r_i < r_{\rm max}} w_i I_i\right)^2}.
   \end{aligned}

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>`:
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_iso_def>`:

.. math::
  :label: errabthetawin