Metadata-Version: 2.3
Name: environmental_insights
Version: 0.3.0
Summary: A Python package for democratizing access to ambient air pollution data and predictive analytics.
License: GPL-3.0-or-later
Keywords: air pollution,predictive analytics,environmental data,geospatial analysis
Author: Liam J. Berrisford
Author-email: l.berrisford3@exeter.ac.uk
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: beautifulsoup4 (>=4.13.4,<5.0.0)
Requires-Dist: geopandas (>=1.0.1,<2.0.0)
Requires-Dist: lightgbm
Requires-Dist: matplotlib
Requires-Dist: netcdf4 (>=1.7.2,<2.0.0)
Requires-Dist: overpy
Requires-Dist: pandas
Requires-Dist: pyarrow
Requires-Dist: pyogrio
Requires-Dist: requests
Requires-Dist: scikit-learn (>=1.6.1,<2.0.0)
Requires-Dist: scipy
Requires-Dist: shapely
Requires-Dist: xarray (>=2025.4.0,<2026.0.0)
Description-Content-Type: text/markdown

# Environmental Insights

[![PyPI version](https://img.shields.io/pypi/v/environmental-insights.svg?cacheSeconds=3600)](https://pypi.org/project/environmental-insights)
[![GitHub release](https://img.shields.io/github/v/release/liamjberrisford/Environmental-Insights.svg?sort=semver&cacheSeconds=3600)](https://github.com/liamjberrisford/Environmental-Insights/releases)
[![Build status](https://img.shields.io/github/actions/workflow/status/liamjberrisford/Environmental-Insights/release.yml?branch=main&cacheSeconds=3600)](https://github.com/liamjberrisford/Environmental-Insights/actions)
[![Tests](https://img.shields.io/github/actions/workflow/status/liamjberrisford/Environmental-Insights/testing.yml?branch=main&label=tests&style=flat-square)](https://github.com/liamjberrisford/Environmental-Insights/actions/workflows/testing.yml)



A Python package for democratizing access to ambient air pollution data and predictive analytics.

---

## 📖 Description

**Environmental Insights** provides easy-to-use functions to download, process, and analyze ambient air pollution and meteorological data over England.  
- Implements supervised machine-learning pipelines to predict hourly pollutant concentrations on a 1 km² grid.  
- Supplies both “typical day” aggregates (percentiles) and full hourly model outputs.  
- Includes geospatial utilities for mapping, interpolation, and uncertainty analysis.

---

## ⚙️ Installation

Install from PyPI:

```bash
pip install environmental-insights
```

Or from source:

```bash
git clone https://github.com/liamjberrisford/Environmental-Insights.git
cd Environmental-Insights
python -m build
pip install dist/environmental_insights-0.2.1b0-py3-none-any.whl
```

---

## 📂 Data Sources

This package downloads and processes two primary CEDA datasets:

1. **Synthetic Hourly Air Pollution Prediction Averages for England (SynthHAPPE)**  
   Berrisford, L. (2025). *Synthetic Hourly Air Pollution Prediction Averages for England (SynthHAPPE).* NERC EDS Centre for Environmental Data Analysis.  
   DOI: [10.5285/4cbd9c53ab07497ba42de5043d1f414b](https://dx.doi.org/10.5285/4cbd9c53ab07497ba42de5043d1f414b)  
   > Representative “typical day” profiles of NO₂, NO, NOₓ, O₃, PM₁₀, PM₂.₅ and SO₂ on a 1 km² grid, with 5th, 50th & 95th percentiles.

2. **Machine Learning for Hourly Air Pollution Prediction in England (ML-HAPPE)**  
   Berrisford, L. (2025). *Machine Learning for Hourly Air Pollution Prediction in England (ML-HAPPE).* NERC EDS Centre for Environmental Data Analysis.  
   DOI: [10.5285/fc735f9878ed43e293b85f85e40df24d](https://dx.doi.org/10.5285/fc735f9878ed43e293b85f85e40df24d)  
   > Full-year (2018) hourly modelled concentrations of NO₂, NO, NOₓ, O₃, PM₁₀, PM₂.₅ and SO₂ on a 1 km² grid, including 5th, 50th & 95th percentiles and underlying training data.

---

For full examples, see the Jupyter-Book tutorial in `book/tutorial_environmental_insights.ipynb`.

## 📚 Documentation

Build and view locally:

```bash
jupyter-book build book/
```

Then open `book/_build/html/index.html` in your browser.  
Highlights:

- **API Reference**: `book/docs/api/environmental_insights/`  
- **Tutorial Notebook**: `book/tutorial_environmental_insights.ipynb`

The documentation is also avaiable via the [GitHub Pages Site](https://liamjberrisford.github.io/Environmental-Insights/home_page.html)

---

## ✅ Testing

Run the full test suite:

```bash
pytest
```

Integration and unit tests are under `tests/`.

---

## 🤝 Contributing

Contributions and bug-reports are very welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on:

- Code style  
- Pull request process  
- Issue reporting  

---

## 📑 Citation

If you use *Environmental Insights* in your work, please cite:

> Berrisford, L. J. (2025). Environmental Insights: Democratizing access to ambient air pollution data and predictive analytics (Version 0.2.1b0) [Software]. GitHub. https://github.com/liamjberrisford/Environmental-Insights  

Also cite the underlying datasets:

- Berrisford, L. (2025). *SynthHAPPE*: Synthetic Hourly Air Pollution Prediction Averages for England. NERC EDS CEDA. DOI: 10.5285/4cbd9c53ab07497ba42de5043d1f414b  
- Berrisford, L. (2025). *ML-HAPPE*: Machine Learning for Hourly Air Pollution Prediction in England. NERC EDS CEDA. DOI: 10.5285/fc735f9878ed43e293b85f85e40df24d  

---

## 📜 License

This project is released under the [GPL-3.0-or-later](LICENSE).  

