Utilities API Reference
This module provides utility functions for computing HEALPix grid connections, distances, and interpolation weights.
Connection Index Functions
compute_connection_indices
- compute_connection_indices(nside_in, nside_out, k, return_weights=False, weight_method='inverse_square')[source]
Compute connection indices and optionally weights for spatial operations.
This is a convenience function that combines hp_distance and get_weights for setting up spatial convolution or upsampling layers.
- Parameters:
nside_in (int) – Input grid resolution parameter (nside).
nside_out (int) – Output grid resolution parameter (nside).
k (int) – Number of nearest neighbors.
return_weights (bool) – If True, also return computed interpolation weights.
weight_method (Literal['inverse_square', 'gaussian', 'exponential', 'tricube']) – Weighting method if return_weights is True.
- Returns:
Tuple of (indices, distances_km) If return_weights is True:
Tuple of (indices, distances_km, weights)
- Return type:
If return_weights is False
Example
>>> # For downsampling (convolution) >>> indices, distances = compute_connection_indices( ... nside_in=64, nside_out=32, k=4 ... ) >>> # For upsampling with weights >>> indices, distances, weights = compute_connection_indices( ... nside_in=32, nside_out=64, k=4, return_weights=True ... )
hp_distance
- hp_distance(nside_in, nside_out, k)[source]
Calculate distances and neighbor indices between HEALPix grids.
Computes the k-nearest neighbors from an input HEALPix grid to an output HEALPix grid using geodesic (haversine) distance on the sphere. This function is essential for constructing the connection indices used in spatial convolution layers.
- Parameters:
- Returns:
indices: Integer array of shape [N_out, k] containing the indices of the k-nearest input pixels for each output pixel.
distances_km: Float array of shape [N_out, k] containing the geodesic distances in kilometers to each neighbor.
- Return type:
A tuple containing
- Raises:
ImportError – If healpy or scikit-learn is not installed.
ValueError – If nside_in, nside_out, or k are not positive integers.
Example
>>> indices, distances = hp_distance(nside_in=64, nside_out=32, k=4) >>> print(indices.shape) # (12288, 4) for nside_out=32 >>> print(distances.shape) # (12288, 4)
Notes
The Earth radius used for distance calculation is 6371 km.
Grid construction has O(N log N) complexity due to BallTree.
For same-resolution grids (nside_in == nside_out), the first neighbor will be the pixel itself with distance 0.
Weighting Functions
get_weights
- get_weights(distances, method='inverse_square', sigma_factor=0.5, epsilon=1e-10)[source]
Calculate interpolation weights based on distances.
Computes normalized weights for spatial interpolation using various distance-based weighting schemes. These weights are used in upsampling and convolution operations to aggregate features from neighboring pixels.
- Parameters:
distances (ndarray[tuple[int, ...], dtype[float64]]) – Array of distances with shape [N, k] where N is the number of points and k is the number of neighbors.
method (Literal['inverse_square', 'gaussian', 'exponential', 'tricube']) –
Weighting method to use. Options are: - “inverse_square”: Inverse distance weighting (IDW) with power 2.
Weight = 1 / (distance^2 + epsilon).
”gaussian”: Gaussian kernel weighting. Weight = exp(-0.5 * (distance / sigma)^2).
”exponential”: Exponential decay weighting. Weight = exp(-distance / scale).
”tricube”: Tricube kernel weighting. Weight = (1 - (distance / max_distance)^3)^3.
sigma_factor (float) – Factor to multiply the mean distance for computing sigma (gaussian) or scale (exponential). Default is 0.5.
epsilon (float) – Small constant to prevent division by zero in inverse_square method. Default is 1e-10.
- Returns:
Normalized weights array with same shape as distances. Weights sum to 1.0 along the last axis (neighbors dimension).
- Raises:
ValueError – If an unsupported weighting method is specified.
- Return type:
Example
>>> distances = np.array([[100.0, 200.0, 300.0], [150.0, 250.0, 350.0]]) >>> weights = get_weights(distances, method="inverse_square") >>> print(weights.sum(axis=1)) # [1.0, 1.0]
Notes
All methods produce normalized weights that sum to 1 per point.
The inverse_square method is most common for IDW interpolation.
Gaussian and exponential methods use adaptive scaling based on the mean distance for each point.
HEALPix Information
get_healpix_resolution_info
- get_healpix_resolution_info(nside)[source]
Get information about a HEALPix resolution.
- Parameters:
nside (int) – HEALPix nside parameter.
- Returns:
nside: The nside parameter.
npix: Total number of pixels (12 * nside^2).
resolution_deg: Approximate resolution in degrees.
resolution_km: Approximate resolution in kilometers.
area_sr: Area per pixel in steradians.
area_km2: Approximate area per pixel in km^2.
- Return type:
Dictionary containing
Example
>>> info = get_healpix_resolution_info(256) >>> print(f"Resolution: {info['resolution_deg']:.2f} degrees")
Usage Examples
Computing Connection Indices for Downsampling
from idx_flow import compute_connection_indices
# Downsample from nside=64 to nside=32 with 4 neighbors
indices, distances = compute_connection_indices(
nside_in=64,
nside_out=32,
k=4
)
print(f"Indices shape: {indices.shape}") # (12288, 4)
print(f"Distances shape: {distances.shape}") # (12288, 4)
Computing Connection Indices for Upsampling
from idx_flow import compute_connection_indices
# Upsample from nside=32 to nside=64 with weights
indices, distances, weights = compute_connection_indices(
nside_in=32,
nside_out=64,
k=4,
return_weights=True,
weight_method="inverse_square"
)
print(f"Indices shape: {indices.shape}") # (49152, 4)
print(f"Weights shape: {weights.shape}") # (49152, 4)
Getting HEALPix Resolution Information
from idx_flow import get_healpix_resolution_info
info = get_healpix_resolution_info(nside=256)
print(f"Number of pixels: {info['npix']}")
print(f"Resolution (deg): {info['resolution_deg']:.3f}")
print(f"Resolution (km): {info['resolution_km']:.2f}")
print(f"Pixel area (km^2): {info['area_km2']:.2f}")