healpix_analyse.radial_filter#

Metric radial filtering on NESTED HEALPix fields.

This module provides deterministic isotropic filtering whose spatial semantics are defined entirely by physical WGS84 centre-to-centre distance.

For an output/target cell i and a contributing neighbour/source cell j:

distance_ij = WGS84 geodesic distance from i to j
weight_ij   = kernel(distance_ij)

The public API deliberately avoids Cartesian concepts such as 3x3 or 5x5 windows and pixel-based smoothing scales. Distances are expressed in metres so that the same kernel retains the same physical meaning across HEALPix refinement levels.

Neighbour selection and WGS84 geometry are delegated to the shared neighbourhood infrastructure. Weighted value gathering, NaN handling, normalization, Torch device preservation, and autograd are delegated to the shared weighted-neighbourhood aggregation helper.

The intended separation is:

physical neighbourhood
        |
        v
shared WGS84 geometry
    distance_m
        |
        v
  kernel(distance_m)
        |
        v
supplied radial weights
        |
        v
weighted_neighbourhood_reduce()
        |
        v
      output

This keeps radial filtering separate from directional filtering. A radial kernel depends only on distance; geographical azimuth or relative bearing is not part of this API.

Functions#

radial_filter(→ ArrayLike)

Apply an isotropic physical-distance kernel to a HEALPix field.

gaussian_filter(→ ArrayLike)

Apply normalized Gaussian smoothing in physical metres.

Module Contents#

healpix_analyse.radial_filter.radial_filter(values: ArrayLike, cell_ids: numpy.ndarray, refinement_level: int, *, radius_m: float, kernel: Kernel, normalize: bool = True, domain: numpy.ndarray | None = None, ellipsoid: str = 'WGS84') → ArrayLike[source]#

Apply an isotropic physical-distance kernel to a HEALPix field.

Parameters:

  • values – NumPy array or PyTorch tensor containing the input signal. The final dimension corresponds one-to-one with cell_ids. Arbitrary leading dimensions are preserved.

  • cell_ids – One-dimensional array of unique NESTED HEALPix cell IDs for which input values are available.

  • refinement_level – HEALPix refinement level.

  • radius_m – Maximum WGS84 centre-to-centre distance, in metres, over which cells may contribute. 0 is valid and represents centre-only physical support.

  • kernel – Callable defining the radial weight as a function of physical distance:

    weight = kernel(distance_m)

    The callable receives a one-dimensional NumPy array of valid centre-neighbour distances. It may return a scalar or an array broadcastable to that shape.

    Finite negative weights are allowed. Non-finite weights at valid neighbour positions raise ValueError.

  • normalize –

    If True (default), return the normalized weighted result:

          sum(weight * value)
-----------------------------
     sum(effective weight)

    using only effective valid samples.

    If False, return the raw weighted sum:

    sum(weight * value)

    NaN-valued signal samples are excluded by the shared aggregation helper. With normalize=True, their weights are also removed from the denominator. If the effective weight sum is zero, the normalized result is NaN.

  • domain – Optional processing and output domain. It must be a subset of cell_ids. Output ordering follows domain exactly.

    Cells outside domain are absent from the effective neighbourhood, even when input values for them are present in cell_ids.

  • ellipsoid – Geographical ellipsoid used by the shared neighbourhood geometry. The current relative-geometry implementation supports "WGS84".

Returns:

numpy.ndarray or torch.Tensor –

Filtered values with shape:

values.shape[:-1] + (len(domain),)

when domain is supplied, or the same final-axis length as cell_ids otherwise.

NumPy input returns NumPy output. Torch input returns Torch output on the original device, with autograd preserved with respect to values.

Notes

The spatial support uses physical WGS84 cell-centre distance. HEALPix ring number and Cartesian pixel-window dimensions are deliberately not part of the public API.

The implementation pipeline is:

 physical-radius neighbourhood
             |
             v
    processing-domain filter
             |
             v
shared relative WGS84 geometry
             |
             v
         distance_m
             |
             v
    user radial kernel
             |
             v
weighted_neighbourhood_reduce
             |
             v
           output

Examples

Apply a normalized inverse-distance-like radial filter:

import numpy as np
from healpix_analyse import radial_filter

def kernel(distance_m):
    return 1.0 / (1.0 + distance_m / 250.0)

filtered = radial_filter(
    values,
    cell_ids,
    refinement_level=17,
    radius_m=1000.0,
    kernel=kernel,
    normalize=True,
)
healpix_analyse.radial_filter.gaussian_filter(values: ArrayLike, cell_ids: numpy.ndarray, refinement_level: int, *, sigma_m: float, truncate: float = 4.0, domain: numpy.ndarray | None = None, ellipsoid: str = 'WGS84') → ArrayLike[source]#

Apply normalized Gaussian smoothing in physical metres.

The Gaussian kernel is:

weight(d) = exp(-0.5 * (d / sigma_m)**2)

and is truncated at:

radius_m = truncate * sigma_m
Parameters:

  • values, cell_ids, refinement_level, domain, ellipsoid – See radial_filter().

  • sigma_m – Gaussian standard deviation in metres. Must be finite and strictly positive.

  • truncate – Gaussian support radius in units of sigma_m. Must be finite and strictly positive. The default is 4.0.

Returns:

numpy.ndarray or torch.Tensor – Normalized Gaussian-smoothed values.

Notes

Gaussian smoothing is normalized by construction. Constant finite fields therefore remain constant, including near partial-domain boundaries after unavailable samples are removed and the remaining effective weights are renormalized.

The physical smoothing scale is independent of HEALPix refinement level: sigma_m=240 always means 240 metres rather than a number of pixels.