healpix_analyse.resample
========================

.. py:module:: healpix_analyse.resample

.. autoapi-nested-parse::

   Resampling helpers for HEALPix and regular latitude/longitude grids.



Classes
-------

.. autoapisummary::

   healpix_analyse.resample.HealPixResampler


Functions
---------

.. autoapisummary::

   healpix_analyse.resample.resample_healpix
   healpix_analyse.resample.resample_to_latlon_grid


Module Contents
---------------

.. py:class:: HealPixResampler(in_level: int, out_level: int, in_cell_ids=None, out_cell_ids=None, *, ellipsoid: str = 'WGS84', radius_deg: Optional[float] = None, sigma_deg: Optional[float] = None, weight_norm: str = 'l1', up_norm: str = 'col_l1', dtype: torch.dtype = torch.float32, device: Optional[Union[str, torch.device]] = None, eps: float = 1e-12)

   Bases: :py:obj:`torch.nn.Module`


   Reusable NESTED HEALPix resampler based on ``HealPixDown``/``Up``.

   :Parameters: * **in_level, out_level** (:py:class:`int`) -- Input and output Grid4Earth/HEALPix levels.  The corresponding NSIDE
                  values are ``2**in_level`` and ``2**out_level``.
                * **in_cell_ids** (:py:class:`array-like`, *optional*) -- NESTED identifiers matching the last dimension of the input data.
                  ``None`` means that the input is a complete sphere in canonical
                  NESTED order.  ``in_level`` is still mandatory.
                * **out_cell_ids** (:py:class:`array-like`, *optional*) -- Exact output cells, in the desired output order.  ``None`` requests
                  the complete output sphere in canonical NESTED order.
                * **ellipsoid** (:py:class:`str`, *default* ``"WGS84"``) -- Geometry passed to every Down/Up operator.
                * **radius_deg, sigma_deg** (:py:class:`float`, *optional*) -- Optional fixed Gaussian parameters passed to each resolution step.
                  When omitted, every step uses its native resolution-dependent values.
                * **weight_norm** (``{"l1", "l2", "none"}``, *default* ``"l1"``) -- Normalisation used by ``HealPixDown``.
                * **up_norm** (``{"adjoint", "col_l1", "diag_l2"}``, *default* ``"col_l1"``) -- Normalisation used by ``HealPixUp``.
                * **dtype, device** (**optional**) -- PyTorch computation options.  CUDA is selected when available.

   .. admonition:: Notes

      Data may have shape ``[..., N_in]``.  NumPy input returns NumPy output;
      Torch input remains differentiable and returns a tensor on ``device``.
      
      Missing or non-finite samples are excluded through normalised convolution.
      A target with at least one non-zero weighted support remains calculable;
      a target with no support is filled with NaN.
      
      Upsampling a requested subset first maps every requested output cell to its
      NESTED ancestor at ``in_level``.  Only available ancestors and their full
      descendant trees are propagated, after which the exact requested cells are
      gathered in their original order.


   .. py:attribute:: in_level


   .. py:attribute:: out_level


   .. py:attribute:: dtype
      :value: Ellipsis



   .. py:attribute:: eps


   .. py:attribute:: ellipsoid
      :value: ''



   .. py:attribute:: weight_norm
      :value: ''



   .. py:attribute:: up_norm
      :value: ''



   .. py:attribute:: input_full_sphere


   .. py:attribute:: output_full_sphere


   .. py:attribute:: n_input


   .. py:attribute:: n_output


   .. py:attribute:: layers


   .. py:attribute:: empty_route
      :value: False



   .. py:property:: device
      :type: torch.device



   .. py:property:: in_cell_ids
      :type: Optional[numpy.ndarray]


      Input identifiers, or ``None`` for a full-sphere input.


   .. py:property:: out_cell_ids
      :type: numpy.ndarray


      Exact output identifiers in returned-data order.


   .. py:method:: forward(in_data: ArrayLike) -> tuple[ArrayLike, numpy.ndarray]

      Resample data and return ``(out_data, out_cell_ids)``.



   .. py:method:: compute(in_data: ArrayLike) -> tuple[ArrayLike, numpy.ndarray]

      Alias for :meth:`forward`.



   .. py:method:: extra_repr() -> str

      Return the extra representation of the module.

      To print customized extra information, you should re-implement
      this method in your own modules. Both single-line and multi-line
      strings are acceptable.



.. py:function:: resample_healpix(in_data: ArrayLike, *, in_level: int, out_level: int, in_cell_ids=None, out_cell_ids=None, ellipsoid: str = 'WGS84', radius_deg: Optional[float] = None, sigma_deg: Optional[float] = None, weight_norm: str = 'l1', up_norm: str = 'col_l1', dtype: torch.dtype = torch.float32, device: Optional[Union[str, torch.device]] = None, eps: float = 1e-12) -> tuple[ArrayLike, numpy.ndarray]

   One-shot NESTED HEALPix resampling convenience function.

   Construct :class:`HealPixResampler` directly when several maps share the
   same input/output geometry, so the sparse operators can be reused.


.. py:function:: resample_to_latlon_grid(lat, lon, data, method='linear')

   Resample HEALPix data onto a regular latitude/longitude grid.