High Level HEALPix API

This section contains the main functionality for creating and working with HEALPix-based dataset representations, including pyramid construction and resolution handling.

Pyramid creation

These functions build HEALPix pyramids from gridded source data and provide the main higher-level workflow for preparing multi-resolution outputs.

create_healpix_pyramid(ds, max_level=None, min_level=0, *, coarsen_mode='auto', min_valid_fraction=0.5, **kwargs)

Create a multi-resolution HEALPix pyramid.

The input dataset is first remapped to max_level with regrid_to_healpix. For nested output ordering, lower levels are derived efficiently with coarsen_healpix. For ring ordering, each lower level is regenerated directly from the source dataset.

Parameters:

Name	Type	Description	Default
ds	Dataset	Source dataset.	required
max_level	int | None	Finest HEALPix level.	None
min_level	int	Coarsest HEALPix level to keep.	0
coarsen_mode	CoarsenMode	Coarsening strategy for building lower pyramid levels. "mean" for continuous data, "mode" for categorical, "auto" to infer from the remapping method.	'auto'
min_valid_fraction	float	Minimum fraction of valid children for a parent cell to be valid. Default 0.5.	0.5
**kwargs	Any	Forwarded to regrid_to_healpix.	{}

Returns:

Type	Description
dict[int, Dataset]	Pyramid keyed by level.

Source code in .tox/docs/lib/python3.13/site-packages/grid_doctor/helpers.py

def create_healpix_pyramid(
    ds: xr.Dataset,
    max_level: int | None = None,
    min_level: int = 0,
    *,
    coarsen_mode: CoarsenMode = "auto",
    min_valid_fraction: float = 0.5,
    **kwargs: Any,
) -> dict[int, xr.Dataset]:
    """Create a multi-resolution HEALPix pyramid.

    The input dataset is first remapped to *max_level* with
    [`regrid_to_healpix`][grid_doctor.remap.regrid_to_healpix].
    For nested output ordering, lower levels are derived efficiently
    with
    [`coarsen_healpix`][grid_doctor.helpers.coarsen_healpix].
    For ring ordering, each lower level is regenerated directly from
    the source dataset.

    Parameters
    ----------
    ds:
        Source dataset.
    max_level:
        Finest HEALPix level.
    min_level:
        Coarsest HEALPix level to keep.
    coarsen_mode:
        Coarsening strategy for building lower pyramid levels.
        ``"mean"`` for continuous data, ``"mode"`` for categorical,
        ``"auto"`` to infer from the remapping method.
    min_valid_fraction:
        Minimum fraction of valid children for a parent cell to be
        valid.  Default ``0.5``.
    **kwargs:
        Forwarded to
        [`regrid_to_healpix`][grid_doctor.remap.regrid_to_healpix].

    Returns
    -------
    dict[int, xarray.Dataset]
        Pyramid keyed by level.
    """
    if max_level is None:
        max_level = resolution_to_healpix_level(get_latlon_resolution(ds))

    pyramid: dict[int, xr.Dataset] = {}
    finest = regrid_to_healpix(ds, max_level, **kwargs)
    pyramid[max_level] = finest

    is_nested = bool(kwargs.get("nest", True))
    if is_nested:
        current = finest
        for level in range(max_level - 1, min_level - 1, -1):
            current = coarsen_healpix(
                current,
                level,
                coarsen_mode=coarsen_mode,
                min_valid_fraction=min_valid_fraction,
            )
            pyramid[level] = current
        return pyramid

    for level in range(max_level - 1, min_level - 1, -1):
        pyramid[level] = regrid_to_healpix(ds, level, **kwargs)
    return pyramid

Resolution helpers

These utilities help translate between source grid resolution and the corresponding HEALPix level used for remapping and pyramid generation.

get_latlon_resolution(ds)

Estimate the horizontal resolution of ds in degrees.

Parameters:

Name	Type	Description	Default
ds	Dataset	Dataset on a regular lon/lat grid, a curvilinear grid, or an unstructured grid.	required

Returns:

Type	Description
float	Approximate grid spacing in degrees.

Examples:

resolution = get_latlon_resolution(ds)
level = resolution_to_healpix_level(resolution)

Source code in .tox/docs/lib/python3.13/site-packages/grid_doctor/helpers.py

def get_latlon_resolution(ds: xr.Dataset) -> float:
    """Estimate the horizontal resolution of *ds* in degrees.

    Parameters
    ----------
    ds:
        Dataset on a regular lon/lat grid, a curvilinear grid, or an
        unstructured grid.

    Returns
    -------
    float
        Approximate grid spacing in degrees.

    Examples
    --------
    ```python
    resolution = get_latlon_resolution(ds)
    level = resolution_to_healpix_level(resolution)
    ```
    """
    if _is_unstructured(ds):
        cell_dim = _get_unstructured_dim(ds)
        n_cells = ds.sizes[cell_dim]
        return float(np.degrees(np.sqrt(4.0 * np.pi / float(n_cells))))

    lat, lon = _get_latlon_arrays(ds)
    if lat.ndim == 1:
        lat_res = float(np.nanmin(np.abs(np.diff(lat))))
        lon_res = float(np.nanmin(np.abs(np.diff(lon))))
    else:
        lat_res = float(np.nanmean(np.abs(np.diff(lat, axis=0))))
        lon_res = float(np.nanmean(np.abs(np.diff(lon, axis=1))))
    return min(lat_res, lon_res)

resolution_to_healpix_level(resolution_deg)

Convert an approximate source resolution to a HEALPix level.

The heuristic uses a characteristic HEALPix pixel spacing of about 58.6° / 2**level.

Parameters:

Name	Type	Description	Default
resolution_deg	float	Approximate source resolution in degrees.	required

Returns:

Type	Description
int	Suggested HEALPix level.

Examples:

level = resolution_to_healpix_level(0.25)

Source code in .tox/docs/lib/python3.13/site-packages/grid_doctor/helpers.py

def resolution_to_healpix_level(resolution_deg: float) -> int:
    """Convert an approximate source resolution to a HEALPix level.

    The heuristic uses a characteristic HEALPix pixel spacing of about
    ``58.6° / 2**level``.

    Parameters
    ----------
    resolution_deg:
        Approximate source resolution in degrees.

    Returns
    -------
    int
        Suggested HEALPix level.

    Examples
    --------
    ```python
    level = resolution_to_healpix_level(0.25)
    ```
    """
    if resolution_deg <= 0.0:
        raise ValueError("resolution_deg must be positive.")
    level = int(np.floor(np.log2(58.6 / resolution_deg)))
    return max(0, level)