usdata 0.22.0__tar.gz → 0.23.0__tar.gz

{usdata-0.22.0 → usdata-0.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: usdata
-Version: 0.22.0
+Version: 0.23.0
 Summary: Unified Python SDK and CLI for discovering, fetching, and tracking provenance of U.S. public scientific data
 Keywords: noaa,usgs,open-data,scientific-data,provenance,reproducible-research,weather,climate,meteorology
 Author: Jake Van Slyke
@@ -66,10 +66,29 @@ for pinning inputs across sources and proving later that they have not changed.
 pip install "usdata[pandas]"
 usdata search precipitation --location Oklahoma
 usdata fetch noaa:ghcn-daily -p stations=USW00013967 --start 2024-05-06 --end 2024-05-07
+```
+
+Save the same station query as `dataset.yaml` in your working directory:
+
+```yaml
+name: first-station
+sources:
+  - dataset: noaa:ghcn-daily
+    start: 2024-05-06
+    end: 2024-05-07
+    params:
+      stations: USW00013967
+```
+
+Then fetch and pin its inputs, and print their citation:
+
+```sh
 usdata pull dataset.yaml && usdata cite dataset.yaml
 ```
 
-The same four steps from Python:
+The first pull writes `dataset.lock.json`; later pulls restore its pinned assets.
+
+From Python, using the same `dataset.yaml`:
 
 ```python
 from usdata import build_query, fetch, get, pull

{usdata-0.22.0 → usdata-0.23.0}/README.md

@@ -21,10 +21,29 @@ for pinning inputs across sources and proving later that they have not changed.
 pip install "usdata[pandas]"
 usdata search precipitation --location Oklahoma
 usdata fetch noaa:ghcn-daily -p stations=USW00013967 --start 2024-05-06 --end 2024-05-07
+```
+
+Save the same station query as `dataset.yaml` in your working directory:
+
+```yaml
+name: first-station
+sources:
+  - dataset: noaa:ghcn-daily
+    start: 2024-05-06
+    end: 2024-05-07
+    params:
+      stations: USW00013967
+```
+
+Then fetch and pin its inputs, and print their citation:
+
+```sh
 usdata pull dataset.yaml && usdata cite dataset.yaml
 ```
 
-The same four steps from Python:
+The first pull writes `dataset.lock.json`; later pulls restore its pinned assets.
+
+From Python, using the same `dataset.yaml`:
 
 ```python
 from usdata import build_query, fetch, get, pull

{usdata-0.22.0 → usdata-0.23.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "usdata"
-version = "0.22.0"
+version = "0.23.0"
 description = "Unified Python SDK and CLI for discovering, fetching, and tracking provenance of U.S. public scientific data"
 readme = "README.md"
 license = "Apache-2.0"

{usdata-0.22.0 → usdata-0.23.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "usdata"
-version = "0.22.0"
+version = "0.23.0"
 description = "Unified Python SDK and CLI for discovering, fetching, and tracking provenance of U.S. public scientific data"
 readme = "README.md"
 license = "Apache-2.0"

{usdata-0.22.0 → usdata-0.23.0}/src/usdata/data/registry.yaml

@@ -731,14 +731,15 @@ datasets:
     since: "0.11"
     title: U.S. Climate Normals 1991-2020
     description: >-
-      Daily, monthly, and annual/seasonal 30-year station normals via the NCEI Access Data
-      Service datasets normals-daily-1991-2020, normals-monthly-1991-2020, and
-      normals-annualseasonal-1991-2020, chosen with a period parameter. Dates are optional;
-      daily and monthly normals accept a month-day window inside a placeholder year. Explicit
+      Hourly, daily, monthly, and annual/seasonal 30-year station normals via the NCEI Access Data
+      Service datasets normals-hourly-1991-2020, normals-daily-1991-2020, normals-monthly-1991-2020,
+      and normals-annualseasonal-1991-2020, chosen with a period parameter. Dates are optional;
+      hourly, daily, and monthly normals accept a month-day window inside a placeholder year.
+      Hourly labels use local standard time, with no February 29 values. Explicit
       stations or station discovery through the companion search service. Variables are NCEI
       data-type codes and the catalog lists the probed ones; the delivered set is the open NCEI
       normals list.
-    keywords: [climate, normals, averages, stations, temperature, precipitation, ncei]
+    keywords: [climate, normals, averages, stations, temperature, precipitation, hourly, ncei]
     protocol: http
     homepage: https://www.ncei.noaa.gov/products/land-based-station/us-climate-normals
     license: US Government Work (public domain)
@@ -747,17 +748,18 @@ datasets:
     capabilities: { spatial_subset: false, temporal_subset: true, variable_subset: true }
     summary: 30-year station climate normals
     formats: [CSV]
-    selection: Monthly, daily, or annual/seasonal normals per station; optional month-day window for daily and monthly
+    selection: Hourly, daily, monthly, or annual/seasonal normals per station; optional month-day window except annual/seasonal; hourly returns whole days
     inputs: Station IDs or a geographic query; dates optional
     reader: pandas
     guide: docs/providers/noaa-normals.md
     examples:
       - examples/climate-normals/README.md
       - examples/climate-anomalies/example.ipynb
+      - examples/hourly-anomalies/example.ipynb
     resolution:
       spatial: "U.S. land surface stations with 1991-2020 normals coverage"
       temporal: >-
-        Daily, monthly, or annual and seasonal normals, chosen with the period parameter
+        Hourly, daily, monthly, or annual and seasonal normals, chosen with the period parameter
     update_frequency: "As needed; the normals are republished about once a decade"
     citation: >-
       Palecki, Michael; Durre, Imke; Applequist, Scott; Arguez, Anthony; Lawrimore, Jay (2021).
@@ -765,6 +767,7 @@ datasets:
       Information; cite the record for the period used
     terms: https://www.ncei.noaa.gov/products/land-based-station/us-climate-normals
     variables:
+      - { name: "HLY-TEMP-NORMAL", units: "degrees Celsius", description: "Hourly normal mean temperature (metric units); local standard time" }
       - { name: "MLY-TMAX-NORMAL", units: "degrees Celsius", description: "Monthly normal maximum temperature" }
       - { name: "MLY-TMIN-NORMAL", units: "degrees Celsius", description: "Monthly normal minimum temperature" }
       - { name: "MLY-PRCP-NORMAL", units: "mm", description: "Monthly normal precipitation total" }
@@ -1144,6 +1147,7 @@ datasets:
     guide: docs/providers/noaa-lcd.md
     examples:
       - examples/hourly-observations/README.md
+      - examples/hourly-anomalies/example.ipynb
     resolution:
       spatial: "Airport and first-order stations, addressed by eleven-digit station id"
       temporal: "Hourly, special, and synoptic reports, plus daily and monthly summaries"

{usdata-0.22.0 → usdata-0.23.0}/src/usdata/providers/noaa/normals.py

@@ -1,14 +1,16 @@
 """U.S. Climate Normals 1991-2020 through the NCEI Access Data Service.
 
-Params: ``period`` (``monthly`` by default, ``daily``, or ``annualseasonal``),
+Params: ``period`` (``monthly`` by default, ``daily``, ``annualseasonal``, or ``hourly``),
 ``stations`` (list or comma string), and ``units`` (metric or standard).
 
-Normals are 30-year averages, not observations, so dates are optional. For daily
-and monthly normals an optional ``start``/``end`` pair selects a calendar window
+Normals are 30-year averages, not observations, so dates are optional. For hourly,
+daily, and monthly normals an optional ``start``/``end`` pair selects a calendar window
 by month and day; the year is ignored and sent as the placeholder 2020, a leap
 year so February 29 is valid. Windows cannot cross the new year. Without dates
 the whole year is requested. Annual/seasonal normals accept no dates. Assets
 carry the 1991-2020 normals period as their time bounds.
+Hourly normals return all hours of each selected day, labeled in local standard
+time as ``MM-DDTHH:MM:SS``. They have no February 29 values.
 """
 
 from __future__ import annotations
@@ -29,6 +31,7 @@ PERIODS = {
     "monthly": "normals-monthly-1991-2020",
     "daily": "normals-daily-1991-2020",
     "annualseasonal": "normals-annualseasonal-1991-2020",
+    "hourly": "normals-hourly-1991-2020",
 }
 PLACEHOLDER_YEAR = 2020
 NORMALS_PERIOD = TimeRange(
@@ -41,7 +44,7 @@ class ClimateNormalsParams(GhcnDailyParams):
     """A normals query also names which averaging period it wants."""
 
     period: Annotated[str, choice(*PERIODS)] = Field(
-        default="monthly", description="monthly (default), daily, or annualseasonal."
+        default="monthly", description="monthly (default), daily, annualseasonal, or hourly."
     )