Foreground separation
=====================

Deterministic fitters
---------------------

The classical fitters in :mod:`ps_eor.fgfit` share a small interface:

.. code-block:: python

   from ps_eor import fgfit

   fitter = fgfit.PolyForegroundFit(
       deg=3,
       fit_type="power_poly",
   )
   result = fitter.run(data_cube, noise_cube)

   foreground = result.fit
   residual = result.sub

The fitted model and residual retain the input cube geometry, so they can be
passed directly to flagging or power-spectrum estimation.

``PolyForegroundFit``
   Fits each visibility independently with a polynomial, Bernstein
   polynomial, power polynomial, or power Bernstein model.

``PcaForegroundFit``
   Separates real and imaginary data using a fixed number of principal
   components. Its result also exposes the mixing representation and
   individual reconstructed components.

``GmcaForegroundFit``
   Uses Generalized Morphological Component Analysis, optionally with a
   frequency transform and polynomial smoothing of the reconstruction.

These methods are useful as inexpensive baselines and when one deterministic
subtraction is sufficient. Model order remains a scientific choice: an
over-flexible fit can remove signal, while an inflexible fit leaves foreground
power in the residual. Use signal injections to quantify that transfer.

ML-GPR
------

ML-GPR models foreground, systematic, noise, and 21-cm covariances jointly.
It returns posterior distributions of component reconstructions and power
spectra rather than one fitted subtraction. It also supports multi-epoch
models that distinguish shared from observation-dependent structure.

See the :doc:`ML-GPR user guide <ml_gpr/index>` for configuration, covariance
design, inference, and posterior products. The deterministic and
probabilistic interfaces are intentionally different because their result
contracts represent different levels of uncertainty.