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.

Important

This is very much a work in progress, and in the early stages. Some of the API available in h3pandas remains unimplemented, none of it has been used in production. The package comes with some tests but we make no claims of completeness regarding those.

In other words: the package in its current form is mostly meant for developers, and not in a state that would be suitable for 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.

Note

A large part of why some of the API remains unimplemented has to do with the relevant functions in the backend not being implemented yet either. Development of the wrapper API within rhealpixdggs is happening in tandem with rhppandas, with the intention of adding adapter functions one by one as the backend is fleshed out.

This also explains why environment.yml points to a branch of the rhealpixdggs-py repository instead of a release of the rhealpixdggs package.

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              
    N216055611   50   14
    N208542111   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                                         
    N216055611   50   14  POINT (14.00085 50.00206)
    N208542111   51   15  POINT (14.99814 51.00185)

• Add cell boundaries as the geometry column:

> rhp2geoboundary = geo2rhp.rhp.rhp_to_geo_boundary()
> rhp2geoboundary
                lat  lng                                           geometry
    rhp_09                                                                 
    N216055611   50   14  POLYGON ((13.99625 50.00459, 14.0017 50.00459,...
    N208542111   51   15  POLYGON ((14.99349 51.00438, 14.99907 51.00438...

• Add a colum with cell resolutions to the dataframe:

> withresolution = geo2rhp.rhp.rhp_get_resolution()
> withresolution
                lat  lng  rhp_resolution
    rhp_09                              
    N216055611   50   14               9
    N208542111   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                            
    N216055611   50   14             N
    N208542111   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                      
    N216055611   50   14  N21605
    N208542111   51   15  N20854

• Add a column with the cell area:

> withcellarea = geo2rhp.rhp.cell_area()
> withcellarea
                lat  lng  rhp_cell_area
    rhp_09                             
    N216055611   50   14       0.258798
    N208542111   51   15       0.258798

Running Tests

rhppandas uses pytest as its test framework. Type pytest in a shell with an active conda environment for rhppandas.

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