Skip to main content

Geospatial Neighborhood Analysis Package

Project description


The Geospatial Neighborhood Analysis Package

.github/workflows/unittests.yml codecov PyPI - Python Version PyPI Conda (channel only) Conda GitHub commits since latest release (branch) DOI

geosnap makes it easier to explore, model, analyze, and visualize the social and spatial dynamics of neighborhoods. Neighborhoods are important for a wide variety of reasons, but they’re hard to study because of some long-standing challenges, including that

  • there is no formal definition of a “neighborhood” so identifying and modeling them is fraught with uncertainty
  • many different physical and social data can characterize a neighborhood (e.g. its proximity to the urban core, its share of residents with a high school education, or the median price of its apartments) so there are countless ways to model neighborhoods by choosing different subsets of attributes
  • conceptually, neighborhoods evolve through both space and time, meaning their socially-construed boundaries can shift over time, as can their demographic makeup.
  • geographic tabulation units change boundaries over time, meaning the raw data are aggregated to different areal units at different points in time.

To address these challenges, geosnap provides a suite of tools for creating socio-spatial datasets, harmonizing those datasets into consistent set of time-static boundaries, modeling bespoke neighborhoods and prototypical neighborhood types, and modeling neighborhood change using classic and spatial statistical methods. It also provides a set of static and interactive visualization tools to help you display and understand the critical information at each step of the process.

Batteries Included: geosnap comes packed with 30 years of census data, thanks to quilt, so you can get started modeling neighborhoods in the U.S. immediately. But you’re not just limited to the data provided with the package. geosnap works with any data you provide, any place in the world.

DC Transitions


The recommended method for installing geosnap is with anaconda.

conda install -c conda-forge geosnap

geosnap is alaso available on PyPI and can be install with pip via

pip install geosnap

User Guide

See the User Guide for a gentle introduction to using geosnap for neighborhood research

API Documentation

See the API docs for a thorough explanation of geosnap's core functionality


the Community class is geosnap’s central data construct that holds space-time neighborhood data.
You can create a Community from geosnap’s built-in data by passing a set of fips codes to a constructor method

from geosnap import Community
dc = Community.from_census(state_fips='11')

Using the .from_census constructor, you’ll get 30 years of census tract data in their original boundaries with over a hundred commonly used demographic and socioeconomic variables. Data are stored as a long-form geodataframe under the gdf attribute

geoid geometry median_contract_rent median_home_value median_household_income median_income_asianhh median_income_blackhh median_income_hispanichh median_income_whitehh n_age_5_older ... p_unemployment_rate p_vacant_housing_units p_veterans p_vietnamese_persons p_white_over_60 p_white_over_65 p_white_under_15 p_widowed_divorced per_capita_income year
53214 11001001600 POLYGON ((-77.02680206298828 38.98410034179688... 477.0 285100.0 75252.0 NaN NaN NaN NaN 4.742191e+70 ... 0.0 2.58 1.028308e+08 0.00 3.159920e+25 4.999423e+17 1.378187e+24 0.0 32166.0 1990
53215 11001001500 POLYGON ((-77.05280303955078 38.98649978637695... 1001.0 366000.0 79681.0 NaN NaN NaN NaN 1.025723e+72 ... 0.0 3.38 7.095389e+07 0.23 6.529311e+30 1.483617e+23 6.816417e+33 0.0 36452.0 1990
53216 11001001701 POLYGON ((-77.02660369873047 38.97769927978516... 429.0 135600.0 34420.0 NaN NaN NaN NaN 6.918716e+64 ... 0.0 3.89 8.990532e+05 0.10 1.184601e+14 1.285720e+10 8.476736e+15 0.0 17782.0 1990
53217 11001001801 POLYGON ((-77.02660369873047 38.97769927978516... 1001.0 0.0 77197.0 NaN NaN NaN NaN 3.084115e+31 ... 0.0 10.00 5.229000e+01 0.00 1.450982e+11 1.437909e+08 1.321830e+14 0.0 14679.0 1990
53218 11001001702 POLYGON ((-77.00859832763672 38.97000122070312... 514.0 129300.0 42661.0 NaN NaN NaN NaN 4.210494e+62 ... 0.0 3.96 7.219278e+04 0.04 4.438992e+13 2.147213e+10 2.352939e+17 0.0 20468.0 1990

5 rows × 195 columns

you can create a geodemographic typology using classic clustering methods on the Community

dc = dc.cluster(method='kmeans', n_clusters=6, columns=['p_unemployment_rate', 'per_capita_income'] )

you can create a regionalization using spatially-constrained clustering methods on the Community

dc = dc.cluster_spatial(method='spenc', n_clusters=6, columns=['p_unemployment_rate', 'per_capita_income'] )

You can also harmonize Community boundaries so that they’re consistent over time. For example

 dc = dc.harmonize(2010, extensive_variables=["population"])

will create a new Community with population in 1990 and 2000 modeled as 2010 tract boundaries (2010 will remain unchanged). Thanks to tobler, geosnap provides several methods for harmonization, from simple areal interpolation to model-based approaches using auxiliary data. See the harmonization example for more code samples

You can explore datasets using a prototype interactive dashboard using

from geosnap.visualize import explore

By default, the dashboard will launch with built-in census data, but if you've stored other databases, then you can exlore those as well.

Many more visualization features coming soon


geosnap development is hosted on github

To get started with the development version, clone this repository or download it manually then cd into the directory and run the following commands:

conda env create -f environment.yml
conda activate geosnap 
python develop

This will download the appropriate dependencies and install geosnap in its own conda environment.

Bug reports

To search for or report bugs, please see geosnap’s issues

License information

See the file “LICENSE.txt” for information on the history of this software, terms & conditions for usage, and a DISCLAIMER OF ALL WARRANTIES.


For a generic citation of geosnap, we recommend the following:

author = {Knaap, Elijah and Kang, Wei and Rey, Sergio and Wolf, Levi John and Cortes, Renan Xavier and Han, Su},
doi = {10.5281/ZENODO.3526163},
title = {{geosnap: The Geospatial Neighborhood Analysis Package}},
url = {},
year = {2019}

If you need to cite a specific release of the package, please find the appropriate version on Zenodo


This project is supported by NSF Award #1733705, Neighborhoods in Space-Time Contexts

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for geosnap, version 0.6.0
Filename, size File type Python version Upload date Hashes
Filename, size geosnap-0.6.0-py3-none-any.whl (909.7 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size geosnap-0.6.0.tar.gz (893.4 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page