Metadata-Version: 2.4
Name: cinei
Version: 2.1.1
Summary: Coupled and Integrated Emission Inventory (CINEI): integrating anthropogenic emission inventories toward complete sectoral coverage, finer spatial resolution, and consistent NMVOC speciation for atmospheric chemistry, climate and multi-disciplinary applications.
Home-page: https://github.com/Luyikeka/cinei
Author: Yijuan Zhang
Author-email: your@email.com
Project-URL: Documentation, https://luyikeka.github.io/cinei/
Project-URL: Source Code, https://github.com/Luyikeka/cinei
Project-URL: Bug Tracker, https://github.com/Luyikeka/cinei/issues
Project-URL: PyPI, https://pypi.org/project/cinei/
Keywords: emission inventory,atmospheric chemistry,NMVOC speciation,CEDS,MEIC,HTAP,EDGAR,WRF-Chem,ICON,CMIP,KM-scale climate modeling,climate modeling,air quality,China emissions,anthropogenic emissions
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: xarray
Requires-Dist: rioxarray
Requires-Dist: geopandas
Requires-Dist: matplotlib
Requires-Dist: requests
Requires-Dist: tqdm
Requires-Dist: scipy
Requires-Dist: rasterio
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# CINEI — Coupled and Integrated Emission Inventory

[![PyPI version](https://badge.fury.io/py/cinei.svg)](https://badge.fury.io/py/cinei)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15000795.svg)](https://doi.org/10.5281/zenodo.15000795)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Documentation](https://img.shields.io/badge/docs-luyikeka.github.io/cinei-blueviolet)](https://luyikeka.github.io/cinei/)

📖 **Full documentation: [https://luyikeka.github.io/cinei/](https://luyikeka.github.io/cinei/)**

---

## Overview

**CINEI** is a Python package for integrating anthropogenic emission
inventories, combining global (e.g. CEDS) and regional (e.g. MEIC for China)
datasets into a unified temporal and spatial resolution NetCDF product.

CINEI is dedicated to coupling and integrating anthropogenic emission
inventories toward:
- **Complete sectoral coverage** — energy, residential, industry,
  agriculture, transportation, waste, shipping, aviation
- **Finer spatial resolution** — from global 0.5° to regional 0.25° or finer
- **Consistent NMVOC speciation** — disaggregation into lumped model species
  (MOZART/SAPRC99 mechanisms)

The outputs are designed for use in atmospheric chemistry simulations,
climate change impact studies, and multi-disciplinary environmental research.

---

## Installation
```bash
pip install cinei
```

---

## Quick Start
```python
import cinei

# 1. Download input data
cinei.download_ceds(save_dir='/data/CEDS', species=['NMVOC'])
cinei.download_htap_monthly(
    save_dir='/data/HTAP', species=['NMVOC'], year=2017, month=1)
cinei.download_meic_sample(save_dir='/data/MEIC', months=['jan'])

# 2. Run emission integration
output = cinei.emis_union(
    species   = 'NMVOC',     # target species (auto-mapped across inventories)
    month     = 1,           # month as integer 1-12
    year      = 2017,        # target year
    outer_dir = '/data/CEDS',  # global background inventory (CEDS)
    inner_dir = '/data/MEIC',  # regional inventory (MEIC for China)
    save_dir  = '/data/output',
    agg_dir   = '/data/HTAP',  # aggregated sectors (waste/shipping/aviation)
    region    = 'China',     # region of interest
    output_res= 0.25,        # output resolution in degrees
)

# 3. Plot all sectors
cinei.cinei_plot(output, save_path='/data/output/sectors.png')

# 4. Optional: NMVOC speciation into lumped model species
cinei.nmvoc_speciation(nmvoc_nc_path=output, save_dir='/data/output/voc/')
```

---

## Key Functions

| Function | Description |
|----------|-------------|
| `emis_union()` | Core integration: merge outer + inner inventories |
| `cinei_plot()` | Plot all 8 sectors + sum in one figure |
| `download_ceds()` | Download CEDS v2021 gridded data |
| `download_htap()` / `download_htap_monthly()` | Download HTAP v3 data |
| `download_edgar()` / `download_edgar_monthly()` | Download EDGAR v8.1 data |
| `download_meic_sample()` | Download MEIC 2017 sample data |
| `nmvoc_speciation()` | Disaggregate NMVOC into lumped model species |
| `check_user_data()` | Diagnose user-provided emission files |
| `standardize_netcdf()` | Standardize NetCDF to CINEI format |
| `list_regions()` | Show supported region presets |

### `emis_union()` argument reference

| Argument | Type | Description |
|----------|------|-------------|
| `species` | str | Species name, case-insensitive. e.g. `'NMVOC'`, `'SO2'`, `'NOx'` |
| `month` | int or str | Month as integer (1-12), `'01'`, or `'Jan'` |
| `year` | int or str | Target year, e.g. `2017` |
| `outer_dir` | str | Directory of global background inventory (CEDS/EDGAR/HTAP/user) |
| `inner_dir` | str | Directory of regional inventory (MEIC/user/EDGAR/HTAP) |
| `save_dir` | str | Output directory |
| `outer_source` | str | Outer inventory type: `'CEDS'`, `'EDGAR'`, `'HTAP'`, `'user'` |
| `inner_source` | str | Inner inventory type: `'MEIC'`, `'user'`, `'EDGAR'`, `'HTAP'` |
| `agg_dir` | str | Directory for HTAP aggregated sectors (waste/shipping/aviation) |
| `mapper_path` | str | Path to species mapper CSV. Default: bundled |
| `country_shp` | str | Path to country shapefile. Default: bundled |
| `province_shp` | str | Path to province shapefile. Default: bundled |
| `output_res` | float | Output resolution: `0.05`, `0.1`, `0.25`, `0.5` |
| `sectors` | list or `'all'` | Sectors to integrate. Default: all 8 sectors |
| `region` | str | Region name: `'China'`, `'Beijing'`, `'NCP'`, `'Germany'`, etc. |
| `global_domain` | bool | If `True`, use global extent |
| `lon_min/max` | float | Manual longitude bounds (when `region=None`) |
| `lat_min/max` | float | Manual latitude bounds (when `region=None`) |
| `nmvoc_speciation` | bool | If `True`, auto-run VOC speciation after integration |

---

## Supported Inventories

| Inventory | Version | Resolution | Coverage |
|-----------|---------|------------|----------|
| CEDS | v_2021_04_21 | 0.5° | Global, 1750–2019 |
| MEIC | v1.4 | 0.25° | China, monthly |
| HTAP | v3 | 0.1° / 0.5° | Global, 2000–2018 |
| EDGAR | v8.1 | 0.1° | Global, 1970–2022 |

---

## Citation

If you use CINEI in your research, please cite:
```
Zhang, Y.: CINEI V1.1, https://doi.org/10.5281/zenodo.15000795, 2025.
```

---

## Author

**Yijuan Zhang, PhD candidate**
Institute of Environmental Physics (IUP), University of Bremen
and Max Planck Institute for Meteorology (MPI-M), Hamburg, Germany

---

## Acknowledgements

The development of CINEI was supported by computing resources provided by:

**Deutsches Klimarechenzentrum (DKRZ)**
*(German Climate Computing Centre)*
Project allocation: b123456

DKRZ provides high-performance computing infrastructure for climate and
earth system research in Germany and is a key facility for the German
climate research community.

---

## License

MIT License
