Unverified Commit 99c3353a authored by Emmanuel Bertin's avatar Emmanuel Bertin Committed by GitHub
Browse files

Merge pull request #46 from astromatic/doc 

Update doc
parents 34c3c87c 752069af

doc/src/Background.rst

+14 −7
Original line number Diff line number Diff line
@@ -18,19 +18,26 @@ Background estimation 
To compute the background map, |SExtractor| makes a first pass through the pixel data, estimating the local background in each mesh of a rectangular grid that covers the whole frame.

The background estimator is a combination of :math:`\kappa\,\sigma` clipping and mode estimation, similar to Stetson’s |DAOPHOT|_ program :cite:`1987PASP_99_191S,1992ASPC_23_90D`.



Briefly, the local background histogram is clipped iteratively until convergence at :math:`\pm 3\sigma` around its median. The mode of the histogram is estimated using:

Briefly, the local background histogram is clipped iteratively until convergence at :math:`\pm 3\sigma` around its median. The mode of the histogram is estimated using the semi-empirical relation



.. math::

  :label: sexbackmode

  :label: ksbackmode



  \mbox{Mode} = 2.5 \times \mbox{Median} - 1.5 \times \mbox{Mean}.

  \mbox{Mode} - \mbox{Mean} \approx \alpha_{\rm{Pearson}} \times (\mbox{Median} - \mbox{Mean}),



Using simulated images, the expression above was found more accurate with clipped distributions :cite:`1996AAS_117_393B` than the usual approximation (e.g., :cite:`stuart2009kendall`):

and therefore



.. math::

  :label: ksbackmode

  :label: sexbackmode



  \mbox{Mode} \approx \alpha_{\rm{Pearson}} \times \mbox{Median} - (\alpha_{\rm{Pearson}} - 1) \times \mbox{Mean},



with :math:`\alpha_{\rm{Pearson}} \approx 3`  :cite:`1895RSTA_0010,1911AITS,stuart2009kendall`.



  \mbox{Mode} = 3 \times \mbox{Median} - 2 \times \mbox{Mean}.

Using simulated images, :cite:`1996AAS_117_393B` found :math:`\alpha_{\rm{Pearson}} \approx 2.5` more appropriate for determining the mode of the background histogram in |SExtractor|.

However, extensive photometric assessments carried out in the context of the `Dark Energy Survey <https://darkenergysurvey.org>`_ later showed that this value leads to a slight overestimation of the local background :cite:`2022ApJS_258_15E`, and a higher :math:`\alpha_{\rm{Pearson}} \approx 3.5` was adopted in |DES|.

Since |SExtractor| v2.28, :math:`\alpha_{\rm{Pearson}}` can be changed using the ``BACK_PEARSON`` configuration parameter.

However, for the sake of compatibility with previous results, the default value of ``BACK_PEARSON`` remains ``2.5``.



:numref:`fig_modevsmean` shows that the mode estimation in :eq:`sexbackmode` is considerably less affected by source crowding than a simple clipped mean :cite:`1981AJ_86_476J,1987AA_183_177I` but it is :math:`\approx 30\%` noisier. 

Obviously :eq:`sexbackmode` is not valid for any distribution; |SExtractor| falls back to a simple median for estimating the local background value if the mode and the median disagree by more than 30%.
@@ -56,7 +63,7 @@ In parallel with the making of the background map, an *RMS background map*, that 
It may be used as an internal weight map if the ``WEIGHT_TYPE`` configuration parameter is to ``BACKGROUND`` (see :ref:`weight-map_format`).



Configuration and tuning

------------------------

~~~~~~~~~~~~~~~~~~~~~~~~



.. note::

  All background configuration parameters also affect background-RMS maps.

doc/src/Model.rst

+2 −1
Original line number Diff line number Diff line
@@ -269,7 +269,7 @@ Model-based star-galaxy separation: :param:`SPREAD_MODEL` 
---------------------------------------------------------



The :param:`SPREAD_MODEL` estimator has been developed as a star/galaxy classifier for the DESDM pipeline :cite:`2012SPIE_8451E_0DM`, and has also been used in other surveys :cite:`2012ApJ_757_83D,2013AA_554A_101B`.

:param:`SPREAD_MODEL` indicates which of the best fitting local PSF model resampled at the current position :math:`\tilde{\boldsymbol{\phi}}` (representing a point source) or a slightly ``fuzzier'' resampled model :math:`\tilde{\boldsymbol{G}}` (representing a galaxy) matches best the image data.

:param:`SPREAD_MODEL` indicates which of the best fitting local PSF model resampled at the current position :math:`\tilde{\boldsymbol{\phi}}` (representing a point source) or a slightly "fuzzier" resampled model :math:`\tilde{\boldsymbol{G}}` (representing a galaxy) matches best the image data.

:math:`\tilde{\boldsymbol{G}}` is obtained by convolving the local PSF model with a circular exponential model with scalelength = 1/16 |FWHM|, and resampling the result at the current position on the pixel grid. :param:`SPREAD_MODEL` is normalized to allow comparing sources with different PSFs throughout the field:



.. math::
@@ -306,6 +306,7 @@ In order to maintain a certain level of purity or completeness across the whole 


.. math::

  :label: spreaderr_model

  :nowrap:



  \begin{eqnarray}

  {\tt SPREADERR\_MODEL} & = & \frac{1}{(\tilde{\boldsymbol{\phi}}^\mathsf{T} {\bf W}\,\boldsymbol{p})^2} \left((\tilde{\boldsymbol{G}}^\mathsf{T} {\bf V}\,\tilde{\boldsymbol{G}})\,(\tilde{\boldsymbol{\phi}}^\mathsf{T} {\bf W}\,\boldsymbol{p})^2\right.\nonumber \\

doc/src/Position.rst

+10 −0
Original line number Diff line number Diff line
@@ -27,6 +27,7 @@ These coordinates define two corners of a rectangle which encloses the detected 


.. math::

  :label: xminymax

  :nowrap:



   \begin{eqnarray}

   {\tt XMIN} & = & \min_{i \in {\cal S}} x_i,\\
@@ -47,6 +48,7 @@ Barycenter coordinates generally define the position of the “center” of a so 


.. math::

  :label: xy

  :nowrap:



   \begin{eqnarray}

   {\tt X} & = & \overline{x} = \frac{\displaystyle \sum_{i \in {\cal S}}
@@ -76,6 +78,7 @@ Second-order moments: :param:`X2`, :param:`Y2`, :param:`XY` 


.. math::

  :label: x2y2

  :nowrap:



   \begin{eqnarray}

   {\tt X2} & = \overline{x^2} = & \frac{\displaystyle \sum_{i \in {\cal S}} p^{(f)}_i x_i^2}{\displaystyle \sum_{i \in {\cal S}} p^{(f)}_i} - \overline{x}^2,\\
@@ -144,6 +147,7 @@ covariance :math:`\overline{xy}`. 


.. math::

  :label: aimage

  :nowrap:



   \begin{eqnarray}

   {\tt A}^2 & = & \overline{x^2}_{\tt THETA},\ \ \ {\rm and}\\
@@ -154,6 +158,7 @@ covariance :math:`\overline{xy}`. 


.. math::

  :label: aimage_2

  :nowrap:



   \begin{eqnarray}

   {\tt A}^2 & = & \frac{\overline{x^2}+\overline{y^2}}{2}
@@ -175,6 +180,7 @@ These parameters [#elongation]_ are directly derived from :param:`A` and :param: 


.. math::

  :label: elongation

  :nowrap:



   \begin{eqnarray}

   {\tt ELONGATION} & = & \frac{\tt A}{\tt B}\ \ \ \ \ \mbox{and}\\
@@ -206,6 +212,7 @@ parameters can be derived from the 2nd order moments: 


.. math::

  :label: ellipse_2

  :nowrap:



   \begin{eqnarray}

   {\tt CXX} & = & \frac{\cos^2 {\tt THETA}}{{\tt A}^2} + \frac{\sin^2
@@ -240,6 +247,7 @@ Furthermore, |SExtractor| does not currently take into account possible correlat 


.. math::

  :label: errxy

  :nowrap:



   \begin{eqnarray}

   {\tt ERRX2} & = {\rm var}(\overline{x}) =
@@ -261,6 +269,7 @@ where :math:`{\sigma_B}_i` is the local background noise and :math:`g_i` the loc 


.. math::

  :label: errabtheta

  :nowrap:



   \begin{eqnarray}

   {\tt ERRA}^2 & = & \frac{{\rm var}(\overline{x})+{\rm var}(\overline{y})}{2}
@@ -277,6 +286,7 @@ And the error ellipse parameters are: 


.. math::

  :label: errellipse

  :nowrap:



   \begin{eqnarray}

   {\tt ERRCXX} & = & \frac{\cos^2 {\tt ERRTHETA}}{{\tt ERRA}^2} +

doc/src/adsarxiv.py

0 → 100644
+221 −0
Original line number Diff line number Diff line 
"""

ADSArxiv PybTeX style

"""

# Copyright Emmanuel Bertin CFHT/CNRS/SorbonneU

# Licensed under GPL v3



from packaging import version as vers

from pybtex import __version__ as pybtex_version

from pybtex.style.formatting.unsrt import Style as UnsrtStyle, date, pages, toplevel

from pybtex.style.template import * # ... and anything else needed

from pybtex.plugin import register_plugin



pybtex_new_version = vers.parse(pybtex_version) >= vers.parse("0.22")



if pybtex_new_version:

    def _format_data(node, data):

        try:

            f = node.format_data

        except AttributeError:

            return node

        else:

            return f(data)





    def _format_list(list_, data):

        return (_format_data(part, data) for part in list_)



    @node

    def href2(children, data):

        parts = _format_list(children, data)

        if "http" in list(parts)[0]:

            parts = _format_list(children, data)

            return richtext.HRef(*parts)

        else:

            parts = _format_list(children, data)

            return richtext.Tag('strong', *parts)



class ADSArxivStyle(UnsrtStyle):



    if pybtex_new_version:

        def format_names(self, role, as_sentence=True):

            formatted_names = names(role, sep=', ', sep2 = ' and ', last_sep=', and ')

            if as_sentence:

                return sentence[ formatted_names ]

            else:

               return formatted_names



        def get_article_template(self, e):

            volume_and_pages = first_of[

            # volume and pages, with optional issue number

                optional[

                    join[

                        field('volume'),

                        optional[ '(', field('number'),')' ],

                        ':', pages

                    ],

                ],

                # pages only

                words[ 'pages', pages ],

            ]

            myurl = first_of[

                    optional_field('adsurl'),

                    optional[ join[ 'http://arxiv.org/abs/', field('eprint') ]],

                    optional_field('url'),

                    optional[ join ['http://dx.doi.org/', field('doi') ]]

            ]

            template = toplevel[

                sentence[ self.format_names('author', as_sentence=False), field('year') ],

                href2[ myurl, self.format_title(e, 'title') ],

                sentence(capfirst=False) [

                    tag('emph')[ field('journal') ],

                    optional[ volume_and_pages ]],

                sentence(capfirst=False) [ optional_field('note') ],

            ]

            return template



        def get_book_template(self, e):

            myurl = first_of[

                optional_field('adsurl'),

                optional[ join ['http://arxiv.org/abs/', field('eprint') ]],

                optional_field('url'),

                optional[ join ['http://dx.doi.org/', field('doi') ]]

            ]

            template = toplevel[

                self.format_author_or_editor(e),

                href2[ myurl, self.format_btitle(e, 'title') ],

                self.format_volume_and_series(e),

                sentence [

                    field('publisher'),

                    optional_field('address'),

                    self.format_edition(e),

                    date

                ],

                optional[ sentence [ self.format_isbn(e) ] ],

                sentence [ optional_field('note') ],

            ]

            return template



        def get_inproceedings_template(self, e):

            myurl = first_of[

                optional_field('adsurl'),

                optional[ join ['http://arxiv.org/abs/', field('eprint') ]],

                optional_field('url'),

                optional[ join ['http://dx.doi.org/', field('doi') ]]

            ]

            template = toplevel[

                sentence[ self.format_names('author', as_sentence=False), field('year') ],

                href2[ myurl, self.format_title(e, 'title') ],

                words[

                    'In',

                    sentence(capfirst=False)[

                        optional[ self.format_editor(e, as_sentence=False) ],

                        self.format_btitle(e, 'booktitle', as_sentence=False),

                        self.format_volume_and_series(e, as_sentence=False),

                        optional[ pages ],

                    ],

                    self.format_address_organization_publisher_date(e),

                ],

                sentence(capfirst=False)[ optional_field('note') ],

            ]

            return template



        def get_misc_template(self, e):

            myurl = first_of[

                    optional_field('adsurl'),

                    optional[ join ['http://arxiv.org/abs/', field('eprint') ]],

                    optional_field('url'),

                    optional[ join ['http://dx.doi.org/', field('doi') ]]

            ]

            template = toplevel[

                optional[ sentence[ self.format_names('author', as_sentence=False), optional [ field('year') ]]],

                optional[ href2[ myurl, self.format_title(e, 'title') ]],

                sentence[ optional[ field('howpublished') ]],

                sentence[ optional_field('note') ],

            ]

            return template

    else:



        def format_article(self, e):

            volume_and_pages = first_of [

            # volume and pages, with optional issue number

                optional [

                    join [

                        field('volume'),

                        optional['(', field('number'),')'],

                        ':', pages

                    ],

                ],

                # pages only

                words ['pages', pages],

            ]

            myurl = first_of [

                    optional_field('adsurl'),

                    optional [join ['http://arxiv.org/abs/'], field('eprint')],

                    optional_field('url'),

                    optional [join ['http://dx.doi.org/', field('doi')]]

            ]

            template = toplevel [

                self.format_names('author'),

                href [myurl, self.format_title(e, 'title')],

                sentence(capfirst=False) [

                    tag('emph') [field('journal')],

                    optional[ volume_and_pages ],

                    field('year')],

                sentence(capfirst=False) [ optional_field('note') ],

            ]

            return template.format_data(e)



        def format_book(self, e):

            myurl = first_of [

                optional_field('adsurl'),

                optional [join ['http://arxiv.org/abs/'], field('eprint')],

                optional_field('url'),

                optional [join ['http://dx.doi.org/', field('doi')]]

            ]

            template = toplevel [

                self.format_author_or_editor(e),

                href [myurl, self.format_btitle(e, 'title')] \

                    if len(myurl.format_data(e)) > 0 \

                    else tag('strong') [self.format_btitle(e, 'title')],

                self.format_volume_and_series(e),

                sentence [

                    field('publisher'),

                    optional_field('address'),

                    self.format_edition(e),

                    date

                ],

                optional[ sentence [ self.format_isbn(e) ] ],

                optional_field('note'),

            ]

            return template.format_data(e)



        def format_inproceedings(self, e):

            myurl = first_of [

                optional_field('adsurl'),

                optional [join ['http://arxiv.org/abs/', field('eprint')]],

                optional_field('url'),

                optional [join ['http://dx.doi.org/', field('doi')]]

            ]

            template = toplevel [

                sentence [self.format_names('author')],

                href [myurl, self.format_title(e, 'title')] \

                    if len(myurl.format_data(e)) > 0 \

                    else tag('strong') [self.format_title(e, 'title')],

                words [

                    'In',

                    sentence(capfirst=False) [

                        optional[ self.format_editor(e, as_sentence=False) ],

                        self.format_btitle(e, 'booktitle', as_sentence=False),

                        self.format_volume_and_series(e, as_sentence=False),

                        optional[ pages ],

                    ],

                    self.format_address_organization_publisher_date(e),

                ],

                sentence(capfirst=False) [ optional_field('note') ],

            ]

            return template.format_data(e)





register_plugin('pybtex.style.formatting', 'adsarxiv', ADSArxivStyle)

doc/src/conf.py

+32 −227

File changed.

Preview size limit exceeded, changes collapsed.