https://github.com/geoarrow/geoarrow-python
Python implementation of the GeoArrow specification
https://github.com/geoarrow/geoarrow-python
geoarrow python
Last synced: about 1 year ago
JSON representation
Python implementation of the GeoArrow specification
- Host: GitHub
- URL: https://github.com/geoarrow/geoarrow-python
- Owner: geoarrow
- License: apache-2.0
- Created: 2023-08-09T15:58:29.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2025-04-30T22:05:53.000Z (about 1 year ago)
- Last Synced: 2025-04-30T23:19:52.352Z (about 1 year ago)
- Topics: geoarrow, python
- Language: Python
- Homepage: http://geoarrow.org/geoarrow-python/
- Size: 3.66 MB
- Stars: 78
- Watchers: 9
- Forks: 4
- Open Issues: 8
-
Metadata Files:
- Readme: README.ipynb
- License: LICENSE
Awesome Lists containing this project
README
{
"cells": [
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"# GeoArrow for Python\n",
"\n",
"The GeoArrow Python packages provide an implementation of the [GeoArrow specification](https://github.com/geoarrow/geoarrow) that integrates with [pyarrow](https://arrow.apache.org/docs/python) and [pandas](https://pandas.pydata.org/). The GeoArrow Python bindings enable input/output to/from Arrow-friendly formats (e.g., Parquet, Arrow Stream, Arrow File) and general-purpose coordinate shuffling tools among GeoArrow, WKT, and WKB encodings. \n",
"\n",
"## Installation\n",
"\n",
"Python bindings for GeoArrow are available on PyPI. You can install them with:\n",
"\n",
"```bash\n",
"pip install geoarrow-pyarrow geoarrow-pandas\n",
"```\n",
"\n",
"You can install the latest development versions with:\n",
"\n",
"```bash\n",
"pip install \"git+https://github.com/geoarrow/geoarrow-python.git#egg=geoarrow-pyarrow&subdirectory=geoarrow-pyarrow\"\n",
"pip install \"git+https://github.com/geoarrow/geoarrow-python.git#egg=geoarrow-pandas&subdirectory=geoarrow-pandas\"\n",
"```\n",
"\n",
"If you can import the namespaces, you're good to go!"
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [],
"source": [
"import geoarrow.pyarrow as ga\n",
"import geoarrow.pandas as _"
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"## Examples\n",
"\n",
"You can create geoarrow-encoded `pyarrow.Array`s with `as_geoarrow()`:"
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"PointArray:PointType(geoarrow.point)[1]\n",
""
]
},
"execution_count": 2,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"ga.as_geoarrow([\"POINT (0 1)\"])"
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"This will work with:\n",
"\n",
"- An existing array created by geoarrow\n",
"- A `geopandas.GeoSeries`\n",
"- A `pyarrow.Array` or `pyarrow.ChunkedArray` (geoarrow text interpreted as well-known text; binary interpreted as well-known binary)\n",
"- Anything that `pyarrow.array()` will convert to a text or binary array\n",
"\n",
"If there is no common geometry type among elements of the input, `as_geoarrow()` will fall back to well-known binary encoding. To explicitly convert to well-known text or binary, use `as_wkt()` or `as_wkb()`.\n",
"\n",
"Alternatively, you can construct GeoArrow arrays directly from a series of buffers as described in the specification:"
]
},
{
"cell_type": "code",
"execution_count": 3,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"PointArray:PointType(geoarrow.point)[3]\n",
"\n",
"\n",
""
]
},
"execution_count": 3,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"import numpy as np\n",
"\n",
"ga.point().from_geobuffers(\n",
" None, \n",
" np.array([1.0, 2.0, 3.0]),\n",
" np.array([3.0, 4.0, 5.0])\n",
")"
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"PointArray:PointType(interleaved geoarrow.point)[3]\n",
"\n",
"\n",
""
]
},
"execution_count": 4,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"ga.point().with_coord_type(ga.CoordType.INTERLEAVED).from_geobuffers(\n",
" None,\n",
" np.array([1.0, 2.0, 3.0, 4.0, 5.0, 6.0])\n",
")"
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"Importing `geoarrow.pyarrow` will register the geoarrow extension types with pyarrow such that you can read/write Arrow streams, Arrow files, and Parquet that contains Geoarrow extension types. A number of these files are available from the [geoarrow-data](https://github.com/geoarrow/geoarrow-data) repository."
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"OBJECTID: int64\n",
"FEAT_CODE: string\n",
"LINE_CLASS: int32\n",
"MISCID_1: string\n",
"MISCNAME_1: string\n",
"MISCID_2: string\n",
"MISCNAME_2: string\n",
"HID: string\n",
"MISCID_3: string\n",
"MISCNAME_3: string\n",
"MISCID_4: string\n",
"MISCNAME_4: string\n",
"SHAPE_LEN: double\n",
"geometry: extension>"
]
},
"execution_count": 5,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"import urllib.request\n",
"from pyarrow import feather\n",
"\n",
"url = \"https://github.com/geoarrow/geoarrow-data/releases/download/v0.1.0/ns-water-basin_line.arrow\"\n",
"local_filename, headers = urllib.request.urlretrieve(url)\n",
"feather.read_table(local_filename).schema"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The `as_geoarrow()` function can accept a `geopandas.GeoSeries` as input:"
]
},
{
"cell_type": "code",
"execution_count": 6,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"MultiLinestringArray:MultiLinestringType(geoarrow.multilinestring <{\"$schema\":\"https://proj.org/schem...>)[255]\n",
"\n",
"\n",
"\n",
"\n",
"\n",
"...245 values...\n",
"\n",
"\n",
"\n",
"\n",
""
]
},
"execution_count": 6,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"import geopandas\n",
"\n",
"url = \"https://github.com/geoarrow/geoarrow-data/releases/download/v0.1.0/ns-water-basin_line.fgb.zip\"\n",
"df = geopandas.read_file(url)\n",
"array = ga.as_geoarrow(df.geometry)\n",
"array"
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"You can convert back to geopandas using `to_geopandas()`:"
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"0 MULTILINESTRING ((648686.211 5099183.050, 6486...\n",
"1 MULTILINESTRING ((687688.017 5117030.253, 6867...\n",
"2 MULTILINESTRING ((631355.706 5122893.354, 6313...\n",
"3 MULTILINESTRING ((665166.211 5138643.057, 6651...\n",
"4 MULTILINESTRING ((673606.211 5162963.061, 6736...\n",
" ... \n",
"250 MULTILINESTRING ((681672.818 5078602.647, 6818...\n",
"251 MULTILINESTRING ((414868.067 5093041.934, 4147...\n",
"252 MULTILINESTRING ((414868.067 5093041.934, 4148...\n",
"253 MULTILINESTRING ((414868.067 5093041.934, 4149...\n",
"254 MULTILINESTRING ((648686.211 5099183.050, 6488...\n",
"Length: 255, dtype: geometry"
]
},
"execution_count": 7,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"ga.to_geopandas(array)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Pandas integration\n",
"\n",
"The `geoarrow-pandas` package provides an extension array that wraps geoarrow memory and an accessor that provides pandas-friendly wrappers around the compute functions available in `geoarrow.pyarrow`."
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"0 MULTIPOINT (277022.6936181751 4820886.609673489)\n",
"1 MULTIPOINT (315701.2552756762 4855051.378571571)\n",
"2 MULTIPOINT (255728.65994492616 4851022.107901295)\n",
"3 MULTIPOINT (245206.7841665779 4895609.409696873)\n",
"4 MULTIPOINT (337143.18135472975 4860312.288760258)\n",
"dtype: string[pyarrow]"
]
},
"execution_count": 8,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"import geoarrow.pandas as _\n",
"import pandas as pd\n",
"\n",
"df = pd.read_feather(\"https://github.com/geoarrow/geoarrow-data/releases/download/v0.1.0/ns-water-basin_point.arrow\")\n",
"df.geometry.geoarrow.format_wkt().head(5)"
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"## Building\n",
"\n",
"Python bindings for geoarrow are managed with [setuptools](https://setuptools.pypa.io/en/latest/index.html).\n",
"This means you can build the project using:\n",
"\n",
"```shell\n",
"git clone https://github.com/geoarrow/geoarrow-python.git\n",
"pip install -e geoarrow-pyarrow/ geoarrow-pandas/\n",
"```\n",
"\n",
"Tests use [pytest](https://docs.pytest.org/):\n",
"\n",
"```shell\n",
"pytest\n",
"```"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.11.2"
},
"orig_nbformat": 4
},
"nbformat": 4,
"nbformat_minor": 2
}