<img align="left" src="https://i.imgur.com/OH8DoTA.png" alt="H3 Logo" width="500">
# H3-Pandas ⬢ 🐼
Integrates [H3](https://github.com/uber/h3-py) with [GeoPandas](https://github.com/geopandas/geopandas)
and [Pandas](https://github.com/pandas-dev/pandas).
[](https://colab.research.google.com/github/DahnJ/H3-Pandas/blob/master/notebook/00-intro.ipynb)
[](https://mybinder.org/v2/gh/DahnJ/H3-Pandas/HEAD?filepath=%2Fnotebook%2F00-intro.ipynb)
[](https://opensource.org/licenses/MIT)
[](https://pip.pypa.io/en/stable/?badge=stable)
---
<h3 align="center">
⬢ <a href="https://mybinder.org/v2/gh/DahnJ/H3-Pandas/HEAD?filepath=%2Fnotebook%2F00-intro.ipynb">Try it out</a> ⬢
</h3>
---
<p align="center">
<a href="https://github.com/DahnJ/H3-Pandas"><img src="https://i.imgur.com/GZWsC8G.gif" alt="example usage" width="450"></a>
</p>
## Installation
### pip
[](https://pypi.python.org/pypi/h3pandas)
```bash
pip install h3pandas
```
### conda
[]()
[](https://anaconda.org/conda-forge/h3pandas)
```bash
conda install -c conda-forge h3pandas
```
## Usage examples
### H3 API
`h3pandas` automatically applies H3 functions to both Pandas Dataframes and GeoPandas Geodataframes
```python
# Prepare data
>>> import pandas as pd
>>> import h3pandas
>>> df = pd.DataFrame({'lat': [50, 51], 'lng': [14, 15]})
```
```python
>>> resolution = 10
>>> df = df.h3.geo_to_h3(resolution)
>>> df
| h3_10 | lat | lng |
|:----------------|------:|------:|
| 8a1e30973807fff | 50 | 14 |
| 8a1e2659c2c7fff | 51 | 15 |
>>> df = df.h3.h3_to_geo_boundary()
>>> df
| h3_10 | lat | lng | geometry |
|:----------------|------:|------:|:----------------|
| 8a1e30973807fff | 50 | 14 | POLYGON ((...)) |
| 8a1e2659c2c7fff | 51 | 15 | POLYGON ((...)) |
```
### H3-Pandas Extended API
`h3pandas` also provides some extended functionality out-of-the-box,
often simplifying common workflows into a single command.
```python
# Set up data
>>> import numpy as np
>>> import pandas as pd
>>> np.random.seed(1729)
>>> df = pd.DataFrame({
>>> 'lat': np.random.uniform(50, 51, 100),
>>> 'lng': np.random.uniform(14, 15, 100),
>>> 'value': np.random.poisson(100, 100)})
>>> })
```
```python
# Aggregate values by their location and sum
>>> df = df.h3.geo_to_h3_aggregate(3)
>>> df
| h3_03 | value | geometry |
|:----------------|--------:|:----------------|
| 831e30fffffffff | 102 | POLYGON ((...)) |
| 831e34fffffffff | 189 | POLYGON ((...)) |
| 831e35fffffffff | 8744 | POLYGON ((...)) |
| 831f1bfffffffff | 1040 | POLYGON ((...)) |
# Aggregate to a lower H3 resolution
>>> df.h3.h3_to_parent_aggregate(2)
| h3_02 | value | geometry |
|:----------------|--------:|:----------------|
| 821e37fffffffff | 9035 | POLYGON ((...)) |
| 821f1ffffffffff | 1040 | POLYGON ((...)) |
```
### Further examples
For more examples, see the
[example notebooks](https://nbviewer.jupyter.org/github/DahnJ/H3-Pandas/tree/master/notebook/).
## API
For a full API documentation and more usage examples, see the
[documentation](https://h3-pandas.readthedocs.io/en/latest/).
## Development
H3-Pandas cover the basics of the H3 API, but there are still many possible improvements.
**Any suggestions and contributions are very welcome**!
In particular, the next steps are:
- [ ] Improvements & stability of the "Extended API", e.g. `k_ring_smoothing`.
Additional possible directions
- [ ] Allow for alternate h3-py APIs such as [memview_int](https://github.com/uber/h3-py#h3apimemview_int)
- [ ] Performance improvements through [Cythonized h3-py](https://github.com/uber/h3-py/pull/147)
- [ ] [Dask](https://github.com/dask/dask) integration through [dask-geopandas](https://github.com/geopandas/dask-geopandas) (experimental as of now)
See [issues](https://github.com/DahnJ/H3-Pandas/issues) for more.
Raw data
{
"_id": null,
"home_page": "https://github.com/DahnJ/H3-Pandas",
"name": "h3pandas",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "python,h3,geospatial,geopandas,pandas,integration,hexagons-are-bestagons",
"author": "Dahn",
"author_email": "dahnjahn@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/cb/fc/28b7a2345f17c25d238dfcb71cd5afb78788408dd2395bc3660d78d60e4e/h3pandas-0.2.6.tar.gz",
"platform": null,
"description": "<img align=\"left\" src=\"https://i.imgur.com/OH8DoTA.png\" alt=\"H3 Logo\" width=\"500\">\n\n\n \n\n# H3-Pandas \u2b22 \ud83d\udc3c\nIntegrates [H3](https://github.com/uber/h3-py) with [GeoPandas](https://github.com/geopandas/geopandas)\nand [Pandas](https://github.com/pandas-dev/pandas).\n[](https://colab.research.google.com/github/DahnJ/H3-Pandas/blob/master/notebook/00-intro.ipynb)\n[](https://mybinder.org/v2/gh/DahnJ/H3-Pandas/HEAD?filepath=%2Fnotebook%2F00-intro.ipynb)\n[](https://opensource.org/licenses/MIT)\n[](https://pip.pypa.io/en/stable/?badge=stable)\n\n \n\n\n---\n\n<h3 align=\"center\">\n \u2b22 <a href=\"https://mybinder.org/v2/gh/DahnJ/H3-Pandas/HEAD?filepath=%2Fnotebook%2F00-intro.ipynb\">Try it out</a> \u2b22\n</h3>\n\n---\n<p align=\"center\">\n <a href=\"https://github.com/DahnJ/H3-Pandas\"><img src=\"https://i.imgur.com/GZWsC8G.gif\" alt=\"example usage\" width=\"450\"></a>\n</p>\n\n\n## Installation\n### pip\n[](https://pypi.python.org/pypi/h3pandas)\n```bash\npip install h3pandas\n```\n\n### conda\n[]()\n[](https://anaconda.org/conda-forge/h3pandas)\n```bash\nconda install -c conda-forge h3pandas\n```\n\n## Usage examples\n\n### H3 API\n`h3pandas` automatically applies H3 functions to both Pandas Dataframes and GeoPandas Geodataframes\n\n```python\n# Prepare data\n>>> import pandas as pd\n>>> import h3pandas\n>>> df = pd.DataFrame({'lat': [50, 51], 'lng': [14, 15]})\n```\n\n```python\n>>> resolution = 10\n>>> df = df.h3.geo_to_h3(resolution)\n>>> df\n\n| h3_10 | lat | lng |\n|:----------------|------:|------:|\n| 8a1e30973807fff | 50 | 14 |\n| 8a1e2659c2c7fff | 51 | 15 |\n\n>>> df = df.h3.h3_to_geo_boundary()\n>>> df\n\n| h3_10 | lat | lng | geometry |\n|:----------------|------:|------:|:----------------|\n| 8a1e30973807fff | 50 | 14 | POLYGON ((...)) |\n| 8a1e2659c2c7fff | 51 | 15 | POLYGON ((...)) |\n```\n\n### H3-Pandas Extended API\n`h3pandas` also provides some extended functionality out-of-the-box, \noften simplifying common workflows into a single command.\n\n```python\n# Set up data\n>>> import numpy as np\n>>> import pandas as pd\n>>> np.random.seed(1729)\n>>> df = pd.DataFrame({\n>>> 'lat': np.random.uniform(50, 51, 100),\n>>> 'lng': np.random.uniform(14, 15, 100),\n>>> 'value': np.random.poisson(100, 100)})\n>>> })\n```\n\n```python\n# Aggregate values by their location and sum\n>>> df = df.h3.geo_to_h3_aggregate(3)\n>>> df\n\n| h3_03 | value | geometry |\n|:----------------|--------:|:----------------|\n| 831e30fffffffff | 102 | POLYGON ((...)) |\n| 831e34fffffffff | 189 | POLYGON ((...)) |\n| 831e35fffffffff | 8744 | POLYGON ((...)) |\n| 831f1bfffffffff | 1040 | POLYGON ((...)) |\n\n# Aggregate to a lower H3 resolution\n>>> df.h3.h3_to_parent_aggregate(2)\n\n| h3_02 | value | geometry |\n|:----------------|--------:|:----------------|\n| 821e37fffffffff | 9035 | POLYGON ((...)) |\n| 821f1ffffffffff | 1040 | POLYGON ((...)) |\n```\n\n\n### Further examples\nFor more examples, see the \n[example notebooks](https://nbviewer.jupyter.org/github/DahnJ/H3-Pandas/tree/master/notebook/).\n\n## API\nFor a full API documentation and more usage examples, see the \n[documentation](https://h3-pandas.readthedocs.io/en/latest/).\n\n## Development\nH3-Pandas cover the basics of the H3 API, but there are still many possible improvements.\n\n**Any suggestions and contributions are very welcome**!\n\nIn particular, the next steps are:\n- [ ] Improvements & stability of the \"Extended API\", e.g. `k_ring_smoothing`. \n\nAdditional possible directions\n- [ ] Allow for alternate h3-py APIs such as [memview_int](https://github.com/uber/h3-py#h3apimemview_int)\n- [ ] Performance improvements through [Cythonized h3-py](https://github.com/uber/h3-py/pull/147)\n- [ ] [Dask](https://github.com/dask/dask) integration through [dask-geopandas](https://github.com/geopandas/dask-geopandas) (experimental as of now)\n\nSee [issues](https://github.com/DahnJ/H3-Pandas/issues) for more.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Integration of H3 and GeoPandas",
"version": "0.2.6",
"project_urls": {
"Download": "https://github.com/DahnJ/H3-Pandas/archive/refs/tags/0.2.6.tar.gz",
"Homepage": "https://github.com/DahnJ/H3-Pandas"
},
"split_keywords": [
"python",
"h3",
"geospatial",
"geopandas",
"pandas",
"integration",
"hexagons-are-bestagons"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cbfc28b7a2345f17c25d238dfcb71cd5afb78788408dd2395bc3660d78d60e4e",
"md5": "c323abda75cb152de868195e2c9b627c",
"sha256": "eda3430a88e81c03791c6f7e393d3a3af797b6f0b69d7d5496f35e35ab2557d0"
},
"downloads": -1,
"filename": "h3pandas-0.2.6.tar.gz",
"has_sig": false,
"md5_digest": "c323abda75cb152de868195e2c9b627c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 138369,
"upload_time": "2023-11-21T19:49:47",
"upload_time_iso_8601": "2023-11-21T19:49:47.989744Z",
"url": "https://files.pythonhosted.org/packages/cb/fc/28b7a2345f17c25d238dfcb71cd5afb78788408dd2395bc3660d78d60e4e/h3pandas-0.2.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-21 19:49:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DahnJ",
"github_project": "H3-Pandas",
"travis_ci": false,
"coveralls": true,
"github_actions": false,
"lcname": "h3pandas"
}
JSON
