diff --git a/notebooks/3-lsib-demo.ipynb b/notebooks/3-lsib-demo.ipynb
index 839bfef..1dead17 100644
--- a/notebooks/3-lsib-demo.ipynb
+++ b/notebooks/3-lsib-demo.ipynb
@@ -6,8 +6,6 @@
"metadata": {},
"source": [
"# Demo: matching LSIB data and Overture's divisions data\n",
- "**Workshop demo for NGA + Esri, May 2026**\n",
- "**~15 min runtime.**\n",
"\n",
"This notebook steps through the process of matching LSIB and Overture data and building a crosswalk file that links LSIB IDs and Overture's GERS IDs.\n",
"\n",
@@ -32,8 +30,8 @@
"\n",
"| LSIB ID | GERS ID | match_class | \n",
"| ----- | ----- | ----- | \n",
- "| UUID 1 | UUID 2 | match | \n",
- "| UUID 1 | UUID 2 | review | \n",
+ "| LSIB UUID | Overture UUID | match | \n",
+ "| LSIB UUID | Overture UUID | review | \n",
"\n",
"A few framing notes that will help orient the rest of the notebook:\n",
"\n",
@@ -74,7 +72,7 @@
},
{
"cell_type": "code",
- "execution_count": null,
+ "execution_count": 20,
"id": "322d4e18-2ad3-4993-9dfa-5a7384e12748",
"metadata": {},
"outputs": [],
@@ -97,22 +95,37 @@
},
{
"cell_type": "code",
- "execution_count": null,
+ "execution_count": 21,
"id": "cf18a867-c065-4091-add2-cdd72e80db45",
"metadata": {},
"outputs": [],
"source": [
- "# Load LSIB\n",
+ "# Set paths for LSIB\n",
"# Download DoS_LSIB_v11_4_24Feb2025.gpkg from geodata.state.gov and place it in the data/ directory before running this cell.\n",
- "LSIB_PATH = DATA / \"DoS_LSIB_v11_4_24Feb2025.gpkg\""
+ "LSIB_PATH = DATA / \"DoS_LSIB_v11_4_24Feb2025.gpkg\"\n",
+ "LSIB_LAYER = \"Department of State LSIB v11.4 24Feb2025\"\n",
+ "\n",
+ "# Set paths for Overture\n",
+ "# division_boundary: the linear features we'll match against LSIB\n",
+ "# division: filtered to subtype='country', used as a UUID -> country-code lookup\n",
+ "OVT_BOUNDARY_S3 = f\"s3://overturemaps-us-west-2/release/{OVERTURE_RELEASE}/theme=divisions/type=division_boundary/*\"\n",
+ "OVT_DIVISION_S3 = f\"s3://overturemaps-us-west-2/release/{OVERTURE_RELEASE}/theme=divisions/type=division/*\"\n"
]
},
{
"cell_type": "code",
- "execution_count": null,
+ "execution_count": 22,
"id": "1073e433-d008-4a82-a56d-02856c240f7d",
"metadata": {},
- "outputs": [],
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Using Overture release: 2026-04-15.0\n"
+ ]
+ }
+ ],
"source": [
"import pystac\n",
"\n",
@@ -126,7 +139,7 @@
},
{
"cell_type": "code",
- "execution_count": null,
+ "execution_count": 23,
"id": "6d13865a-b19d-4cc1-b732-c183e3738995",
"metadata": {},
"outputs": [],
@@ -137,10 +150,18 @@
},
{
"cell_type": "code",
- "execution_count": null,
+ "execution_count": 24,
"id": "ff860c5e",
"metadata": {},
- "outputs": [],
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "DuckDB ready.\n"
+ ]
+ }
+ ],
"source": [
"# DuckDB with anonymous S3 access for Overture's public bucket.\n",
"con = duckdb.connect()\n",
@@ -197,10 +218,21 @@
},
{
"cell_type": "code",
- "execution_count": null,
+ "execution_count": 25,
"id": "95a39a10",
"metadata": {},
- "outputs": [],
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "LSIB rows: 395\n",
+ "CRS: EPSG:4326\n",
+ "LSIB after dropping Q2: 381\n",
+ "Unique LSIB pair keys: 357\n"
+ ]
+ }
+ ],
"source": [
"# Load LSIB\n",
"lsib = gpd.read_file(LSIB_PATH, layer=LSIB_LAYER)\n",
@@ -241,10 +273,32 @@
},
{
"cell_type": "code",
- "execution_count": null,
+ "execution_count": 26,
"id": "72610dc9",
"metadata": {},
- "outputs": [],
+ "outputs": [
+ {
+ "data": {
+ "application/vnd.jupyter.widget-view+json": {
+ "model_id": "45ad561ff7e24a9a9370bc64dbf0e351",
+ "version_major": 2,
+ "version_minor": 0
+ },
+ "text/plain": [
+ "FloatProgress(value=0.0, layout=Layout(width='auto'), style=ProgressStyle(bar_color='black'))"
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ },
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Overture country divisions: 219\n"
+ ]
+ }
+ ],
"source": [
"# Load Overture `division` data for the country subtype to create the id->country lookup\n",
"countries_sql = f\"\"\"\n",
@@ -258,10 +312,33 @@
},
{
"cell_type": "code",
- "execution_count": null,
+ "execution_count": 27,
"id": "bb1a41d5",
"metadata": {},
- "outputs": [],
+ "outputs": [
+ {
+ "data": {
+ "application/vnd.jupyter.widget-view+json": {
+ "model_id": "fa776d20d53f4689b92c1bf03b9030f5",
+ "version_major": 2,
+ "version_minor": 0
+ },
+ "text/plain": [
+ "FloatProgress(value=0.0, layout=Layout(width='auto'), style=ProgressStyle(bar_color='black'))"
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ },
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Country-to-country Overture boundaries: 363\n",
+ "Unique Overture pair keys: 338\n"
+ ]
+ }
+ ],
"source": [
"# Pull all is_land=true boundary features from Overture `division_boundary` data.\n",
"# This includes boundaries at every administrative level: country-to-country,\n",
@@ -326,10 +403,18 @@
},
{
"cell_type": "code",
- "execution_count": null,
+ "execution_count": 28,
"id": "8c331ccf",
"metadata": {},
- "outputs": [],
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Reprojected to EPSG:6933 for metric computation.\n"
+ ]
+ }
+ ],
"source": [
"# Reproject both to metric CRS for length and buffer math\n",
"lsib_m = lsib.to_crs(METRIC_CRS)\n",
@@ -376,10 +461,66 @@
},
{
"cell_type": "code",
- "execution_count": null,
+ "execution_count": 29,
"id": "4ffee043",
"metadata": {},
- "outputs": [],
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "=== LSIB v11.4 ===\n",
+ "Rows: 381\n",
+ "Geometry: ['MultiLineString']\n",
+ "\n",
+ "Columns and dtypes:\n",
+ "CC1 str\n",
+ "CC1_GENC3 str\n",
+ "CC1_WPID str\n",
+ "COUNTRY1 str\n",
+ "CC2 str\n",
+ "CC2_GENC3 str\n",
+ "CC2_WPID str\n",
+ "COUNTRY2 str\n",
+ "RANK str\n",
+ "LABEL str\n",
+ "STATUS str\n",
+ "NOTES str\n",
+ "ID str\n",
+ "ANTECIDS str\n",
+ "PREVIDS str\n",
+ "PARENTID str\n",
+ "PARENTSEG object\n",
+ "geometry geometry\n",
+ "cc1_iso str\n",
+ "cc2_iso str\n",
+ "pair_key str\n",
+ "\n",
+ "First row (transposed for readability):\n",
+ "CC1 AF\n",
+ "CC1_GENC3 AFG\n",
+ "CC1_WPID 5c56cf7d-c485-4659-9399-5c17e9003112\n",
+ "COUNTRY1 AFGHANISTAN\n",
+ "CC2 CN\n",
+ "CC2_GENC3 CHN\n",
+ "CC2_WPID 422131df-82bc-4f1b-9a1f-ee89cc970e19\n",
+ "COUNTRY2 CHINA\n",
+ "RANK 1\n",
+ "LABEL NaN\n",
+ "STATUS International Boundary\n",
+ "NOTES NaN\n",
+ "ID 4990410a-4158-4932-8445-90397c840a87\n",
+ "ANTECIDS NaN\n",
+ "PREVIDS 4990410a-4158-4932-8445-90397c840a87\n",
+ "PARENTID NaN\n",
+ "PARENTSEG None\n",
+ "geometry MULTILINESTRING ((74.88986200000005 37.2340899...\n",
+ "cc1_iso AF\n",
+ "cc2_iso CN\n",
+ "pair_key AF|CN\n"
+ ]
+ }
+ ],
"source": [
"# LSIB columns and types\n",
"print(\"=== LSIB v11.4 ===\")\n",
@@ -395,10 +536,31 @@
},
{
"cell_type": "code",
- "execution_count": null,
+ "execution_count": 30,
"id": "44e32a3b",
"metadata": {},
- "outputs": [],
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "=== Overture division (subtype='country') ===\n",
+ "Rows: 219\n",
+ "\n",
+ "Columns and dtypes:\n",
+ "id str\n",
+ "country str\n",
+ "\n",
+ "First few rows:\n",
+ " id country\n",
+ "0 a92c1621-fad0-4bdd-963b-9623f7514df2 WS\n",
+ "1 fef8748b-0c91-46ad-9f2d-976d8d2de3e9 TO\n",
+ "2 577750a0-cfee-454d-996c-dd5867f185ee EC\n",
+ "3 449b9525-0be3-4a9a-bf19-d65f07f7e81e PE\n",
+ "4 1b152fd1-e23c-497e-befe-b3c1e8644ed5 NI\n"
+ ]
+ }
+ ],
"source": [
"# Overture `division` (filtered to subtype='country') — the lookup table\n",
"print(\"=== Overture division (subtype='country') ===\")\n",
@@ -413,10 +575,42 @@
},
{
"cell_type": "code",
- "execution_count": null,
+ "execution_count": 31,
"id": "af29296d",
"metadata": {},
- "outputs": [],
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "=== Overture division_boundary (filtered to is_land, country-to-country) ===\n",
+ "Rows: 363\n",
+ "Geometry: ['LineString', 'MultiLineString']\n",
+ "\n",
+ "Columns and dtypes:\n",
+ "id str\n",
+ "division_ids object\n",
+ "is_disputed bool\n",
+ "is_land bool\n",
+ "is_territorial bool\n",
+ "cc_left str\n",
+ "cc_right str\n",
+ "pair_key str\n",
+ "geometry geometry\n",
+ "\n",
+ "First row (transposed for readability):\n",
+ "id ce592c92-7c1f-3e07-92f7-afbe10114a5b\n",
+ "division_ids [fc20aaf8-7a12-4cb2-9b0b-ebb1a4b652aa, 388f999...\n",
+ "is_disputed False\n",
+ "is_land True\n",
+ "is_territorial False\n",
+ "cc_left MX\n",
+ "cc_right GT\n",
+ "pair_key GT|MX\n",
+ "geometry LINESTRING (-92.2283178 14.5310748, -92.227722...\n"
+ ]
+ }
+ ],
"source": [
"# Overture division_boundary columns and types\n",
"print(\"=== Overture division_boundary (filtered to is_land, country-to-country) ===\")\n",
@@ -482,10 +676,26 @@
},
{
"cell_type": "code",
- "execution_count": null,
+ "execution_count": 32,
"id": "9efe8fc7",
"metadata": {},
- "outputs": [],
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "bucket\n",
+ "clean_1_to_1 301\n",
+ "lsib_only 38\n",
+ "overture_only 19\n",
+ "fragmented 14\n",
+ "both_fragmented 4\n",
+ "Name: count, dtype: int64\n",
+ "\n",
+ "Total pairs: 376\n"
+ ]
+ }
+ ],
"source": [
"# Count features per pair on each side\n",
"lsib_counts = lsib_m.groupby(\"pair_key\").size().rename(\"n_lsib\")\n",
@@ -548,10 +758,24 @@
},
{
"cell_type": "code",
- "execution_count": null,
+ "execution_count": 33,
"id": "a066cd8e",
"metadata": {},
- "outputs": [],
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "LSIB features for AR|BR: 1\n",
+ "Overture features for AR|BR: 2\n",
+ " overlap_lsib: 0.9846\n",
+ " overlap_ovt: 0.9791\n",
+ " length_ratio: 0.9958\n",
+ " len_lsib_m: 1,282,040.4927\n",
+ " len_ovt_m: 1,287,422.3779\n"
+ ]
+ }
+ ],
"source": [
"def overlap_metrics(lsib_geom, ovt_geom, tolerance_m=250):\n",
" \"\"\"Compute bidirectional overlap and length ratio between two geometries.\n",
@@ -652,10 +876,124 @@
},
{
"cell_type": "code",
- "execution_count": null,
+ "execution_count": 34,
"id": "5fc9a92c",
"metadata": {},
- "outputs": [],
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Scoring 319 pairs...\n",
+ "Scored 319 pairs.\n"
+ ]
+ },
+ {
+ "data": {
+ "text/html": [
+ "\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " | \n",
+ " pair_key | \n",
+ " bucket | \n",
+ " overlap_lsib | \n",
+ " overlap_ovt | \n",
+ " length_ratio | \n",
+ " len_lsib_m | \n",
+ " len_ovt_m | \n",
+ "
\n",
+ " \n",
+ " \n",
+ " \n",
+ " | 0 | \n",
+ " AD|ES | \n",
+ " clean_1_to_1 | \n",
+ " 0.954292 | \n",
+ " 0.940533 | \n",
+ " 0.987315 | \n",
+ " 66291.347084 | \n",
+ " 67143.064109 | \n",
+ "
\n",
+ " \n",
+ " | 1 | \n",
+ " AD|FR | \n",
+ " clean_1_to_1 | \n",
+ " 1.000000 | \n",
+ " 1.000000 | \n",
+ " 0.986514 | \n",
+ " 61418.812980 | \n",
+ " 60590.493463 | \n",
+ "
\n",
+ " \n",
+ " | 2 | \n",
+ " AE|OM | \n",
+ " clean_1_to_1 | \n",
+ " 0.919314 | \n",
+ " 0.900602 | \n",
+ " 0.973507 | \n",
+ " 611390.572083 | \n",
+ " 628029.209635 | \n",
+ "
\n",
+ " \n",
+ " | 3 | \n",
+ " AE|SA | \n",
+ " clean_1_to_1 | \n",
+ " 0.695048 | \n",
+ " 0.695773 | \n",
+ " 0.999559 | \n",
+ " 445127.424700 | \n",
+ " 444930.971054 | \n",
+ "
\n",
+ " \n",
+ " | 4 | \n",
+ " AF|CN | \n",
+ " clean_1_to_1 | \n",
+ " 0.965696 | \n",
+ " 0.985312 | \n",
+ " 0.979614 | \n",
+ " 94400.992972 | \n",
+ " 92476.491563 | \n",
+ "
\n",
+ " \n",
+ "
\n",
+ "
"
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
"source": [
"# Histograms of the two metrics, with the 0.95 match threshold marked\n",
"import matplotlib.pyplot as plt\n",
@@ -775,10 +1158,23 @@
},
{
"cell_type": "code",
- "execution_count": null,
+ "execution_count": 37,
"id": "4e9bb92c",
"metadata": {},
- "outputs": [],
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "match_class\n",
+ "match 169\n",
+ "geometric_disagreement 100\n",
+ "review 45\n",
+ "unmatched 5\n",
+ "Name: count, dtype: int64\n"
+ ]
+ }
+ ],
"source": [
"def classify_match(row, match_thresh=0.95, length_thresh=0.95, floor=0.10):\n",
" if pd.isna(row.overlap_lsib) or pd.isna(row.overlap_ovt):\n",
@@ -818,10 +1214,140 @@
},
{
"cell_type": "code",
- "execution_count": null,
+ "execution_count": 38,
"id": "a612964e",
"metadata": {},
- "outputs": [],
+ "outputs": [
+ {
+ "data": {
+ "text/html": [
+ "\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " | \n",
+ " bucket | \n",
+ " match_class | \n",
+ " len_lsib_m | \n",
+ " len_ovt_m | \n",
+ " length_ratio | \n",
+ " overlap_lsib | \n",
+ " overlap_ovt | \n",
+ "
\n",
+ " \n",
+ " | pair_key | \n",
+ " | \n",
+ " | \n",
+ " | \n",
+ " | \n",
+ " | \n",
+ " | \n",
+ " | \n",
+ "
\n",
+ " \n",
+ " \n",
+ " \n",
+ " | AR|BR | \n",
+ " fragmented | \n",
+ " match | \n",
+ " 1.282040e+06 | \n",
+ " 1.287422e+06 | \n",
+ " 0.995820 | \n",
+ " 0.984609 | \n",
+ " 0.979073 | \n",
+ "
\n",
+ " \n",
+ " | NO|SE | \n",
+ " clean_1_to_1 | \n",
+ " match | \n",
+ " 1.910568e+06 | \n",
+ " 1.854913e+06 | \n",
+ " 0.970870 | \n",
+ " 0.971018 | \n",
+ " 1.000000 | \n",
+ "
\n",
+ " \n",
+ " | DE|LU | \n",
+ " clean_1_to_1 | \n",
+ " unmatched | \n",
+ " 6.627805e+03 | \n",
+ " 1.389564e+05 | \n",
+ " 0.047697 | \n",
+ " 1.000000 | \n",
+ " 0.053010 | \n",
+ "
\n",
+ " \n",
+ " | MY|SG | \n",
+ " clean_1_to_1 | \n",
+ " unmatched | \n",
+ " 8.291065e+04 | \n",
+ " 4.368652e+01 | \n",
+ " 0.000527 | \n",
+ " 0.006549 | \n",
+ " 1.000000 | \n",
+ "
\n",
+ " \n",
+ " | IN|PK | \n",
+ " fragmented | \n",
+ " geometric_disagreement | \n",
+ " 3.158016e+06 | \n",
+ " 3.120645e+06 | \n",
+ " 0.988166 | \n",
+ " 0.919869 | \n",
+ " 0.930455 | \n",
+ "
\n",
+ " \n",
+ " | KE|SS | \n",
+ " both_fragmented | \n",
+ " unmatched | \n",
+ " 3.105996e+05 | \n",
+ " 4.212717e+05 | \n",
+ " 0.737290 | \n",
+ " 0.031459 | \n",
+ " 0.022859 | \n",
+ "
\n",
+ " \n",
+ "
\n",
+ "