rHP-Pandas

Package rhppandas intends to recreate for rHEALPix what h3pandas, developed by Daniel Jahn (https://github.com/DahnJ/H3-Pandas), does for h3-py, the Python binding for Uber's H3 DGGS. It provides a bridge between package rhealpixdggs and the dataframes used by pandas and geopandas.

Comments, bug reports and suggestions are all welcome.

In other words: the package in its current form is mostly meant for developers, or maybe for experienced end users.

Conda Environment

Use yaml file environment.yml to create a conda environment for basic use if you'd like to give the package a spin.

Adding yaml file environment-dev.yml to your conda environment will add the packages you need to run the automated tests.

Usage Examples

Using a basic dataframe with lat/lng coordinates:

> from rhppandas import rhppandas
> import pandas as pd
>
> basic_dataframe = pd.DataFrame({"lat": [50, 51], "lng": [14, 15]})
> basic_dataframe
       lat  lng
    0   50   14
    1   51   15

• Add rhealpixdggs cell indices as the first column in the dataframe:

> geo2rhp = basic_dataframe.rhp.geo_to_rhp(9)
> geo2rhp
               lat  lng
    rhp_09              
    N216055147   50   14
    N208518546   51   15

• Turn DGGS cell indices into points and add them in the geometry column:

> rhp2geo = geo2rhp.rhp.rhp_to_geo()
> rhp2geo
                lat  lng                   geometry
    rhp_09                                         
    N216055147   50   14    POINT (14.0006 49.9997)
    N208518546   51   15  POINT (15.00186 50.99928)

• Add cell boundaries as the geometry column:

> rhp2geoboundary = geo2rhp.rhp.rhp_to_geo_boundary()
> rhp2geoboundary
                lat  lng                                           geometry
    rhp_09                                                                 
    N216055147   50   14  POLYGON ((13.99601 50.00223, 14.00145 50.00223...
    N208518546   51   15  POLYGON ((14.99721 51.0018, 15.00279 51.0018, ...

• Add a colum with cell resolutions to the dataframe:

> withresolution = geo2rhp.rhp.rhp_get_resolution()
> withresolution
                lat  lng  rhp_resolution
    rhp_09                              
    N216055147   50   14               9
    N208518546   51   15               9

• Add a column with the parent cell at resolution 0:

> withbasecell = geo2rhp.rhp.rhp_get_base_cell()
> withbasecell
                lat  lng rhp_base_cell
    rhp_09                            
    N216055147   50   14             N
    N208518546   51   15             N

• Add a column with the parent cell indices at resolution 5:

> withparent = geo2rhp.rhp.rhp_to_parent(5)
> withparent
                lat  lng  rhp_05
    rhp_09                      
    N216055147   50   14  N21605
    N208518546   51   15  N20851

• Add a column with the cell area:

> withcellarea = geo2rhp.rhp.cell_area()
> withcellarea
                lat  lng  rhp_cell_area
    rhp_09                             
    N216055147   50   14       0.219428
    N208518546   51   15       0.219428

Running Tests

rhppandas uses pytest as its test framework. Make sure that your environment includes both environment.yml and environment-dev.yml and is activated. Then type pytest in a shell with the active conda environment.

Typing pytest --cov will run the tests and print some info on test coverage of the code base.

Deployment

Releases go to PyPI, then to conda-forge via the rhppandas-feedstock.

From a clean, pushed develop:

scripts/release.sh --bump patch|minor|major

This runs the tests, bumps the version, pushes a vX.Y.Z tag and opens a draft GitHub release. Edit the notes and publish it; that triggers .github/workflows/publish.yml, which uploads to PyPI using trusted publishing (no tokens). scripts/release.sh --help lists the other options, including a TestPyPI rehearsal. The conda-forge bot then opens a feedstock PR; check its run requirements against pyproject.toml before merging.