healpix_analyse.neighbour_reduce ================================ .. py:module:: healpix_analyse.neighbour_reduce .. autoapi-nested-parse:: Generic neighbourhood reductions for nested HEALPix fields. This module provides local, unweighted reductions over geometrically defined HEALPix neighbourhoods. Neighbourhood geometry is shared with :mod:`healpix_analyse.morphology`. In particular, the two supported neighbourhood definitions are: ``cell_center`` Include cells whose centres lie within ``radius_m`` metres of the target-cell centre. ``cone_coverage`` Include cells intersecting the circular coverage region returned by :func:`healpix_geo.nested.cone_coverage`. The public API supports both NumPy arrays and PyTorch tensors. Domain semantics ---------------- ``cell_ids`` identifies all HEALPix cells for which input values are available. ``domain`` identifies the valid processing/output domain. If ``domain is None``, the processing domain is exactly ``cell_ids``. If ``domain`` is supplied, every domain cell must occur in ``cell_ids``:: domain subset_of cell_ids Only cells belonging to ``domain`` participate in a reduction. A cell that is geometrically inside a neighbourhood but outside ``domain`` is not treated as zero, False, NaN, or any other padding value. It is simply absent from the effective neighbourhood. The output order follows ``domain`` exactly when it is supplied, and ``cell_ids`` otherwise. Classes ------- .. autoapisummary:: healpix_analyse.neighbour_reduce.HealPixNeighbourReducer Functions --------- .. autoapisummary:: healpix_analyse.neighbour_reduce.neighbour_reduce healpix_analyse.neighbour_reduce.median_filter healpix_analyse.neighbour_reduce.mean_filter healpix_analyse.neighbour_reduce.min_filter healpix_analyse.neighbour_reduce.max_filter Module Contents --------------- .. py:class:: HealPixNeighbourReducer(cell_ids, refinement_level: int, *, radius_m: float, domain=None, neighbourhood: healpix_analyse._neighbourhood.NeighbourhoodMethod = 'cell_center', include_self: bool = True, ellipsoid: str = 'WGS84') Reusable HEALPix neighbourhood-reduction operator. Geometry is constructed once during initialisation and can then be reused for multiple fields sharing the same ``cell_ids`` and processing ``domain``. :Parameters: * **cell_ids** -- One-dimensional array of unique NESTED HEALPix cell IDs for which input values are available. Input order is preserved and defines the relationship between ``cell_ids`` and the last dimension of ``values``. * **refinement_level** -- HEALPix refinement level, between 0 and 29. * **radius_m** -- Physical neighbourhood radius in metres. * **domain** -- Optional processing/output domain. If ``None``, all cells in ``cell_ids`` form the processing domain. If supplied, every cell in ``domain`` must also occur in ``cell_ids``. Cells outside ``domain`` never participate in a reduction, even when they lie geometrically within ``radius_m`` and have an available value in ``values``. Output ordering follows ``domain`` exactly. * **neighbourhood** -- HEALPix neighbourhood definition. ``"cell_center"`` Include HEALPix cells whose centres are within ``radius_m`` metres of the target-cell centre. ``"cone_coverage"`` Include cells intersecting the circular coverage region used by ``healpix_geo.nested.cone_coverage``. * **include_self** -- Whether the target cell participates in its own reduction. Defaults to ``True``. * **ellipsoid** -- Reference ellipsoid used by the shared morphology geometry. Defaults to ``"WGS84"``. .. admonition:: Notes Near a partial-domain boundary, the number of contributing samples can decrease because cells outside ``domain`` are excluded rather than padded with artificial values. .. py:attribute:: refinement_level .. py:attribute:: radius_m .. py:attribute:: neighbourhood :value: 'cell_center' .. py:attribute:: include_self :value: True .. py:attribute:: ellipsoid :value: 'WGS84' .. py:attribute:: cell_ids .. py:property:: output_cell_ids :type: numpy.ndarray Return output HEALPix IDs in exact output order. .. py:function:: neighbour_reduce(values: ArrayLike, cell_ids, refinement_level: int, *, radius_m: float, reduction: Reduction = 'mean', domain=None, neighbourhood: healpix_analyse._neighbourhood.NeighbourhoodMethod = 'cell_center', include_self: bool = True, ellipsoid: str = 'WGS84') -> ArrayLike Reduce field values over local HEALPix neighbourhoods. :Parameters: * **values** -- NumPy array or PyTorch tensor. The last dimension is aligned one-to-one with ``cell_ids``. Arbitrary leading dimensions are supported. * **cell_ids** -- One-dimensional array of unique NESTED HEALPix cell IDs for which input values are available. The order of ``cell_ids`` is preserved. * **refinement_level** -- HEALPix refinement level, between 0 and 29. * **radius_m** -- Physical neighbourhood radius in metres. * **reduction** -- Reduction applied to each effective local neighbourhood. Supported values are ``"mean"``, ``"sum"``, ``"min"``, ``"max"``, ``"median"``, ``"count"``, ``"std"``, ``"any"``, ``"all"``, and ``"mode"``. * **domain** -- Optional processing/output domain. If ``None``, all cells in ``cell_ids`` form the domain. If provided, ``domain`` must be a subset of ``cell_ids``. The output contains one value per domain cell and follows the exact order of ``domain``. Cells outside ``domain`` never participate in a reduction, even when they lie geometrically within ``radius_m`` and have an input value in ``values``. Such cells are not zero-padded or assigned another synthetic value. They are simply absent from the effective neighbourhood. * **neighbourhood** -- Definition of the HEALPix neighbourhood. ``"cell_center"`` Include cells whose centres are within ``radius_m`` metres of the target-cell centre. ``"cone_coverage"`` Include cells intersecting the corresponding circular coverage region. * **include_self** -- Whether the target cell participates in its own reduction. Defaults to ``True``. * **ellipsoid** -- Reference ellipsoid used for physical-distance calculations. Defaults to ``"WGS84"``. :returns: :py:class:`numpy.ndarray` or :py:class:`torch.Tensor` -- Reduced values. The backend follows ``values``. The final dimension follows ``domain`` when explicitly supplied and ``cell_ids`` otherwise. .. admonition:: Notes Near a partial-domain boundary, the effective neighbourhood can contain fewer samples because cells outside the processing domain are excluded rather than padded. Numerical ``median`` and categorical ``mode`` are intentionally different operations. For an even number of numerical samples, ``median`` averages the two central sorted values. Empty effective neighbourhoods have the following identities: - ``sum`` -> 0 - ``count`` -> 0 - ``any`` -> False - ``all`` -> True Other reductions raise ``ValueError`` on an empty effective neighbourhood. .. py:function:: median_filter(values: ArrayLike, cell_ids, refinement_level: int, *, radius_m: float, domain=None, neighbourhood: healpix_analyse._neighbourhood.NeighbourhoodMethod = 'cell_center', include_self: bool = True, ellipsoid: str = 'WGS84') -> ArrayLike Apply a numerical median over HEALPix neighbourhoods. .. py:function:: mean_filter(values: ArrayLike, cell_ids, refinement_level: int, *, radius_m: float, domain=None, neighbourhood: healpix_analyse._neighbourhood.NeighbourhoodMethod = 'cell_center', include_self: bool = True, ellipsoid: str = 'WGS84') -> ArrayLike Apply a mean over HEALPix neighbourhoods. .. py:function:: min_filter(values: ArrayLike, cell_ids, refinement_level: int, *, radius_m: float, domain=None, neighbourhood: healpix_analyse._neighbourhood.NeighbourhoodMethod = 'cell_center', include_self: bool = True, ellipsoid: str = 'WGS84') -> ArrayLike Apply a minimum over HEALPix neighbourhoods. .. py:function:: max_filter(values: ArrayLike, cell_ids, refinement_level: int, *, radius_m: float, domain=None, neighbourhood: healpix_analyse._neighbourhood.NeighbourhoodMethod = 'cell_center', include_self: bool = True, ellipsoid: str = 'WGS84') -> ArrayLike Apply a maximum over HEALPix neighbourhoods.