.. _literature_completeness:

Survey Completeness
===================

This page collects the key references for the completeness scan estimator
implemented in :func:`~sum_stat.completeness_scan`.

----

The Johnston–Teodoro–Hendry series
------------------------------------

Three companion papers develop the Tc/Tv completeness scan:

.. list-table::
   :header-rows: 1
   :widths: 10 50 40

   * - Paper
     - Citation
     - Key contribution
   * - I
     - `Johnston, Teodoro & Hendry (2007)
       <https://ui.adsabs.harvard.edu/abs/2007MNRAS.376.1757J>`_,
       MNRAS 376, 1757
       (`arXiv:astro-ph/0703040 <https://arxiv.org/abs/astro-ph/0703040>`_)
     - Extended Rauzy (2001) Tc/Tv to account for a **bright magnitude limit**
       in addition to the faint limit; introduced the full **scan of m\*** so
       that Tc(m\*) and Tv(m\*) are computed as functions of the completeness
       threshold rather than as single numbers.  Demonstrated on MGC, SDSS, and
       2dFGRS — the original Rauzy formulation (faint limit only) gives spurious
       results for surveys with a non-negligible bright cut.
   * - II
     - `Teodoro, Johnston & Hendry (2010)
       <https://ui.adsabs.harvard.edu/abs/2010MNRAS.405.1187T>`_,
       MNRAS 405, 1187
       (`arXiv:1005.3888 <https://arxiv.org/abs/1005.3888>`_)
     - **Adaptive S/N smoothing**: instead of a fixed magnitude-redshift grid,
       the bin widths are adjusted dynamically so that each scan point contains
       the same information content (constant S/N = sqrt(N_bin)).  Prevents
       shot-noise artefacts in sparse regions and false completeness detections.
       Survey-specific calibration is required; SDSS, MGC, and 2dFGRS thresholds
       are provided.
   * - III
     - `Johnston, Teodoro & Hendry (2012)
       <https://ui.adsabs.harvard.edu/abs/2012MNRAS.421..270J>`_,
       MNRAS 421, 270
       (`arXiv:1107.0858 <https://arxiv.org/abs/1107.0858>`_)
     - Full **error propagation** for Tc and Tv; catalogue of characteristic
       incompleteness signatures (a drop in Tc/Tv followed by a peak at fainter
       magnitudes indicates missing objects in the affected range;
       over-completeness shows the opposite pattern).  Framework extended to
       constrain pure luminosity evolution without assuming a parametric LF shape.

----

Background: Rauzy (2001)
--------------------------

`Rauzy (2001) <https://ui.adsabs.harvard.edu/abs/2001MNRAS.324...51R>`_,
MNRAS 324, 51, introduced the ζ rank variable and the original Tc statistic
(single faint-limit only).  The Johnston–Teodoro–Hendry series builds directly
on this foundation.  The original single-threshold test is available as
:func:`~sum_stat.lf_smf.independence.rauzy_completeness`.

----

Method summary
--------------

For a flux-limited survey with faint limit m_lim and optional bright limit
m_bright, the completeness scan proceeds as follows.

For each test threshold m\*:

1. Select the subsample S(m\*) = {galaxies with m_bright ≤ m_app ≤ m\*}.
2. For each galaxy i in S(m\*), form the associated set:

   .. math::

      J_i = \{j \mid z_j \le z_i
               \;\text{and}\;
               M_j \le m^* - \mu(z_i)
               \;\text{and}\;
               M_j \ge m_\mathrm{bright} - \mu(z_i)\}

   where μ(z) is the distance modulus.  The bright-limit condition is omitted
   when m_bright is not specified.

3. Compute the rank variable and ζ statistic (Rauzy 2001):

   .. math::

      R_i = \bigl|\{j \in J_i : M_j \le M_i\}\bigr|,
      \qquad
      \zeta_i = \frac{R_i}{|J_i| + 1} \in (0, 1)

   Under the null hypothesis of a complete sample, ζ_i ~ Uniform(0, 1).

4. Compute the standardised statistics:

   .. math::

      T_c(m^*) = \frac{\bar{\zeta} - 0.5}{\sqrt{1/(12n)}},
      \qquad
      T_v(m^*) = \frac{s^2_\zeta - 1/12}{\sqrt{1/(80n)}}

   where :math:`n = |S(m^*)|` and both statistics are asymptotically N(0, 1) under H₀.

Significant **negative** Tc or Tv at threshold m\* indicates that the sample
is missing galaxies fainter than m\* (incompleteness).  The adaptive S/N
smoothing (Paper II) replaces the cumulative scan with a sliding window of
N_target galaxies to maintain constant detection sensitivity.

----

See also
--------

* :func:`~sum_stat.completeness_scan` — public API.
* :func:`~sum_stat.lf_smf.independence.rauzy_completeness` — single-threshold Rauzy test.
* :func:`~sum_stat.lf_smf.independence.efron_petrosian_tau` — Efron–Petrosian τ test.
* :ref:`literature_lf` — luminosity function measurements.
* :ref:`literature_smf` — stellar mass function measurements.