Polars

Functions

API to use h3ronpy with the polars dataframe library.

Warning

To avoid pulling in unused dependencies, h3ronpy does not declare a dependency to polars. This package needs to be installed separately.

Polars API extensions

Polars itself provides multiple ways to extend its API - h3ronpy makes use of this to provide custom extensions for Series and Expr types in the h3 namespace.

To make these extensions available, the h3ronpy.polars module needs to be imported.

Expressions

Example:

import polars as pl
# to register extension functions in the polars API
import h3ronpy.polars

df = pl.DataFrame({
    "cell": ["8852dc41cbfffff", "8852dc41bbfffff"],
    "value": ["a", "b"]
})

(df.lazy()
    .select([
        pl.col("cell")
            .h3.cells_parse()
            .h3.grid_disk(2)
            .alias("disk"),
        pl.col("value")
    ])

    .group_by("value")
    .agg([
        pl.col("disk")
            .explode()
            .h3.cells_area_km2()
            .sum()
    ])
    .collect()
)

shape: (2, 2)

value	area_km2
str	f64
"b"	11.832943
"a"	11.843943

All methods of the H3Expr class are available in the h3 object of a polars Expr:

class h3ronpy.polars.H3Expr(expr: Expr)

Registers H3 functionality with polars Expr expressions.

The methods of this class mirror the functionality provided by the functions of this module. Please refer to the module functions for more documentation.

Parameters:: expr (pl.Expr)

cells_area_km2() → Expr

Return type:: Expr

cells_area_m2() → Expr

Return type:: Expr

cells_area_rads2() → Expr

Return type:: Expr

cells_parse(set_failing_to_invalid: bool = False) → Expr

Parameters:: set_failing_to_invalid (bool)
Return type:: Expr

cells_resolution() → Expr

Return type:: Expr

cells_to_string() → Expr

Return type:: Expr

cells_valid() → Expr

Return type:: Expr

change_resolution(resolution: int) → Expr

Parameters:: resolution (int)
Return type:: Expr

change_resolution_list(resolution: int) → Expr

Parameters:: resolution (int)
Return type:: Expr

compact(mixed_resolutions: bool = False) → Expr

Parameters:: mixed_resolutions (bool)
Return type:: Expr

directededges_parse(set_failing_to_invalid: bool = False) → Expr

Parameters:: set_failing_to_invalid (bool)
Return type:: Expr

directededges_to_string() → Expr

Return type:: Expr

directededges_valid() → Expr

Return type:: Expr

grid_disk(k: int, flatten: bool = False) → Expr

Parameters:

k (int)
flatten (bool)

Return type:

Expr

uncompact(target_resolution: int) → Expr

Parameters:: target_resolution (int)
Return type:: Expr

vertexes_parse(set_failing_to_invalid: bool = False) → Expr

Parameters:: set_failing_to_invalid (bool)
Return type:: Expr

vertexes_to_string() → Expr

Return type:: Expr

vertexes_valid() → Expr

Return type:: Expr

Series

Example:

import polars as pl
# to register extension functions in the polars API
import h3ronpy.polars

cell_strings = (pl.Series("cells", ["8852dc41cbfffff"])
    .h3.cells_parse()
    .h3.grid_disk(1)
    .explode()
    .sort()
    .h3.cells_to_string())

cell_strings

shape: (7,)


str
"8852dc4035fffff"
"8852dc4037fffff"
"8852dc41c1fffff"
"8852dc41c3fffff"
"8852dc41c9fffff"
"8852dc41cbfffff"
"8852dc41ddfffff"

All methods of the H3SeriesShortcuts class are available in the h3 object of a polars Series:

class h3ronpy.polars.H3SeriesShortcuts(s: Series)

Registers H3 functionality with polars Series.

The methods of this class mirror the functionality provided by the functions of this module. Please refer to the module functions for more documentation.

Parameters:: s (pl.Series)

cells_area_km2() → Series

Return type:: Series

cells_area_m2() → Series

Return type:: Series

cells_area_rads2() → Series

Return type:: Series

cells_parse(set_failing_to_invalid: bool = False) → Series

Parameters:: set_failing_to_invalid (bool)
Return type:: Series

cells_resolution() → Series

Return type:: Series

cells_to_string() → Series

Return type:: Series

cells_valid() → Series

Return type:: Series

change_resolution(resolution: int) → Series

Parameters:: resolution (int)
Return type:: Series

change_resolution_list(resolution: int) → Series

Parameters:: resolution (int)
Return type:: Series

compact(mixed_resolutions: bool = False) → Series

Parameters:: mixed_resolutions (bool)
Return type:: Series

directededges_parse(set_failing_to_invalid: bool = False) → Series

Parameters:: set_failing_to_invalid (bool)
Return type:: Series

directededges_to_string() → Series

Return type:: Series

directededges_valid() → Series

Return type:: Series

grid_disk(k: int, flatten: bool = False) → Series

Parameters:

k (int)
flatten (bool)

Return type:

Series

uncompact(target_resolution: int) → Series

Parameters:: target_resolution (int)
Return type:: Series

vertexes_parse(set_failing_to_invalid: bool = False) → Series

Parameters:: set_failing_to_invalid (bool)
Return type:: Series

vertexes_to_string() → Series

Return type:: Series

vertexes_valid() → Series

Return type:: Series