Spherical and wide-field analysis
=================================

When to use spherical cubes
---------------------------

The Cartesian visibility representation uses a flat-sky geometry. For a large
field of view, :mod:`ps_eor.sphcube` provides the corresponding HEALPix and
spherical-harmonic representations:

``SphImageCube``
   Frequency-dependent HEALPix maps shaped
   ``(n_frequencies, 12 * nside**2)``.

``SphDataCube``
   Complex spherical-harmonic coefficients shaped
   ``(n_frequencies, n_modes)`` with matching ``(ell, m)`` coordinates. The
   transverse coordinate used by the power-spectrum code is
   ``u = ell / (2 pi)``.

Converting Cartesian data
-------------------------

A Cartesian cube can be reprojected and transformed to spherical harmonics:

.. code-block:: python

   from ps_eor import sphcube

   alm_cube = sphcube.SphDataCube.from_cartcube(
       cart_cube,
       nside=128,
       lmax=600,
   )
   alm_cube.filter_lm(lmin=20, lmax=500)
   alm_cube.save("spherical-visibilities.h5")

The image transform is useful for inspection:

.. code-block:: python

   sky_cube = alm_cube.image(
       mask_corrected=True,
       mask_correction_threshold=0.1,
   )
   sky_cube.plot(fmhz="med")

Mask correction divides by the recorded sky window only where its response
exceeds the selected threshold. It can amplify noise near the mask boundary,
so it should be used for inspection with an explicit threshold rather than
treated as an unrestricted inverse.

Combining and estimating power
------------------------------

:class:`~ps_eor.sphcube.SphDataCubeCombiner` forms a weighted mean of
observations on a common harmonic grid and their shared frequency channels.
As with Cartesian data, most ``filter_*`` methods modify a spherical cube in
place.

The same :class:`~ps_eor.pspec.PowerSpectraBuilder` used for Cartesian data
detects a spherical cube and returns the spherical-geometry estimator:

.. code-block:: python

   from ps_eor import pspec

   ps_gen = pspec.PowerSpectraBuilder(config).get(alm_cube)
   products = ps_gen.get_all(kbins, alm_cube)

This keeps the public power-spectrum workflow consistent while using the
appropriate angular normalization internally.