.. _development-estimators:

Estimators in development
==========================

.. warning::

   All estimators on this page are **not production-ready**.  Results have not
   been validated against published reference data.  APIs and output formats
   may change without notice.  Do not use them for scientific analysis.

   The four stable estimators are: **SMF**, **w**\ :sub:`p`\ **(r**\ :sub:`p`\ **)**,
   **w(θ)**, and **ΔΣ(r**\ :sub:`p`\ **)**.  See :ref:`overview` for a complete
   maturity table.

.. contents:: Contents
   :local:
   :depth: 1

----

Luminosity function — LF φ(M)
------------------------------

**Module**: :mod:`sum_stat.lf_smf` (shared with SMF)

**Estimators**: 1/Vmax (:func:`~sum_stat.luminosity_function_vmax`),
SWML (:func:`~sum_stat.lf_smf.swml.luminosity_function_swml`),
C⁻ (:func:`~sum_stat.lf_smf.cminus.cumulative_luminosity_function_cminus`)

**Current status**: The LF estimators are implemented and the code compiles
and runs.  They share the mathematical framework with the validated SMF
estimators.  The gap is a completed, automated validation against published LF
measurements (e.g., COSMOS2015 from Ilbert+ 2013, GAMA from Loveday+ 2015).

**What is needed before promotion to stable**:

- Automated comparison against COSMOS LF in ``≥ 2`` redshift bins, Δφ/φ < 10%.
- Automated comparison against GAMA r-band LF, Δφ/φ < 10%.
- Recovered Schechter α and M★ within 1σ from mock LF catalogues using
  1/Vmax, SWML, and C⁻.

**Relevant script**: ``scripts/measure_joint_sumstat.py --stats LF``

----

3D correlation function — ξ(r)
--------------------------------

**Module**: :mod:`sum_stat.twopcf` (:func:`~sum_stat.xi_r`)

**Current status**: Implemented on top of treecorr (Landy-Szalay).  Outputs
shape-verified.  Not validated against any published ξ(r) measurement.

**What is needed before promotion to stable**:

- Recovery of a known power-law ξ(r) from a Poisson-sampled mock in a
  periodic box, to < 5% on scales 1–30 Mpc.
- Comparison against a published ξ(r) measurement (e.g., BOSS LOWZ).

----

Redshift-space multipoles — ξ\ :sub:`ℓ`\ (s)
----------------------------------------------

**Module**: :mod:`sum_stat.twopcf` (:func:`~sum_stat.xi_multipoles`)

**Current status**: Implemented (treecorr pair counts + JAX Legendre
decomposition).  Monopole–quadrupole ratio verified against linear theory
at large scales in a single test.

**What is needed before promotion to stable**:

- Recovery of monopole + quadrupole from an N-body snapshot with known RSD
  parameter β = f/b, to < 10%.
- Comparison against a published ξ\ :sub:`ℓ`\ (s) from BOSS or eBOSS.

----

Angular power spectrum — C\ :sub:`ℓ`
--------------------------------------

**Module**: :mod:`sum_stat.powspec` (:func:`~sum_stat.cl_angular`)

**Current status**: Implemented with healpy pseudo-C\ :sub:`ℓ`.  Output
shape and unit verified.  No validation run.

**What is needed before promotion to stable**:

- Recovery of a known C\ :sub:`ℓ` from a Gaussian random field realisation,
  fractional error < 5% for ℓ = 10–500.

----

3D power spectrum — P\ :sub:`ℓ`\ (k)
---------------------------------------

**Module**: :mod:`sum_stat.powspec` (:func:`~sum_stat.pk3d`,
:func:`~sum_stat.pk_multipoles`)

**Current status**: Implemented with JAX FFT (FKP-weighted).  Verified
against known P(k) from a Gaussian random field at the 10% level.  Not yet
compared to a published measurement.

**What is needed before promotion to stable**:

- End-to-end recovery of a ΛCDM P(k) from an N-body snapshot, within 5%
  on scales k = 0.05–0.5 h/Mpc.
- Comparison against a published P(k) (e.g., BOSS DR12).

----

kNN cumulative distribution — F\ :sub:`k`\ (r)
------------------------------------------------

**Module**: :mod:`sum_stat.knn` (:func:`~sum_stat.knn_cdf`,
:func:`~sum_stat.cross_knn_cdf`, :func:`~sum_stat.knn_volume_map`)

**Current status**: Implemented with pyfnntw (Rust kd-tree) + JAX.
Unit tests pass (output shape, monotonicity, Poisson limit).  Not yet run on
any galaxy survey or simulation catalogue.

**What is needed before promotion to stable**:

- Recovery of the Poisson kNN-CDF from a uniform random catalogue, residual
  < 1%.
- Measurement on an Uchuu HOD mock and comparison against the Banerjee & Abel
  (2021) reference curves.

----

Redshift distributions — n(z)
-------------------------------

**Module**: :mod:`sum_stat.nz` (:func:`~sum_stat.nz.nz_histogram`,
:func:`~sum_stat.nz.nz_kde`)

**Current status**: Histogram and KDE wrappers implemented and tested.
Used internally by the lensing pipeline.  Not documented or validated as a
stand-alone product.

**What is needed before promotion to stable**:

- Formal API stabilisation (bin-centre convention, normalisation).
- Integration into the joint output HDF5 schema.

----

.. seealso::

   :doc:`bibliography` — full reference list for all estimators and surveys,
   with ADS links.