h3pandas


Nameh3pandas JSON
Version 0.2.6 PyPI version JSON
download
home_pagehttps://github.com/DahnJ/H3-Pandas
SummaryIntegration of H3 and GeoPandas
upload_time2023-11-21 19:49:47
maintainer
docs_urlNone
authorDahn
requires_python>=3.8
licenseMIT
keywords python h3 geospatial geopandas pandas integration hexagons-are-bestagons
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage
            <img align="left" src="https://i.imgur.com/OH8DoTA.png" alt="H3 Logo" width="500">


&nbsp;

# 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).
[![image](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/DahnJ/H3-Pandas/blob/master/notebook/00-intro.ipynb)
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/DahnJ/H3-Pandas/HEAD?filepath=%2Fnotebook%2F00-intro.ipynb)
[![image](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Documentation Status](https://readthedocs.org/projects/pip/badge/?version=stable)](https://pip.pypa.io/en/stable/?badge=stable)

&nbsp;


---

<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
[![image](https://img.shields.io/pypi/v/h3pandas.svg)](https://pypi.python.org/pypi/h3pandas)
```bash
pip install h3pandas
```

### conda
[![conda-version](https://anaconda.org/conda-forge/h3pandas/badges/version.svg)]()
[![Anaconda-Server Badge](https://anaconda.org/conda-forge/h3pandas/badges/downloads.svg)](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&nbsp;\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[![image](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/DahnJ/H3-Pandas/blob/master/notebook/00-intro.ipynb)\n[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/DahnJ/H3-Pandas/HEAD?filepath=%2Fnotebook%2F00-intro.ipynb)\n[![image](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Documentation Status](https://readthedocs.org/projects/pip/badge/?version=stable)](https://pip.pypa.io/en/stable/?badge=stable)\n\n&nbsp;\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[![image](https://img.shields.io/pypi/v/h3pandas.svg)](https://pypi.python.org/pypi/h3pandas)\n```bash\npip install h3pandas\n```\n\n### conda\n[![conda-version](https://anaconda.org/conda-forge/h3pandas/badges/version.svg)]()\n[![Anaconda-Server Badge](https://anaconda.org/conda-forge/h3pandas/badges/downloads.svg)](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"
}
        
Elapsed time: 0.16890s