Serve weather data from GHCNh through a generic load_data api

.gitignore

@@ -21,3 +21,6 @@ coverage.xml
 !.github/
 !.gitignore
 !.gitattributes
+
+# validation run artifact
+validation_results.csv

CHANGELOG.md

@@ -4,6 +4,37 @@ Changelog
 Development
 -----------
 
+* Observed weather data is served from NOAA GHCNh; ISD and GSOD stopped
+  receiving data 2025-08-27. Overlap validation against ISD history shows
+  median hourly deviation of 0.0001 degrees C
+  (`scripts/validate_ghcnh_against_isd.py`).
+* New api: `load_data(usaf_id, start, end, frequency, variables)` returns a
+  DataFrame and warnings, replacing the `load_isd_*`/`load_gsod_*` family;
+  `ISDStation` is renamed `WeatherStation`. GHCNh variables beyond
+  temperature (dew point, relative humidity, wind speed, ...) are available
+  through `variables`.
+* Station registry maps each station to its GHCNh id
+  (`get_ghcn_id(usaf_id)` for one station, `get_ghcn_ids()` for the
+  registry); 349 stations with no
+  GHCNh counterpart are removed. Each station records the first and last
+  year its GHCNh record has observations (`ghcn_first_year`,
+  `ghcn_last_year`); about a fifth of the registry, nearly all low
+  quality, has no observations after 2023.
+* Station quality ratings are computed from the GHCNh inventory (same
+  rule as before: every month of the last five full years above 600
+  observations is high, above 360 is medium). Tiers move for about a
+  fifth of stations, mostly upgrades of stations the retired ISD
+  inventory undercounted: 1858 high / 393 medium / 2246 low.
+* Quality can be rated for the period being requested:
+  `get_station_quality(usaf_id, start, end)` and
+  `rank_stations(..., rating_period=(start, end))` rate stations over
+  the five calendar years ending two years after the period's last
+  date (sliding back to end no later than the last full year), so
+  historical requests rank stations by their reliability in that era.
+  The packaged database carries the monthly counts (`ghcn_inventory`).
+* Caching uses new ghcnh-* keys; ISD-era cache entries are never served.
+* Deleted: FTP fetch code, ISD/GSOD parsing, filename helpers and CLI
+  commands, sphinx docs (documentation moves to opendsm.energy).
 * Switched to https api over FTP for temperature data fetching
 * Remove deprecated `typing` dependency
 * Switch from snapshottest to syrupy for snapshot testing.

README.md

@@ -1,16 +1,30 @@
 # EEweather: Weather station wrangling for EEmeter
 
 [![License](https://img.shields.io/github/license/opendsm/eeweather.svg)](https://github.com/opendsm/eeweather)
-[![Documentation Status](https://readthedocs.org/projects/eeweather/badge/?version=latest)](http://eeweather.readthedocs.io/en/latest/?badge=latest)
 [![PyPI Version](https://img.shields.io/pypi/v/eeweather.svg)](https://pypi.python.org/pypi/eeweather)
 
 ---
 
-**EEweather** — tools for matching to and fetching data from NCEI ISD, TMY3, or CZ2010 weather stations.
+**EEweather** — tools for matching to and fetching data from NCEI GHCNh, TMY3, or CZ2010 weather stations.
 
 EEweather comes with a database of weather station metadata, ZCTA metadata, and GIS data that makes it easier to find the right weather station to use for a particular ZIP code or lat/long coordinate.
 
-[Read the docs.](https://eeweather.readthedocs.org/)
+[Documentation lives at opendsm.energy.](https://opendsm.energy)
+
+## Usage
+
+```python
+import datetime
+import eeweather
+
+station = eeweather.WeatherStation("722880")
+df, warnings = station.load_data(
+    datetime.datetime(2024, 1, 1, tzinfo=datetime.timezone.utc),
+    datetime.datetime(2024, 12, 31, tzinfo=datetime.timezone.utc),
+    frequency="hourly",
+    variables=("temperature",),
+)
+```
 
 ## Installation
 
@@ -22,8 +36,7 @@ $ pip install eeweather
 
 ## Supported Sources of Weather Data
 
-- NCEI Integrated Surface Database (ISD)
-- Global Summary of the Day (GSOD)
+- NOAA Global Historical Climatology Network hourly (GHCNh)
 - NREL Typical Meteorological Year 3 (TMY3)
 - California Energy Commission 1998-2009 Weather Normals (CZ2010)
 
@@ -40,6 +53,7 @@ $ pip install eeweather
   - US Census Bureau (ZCTAs, county shapefiles)
   - Building America climate zone county lists
   - NOAA NCEI Integrated Surface Database Station History
+  - NOAA GHCNh station list
   - NREL TMY3 site
 - Plot maps of outputs
 
@@ -53,24 +67,6 @@ $ source .venv/bin/activate
 $ pip install -e .[dev]
 ```
 
-Build docs:
-
-```
-$ make -C docs html
-```
-
-Autobuild docs:
-
-```
-$ make -C docs livehtml
-```
-
-Check spelling in docs:
-
-```
-$ make -C docs spelling
-```
-
 Run tests:
 
 ```
@@ -93,12 +89,6 @@ Run a tutorial notebook (copy link w/ token, open tutorial.ipynb):
 $ docker-compose up jupyter
 ```
 
-Live-edit docs:
-
-```
-$ docker-compose up docs
-```
-
 Open a shell:
 
 ```

docker-compose.yml

@@ -9,30 +9,13 @@ services:
     volumes:
       - .:/app
 
-  docs:
-    image: eeweather_shell
-    ports:
-      - "${HOST_PORT_DOCS:-8000}:8000"
-    entrypoint: make -C docs livehtml
-    volumes:
-      - .:/app
-
   test:
     image: eeweather_shell
     entrypoint: py.test -n0
     volumes:
       - .:/app
       - /app/tests/__pycache__/
 
-  jupyter:
-    ports:
-      - "${HOST_PORT_JUPYTER:-8888}:${HOST_PORT_JUPYTER:-8888}"
-    image: eeweather_shell
-    entrypoint: |
-      jupyter lab scripts/ --ip=0.0.0.0 --port=${HOST_PORT_JUPYTER:-8888} --allow-root --no-browser
-    volumes:
-      - .:/app
-
   eeweather:
     image: eeweather_shell
     entrypoint: eeweather