Metadata-Version: 2.4
Name: rhppandas
Version: 0.3.0
Summary: Integration of rHEALPixDGGS and Pandas/GeoPandas
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: python,rHEALPix,rhealpixdggs,geospatial,geopandas,pandas,integration
Author: MWLR
Author-email: lawr@landcareresearch.co.nz
Requires-Python: >=3.11
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: GIS
Provides-Extra: dev
Requires-Dist: geopandas
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pytest ; extra == "dev"
Requires-Dist: pytest-cov ; extra == "dev"
Requires-Dist: rhealpixdggs (>=0.7.1)
Requires-Dist: shapely
Requires-Dist: typing-extensions
Project-URL: bug_reports, https://github.com/manaakiwhenua/rHP-Pandas/issues
Project-URL: source, https://github.com/manaakiwhenua/rHP-Pandas
Description-Content-Type: text/markdown

# 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.

> [!IMPORTANT]
> This a work in progress. Most of the API outlined by `h3pandas` has been implemented but its use in production remains limited. 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, 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.

> [!NOTE]
> `rhppandas` requires `rhealpixdggs` 0.7.1 or later. That release completed the backend implementations of `linetrace` (now exact for every cell shape, including the polar cap cells) and `cell_ring` / `k_ring` (now correct around the corners of the DGGS cube, using graph distance). Line segments are traced as straight lines in longitude-latitude space and do not wrap around the antimeridian unless `linetrace` is called with `wrap_antimeridian=True`. Development of the wrapper API within `rhealpixdggs` happened in tandem with `rhppandas` and currently matches what `h3pandas` uses from `h3-py`.

## 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
There is a PyPI and conda package `rhppandas`.
The conda package is maintained at [conda-forge](https://github.com/conda-forge/rhealpixdggs-feedstock).

