Implement h3.compact and uncompact

[KoalaGeo]

Hi,

This library is great! Do you have plans to implement the H3 compact and uncompact functions?

Regards,

Edd

[DahnJ]

Hi @KoalaGeo glad you like the library!

Currently, I have no such plans.

What behaviour would you expect these functions to have in H3-Pandas?

compact and uncompact are set operations and applying them to a dataframe with potential additional data is not straightforward. I see two general options

1. The data would have to be removed and the returned dataframe would be index-only. This would not be difficult to implement. I can see how that's still potentially convenient, as it allows you to string further h3 operations.
2. The compacted/uncompacted cells would have to be matched back with the rows they originated from with some (dis)aggregation operation being performed on the data. k_ring_smoothing does something similar.

It would be helpful if you could elaborate on your usecase to drive the potential API.

[KoalaGeo]

I'm working with polygons, primarily categorical data (geology, rock type, formation name, descriptions etc).

I'm using polyfill / polyfill_resample, however it's resulting in massive numbers of polygons to accurately represent the input geometries - resolution 13 or 14 required.

I could do with the compact function at the end to simplify the data to fewer features using an index attribute eg rock type.

[alpha-beta-soup]

Here's a very loose implementation I just cooked up which implements the core of @KoalaGeo's idea, which is what I need also (categorical data primarily, but not necessarily).

def number_of_children(cell, desired_resolution: int) -> int:
    # NB we enumerate all children due to the presence of pentagonal cells
    # The H3 API has cellToChildrenSize, but it is not available in Python API?
    return len(h3py.cell_to_children(cell, desired_resolution))

def h3compaction(df: pd.DataFrame, res: int, parent_res: int) -> pd.DataFrame:
    """
    Compacts an H3 dataframe up to a given low resolution (parent_res), up to an existing maximum resolution (res).
    """
    compaction_result : dict = {}
    unprocessed_indices : set = set(df.index)

    # Iterate from the minimum to the maximum resolution level
    for r in range(parent_res, res):
        
        parents : set = {h3py.cell_to_parent(cell, r) for cell in unprocessed_indices}

        for parent in parents:
            expected_count : int = number_of_children(parent, res)
            
            # Collect indices for actual children of this parent
            actual_children : set = {index for index in unprocessed_indices if h3py.cell_to_parent(index, r) == parent}
            
            if len(actual_children) == expected_count:
                # Evaluate attributes for uniformity across these children
                child_df = df.loc[list(actual_children)]
                if child_df.apply(pd.Series.nunique).max() == 1:
                    compaction_result[parent] = child_df.iloc[0]
                    unprocessed_indices -= actual_children  # Mark these as processed by removing
    
    # Add any remaining cells >= max_res to the results
    for index in unprocessed_indices:
        compaction_result[index] = df.loc[index]

    return pd.DataFrame.from_dict(compaction_result, orient='index')

Decompaction is more straightforward.

[alpha-beta-soup]

Sample output to help make it clearer that this compacts within a resolution "range".