Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions .github/workflows/pre-commit.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
---
name: pre-commit

on:
pull_request:
push:
branches: [main]

jobs:
checks:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v6
- uses: pre-commit/action@v3.0.1
1 change: 0 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -141,4 +141,3 @@ checklink/cookies.txt

# .gitconfig is now autogenerated
.gitconfig

2 changes: 1 addition & 1 deletion .jupyter/desktop-settings.json
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
{
"pythonPath": "/home/kyle/anaconda3/envs/tigris/bin/python"
}
}
Original file line number Diff line number Diff line change
@@ -1 +1 @@
{"data":{"layout-restorer:data":{"main":{"dock":{"type":"tab-area","currentIndex":1,"widgets":["notebook:docs/03-data-utilities.ipynb","notebook:Untitled.ipynb"]},"current":"notebook:Untitled.ipynb"},"down":{"size":0,"widgets":[]},"left":{"collapsed":false,"current":"filebrowser","widgets":["filebrowser","running-sessions","@jupyterlab/toc:plugin","extensionmanager.main-view"]},"right":{"collapsed":true,"widgets":["jp-property-inspector","debugger-sidebar"]},"relativeSizes":[0.17988593974175035,0.8201140602582496,0]},"file-browser-filebrowser:cwd":{"path":""},"notebook:docs/03-data-utilities.ipynb":{"data":{"path":"docs/03-data-utilities.ipynb","factory":"Notebook"}},"notebook:Untitled.ipynb":{"data":{"path":"Untitled.ipynb","factory":"Notebook"}}},"metadata":{"id":"default"}}
{"data":{"layout-restorer:data":{"main":{"dock":{"type":"tab-area","currentIndex":1,"widgets":["notebook:docs/03-data-utilities.ipynb","notebook:Untitled.ipynb"]},"current":"notebook:Untitled.ipynb"},"down":{"size":0,"widgets":[]},"left":{"collapsed":false,"current":"filebrowser","widgets":["filebrowser","running-sessions","@jupyterlab/toc:plugin","extensionmanager.main-view"]},"right":{"collapsed":true,"widgets":["jp-property-inspector","debugger-sidebar"]},"relativeSizes":[0.17988593974175035,0.8201140602582496,0]},"file-browser-filebrowser:cwd":{"path":""},"notebook:docs/03-data-utilities.ipynb":{"data":{"path":"docs/03-data-utilities.ipynb","factory":"Notebook"}},"notebook:Untitled.ipynb":{"data":{"path":"Untitled.ipynb","factory":"Notebook"}}},"metadata":{"id":"default"}}
20 changes: 20 additions & 0 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
---
ci:
autofix_prs: false

repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.13.3
hooks:
- id: ruff-check
args: [--fix, --exit-non-zero-on-fix]
- id: ruff-format
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v6.0.0
hooks:
- id: debug-statements
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-yaml
- id: check-toml
- id: check-added-large-files
2 changes: 1 addition & 1 deletion LICENSE
Original file line number Diff line number Diff line change
Expand Up @@ -4,4 +4,4 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
2 changes: 1 addition & 1 deletion MANIFEST.in
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
include pygris/internals/*.csv
include requirements.txt
include requirements.txt
27 changes: 25 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
## pygris

__pygris__ is a Python package to help users access US Census Bureau TIGER/Line and cartographic boundary shapefiles and load them into Python as GeoDataFrames. The goal of the package is to make it simple to access US Census geographic data; data can be acquired with a single function for a given geography (e.g. `tracts()` for Census tracts) along with a few options.
__pygris__ is a Python package to help users access US Census Bureau TIGER/Line and cartographic boundary shapefiles and load them into Python as GeoDataFrames. The goal of the package is to make it simple to access US Census geographic data; data can be acquired with a single function for a given geography (e.g. `tracts()` for Census tracts) along with a few options.

The package is a general port of the [R __tigris__ package](https://github.com/walkerke/tigris) with a few modifications. The framework of and philosophy behind the __tigris__ package is covered in [Chapter 5 of my book, _Analyzing US Census Data: Methods, Maps and Models in R_](https://walker-data.com/census-r/census-geographic-data-and-applications-in-r.html).
The package is a general port of the [R __tigris__ package](https://github.com/walkerke/tigris) with a few modifications. The framework of and philosophy behind the __tigris__ package is covered in [Chapter 5 of my book, _Analyzing US Census Data: Methods, Maps and Models in R_](https://walker-data.com/census-r/census-geographic-data-and-applications-in-r.html).

Install __pygris__ from PyPI with the following command:

Expand Down Expand Up @@ -36,3 +36,26 @@ Read the following articles for more information on how to use the package:
* [Working with geometries in pygris](https://walker-data.com/pygris/02-geometries)
* [Data utilities in pygris](https://walker-data.com/pygris/03-data-utilities)
* [Geocoding and custom filters in pygris](https://walker-data.com/pygris/04-geocoding)

## Contributing

Contributions are welcome. This repository uses [pre-commit](https://pre-commit.com/) to run lint checks and code formatting (via [ruff](https://docs.astral.sh/ruff/)) on every commit, and the same checks run on every pull request in continuous integration.

To set it up:

```bash
pip install pre-commit
pre-commit install
```

The configured checks will then run automatically when you create a commit. To run them against all files in the repository manually:

```bash
pre-commit run --all-files
```

If a check fails:

* Formatting checks (like `ruff-format`, `trailing-whitespace`, and `end-of-file-fixer`) will typically fix the files automatically. Add the modified files and create the commit again.
* Check errors that don't modify files (like `ruff-check` findings) need to be fixed manually before re-committing. Some warnings can be suppressed with a `# noqa` comment where the rule is not applicable; see the [ruff rules documentation](https://docs.astral.sh/ruff/rules/) for details.
* If a check fails, the same failure will show up as a failing check on your pull request, so it is easiest to resolve them locally before submitting.
15 changes: 8 additions & 7 deletions docs/01-basic-usage.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@
"source": [
"import pygris\n",
"\n",
"ny_roads = pygris.roads(state = \"NY\", county = \"New York\")\n",
"ny_roads = pygris.roads(state=\"NY\", county=\"New York\")\n",
"\n",
"ny_roads.plot()"
]
Expand Down Expand Up @@ -100,19 +100,20 @@
}
],
"source": [
"from pygris import counties\n",
"import matplotlib.pyplot as plt\n",
"\n",
"from pygris import counties\n",
"\n",
"# Get the default TIGER/Line file for counties in Michigan\n",
"mi_tiger = counties(state = \"MI\", cache = True)\n",
"mi_tiger = counties(state=\"MI\", cache=True)\n",
"\n",
"# Get the cartographic boundary file with cb = True\n",
"mi_cartographic = counties(state = \"MI\", cb = True, cache = True)\n",
"mi_cartographic = counties(state=\"MI\", cb=True, cache=True)\n",
"\n",
"# Plot the two side-by-side to compare them\n",
"fig, ax = plt.subplots(ncols = 2)\n",
"mi_tiger.plot(ax = ax[0])\n",
"mi_cartographic.plot(ax = ax[1])\n",
"fig, ax = plt.subplots(ncols=2)\n",
"mi_tiger.plot(ax=ax[0])\n",
"mi_cartographic.plot(ax=ax[1])\n",
"\n",
"ax[0].set_title(\"TIGER/Line\")\n",
"ax[1].set_title(\"Cartographic\")"
Expand Down
18 changes: 10 additions & 8 deletions docs/02-geometries.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@
"source": [
"from pygris import states\n",
"\n",
"us = states(cb = True, resolution = \"20m\")\n",
"us = states(cb=True, resolution=\"20m\")\n",
"\n",
"us.plot()"
]
Expand Down Expand Up @@ -133,7 +133,7 @@
}
],
"source": [
"us_shifted = shift_geometry(us, position = \"outside\", preserve_area = True)\n",
"us_shifted = shift_geometry(us, position=\"outside\", preserve_area=True)\n",
"\n",
"us_shifted.plot()"
]
Expand Down Expand Up @@ -175,14 +175,16 @@
"import geopandas as gp\n",
"from matplotlib import pyplot as plt\n",
"\n",
"fbi_offices = gp.read_file(\"https://gist.githubusercontent.com/walkerke/a9211114fcbbe74cb04e3a6720b17d09/raw/085ca1d5dad7b37b45b0bdb5e16c160c4fb0bc37/fbi-offices.geojson\")\n",
"fbi_offices = gp.read_file(\n",
" \"https://gist.githubusercontent.com/walkerke/a9211114fcbbe74cb04e3a6720b17d09/raw/085ca1d5dad7b37b45b0bdb5e16c160c4fb0bc37/fbi-offices.geojson\"\n",
")\n",
"\n",
"fbi_rescaled = shift_geometry(fbi_offices)\n",
"\n",
"fig, ax = plt.subplots()\n",
"\n",
"us_rescaled.plot(ax = ax, color = \"grey\")\n",
"fbi_rescaled.plot(ax = ax, color = \"black\")"
"us_rescaled.plot(ax=ax, color=\"grey\")\n",
"fbi_rescaled.plot(ax=ax, color=\"black\")"
]
},
{
Expand Down Expand Up @@ -395,9 +397,9 @@
}
],
"source": [
"from pygris import tracts \n",
"from pygris import tracts\n",
"\n",
"king_tracts = tracts(state = \"WA\", county = \"King\", cb = True, cache = True)\n",
"king_tracts = tracts(state=\"WA\", county=\"King\", cb=True, cache=True)\n",
"\n",
"king_tracts.explore()"
]
Expand Down Expand Up @@ -614,7 +616,7 @@
"source": [
"from pygris.utils import erase_water\n",
"\n",
"king_tiger = tracts(\"WA\", \"King\", cb = False, cache = True)\n",
"king_tiger = tracts(\"WA\", \"King\", cb=False, cache=True)\n",
"\n",
"king_erased = erase_water(king_tiger)\n",
"\n",
Expand Down
53 changes: 28 additions & 25 deletions docs/03-data-utilities.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -27,16 +27,13 @@
"source": [
"from pygris.data import get_census\n",
"\n",
"us_youth_sahie = get_census(dataset = \"timeseries/healthins/sahie\",\n",
" variables = \"PCTUI_PT\",\n",
" params = {\n",
" \"for\": \"county:*\",\n",
" \"in\": \"state:*\",\n",
" \"time\": 2019,\n",
" \"AGECAT\": 4\n",
" }, \n",
" return_geoid = True, \n",
" guess_dtypes = True)"
"us_youth_sahie = get_census(\n",
" dataset=\"timeseries/healthins/sahie\",\n",
" variables=\"PCTUI_PT\",\n",
" params={\"for\": \"county:*\", \"in\": \"state:*\", \"time\": 2019, \"AGECAT\": 4},\n",
" return_geoid=True,\n",
" guess_dtypes=True,\n",
")"
]
},
{
Expand Down Expand Up @@ -167,22 +164,19 @@
}
],
"source": [
"from pygris import counties \n",
"from pygris.utils import shift_geometry\n",
"from matplotlib import pyplot as plt\n",
"\n",
"us_counties = counties(cb = True, resolution = \"20m\", cache = True, year = 2019)\n",
"from pygris import counties\n",
"from pygris.utils import shift_geometry\n",
"\n",
"us_counties = counties(cb=True, resolution=\"20m\", cache=True, year=2019)\n",
"us_counties_rescaled = shift_geometry(us_counties)\n",
"\n",
"us_counties_merged = us_counties_rescaled.merge(us_youth_sahie, on = \"GEOID\")\n",
"us_counties_merged = us_counties_rescaled.merge(us_youth_sahie, on=\"GEOID\")\n",
"\n",
"us_counties_merged.plot(\n",
" column = \"PCTUI_PT\",\n",
" cmap = \"viridis\",\n",
" figsize = (8, 6)\n",
")\n",
"us_counties_merged.plot(column=\"PCTUI_PT\", cmap=\"viridis\", figsize=(8, 6))\n",
"\n",
"plt.title(\"% uninsured under age 19 by county, 2019\")\n"
"plt.title(\"% uninsured under age 19 by county, 2019\")"
]
},
{
Expand Down Expand Up @@ -353,7 +347,7 @@
"source": [
"from pygris.data import get_lodes\n",
"\n",
"tx_od = get_lodes(state = \"TX\", year = 2022, lodes_type = \"od\", cache = True)\n",
"tx_od = get_lodes(state=\"TX\", year=2022, lodes_type=\"od\", cache=True)\n",
"\n",
"tx_od.head()"
]
Expand Down Expand Up @@ -523,8 +517,14 @@
}
],
"source": [
"tx_od_tract = get_lodes(state = \"TX\", year = 2022, lodes_type = \"od\", cache = True,\n",
" return_geometry = True, agg_level = \"tract\")\n",
"tx_od_tract = get_lodes(\n",
" state=\"TX\",\n",
" year=2022,\n",
" lodes_type=\"od\",\n",
" cache=True,\n",
" return_geometry=True,\n",
" agg_level=\"tract\",\n",
")\n",
"\n",
"tx_od_tract.head()"
]
Expand Down Expand Up @@ -865,9 +865,12 @@
"source": [
"tcu_ids = [\"48439104203\", \"48439104301\"]\n",
"\n",
"tcu_origins = tx_od_tract.loc[(tx_od_tract['w_geocode'].isin(tcu_ids)) & (tx_od_tract['h_geocode'].str.slice(stop = 5) == \"48439\")]\n",
"tcu_origins = tx_od_tract.loc[\n",
" (tx_od_tract[\"w_geocode\"].isin(tcu_ids))\n",
" & (tx_od_tract[\"h_geocode\"].str.slice(stop=5) == \"48439\")\n",
"]\n",
"\n",
"tcu_origins.explore(column = \"S000\")"
"tcu_origins.explore(column=\"S000\")"
]
},
{
Expand Down
46 changes: 30 additions & 16 deletions docs/04-geocoding.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@
"source": [
"from pygris.geocode import geocode\n",
"\n",
"geocode(address = \"1600 Pennsylvania Ave NW, Washington DC\")"
"geocode(address=\"1600 Pennsylvania Ave NW, Washington DC\")"
]
},
{
Expand Down Expand Up @@ -282,7 +282,9 @@
}
],
"source": [
"geocode(address = \"1600 Pennsylvania Ave NW, Washington DC\", as_gdf = True).explore(marker_type = \"marker\")"
"geocode(address=\"1600 Pennsylvania Ave NW, Washington DC\", as_gdf=True).explore(\n",
" marker_type=\"marker\"\n",
")"
]
},
{
Expand Down Expand Up @@ -349,7 +351,7 @@
"source": [
"from pygris.geocode import geolookup\n",
"\n",
"geolookup(longitude = -98.90629, latitude= 32.75639)"
"geolookup(longitude=-98.90629, latitude=32.75639)"
]
},
{
Expand Down Expand Up @@ -437,14 +439,17 @@
],
"source": [
"import pandas as pd\n",
"\n",
"from pygris.geocode import batch_geocode\n",
"\n",
"my_addresses = pd.DataFrame(\n",
" {\"building\": [\"Chrysler Building\", \"Empire State Building\", \"Flatiron Building\"],\n",
" \"address\": [\"405 Lexington Ave\", \"20 W 34th St\", \"175 5th Ave\"],\n",
" \"city\": \"New York\",\n",
" \"state\": \"New York\",\n",
" \"zip\": [\"10174\", \"10018\", \"10010\"]}\n",
" {\n",
" \"building\": [\"Chrysler Building\", \"Empire State Building\", \"Flatiron Building\"],\n",
" \"address\": [\"405 Lexington Ave\", \"20 W 34th St\", \"175 5th Ave\"],\n",
" \"city\": \"New York\",\n",
" \"state\": \"New York\",\n",
" \"zip\": [\"10174\", \"10018\", \"10010\"],\n",
" }\n",
")\n",
"\n",
"my_addresses"
Expand Down Expand Up @@ -583,9 +588,15 @@
}
],
"source": [
"my_points = batch_geocode(my_addresses, id_column = \"building\",\n",
" address = \"address\", city = \"city\", state = \"state\",\n",
" zip = \"zip\", as_gdf = True)\n",
"my_points = batch_geocode(\n",
" my_addresses,\n",
" id_column=\"building\",\n",
" address=\"address\",\n",
" city=\"city\",\n",
" state=\"state\",\n",
" zip=\"zip\",\n",
" as_gdf=True,\n",
")\n",
"\n",
"my_points"
]
Expand Down Expand Up @@ -789,8 +800,7 @@
}
],
"source": [
"\n",
"my_points.explore(marker_type = \"marker\")"
"my_points.explore(marker_type=\"marker\")"
]
},
{
Expand Down Expand Up @@ -1019,8 +1029,9 @@
"source": [
"from pygris import tracts\n",
"\n",
"capitol_tracts = tracts(state = \"TX\", cb = True,\n",
" subset_by = {\"1100 Congress Ave., Austin, TX 78701\": 5000})\n",
"capitol_tracts = tracts(\n",
" state=\"TX\", cb=True, subset_by={\"1100 Congress Ave., Austin, TX 78701\": 5000}\n",
")\n",
"\n",
"capitol_tracts.explore()"
]
Expand Down Expand Up @@ -1240,7 +1251,10 @@
"source": [
"import pandas as pd\n",
"\n",
"union_tracts_list = [tracts(cb = True, state = x, subset_by = {\"2501 Seaport Dr, Chester, PA 19013\": 10000}) for x in ['DE', 'PA', 'NJ']]\n",
"union_tracts_list = [\n",
" tracts(cb=True, state=x, subset_by={\"2501 Seaport Dr, Chester, PA 19013\": 10000})\n",
" for x in [\"DE\", \"PA\", \"NJ\"]\n",
"]\n",
"\n",
"union_tracts = pd.concat(union_tracts_list)\n",
"\n",
Expand Down
Loading
Loading