notebooks/quickstart.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction\n",
    "\n",
    "This notebook demonstrates the usage of `polars_h3`, a plugin extending the Polars DataFrame API with H3 geospatial functions.\n",
    "\n",
    "## What is H3?\n",
    "H3 is a hierarchical hexagonal geospatial indexing system. It assigns indexes to the surface of the Earth in a hexagonal grid at multiple resolutions. With `polars_h3`, you can integrate H3 operations directly into Polars workflows.\n",
    "\n",
    "## Prerequisites\n",
    "- Polars\n",
    "- polars_h3\n",
    "- H3 Python bindings\n",
    "\n",
    "Make sure these are installed in your environment.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# If needed, uncomment to install\n",
    "# !pip install polars polars_h3 h3"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "import polars as pl\n",
    "import polars_h3 as plh3\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Convert Latitude/Longitude to H3 Cell\n",
    "\n",
    "We can convert a given latitude and longitude to an H3 cell at a specified resolution.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div><style>\n",
       ".dataframe > thead > tr,\n",
       ".dataframe > tbody > tr {\n",
       "  text-align: right;\n",
       "  white-space: pre-wrap;\n",
       "}\n",
       "</style>\n",
       "<small>shape: (1, 3)</small><table border=\"1\" class=\"dataframe\"><thead><tr><th>latitude</th><th>longitude</th><th>h3_cell</th></tr><tr><td>f64</td><td>f64</td><td>u64</td></tr></thead><tbody><tr><td>37.77527</td><td>-122.418307</td><td>617700169958293503</td></tr></tbody></table></div>"
      ],
      "text/plain": [
       "shape: (1, 3)\n",
       "┌──────────┬─────────────┬────────────────────┐\n",
       "│ latitude ┆ longitude   ┆ h3_cell            │\n",
       "│ ---      ┆ ---         ┆ ---                │\n",
       "│ f64      ┆ f64         ┆ u64                │\n",
       "╞══════════╪═════════════╪════════════════════╡\n",
       "│ 37.77527 ┆ -122.418307 ┆ 617700169958293503 │\n",
       "└──────────┴─────────────┴────────────────────┘"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df = pl.DataFrame(\n",
    "    {\"latitude\": [37.7752702151959], \"longitude\": [-122.418307270836]}\n",
    ").with_columns(h3_cell=plh3.latlng_to_cell(\"latitude\", \"longitude\", 9))\n",
    "\n",
    "df\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Convert H3 Cell Back to Latitude/Longitude\n",
    "\n",
    "We can also retrieve the coordinates for the center of an H3 cell.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div><style>\n",
       ".dataframe > thead > tr,\n",
       ".dataframe > tbody > tr {\n",
       "  text-align: right;\n",
       "  white-space: pre-wrap;\n",
       "}\n",
       "</style>\n",
       "<small>shape: (1, 5)</small><table border=\"1\" class=\"dataframe\"><thead><tr><th>latitude</th><th>longitude</th><th>h3_cell</th><th>lat</th><th>lng</th></tr><tr><td>f64</td><td>f64</td><td>u64</td><td>f64</td><td>f64</td></tr></thead><tbody><tr><td>37.77527</td><td>-122.418307</td><td>617700169958293503</td><td>37.776702</td><td>-122.418459</td></tr></tbody></table></div>"
      ],
      "text/plain": [
       "shape: (1, 5)\n",
       "┌──────────┬─────────────┬────────────────────┬───────────┬─────────────┐\n",
       "│ latitude ┆ longitude   ┆ h3_cell            ┆ lat       ┆ lng         │\n",
       "│ ---      ┆ ---         ┆ ---                ┆ ---       ┆ ---         │\n",
       "│ f64      ┆ f64         ┆ u64                ┆ f64       ┆ f64         │\n",
       "╞══════════╪═════════════╪════════════════════╪═══════════╪═════════════╡\n",
       "│ 37.77527 ┆ -122.418307 ┆ 617700169958293503 ┆ 37.776702 ┆ -122.418459 │\n",
       "└──────────┴─────────────┴────────────────────┴───────────┴─────────────┘"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df_coords = df.with_columns(\n",
    "    lat=plh3.cell_to_lat(\"h3_cell\"), lng=plh3.cell_to_lng(\"h3_cell\")\n",
    ")\n",
    "\n",
    "df_coords\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Check Validity and Resolution of H3 Cells\n",
    "\n",
    "Use `is_valid_cell` and `get_resolution` to inspect cells.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div><style>\n",
       ".dataframe > thead > tr,\n",
       ".dataframe > tbody > tr {\n",
       "  text-align: right;\n",
       "  white-space: pre-wrap;\n",
       "}\n",
       "</style>\n",
       "<small>shape: (1, 5)</small><table border=\"1\" class=\"dataframe\"><thead><tr><th>latitude</th><th>longitude</th><th>h3_cell</th><th>is_valid</th><th>resolution</th></tr><tr><td>f64</td><td>f64</td><td>u64</td><td>bool</td><td>u32</td></tr></thead><tbody><tr><td>37.77527</td><td>-122.418307</td><td>617700169958293503</td><td>true</td><td>9</td></tr></tbody></table></div>"
      ],
      "text/plain": [
       "shape: (1, 5)\n",
       "┌──────────┬─────────────┬────────────────────┬──────────┬────────────┐\n",
       "│ latitude ┆ longitude   ┆ h3_cell            ┆ is_valid ┆ resolution │\n",
       "│ ---      ┆ ---         ┆ ---                ┆ ---      ┆ ---        │\n",
       "│ f64      ┆ f64         ┆ u64                ┆ bool     ┆ u32        │\n",
       "╞══════════╪═════════════╪════════════════════╪══════════╪════════════╡\n",
       "│ 37.77527 ┆ -122.418307 ┆ 617700169958293503 ┆ true     ┆ 9          │\n",
       "└──────────┴─────────────┴────────────────────┴──────────┴────────────┘"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df_inspect = df.with_columns(\n",
    "    is_valid=plh3.is_valid_cell(\"h3_cell\"),\n",
    "    resolution=plh3.get_resolution(\"h3_cell\"),\n",
    ")\n",
    "\n",
    "df_inspect\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Converting Between Integer and String H3 Representations\n",
    "\n",
    "H3 cells can be stored as 64-bit integers or hex strings. `int_to_str` and `str_to_int` can help convert between these.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div><style>\n",
       ".dataframe > thead > tr,\n",
       ".dataframe > tbody > tr {\n",
       "  text-align: right;\n",
       "  white-space: pre-wrap;\n",
       "}\n",
       "</style>\n",
       "<small>shape: (1, 5)</small><table border=\"1\" class=\"dataframe\"><thead><tr><th>latitude</th><th>longitude</th><th>h3_cell</th><th>h3_str</th><th>h3_int</th></tr><tr><td>f64</td><td>f64</td><td>u64</td><td>str</td><td>u64</td></tr></thead><tbody><tr><td>37.77527</td><td>-122.418307</td><td>617700169958293503</td><td>&quot;8928308280fffff&quot;</td><td>617700169958293503</td></tr></tbody></table></div>"
      ],
      "text/plain": [
       "shape: (1, 5)\n",
       "┌──────────┬─────────────┬────────────────────┬─────────────────┬────────────────────┐\n",
       "│ latitude ┆ longitude   ┆ h3_cell            ┆ h3_str          ┆ h3_int             │\n",
       "│ ---      ┆ ---         ┆ ---                ┆ ---             ┆ ---                │\n",
       "│ f64      ┆ f64         ┆ u64                ┆ str             ┆ u64                │\n",
       "╞══════════╪═════════════╪════════════════════╪═════════════════╪════════════════════╡\n",
       "│ 37.77527 ┆ -122.418307 ┆ 617700169958293503 ┆ 8928308280fffff ┆ 617700169958293503 │\n",
       "└──────────┴─────────────┴────────────────────┴─────────────────┴────────────────────┘"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df_int_str = df.with_columns(\n",
    "    h3_str=plh3.int_to_str(\"h3_cell\"),\n",
    "    h3_int=plh3.str_to_int(plh3.int_to_str(\"h3_cell\")),\n",
    ")\n",
    "\n",
    "df_int_str\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Finding Neighbors\n",
    "\n",
    "Given an H3 cell, we can find its neighbors at the same resolution.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div><style>\n",
       ".dataframe > thead > tr,\n",
       ".dataframe > tbody > tr {\n",
       "  text-align: right;\n",
       "  white-space: pre-wrap;\n",
       "}\n",
       "</style>\n",
       "<small>shape: (1, 4)</small><table border=\"1\" class=\"dataframe\"><thead><tr><th>latitude</th><th>longitude</th><th>h3_cell</th><th>neighbors</th></tr><tr><td>f64</td><td>f64</td><td>u64</td><td>list[u64]</td></tr></thead><tbody><tr><td>37.77527</td><td>-122.418307</td><td>617700169958293503</td><td>[617700169958293503, 617700169958031359, … 617700169957507071]</td></tr></tbody></table></div>"
      ],
      "text/plain": [
       "shape: (1, 4)\n",
       "┌──────────┬─────────────┬────────────────────┬─────────────────────────────────┐\n",
       "│ latitude ┆ longitude   ┆ h3_cell            ┆ neighbors                       │\n",
       "│ ---      ┆ ---         ┆ ---                ┆ ---                             │\n",
       "│ f64      ┆ f64         ┆ u64                ┆ list[u64]                       │\n",
       "╞══════════╪═════════════╪════════════════════╪═════════════════════════════════╡\n",
       "│ 37.77527 ┆ -122.418307 ┆ 617700169958293503 ┆ [617700169958293503, 617700169… │\n",
       "└──────────┴─────────────┴────────────────────┴─────────────────────────────────┘"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df_neighbors = df.with_columns(\n",
    "    neighbors=plh3.grid_disk(\"h3_cell\", 1)  # radius=1 ring around the cell\n",
    ")\n",
    "\n",
    "df_neighbors\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Directed Edges\n",
    "\n",
    "`polars_h3` lets you find directed edges between cells and perform operations on them.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div><style>\n",
       ".dataframe > thead > tr,\n",
       ".dataframe > tbody > tr {\n",
       "  text-align: right;\n",
       "  white-space: pre-wrap;\n",
       "}\n",
       "</style>\n",
       "<small>shape: (6, 6)</small><table border=\"1\" class=\"dataframe\"><thead><tr><th>latitude</th><th>longitude</th><th>h3_cell</th><th>edges</th><th>origin</th><th>destination</th></tr><tr><td>f64</td><td>f64</td><td>u64</td><td>u64</td><td>u64</td><td>u64</td></tr></thead><tbody><tr><td>37.77527</td><td>-122.418307</td><td>617700169958293503</td><td>1266218516299644927</td><td>617700169958293503</td><td>617700169961177087</td></tr><tr><td>37.77527</td><td>-122.418307</td><td>617700169958293503</td><td>1338276110337572863</td><td>617700169958293503</td><td>617700169964847103</td></tr><tr><td>37.77527</td><td>-122.418307</td><td>617700169958293503</td><td>1410333704375500799</td><td>617700169958293503</td><td>617700169965109247</td></tr><tr><td>37.77527</td><td>-122.418307</td><td>617700169958293503</td><td>1482391298413428735</td><td>617700169958293503</td><td>617700169957507071</td></tr><tr><td>37.77527</td><td>-122.418307</td><td>617700169958293503</td><td>1554448892451356671</td><td>617700169958293503</td><td>617700169957769215</td></tr><tr><td>37.77527</td><td>-122.418307</td><td>617700169958293503</td><td>1626506486489284607</td><td>617700169958293503</td><td>617700169958031359</td></tr></tbody></table></div>"
      ],
      "text/plain": [
       "shape: (6, 6)\n",
       "┌──────────┬─────────────┬──────────────────┬──────────────────┬─────────────────┬─────────────────┐\n",
       "│ latitude ┆ longitude   ┆ h3_cell          ┆ edges            ┆ origin          ┆ destination     │\n",
       "│ ---      ┆ ---         ┆ ---              ┆ ---              ┆ ---             ┆ ---             │\n",
       "│ f64      ┆ f64         ┆ u64              ┆ u64              ┆ u64             ┆ u64             │\n",
       "╞══════════╪═════════════╪══════════════════╪══════════════════╪═════════════════╪═════════════════╡\n",
       "│ 37.77527 ┆ -122.418307 ┆ 6177001699582935 ┆ 1266218516299644 ┆ 617700169958293 ┆ 617700169961177 │\n",
       "│          ┆             ┆ 03               ┆ 927              ┆ 503             ┆ 087             │\n",
       "│ 37.77527 ┆ -122.418307 ┆ 6177001699582935 ┆ 1338276110337572 ┆ 617700169958293 ┆ 617700169964847 │\n",
       "│          ┆             ┆ 03               ┆ 863              ┆ 503             ┆ 103             │\n",
       "│ 37.77527 ┆ -122.418307 ┆ 6177001699582935 ┆ 1410333704375500 ┆ 617700169958293 ┆ 617700169965109 │\n",
       "│          ┆             ┆ 03               ┆ 799              ┆ 503             ┆ 247             │\n",
       "│ 37.77527 ┆ -122.418307 ┆ 6177001699582935 ┆ 1482391298413428 ┆ 617700169958293 ┆ 617700169957507 │\n",
       "│          ┆             ┆ 03               ┆ 735              ┆ 503             ┆ 071             │\n",
       "│ 37.77527 ┆ -122.418307 ┆ 6177001699582935 ┆ 1554448892451356 ┆ 617700169958293 ┆ 617700169957769 │\n",
       "│          ┆             ┆ 03               ┆ 671              ┆ 503             ┆ 215             │\n",
       "│ 37.77527 ┆ -122.418307 ┆ 6177001699582935 ┆ 1626506486489284 ┆ 617700169958293 ┆ 617700169958031 │\n",
       "│          ┆             ┆ 03               ┆ 607              ┆ 503             ┆ 359             │\n",
       "└──────────┴─────────────┴──────────────────┴──────────────────┴─────────────────┴─────────────────┘"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Example: Convert a cell to its directed edges, then convert those edges back to their origin/destination.\n",
    "df_edges = df.with_columns(edges=plh3.origin_to_directed_edges(\"h3_cell\"))\n",
    "\n",
    "df_edges_explored = df_edges.explode(\"edges\").with_columns(\n",
    "    origin=plh3.get_directed_edge_origin(\"edges\"),\n",
    "    destination=plh3.get_directed_edge_destination(\"edges\"),\n",
    ")\n",
    "\n",
    "df_edges_explored\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Geospatial Metrics: Distances and Areas\n",
    "\n",
    "We can compute great circle distances between two lat/lng points and compute areas of H3 cells.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div><style>\n",
       ".dataframe > thead > tr,\n",
       ".dataframe > tbody > tr {\n",
       "  text-align: right;\n",
       "  white-space: pre-wrap;\n",
       "}\n",
       "</style>\n",
       "<small>shape: (1, 6)</small><table border=\"1\" class=\"dataframe\"><thead><tr><th>lat1</th><th>lng1</th><th>lat2</th><th>lng2</th><th>distance_km</th><th>distance_m</th></tr><tr><td>f64</td><td>f64</td><td>f64</td><td>f64</td><td>f64</td><td>f64</td></tr></thead><tbody><tr><td>40.7128</td><td>-74.006</td><td>42.3601</td><td>-71.0589</td><td>306.204589</td><td>306204.588543</td></tr></tbody></table></div>"
      ],
      "text/plain": [
       "shape: (1, 6)\n",
       "┌─────────┬─────────┬─────────┬──────────┬─────────────┬───────────────┐\n",
       "│ lat1    ┆ lng1    ┆ lat2    ┆ lng2     ┆ distance_km ┆ distance_m    │\n",
       "│ ---     ┆ ---     ┆ ---     ┆ ---      ┆ ---         ┆ ---           │\n",
       "│ f64     ┆ f64     ┆ f64     ┆ f64      ┆ f64         ┆ f64           │\n",
       "╞═════════╪═════════╪═════════╪══════════╪═════════════╪═══════════════╡\n",
       "│ 40.7128 ┆ -74.006 ┆ 42.3601 ┆ -71.0589 ┆ 306.204589  ┆ 306204.588543 │\n",
       "└─────────┴─────────┴─────────┴──────────┴─────────────┴───────────────┘"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df_metrics = pl.DataFrame(\n",
    "    {\n",
    "        \"lat1\": [40.7128],\n",
    "        \"lng1\": [-74.0060],  # New York\n",
    "        \"lat2\": [42.3601],\n",
    "        \"lng2\": [-71.0589],  # Boston\n",
    "    }\n",
    ").with_columns(\n",
    "    distance_km=plh3.great_circle_distance(\"lat1\", \"lng1\", \"lat2\", \"lng2\", \"km\"),\n",
    "    distance_m=plh3.great_circle_distance(\"lat1\", \"lng1\", \"lat2\", \"lng2\", \"m\"),\n",
    ")\n",
    "\n",
    "df_metrics\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Computing H3 Cell Area\n",
    "\n",
    "We can also compute the area of the H3 cell in km² or m².\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div><style>\n",
       ".dataframe > thead > tr,\n",
       ".dataframe > tbody > tr {\n",
       "  text-align: right;\n",
       "  white-space: pre-wrap;\n",
       "}\n",
       "</style>\n",
       "<small>shape: (16, 3)</small><table border=\"1\" class=\"dataframe\"><thead><tr><th>h3_resolution</th><th>area_km2</th><th>num_cells</th></tr><tr><td>i64</td><td>f64</td><td>i64</td></tr></thead><tbody><tr><td>0</td><td>4.3574e6</td><td>122</td></tr><tr><td>1</td><td>609788.441794</td><td>842</td></tr><tr><td>2</td><td>86801.780398</td><td>5882</td></tr><tr><td>3</td><td>12393.434655</td><td>41162</td></tr><tr><td>4</td><td>1770.347654</td><td>288122</td></tr><tr><td>&hellip;</td><td>&hellip;</td><td>&hellip;</td></tr><tr><td>11</td><td>0.002149</td><td>237279209162</td></tr><tr><td>12</td><td>0.000307</td><td>1660954464122</td></tr><tr><td>13</td><td>0.000043</td><td>11626681248842</td></tr><tr><td>14</td><td>0.000006</td><td>81386768741882</td></tr><tr><td>15</td><td>0.000015</td><td>569707381193162</td></tr></tbody></table></div>"
      ],
      "text/plain": [
       "shape: (16, 3)\n",
       "┌───────────────┬───────────────┬─────────────────┐\n",
       "│ h3_resolution ┆ area_km2      ┆ num_cells       │\n",
       "│ ---           ┆ ---           ┆ ---             │\n",
       "│ i64           ┆ f64           ┆ i64             │\n",
       "╞═══════════════╪═══════════════╪═════════════════╡\n",
       "│ 0             ┆ 4.3574e6      ┆ 122             │\n",
       "│ 1             ┆ 609788.441794 ┆ 842             │\n",
       "│ 2             ┆ 86801.780398  ┆ 5882            │\n",
       "│ 3             ┆ 12393.434655  ┆ 41162           │\n",
       "│ 4             ┆ 1770.347654   ┆ 288122          │\n",
       "│ …             ┆ …             ┆ …               │\n",
       "│ 11            ┆ 0.002149      ┆ 237279209162    │\n",
       "│ 12            ┆ 0.000307      ┆ 1660954464122   │\n",
       "│ 13            ┆ 0.000043      ┆ 11626681248842  │\n",
       "│ 14            ┆ 0.000006      ┆ 81386768741882  │\n",
       "│ 15            ┆ 0.000015      ┆ 569707381193162 │\n",
       "└───────────────┴───────────────┴─────────────────┘"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df_area = pl.DataFrame({\"h3_resolution\": list(range(0, 16))}).with_columns(\n",
    "    area_km2=plh3.average_hexagon_area(\"h3_resolution\", \"km^2\"),\n",
    "    num_cells=plh3.get_num_cells(\"h3_resolution\"),\n",
    ")\n",
    "\n",
    "df_area\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Conclusion\n",
    "\n",
    "This notebook provided a brief introduction to `polars_h3`. We covered:\n",
    "\n",
    "- Converting between lat/lng and H3 cells\n",
    "- Checking validity and resolution\n",
    "- Finding neighbors and directed edges\n",
    "- Computing distances and areas\n",
    "\n",
    "For more advanced use cases, refer to the documentation and the test files included with `polars_h3`.\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".venv",
   "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.12.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}