Hierarchy Navigation Summary

Create a small utility that summarizes where an input H3 cell sits in the hierarchy, including its parent at a coarser resolution, every child at a finer resolution, the center child, and the child's positional index within its parent.

Capabilities

Parent and children lookup

• Given the resolution 9 cell 8928308280fffff, a parent resolution of 7, and a child resolution of 9, return the parent index at resolution 7 and the full list of resolution 9 children for that parent. The children list must contain 49 entries and include the original cell. @test

Center child detection

• For the same inputs, identify the center child at resolution 9 and flag whether the provided cell is the center child. @test

Child position roundtrip

• Compute the provided cell's position index relative to its parent at resolution 7 and reconstruct the same child from that position index at resolution 9. @test

Resolution validation

• Reject requests where the parent resolution is greater than or equal to the input cell's resolution, where the child resolution is not finer than the parent resolution, or where either resolution is outside the valid range supported by the package. @test

Implementation

@generates

API

from typing import TypedDict


class HierarchySummary(TypedDict):
    parent: str
    parent_resolution: int
    children: list[str]
    child_resolution: int
    center_child: str
    center_is_input: bool
    child_position: int
    reconstructed_child: str


def summarize_hierarchy(cell: str, parent_resolution: int, child_resolution: int) -> HierarchySummary:
    """
    Build a hierarchy summary for a given cell.

    Args:
        cell: H3 cell index string at resolution >= parent_resolution
        parent_resolution: target coarser resolution for parent lookup
        child_resolution: target finer resolution for enumerating children

    Returns:
        Summary describing the parent index, children at the child resolution,
        whether the input is the center child, and a roundtrip reconstruction
        of the original cell from its positional index within the parent.
    """

Dependencies { .dependencies }

h3 { .dependency }

Provides hierarchical traversal between parent and child cells plus position mapping.