healpix_analyse.neighbour_reduce#

Generic neighbourhood reductions for nested HEALPix fields.

This module provides local, unweighted reductions over geometrically defined HEALPix neighbourhoods.

Neighbourhood geometry is shared with 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 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#

HealPixNeighbourReducer

Reusable HEALPix neighbourhood-reduction operator.

Functions#

neighbour_reduce(→ ArrayLike)

Reduce field values over local HEALPix neighbourhoods.

median_filter(→ ArrayLike)

Apply a numerical median over HEALPix neighbourhoods.

mean_filter(→ ArrayLike)

Apply a mean over HEALPix neighbourhoods.

min_filter(→ ArrayLike)

Apply a minimum over HEALPix neighbourhoods.

max_filter(→ ArrayLike)

Apply a maximum over HEALPix neighbourhoods.

Module Contents#

class healpix_analyse.neighbour_reduce.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')[source]#

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".

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.

refinement_level#
radius_m#
neighbourhood = 'cell_center'#
include_self = True#
ellipsoid = 'WGS84'#
cell_ids#
property output_cell_ids: numpy.ndarray#

Return output HEALPix IDs in exact output order.

healpix_analyse.neighbour_reduce.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[source]#

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:

numpy.ndarray or torch.Tensor – Reduced values.

The backend follows values. The final dimension follows domain when explicitly supplied and cell_ids otherwise.

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.

healpix_analyse.neighbour_reduce.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[source]#

Apply a numerical median over HEALPix neighbourhoods.

healpix_analyse.neighbour_reduce.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[source]#

Apply a mean over HEALPix neighbourhoods.

healpix_analyse.neighbour_reduce.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[source]#

Apply a minimum over HEALPix neighbourhoods.

healpix_analyse.neighbour_reduce.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[source]#

Apply a maximum over HEALPix neighbourhoods.