Metadata-Version: 2.4
Name: vayuayan
Version: 0.1.4
Summary: Package for fetching and analyzing air quality data from multiple sources
Author-email: Saket Choudhary <saketc@iitb.ac.in>, Mahesh Kumar Prajapat <22b0433@iitb.ac.in>
Maintainer-email: Saket Choudhary <saketc@iitb.ac.in>, Mahesh Kumar Prajapat <22b0433@iitb.ac.in>
License-Expression: MIT
Project-URL: Homepage, https://github.com/saketlab/vayuayan
Project-URL: Repository, https://github.com/saketlab/vayuayan.git
Project-URL: Documentation, https://saketlab.github.io/vayuayan
Project-URL: Bug Tracker, https://github.com/saketlab/vayuayan/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: openpyxl==3.1.5
Requires-Dist: urllib3>=1.26.0
Requires-Dist: geopandas>=1.0.1
Requires-Dist: geopy>=2.4.1
Requires-Dist: rioxarray>=0.15.0
Requires-Dist: xarray>=2024.7.0
Requires-Dist: netCDF4>=1.7.2
Requires-Dist: tqdm>=4.62.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Provides-Extra: docs
Requires-Dist: myst-nb>=1.3.0; extra == "docs"
Requires-Dist: sphinx>=8.2.3; extra == "docs"
Requires-Dist: furo>=2024.8.6; extra == "docs"
Requires-Dist: sphinx-multiversion>=0.2.4; extra == "docs"
Provides-Extra: notebooks
Requires-Dist: jupyter; extra == "notebooks"
Requires-Dist: matplotlib; extra == "notebooks"
Requires-Dist: seaborn; extra == "notebooks"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/saketlab/vayuayan/master/docs/assets/vayuayan.png" alt="Vayuayan Logo" width="200"/>
</p>

# Vayuayan

**Vayuayan** is a comprehensive Python package for fetching and analysing air quality data from multiple sources worldwide:

- **WUSTL ACAG**: [Washington University satellite PM2.5 data](https://sites.wustl.edu/acag/datasets/surface-pm2-5/) (Global)
- **CPCB India**: Central Pollution Control Board](https://cpcb.nic.in/) monitoring network (India only)

## Installation

Install from PyPI (recommended):

```bash
pip install vayuayan
```

Install development version from GitHub:

```bash
pip install git+https://github.com/saketlab/vayuayan.git
```

Or install from source:

```bash
git clone https://github.com/saketlab/vayuayan.git
cd vayuayan
pip install -e .
```

## Quick Start

### Command Line Interface

```bash
# List available states/regions for AQI data
vayuayan list_states

# List cities in a state
vayuayan list_cities "Maharashtra"

# List monitoring stations in a city
vayuayan list_stations "Mumbai"

# Download historical city-level AQI data
vayuayan city_data --city "Mumbai" --year 2024 --path "mumbai_aqi_2024.csv"

# Download historical station-level data
vayuayan station_data --station_id "site_5964" --year 2024 --path "station_data_2024.csv"

# Get your current location (IP-based)
vayuayan locate_me

# Find nearest monitoring station
vayuayan nearest_station --lat 19.0760 --lon 72.8777

# Get live air quality data
vayuayan live_aqi --station_id "site_5964" --path "live_data.json"

# Analyze PM2.5 satellite data for a region (combines all polygons)
vayuayan pm25 --geojson_path "delhi_ncr.geojson" --year 2023 --month 11

# Analyze PM2.5 data grouped by state
vayuayan pm25 --geojson_path "india_districts.geojson" --year 2023 --month 11 --group_by state_name

# Analyze PM2.5 data grouped by multiple columns (state and district)
vayuayan pm25 --geojson_path "india_districts.geojson" --year 2023 --month 11 --group_by state_name,district_name
```

### Python API

```python
from vayuayan import CPCBHistorical, CPCBLive, PM25Client

# Historical data client
historical = CPCBHistorical()
states = historical.get_state_list()
mumbai_stations = historical.get_station_list("Mumbai")

# Live monitoring client
live = CPCBLive()
location = live.get_system_location()
nearest_station = live.get_nearest_station(location)
current_aqi = live.get_live_aqi_data()

# Satellite PM2.5 analysis
pm25 = PM25Client()
# Combined stats for entire region
delhi_stats = pm25.get_pm25_stats("delhi_ncr.geojson", 2023, 11)
# Stats grouped by state
state_stats = pm25.get_pm25_stats("india_districts.geojson", 2023, 11, group_by="state_name")
# Stats grouped by multiple columns (state and district)
district_stats = pm25.get_pm25_stats("india_districts.geojson", 2023, 11, group_by="state_name,district_name")
```

## Contributing

Contributions are welcome! Please feel free to submit a pull request.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Disclaimer

This package is not officially affiliated with any government agency or air quality monitoring network. It's a third-party tool for accessing publicly available environmental data. Users are responsible for verifying data accuracy and following proper attribution guidelines.

## Etymology

**Vayuayan** (वायुअयन) combines two Sanskrit words:
- **Vayu** (वायु): Wind, air 
- **Ayan** (अयन): Path, journey, movement

Together, "Vayuayan" means "the path of wind" - representing the journey and movement of air quality data across space and time.
