Metadata-Version: 2.4
Name: climagrid
Version: 0.1.0
Summary: Climate data, grid-ready — open NOAA/NASA/USDA inputs for electric utility predictive maintenance
Project-URL: Homepage, https://github.com/TemidireAdesiji/climagrid
Project-URL: Documentation, https://climagrid.readthedocs.io
Project-URL: Repository, https://github.com/TemidireAdesiji/climagrid
Project-URL: Issues, https://github.com/TemidireAdesiji/climagrid/issues
Author: Temidire Adesiji
License: Apache-2.0
License-File: LICENSE
Keywords: NASA,NOAA,USDA,climate,electric utility,grid resilience,predictive maintenance,rural cooperative,weather
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: geopandas>=0.14
Requires-Dist: httpx>=0.25
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyproj>=3.5
Requires-Dist: requests>=2.31
Requires-Dist: scipy>=1.11
Requires-Dist: shapely>=2.0
Requires-Dist: xarray>=2024.1
Provides-Extra: dev
Requires-Dist: hypothesis>=6.0; extra == 'dev'
Requires-Dist: ipykernel>=6.25; extra == 'dev'
Requires-Dist: mypy>=1.5; extra == 'dev'
Requires-Dist: nbconvert>=7.0; extra == 'dev'
Requires-Dist: nbformat>=5.9; extra == 'dev'
Requires-Dist: pandas-stubs>=2.0; extra == 'dev'
Requires-Dist: plotext>=5.2; extra == 'dev'
Requires-Dist: pyarrow>=14.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: responses>=0.24; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Requires-Dist: scikit-learn>=1.3; extra == 'dev'
Requires-Dist: types-requests>=2.31; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo>=2023.9; extra == 'docs'
Requires-Dist: myst-parser>=2.0; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints>=1.24; extra == 'docs'
Requires-Dist: sphinx>=7.0; extra == 'docs'
Provides-Extra: full
Requires-Dist: cfgrib>=0.9; extra == 'full'
Requires-Dist: herbie-data>=2024.3; extra == 'full'
Requires-Dist: metpy>=1.5; extra == 'full'
Requires-Dist: pvlib>=0.10; extra == 'full'
Provides-Extra: met
Requires-Dist: metpy>=1.5; extra == 'met'
Provides-Extra: nasa
Requires-Dist: pvlib>=0.10; extra == 'nasa'
Provides-Extra: noaa-nwp
Requires-Dist: cfgrib>=0.9; extra == 'noaa-nwp'
Requires-Dist: herbie-data>=2024.3; extra == 'noaa-nwp'
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/assets/banner.png" alt="climagrid" />
</p>

<h1 align="center">climagrid</h1>

<p align="center">
  Free, open-source environmental stress features for electric utility predictive maintenance —<br/>
  turning public NOAA, NASA, USDA, and USFS data into ML-ready inputs for the tools utilities already run.
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache 2.0" /></a>
  <a href="https://pypi.org/project/climagrid/"><img src="https://img.shields.io/pypi/v/climagrid?logo=pypi&logoColor=white" alt="PyPI" /></a>
  <a href="https://github.com/TemidireAdesiji/climagrid/actions/workflows/ci.yml"><img src="https://github.com/TemidireAdesiji/climagrid/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
  <a href="https://climagrid.readthedocs.io/en/latest/"><img src="https://readthedocs.org/projects/climagrid/badge/?version=latest" alt="Docs" /></a>
  <img src="https://img.shields.io/badge/python-3.10+-3776ab?logo=python&logoColor=white" alt="Python 3.10+" />
  <a href="https://doi.org/10.5281/zenodo.XXXXXXX"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.XXXXXXX.svg" alt="DOI" /></a>
</p>

---

## Why this exists

Power outages cost the U.S. economy about **$67 billion every year** on average, according to Oak Ridge National Laboratory. Most of those outages trace back to weather, vegetation, and environmental stress on aging grid equipment: transformers, power lines, and circuit breakers.

Large utilities can afford expensive software to monitor this risk. The **roughly 900 rural electric cooperatives and 2,000 municipal utilities that serve 42 million Americans across 56% of U.S. landmass** mostly cannot. They have small engineering teams, no data scientists, and no budget for six-figure software contracts.

climagrid is built for them. It is free, open source (Apache 2.0), and runs on a single laptop. It takes weather and environmental data that the U.S. government already publishes for free, from NOAA, NASA, the USDA, and the U.S. Forest Service, and turns it into the kind of information a maintenance engineer can actually use: *which of my transformers are under the most stress this month? Which power-line spans are at the highest fire risk? Which areas need a crew sent out first?*

The U.S. Department of Energy reports that predictive maintenance can cut equipment costs by 25-30% and return roughly $10 for every $1 invested. climagrid aims to make those benefits available to the smaller utilities that serve rural America.

---

## What it does

```mermaid
flowchart LR
    subgraph sources["Public Data Sources"]
        direction TB
        hrrr["NOAA HRRR\natmospheric · 3 km"]
        power["NASA POWER\nsatellite-derived"]
        ncei["NOAA NCEI\nsurface stations"]
        nrcs["USDA NRCS\nsoil sensors"]
        wfigs["USFS WFIGS\nfire perimeters"]
    end

    assets["Your assets\nCSV or GeoJSON\nasset_id · lat · lon"]

    run(["climagrid.run()"])

    subgraph features["Stress Features — one row per asset per hour"]
        direction TB
        thermal["feat_thermal_aging_factor"]
        sag["feat_conductor_sag_index"]
        ice["feat_ice_loading_risk"]
        ft["feat_freeze_thaw_cycles"]
        soil["feat_soil_saturation_index"]
        fire["feat_wildfire_proximity"]
    end

    df[("ML-ready DataFrame")]

    sources --> run
    assets --> run
    run --> features
    features --> df
```

---

## Who this is for

- **Rural electric cooperatives** and **municipal utilities** that want to start using weather and environmental data in their maintenance planning but don't have a data-science team to build the pipeline.
- **Utility engineers** who already run predictive-maintenance or anomaly-detection models and want to add environmental features to improve them.
- **Researchers and journalists** studying grid resilience and rural energy equity.

If you serve fewer than 100,000 meters and your weather "data integration" today is "we check the National Weather Service app before a storm," this toolkit is built for you.

---

## Quick start

```bash
pip install climagrid
```

```python
import climagrid
from datetime import datetime, timezone

df = climagrid.run(
    "my_transformers.csv",          # CSV with asset_id, lat, lon columns
    start_dt=datetime(2024, 7, 1,  tzinfo=timezone.utc),
    end_dt=datetime(2024, 7, 31, tzinfo=timezone.utc),
    sources=["nasa_power"],         # no API key required
    features="all",
)
df.to_parquet("stress_features.parquet")
```

![climagrid terminal demo](docs/assets/demo.gif)

You now have a file you can join to your maintenance records and feed into whatever model or spreadsheet you already use. See the [quickstart notebook](examples/quickstart.ipynb) for a worked example.

![Asset thermal stress map — Central Texas](docs/assets/quickstart_map.png)

For the lower-level adapter API (fetching individual data sources, custom feature computation) see the [documentation](https://climagrid.readthedocs.io).

---

## Data sources

| Agency | Dataset | Variables | Frequency |
|---|---|---|---|
| NOAA | HRRR (3 km CONUS) | Temperature, wind, precipitation, humidity, solar | Hourly |
| NOAA | NCEI CDO (stations) | Temperature, wind, precipitation | Hourly/Daily |
| NASA | POWER API (MERRA-2) | Surface meteorology, irradiance | Hourly/Daily |
| USDA NRCS | SCAN / SNOTEL | Soil moisture, soil temperature, snow water equivalent | Hourly |
| USFS / NIFC | WFIGS | Active wildfire perimeters, fire area | Daily |

All sources are free and publicly accessible. NOAA NCEI requires a free API token (register at ncdc.noaa.gov/cdo-web/token, then set the `NOAA_CDO_TOKEN` environment variable). All other sources work without credentials.

---

## Environmental stress features

| Feature | Output column | Target assets | Standard |
|---|---|---|---|
| Transformer thermal aging factor | `feat_thermal_aging_factor` | Transformers | IEEE C57.91 |
| Heat accumulation hours | `feat_heat_hours_above_35c` | Transformers, switchgear | IEEE C57.91 |
| Freeze-thaw cycles | `feat_freeze_thaw_cycles` | Conductors, insulators, poles | — |
| Ice loading risk | `feat_ice_loading_risk` | Overhead T&D lines | ASCE 7-22 |
| Soil saturation index | `feat_soil_saturation_index` | Underground cables, poles | — |
| Wildfire proximity score | `feat_wildfire_proximity` | All overhead assets | — |
| Conductor sag index | `feat_conductor_sag_index` | Overhead T&D lines | IEEE 738-2012 |

---

## How this is different from existing tools

| Tool | What it does | How climagrid is different |
|---|---|---|
| atlite (PyPSA) | Turns weather into renewable-generation forecasts | climagrid focuses on equipment failure stress, not generation |
| ERAD (NREL) | Estimates damage from one-time disasters (hurricanes, floods) | climagrid produces continuous stress features for day-to-day maintenance |
| OpenSTEF | Forecasts feeder load using weather inputs | climagrid produces asset-health features, not load forecasts |
| NRECA OMF | Simulates rural-coop feeders to evaluate new technologies | climagrid feeds maintenance models, not feeder simulators |
| EEweather (OpenDSM) | Pulls NOAA temperature for energy-efficiency baselines | climagrid integrates five federal sources and produces grid-stress features |

See the [full related-work review](docs/related_work.md).

---

## National impact

- About **42 million Americans** are served by rural electric cooperatives, covering **56% of U.S. landmass** (NRECA).
- Major U.S. power outages cost roughly **$67 billion per year** on average (Oak Ridge National Laboratory).
- Predictive maintenance reduces equipment-maintenance costs by **25-30%** with about a **10-to-1 return on investment** (U.S. Department of Energy).
- climagrid is released under the **Apache 2.0 license** so that any utility, regardless of size or budget, can use, modify, and redistribute it freely and permanently.

For more on how climagrid ties into U.S. grid resilience priorities, see [docs/national_impact.md](docs/national_impact.md).

---

## Citation

If you use climagrid in research, regulatory filings, or utility planning, please cite it using the metadata in [CITATION.cff](CITATION.cff), or:

```
Adesiji, T. (2026). climagrid: Open-source environmental stress feature toolkit
for electric utility predictive maintenance (v0.1.0). Apache 2.0.
https://doi.org/10.5281/zenodo.XXXXXXX
```

---

## Contributing

climagrid welcomes contributions from utility engineers, data scientists, and researchers. See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add a new data source adapter or stress feature. Project governance is documented in [GOVERNANCE.md](GOVERNANCE.md).

---

## License

Apache License 2.0. See [LICENSE](LICENSE) for full text.

Copyright 2026 Temidire Adesiji
