<p align="left">
<img src="writing/figs/modified-logo.png" alt="" width="120"/>
</p>
## popexposure: Functions to estimate the number of people living near environmental hazards
[](https://github.com/heathermcb/popexposure)
[](https://badge.fury.io/py/popexposure)
## Overview
`popexposure` is an open-source Python package providing fast, memory-efficient, and consistent estimates of the number of people living near environmental hazards, enabling environmental scientists to assess population-level exposure to environmental hazards based on residential proximity. Methodological details can be found in [McBrien et al (2025)](). Extensive documentation can be found on in our quick start [tutorial](https://github.com/heathermcb/popexposure/blob/main/demo/).
## Installation
The easiest way to install `popexposure` is via the latest pre-compiled binaries from PyPI with:
```bash
pip install popexposure
```
You can build `popexposure` from source as you would any other Python package with:
```bash
git clone https://github.com/heathermcb/popexposure
cd popexposure
python -m pip install .
```
## Tutorials
A number of tutorials providing worked examples using `popexposure` can be found in our [demos](https://github.com/heathermcb/Pop_Exp/tree/main/demo/demo) folder.
## Quickstart
```python
import glob
import pandas as pd
from popexposure.find_exposure import PopEstimator
# Instantiate estimator
pop_est = PopEstimator()
# List of years and corresponding hazard file paths
years = [2016, 2017, 2018]
hazard_paths = [
"hazard_2016.geojson",
"hazard_2017.geojson",
"hazard_2018.geojson"
]
pop_path = "my_pop_raster.tif"
admin_units_path = "my_admin_units.geojson"
# Prepare admin units data
admin_units = pop_est.prep_data(admin_units_path, geo_type="admin_unit")
# Find total num ppl residing <= 10km of each hazard in each year
exposed_list = []
for year, hazard_path in zip(years, hazard_paths):
# Prepare hazard data for this year
hazards = pop_est.prep_data(hazard_path, geo_type="hazard")
# Estimate exposed population
exposed = pop_est.est_exposed_pop(
pop_path=pop_path,
hazard_specific=False, # set to True if you want per-hazard results
hazards=hazards,
admin_units=admin_units # leave as None for estimates not by admin unit
)
exposed['year'] = year
exposed_list.append(exposed)
exposed_df = pd.concat(exposed_list, axis=0)
# Save output
exposed_df.to_parquet("pop_exposed_to_hazards.parquet")
```
## Available functions
| Function | Overview | Inputs | Outputs |
| ------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `prep_data` | Reads, cleans, and preprocesses geospatial hazard or admin unit data by removing empty or missing geometries, and buffering hazard data according to user-passed buffer distances | Path to hazard or administrative unit file (`.geojson` or `.parquet`), `geo_type` (`"hazard"` or `"admin_unit"`) | Cleaned `GeoDataFrame` with valid geometries |
| `est_exposed_pop` | Estimates number of people living within hazard buffer(s) using a raster | Population raster path (`.tif`), hazard data, `hazard_specific` (bool), optional administrative units | DataFrame with exposed population counts by hazard/administrative unit |
| `est_pop` | Estimates total population in admin geographies using a raster | Population raster path (`.tif`), administrative unit data (`GeoDataFrame`) | DataFrame with total population per administrative unit |
## Getting help and contributing
If you have any questions, a feature request, or would like to report a bug, please [open an issue](https://github.com/heathermcb/Pop_Exp/issues). We also welcome any new contributions and ideas. If you want to add code, please submit a [pull request](https://github.com/heathermcb/Pop_Exp/pulls) and we will get back to you when we can. Thanks!
## Citing this package
Please cite our paper [McBrien et al (2025)]().
## Authors
- [Heather McBrien](https://scholar.google.com/citations?user=0Hz3a1AAAAAJ&hl=en&oi=ao)
- [Joan A. Casey](https://scholar.google.com/citations?user=LjrwHBMAAAAJ&hl=en)
- [Lawrence Chillrud](https://scholar.google.com/citations?hl=en&user=HrSjGh0AAAAJ)
- [Nina M. Flores](https://scholar.google.com/citations?user=fkttN9UAAAAJ&hl=en&oi=ao)
- [Lauren B. Wilner](https://scholar.google.com/citations?user=rLX9LVYAAAAJ&hl=en&oi=ao)
## References
Our package is a fancy wrapper for the package [exactextract](https://pypi.org/project/exactextract/).
Raw data
{
"_id": null,
"home_page": "https://github.com/heathermcb/popexposure",
"name": "popexposure",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "population, exposure, wildfires, environmental hazards, climate hazards, find people exposed",
"author": "heathermcb",
"author_email": "heathermcbrien2.0@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/44/31/f46646536db1fc9e4a1b80b298af1cd917aca39d21d2caf7a7ff6b2afd2c/popexposure-1.0.0.dev13.tar.gz",
"platform": null,
"description": "<p align=\"left\">\n <img src=\"writing/figs/modified-logo.png\" alt=\"\" width=\"120\"/>\n</p>\n\n## popexposure: Functions to estimate the number of people living near environmental hazards\n\n\n\n[](https://github.com/heathermcb/popexposure)\n[](https://badge.fury.io/py/popexposure)\n\n## Overview\n\n`popexposure` is an open-source Python package providing fast, memory-efficient, and consistent estimates of the number of people living near environmental hazards, enabling environmental scientists to assess population-level exposure to environmental hazards based on residential proximity. Methodological details can be found in [McBrien et al (2025)](). Extensive documentation can be found on in our quick start [tutorial](https://github.com/heathermcb/popexposure/blob/main/demo/).\n\n## Installation\n\nThe easiest way to install `popexposure` is via the latest pre-compiled binaries from PyPI with:\n\n```bash\npip install popexposure\n```\n\nYou can build `popexposure` from source as you would any other Python package with:\n\n```bash\ngit clone https://github.com/heathermcb/popexposure\ncd popexposure\npython -m pip install .\n```\n\n## Tutorials\n\nA number of tutorials providing worked examples using `popexposure` can be found in our [demos](https://github.com/heathermcb/Pop_Exp/tree/main/demo/demo) folder.\n\n## Quickstart\n\n```python\nimport glob\nimport pandas as pd\nfrom popexposure.find_exposure import PopEstimator\n\n# Instantiate estimator\npop_est = PopEstimator()\n\n# List of years and corresponding hazard file paths\nyears = [2016, 2017, 2018]\nhazard_paths = [\n \"hazard_2016.geojson\",\n \"hazard_2017.geojson\",\n \"hazard_2018.geojson\"\n]\npop_path = \"my_pop_raster.tif\"\nadmin_units_path = \"my_admin_units.geojson\"\n\n# Prepare admin units data\nadmin_units = pop_est.prep_data(admin_units_path, geo_type=\"admin_unit\")\n\n# Find total num ppl residing <= 10km of each hazard in each year\nexposed_list = []\n\nfor year, hazard_path in zip(years, hazard_paths):\n # Prepare hazard data for this year\n hazards = pop_est.prep_data(hazard_path, geo_type=\"hazard\")\n # Estimate exposed population\n exposed = pop_est.est_exposed_pop(\n pop_path=pop_path,\n hazard_specific=False, # set to True if you want per-hazard results\n hazards=hazards,\n admin_units=admin_units # leave as None for estimates not by admin unit\n )\n exposed['year'] = year\n exposed_list.append(exposed)\n\nexposed_df = pd.concat(exposed_list, axis=0)\n\n# Save output\nexposed_df.to_parquet(\"pop_exposed_to_hazards.parquet\")\n```\n\n## Available functions\n\n| Function | Overview | Inputs | Outputs |\n| ------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |\n| `prep_data` | Reads, cleans, and preprocesses geospatial hazard or admin unit data by removing empty or missing geometries, and buffering hazard data according to user-passed buffer distances | Path to hazard or administrative unit file (`.geojson` or `.parquet`), `geo_type` (`\"hazard\"` or `\"admin_unit\"`) | Cleaned `GeoDataFrame` with valid geometries |\n| `est_exposed_pop` | Estimates number of people living within hazard buffer(s) using a raster | Population raster path (`.tif`), hazard data, `hazard_specific` (bool), optional administrative units | DataFrame with exposed population counts by hazard/administrative unit |\n| `est_pop` | Estimates total population in admin geographies using a raster | Population raster path (`.tif`), administrative unit data (`GeoDataFrame`) | DataFrame with total population per administrative unit |\n\n## Getting help and contributing\n\nIf you have any questions, a feature request, or would like to report a bug, please [open an issue](https://github.com/heathermcb/Pop_Exp/issues). We also welcome any new contributions and ideas. If you want to add code, please submit a [pull request](https://github.com/heathermcb/Pop_Exp/pulls) and we will get back to you when we can. Thanks!\n\n## Citing this package\n\nPlease cite our paper [McBrien et al (2025)]().\n\n## Authors\n\n- [Heather McBrien](https://scholar.google.com/citations?user=0Hz3a1AAAAAJ&hl=en&oi=ao)\n- [Joan A. Casey](https://scholar.google.com/citations?user=LjrwHBMAAAAJ&hl=en)\n- [Lawrence Chillrud](https://scholar.google.com/citations?hl=en&user=HrSjGh0AAAAJ)\n- [Nina M. Flores](https://scholar.google.com/citations?user=fkttN9UAAAAJ&hl=en&oi=ao)\n- [Lauren B. Wilner](https://scholar.google.com/citations?user=rLX9LVYAAAAJ&hl=en&oi=ao)\n\n## References\n\nOur package is a fancy wrapper for the package [exactextract](https://pypi.org/project/exactextract/).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A package for finding the number of people residing near environmental hazards",
"version": "1.0.0.dev13",
"project_urls": {
"Documentation": "https://github.com/heathermcb/popexposure#readme",
"Homepage": "https://github.com/heathermcb/popexposure",
"Source": "https://github.com/heathermcb/popexposure"
},
"split_keywords": [
"population",
" exposure",
" wildfires",
" environmental hazards",
" climate hazards",
" find people exposed"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cdaefa67c479aee670d96c22315615eee46a3ac2378e014e0bb1a7eb40780c8a",
"md5": "80cb4d09afd9ce72f8389a1f16d3fd18",
"sha256": "4943aa5896ddcbe08adc08cf572f3798375fdcbb13d785dd87f687709016b7e6"
},
"downloads": -1,
"filename": "popexposure-1.0.0.dev13-py3-none-any.whl",
"has_sig": false,
"md5_digest": "80cb4d09afd9ce72f8389a1f16d3fd18",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 17292,
"upload_time": "2025-07-09T22:56:06",
"upload_time_iso_8601": "2025-07-09T22:56:06.178657Z",
"url": "https://files.pythonhosted.org/packages/cd/ae/fa67c479aee670d96c22315615eee46a3ac2378e014e0bb1a7eb40780c8a/popexposure-1.0.0.dev13-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4431f46646536db1fc9e4a1b80b298af1cd917aca39d21d2caf7a7ff6b2afd2c",
"md5": "a2b1b4ef2cc51c4b2bc69cd0bc2a9511",
"sha256": "a47667a2e7d405e8ff30c0f71977de74e8e28a71f994d277d677bb82f4f8a6be"
},
"downloads": -1,
"filename": "popexposure-1.0.0.dev13.tar.gz",
"has_sig": false,
"md5_digest": "a2b1b4ef2cc51c4b2bc69cd0bc2a9511",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 15822,
"upload_time": "2025-07-09T22:56:07",
"upload_time_iso_8601": "2025-07-09T22:56:07.404082Z",
"url": "https://files.pythonhosted.org/packages/44/31/f46646536db1fc9e4a1b80b298af1cd917aca39d21d2caf7a7ff6b2afd2c/popexposure-1.0.0.dev13.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 22:56:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "heathermcb",
"github_project": "popexposure",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "popexposure"
}
JSON
