Metadata-Version: 2.4
Name: vayuayan
Version: 0.3.0
Summary: Air quality data from CPCB stations and OAQ sensors in India, and satellite PM2.5 data from WUSTL ACAG
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://vayuayan.saketlab.org/python/
Project-URL: Bug Tracker, https://github.com/saketlab/vayuayan/issues
Project-URL: Changelog, https://vayuayan.saketlab.org/python/history.html
Keywords: air quality,AQI,PM2.5,pollution,CPCB,India,satellite,WUSTL ACAG,GeoJSON
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
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 :: Scientific/Engineering :: GIS
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: pandas>=2.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: urllib3>=1.26.0
Requires-Dist: geopandas>=1.0.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
Requires-Dist: earthengine-api>=0.1.384
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: duckdb; extra == "dev"
Requires-Dist: pyarrow; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: matplotlib>=3.5; extra == "dev"
Provides-Extra: plot
Requires-Dist: matplotlib>=3.5; extra == "plot"
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"
Requires-Dist: sphinxext-opengraph>=0.9.1; extra == "docs"
Requires-Dist: sphinx-sitemap>=2.6.0; 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/main/python/docs/assets/vayuayan.png" alt="Vayuayan Logo" width="200"/>
</p>

# Vayuayan

Vayuayan downloads and examines air quality data from three sources:

- The monitoring stations of the [Central Pollution Control Board (CPCB)](https://cpcb.nic.in/) in India.
- Low-cost sensor networks in India, from [Open Air Quality (OAQ)](https://oaq.notf.in).
- [Satellite PM2.5 data](https://sites.wustl.edu/acag/datasets/surface-pm2-5/) for all areas of the Earth, from the Atmospheric Composition Analysis Group (ACAG) at Washington University in St. Louis (WUSTL).

Vayuayan calculates the CPCB National Air Quality Index. It changes CPCB files into tidy (long) tables. It compares sensor data with the US EPA targets for PM2.5 sensors.

## Installation

Install from PyPI (recommended):

```bash
pip install vayuayan
```

The plotting functions (`plot_daily_record_*`) need matplotlib: `pip install "vayuayan[plot]"`.

Install the development version from GitHub:

```bash
pip install "git+https://github.com/saketlab/vayuayan.git#subdirectory=python"
```

Or install from the source code:

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

## Cache

Vayuayan keeps CPCB files of past years in `~/.cache/vayuayan`. To use a different directory, set `VAYUAYAN_CACHE_DIR`.

## 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"

# Compute the daily National AQI of a station from its raw 15-minute data
vayuayan daily_aqi --station_id "site_301" --year 2024 --path "daily_aqi.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()

# National AQI from concentrations (24-hour averages; 8-hour for CO and O3)
from vayuayan import compute_aqi

compute_aqi({"PM2.5": 45, "PM10": 80, "NO2": 30})  # AQI 80, Satisfactory, PM10

# Daily AQI and tidy rows from raw CPCB data
daily = historical.daily_aqi("site_301", "2024")
rows = historical.download_raw_aqi_data_station_level("site_301", "2024", "", tidy=True)

# Satellite PM2.5 analysis (V6.GL.03 by default)
pm25 = PM25Client()
# Monthly statistics, and state statistics as a GeoDataFrame for a map
monthly = pm25.get_pm25_monthly_stats("delhi_ncr.geojson", 2023)
state_map = pm25.get_pm25_stats(
    "india_districts.geojson", 2023, 11, group_by="state_name", geometry=True
)
# 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

We accept contributions. To contribute, open a pull request.

## Disclaimer

This package has no official relation to a government agency or to an air quality monitoring network. It is a third-party tool for public environmental data. Users must make sure that the data is accurate. Users must also give the correct attribution.

## Etymology

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

Thus, "Vayuayan" means "the path of wind". The name refers to the movement of air quality data across space and time.
