Skip to main content

EarthAI Platform Support Portal

Spatial Join in GeoPandas

Brown, Jason
  • Updated

A spatial join operation is analogous to a database table join or DataFrame merge operation, but considers the geographic relationships between records. In the context of EarthAI Notebooks, a spatial join is an operation that merges two DataFrames, each having a geometric object column, by some spatial relationship of their geometries.

The spatial join is important because it allows a variety of geographic data sources to be combined and reasoned over. We can use spatial joins to combine domain-specific information with raster @ref:catalogs.

This page discusses the case where both of the DataFrames are GeoPandas GeoDataFrames. The same example is presented for PySpark DataFrames in @ref:this page.

Let's get started with some basic imports.

In [1]:
from earthai.all import *

import geopandas
from shapely.geometry import Point

%matplotlib inline
Importing EarthAI libraries.
EarthAI version 1.4.0; RasterFrames version 0.9.0.dev+astraea.1ce1ff3; PySpark version 2.4.4

Read Vector Data

We will read some vector data describing boundaries of states in the US. We will read it as a GeoDataFrame, which is a Pandas DataFrame with extras for handling vector data! We filter just to the states of Alabama and Arkansas to keep our example simple.

In [2]:
geo_admin_url = 'https://raw.githubusercontent.com/datasets/geo-admin1-us/master/data/admin1-us.geojson'
adm1 = geopandas.read_file(geo_admin_url).drop(columns='id')
adm1_alar = adm1[adm1.state_code.isin(['AL', 'AR'])]
adm1_alar.plot()
Out[2]:
<matplotlib.axes._subplots.AxesSubplot at 0x7f2dd76fa950>

Now we will construct a small DataFrame containing city locations as point geometries. Note the inclusion of Charlotte, North Carolina.

In [3]:
city_df = geopandas.GeoDataFrame([
    {'city_name': 'Hot Springs', 'geom': Point(-93.055278, 34.497222)},
    {'city_name': 'Tuscaloosa', 'geom': Point(-87.534607, 33.20654)},
    {'city_name': 'Mobile', 'geom': Point(-88.043056, 30.694444)},
    {'city_name': 'Little Rock', 'geom': Point(-92.331111, 34.736111)},
    {'city_name': 'Charlotte', 'geom': Point(-80.843056, 35.227222)}
], geometry='geom', crs='epsg:4326')

city_df
Out[3]:
city_name geom
0 Hot Springs POINT (-93.05528 34.49722)
1 Tuscaloosa POINT (-87.53461 33.20654)
2 Mobile POINT (-88.04306 30.69444)
3 Little Rock POINT (-92.33111 34.73611)
4 Charlotte POINT (-80.84306 35.22722)

Spatial Join

We use the GeoPandas implementation of [spatial join called sjoin][gpd_sjoin]. Let's join the city as the left hand side. We see that the resulting DataFrame has a single geometric column on it, from the left hand side. We will plot coloring the city locations by state that is found from the joined data.

In [4]:
sjoin_city_state = geopandas.sjoin(city_df, adm1_alar)
sjoin_city_state.plot(column='state_code', cmap='Paired')
Out[4]:
<matplotlib.axes._subplots.AxesSubplot at 0x7f2dd50fff90>

If we invert the join, we see the state polygon is the resulting geometry column.

In [5]:
sjoin_state_city = geopandas.sjoin(adm1_alar, city_df)
sjoin_state_city.plot(column='state_code', cmap='Paired')
Out[5]:
<matplotlib.axes._subplots.AxesSubplot at 0x7f2dd50acc50>

But observe the contents of the DataFrame are otherwise equivalent. The attribute columns are the same.

In [6]:
sorted(sjoin_state_city.columns), sorted(sjoin_city_state.columns)
Out[6]:
(['ISO3166-1-Alpha-3',
  'city_name',
  'country',
  'geometry',
  'index_right',
  'name',
  'state_code'],
 ['ISO3166-1-Alpha-3',
  'city_name',
  'country',
  'geom',
  'index_right',
  'name',
  'state_code'])

And the number of records is the same. That means that each state geometry is repeated for each intersecting city.

In [7]:
len(sjoin_state_city), len(sjoin_city_state)
Out[7]:
(4, 4)

Left Outer Join

As discussed on the [GeoPandas docs][gpd_sjoin], we can also tailor the join operation and spatial predicate used. For example, if we do a left join we will get Charlotte, NC in the resulting DataFrame.

In [8]:
geopandas.sjoin(city_df, adm1_alar, how='left')
Out[8]:
city_name geom index_right name country ISO3166-1-Alpha-3 state_code
0 Hot Springs POINT (-93.05528 34.49722) 14.0 Arkansas United States of America USA AR
1 Tuscaloosa POINT (-87.53461 33.20654) 28.0 Alabama United States of America USA AL
2 Mobile POINT (-88.04306 30.69444) 28.0 Alabama United States of America USA AL
3 Little Rock POINT (-92.33111 34.73611) 14.0 Arkansas United States of America USA AR
4 Charlotte POINT (-80.84306 35.22722) NaN NaN NaN NaN NaN

Related articles

Comments

0 comments

Article is closed for comments.