usdata 0.22.0__tar.gz → 0.24.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: usdata
-Version: 0.22.0
+Version: 0.24.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
@@ -93,7 +112,7 @@ breaking changes.
 | [docs.usdata.dev](https://docs.usdata.dev/) | How to use it: [install](https://docs.usdata.dev/install/), [getting started](https://docs.usdata.dev/getting-started/), guides, dataset notes, and reference |
 | [Severe-weather case study](https://usdata.dev/examples/severe-weather-case-study/) | One tornado, six sources, one manifest and lockfile, ending in a citation |
 
-Twenty-five datasets are available today and twenty more are planned, grouped
+Twenty-six datasets are available today and twenty more are planned, grouped
 by agency and product family in the [catalog](docs/providers/README.md).
 
 ## How this compares

{usdata-0.22.0 → usdata-0.24.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
@@ -48,7 +67,7 @@ breaking changes.
 | [docs.usdata.dev](https://docs.usdata.dev/) | How to use it: [install](https://docs.usdata.dev/install/), [getting started](https://docs.usdata.dev/getting-started/), guides, dataset notes, and reference |
 | [Severe-weather case study](https://usdata.dev/examples/severe-weather-case-study/) | One tornado, six sources, one manifest and lockfile, ending in a citation |
 
-Twenty-five datasets are available today and twenty more are planned, grouped
+Twenty-six datasets are available today and twenty more are planned, grouped
 by agency and product family in the [catalog](docs/providers/README.md).
 
 ## How this compares

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

@@ -1,6 +1,6 @@
 [project]
 name = "usdata"
-version = "0.22.0"
+version = "0.24.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.24.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "usdata"
-version = "0.22.0"
+version = "0.24.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.24.0}/src/usdata/data/registry.yaml

@@ -641,6 +641,47 @@ datasets:
     limits: { max_window: P366D }
     adapter: usdata.providers.noaa.coops:CoopsTidePredictions
 
+  - id: noaa:coops-currents
+    provider: noaa
+    status: available
+    system: noaa:coops
+    domain: ocean-physics
+    since: "0.24"
+    title: CO-OPS Observed Currents
+    description: >-
+      Native six-minute current speed and direction from the anonymous CO-OPS
+      Data API. Select one alphanumeric station, a positive bin, units, and a
+      UTC interval of at most 28 days. Raw CSV preserves gaps and blank values.
+      Bin depths can change between deployments; the CSV carries bin number,
+      not depth or a verification-quality flag. Predictions, all-bin queries,
+      station discovery, and resampling are not included.
+    keywords: [currents, current speed, current direction, coastal, ocean, coops, ports, stations, bin]
+    protocol: http
+    homepage: https://api.tidesandcurrents.noaa.gov/api/prod/
+    license: US Government Work (public domain)
+    capabilities: { spatial_subset: false, temporal_subset: true, variable_subset: false }
+    summary: Coastal current speed and direction
+    formats: [CSV]
+    selection: Native six-minute observations for one station and explicit bin; at most 28 days
+    inputs: Alphanumeric station, positive bin, and both minute-aligned timestamps
+    reader: pandas
+    guide: docs/providers/noaa-coops-currents.md
+    examples:
+      - examples/coastal-currents/example.ipynb
+    resolution:
+      spatial: One current-meter station and bin per request; bin depths depend on deployment
+      temporal: Six-minute observations
+    citation: >-
+      NOAA National Ocean Service, CO-OPS observed currents, accessed via usdata
+    terms: https://tidesandcurrents.noaa.gov/disclaimers.html
+    variables:
+      - { name: "Date Time", units: "UTC", description: "Observation time, requested with time_zone=gmt" }
+      - { name: "Speed", units: "cm/s", description: "Observed current speed in metric units; knots with english units" }
+      - { name: "Direction", units: "degrees", description: "Observed current direction" }
+      - { name: "Bin", description: "Requested bin number, not a depth measurement" }
+    limits: { max_window: P28D }
+    adapter: usdata.providers.noaa.coops:CoopsCurrents
+
   - id: noaa:gsom
     provider: noaa
     status: available
@@ -731,14 +772,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 +789,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 +808,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 +1188,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.24.0}/src/usdata/providers/noaa/coops.py

@@ -1,17 +1,21 @@
-"""CO-OPS observed water levels and tide predictions as raw CSV.
+"""CO-OPS observed water levels, currents, and tide predictions as raw CSV.
 
-Both datasets share one station model: one seven-digit ``station``, an explicit
+Water levels and tide predictions share one station model: one seven-digit ``station``, an explicit
 ``datum``, optional ``units`` (metric or english), and both timestamps at minute
 precision, requested in UTC; a bare end date means 23:59 on that day.
 Observations span at most 28 days; predictions
 span at most a year on any ``interval`` (six-minute by default, another minute
 step, hourly, or high/low), within NOAA's own limits.
+Currents instead name an alphanumeric station and explicit positive bin, with
+no datum or interval selector. Their native six-minute observations share the
+28-day window and use cm/s (metric) or knots (english).
 """
 
 from __future__ import annotations
 
 import csv
 import hashlib
+import math
 from collections.abc import Iterator
 from datetime import UTC, datetime, timedelta
 from pathlib import Path
@@ -25,7 +29,7 @@ from usdata.models import Asset, Protocol, Query, TimeRange
 from usdata.protocols import http
 from usdata.providers.base import QueryError
 from usdata.providers.http import HttpProvider
-from usdata.providers.params import choice
+from usdata.providers.params import choice, positive_int
 from usdata.query import LAST_INSTANT
 
 DATA_URL = "https://api.tidesandcurrents.noaa.gov/api/prod/datagetter"
@@ -44,6 +48,7 @@ OBSERVATION_COLUMNS = {
     "Quality",
 }
 PREDICTION_COLUMNS = {"Date Time", "Prediction"}
+CURRENTS_COLUMNS = {"Date Time", "Speed", "Direction", "Bin"}
 
 
 def _rows(path: Path, asset: Asset, required: set[str]) -> Iterator[dict[str, str]]:
@@ -150,6 +155,29 @@ class CoopsPredictionParams(CoopsParams):
         return token
 
 
+class CoopsCurrentsParams(BaseModel):
+    """One current-meter station and bin; a bin is not a permanent depth."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    station: str = Field(
+        description="Required alphanumeric CO-OPS currents station id, for example 'cb0102'."
+    )
+    bin: Annotated[int, positive_int()] = Field(
+        description="Required positive bin number; 0 (all bins) is not supported."
+    )
+    units: Annotated[str, choice("metric", "english")] = Field(
+        default="metric", description="metric (default, cm/s) or english (knots)."
+    )
+
+    @field_validator("station", mode="before")
+    @classmethod
+    def _one_station_id(cls, value: object) -> object:
+        if not isinstance(value, str) or not value.isascii() or not value.isalnum():
+            raise ValueError("must be an alphanumeric string, for example 'cb0102'")
+        return value
+
+
 class _CoopsStation(HttpProvider):
     """Shared window, request, and validation rules for CO-OPS station products."""
 
@@ -255,3 +283,38 @@ class CoopsTidePredictions(_CoopsStation):
     def _validate(self, path: Path, asset: Asset) -> None:
         interval = httpx.URL(asset.href).params.get("interval", "6")
         _validate_predictions(path, asset, interval)
+
+
+class CoopsCurrents(_CoopsStation):
+    """One station's observed current speed and direction at an explicit bin."""
+
+    product = "currents"
+    label = "current"
+    params_model = CoopsCurrentsParams
+
+    def list_assets(self, query: Query) -> list[Asset]:
+        """Describe one native-interval CSV request; check availability on fetch."""
+        params = self.parse_params(query, CoopsCurrentsParams)
+        self.reject(query, "bbox", "text", "variables", hint="CO-OPS requires an explicit station")
+        start, end = self._window(query, MAX_INTERVAL)
+        request = {"bin": str(params.bin), "units": params.units}
+        return [self._asset(params.station, start, end, request)]
+
+    def _validate(self, path: Path, asset: Asset) -> None:
+        expected_bin = int(httpx.URL(asset.href).params["bin"])
+        count = 0
+        for row in _rows(path, asset, CURRENTS_COLUMNS):
+            token = row["Bin"]
+            if not token.isascii() or not token.isdigit() or int(token) != expected_bin:
+                raise ValueError("record does not match the requested bin")
+            # Preserve blank measurements and missing timestamps, not invented values.
+            for field in ("Speed", "Direction"):
+                if row[field]:
+                    value = float(row[field])
+                    if not math.isfinite(value) or value < 0:
+                        raise ValueError(f"invalid current {field.lower()}")
+                    if field == "Direction" and value > 360:
+                        raise ValueError("current direction must be between 0 and 360 degrees")
+            count += 1
+        if not count:
+            raise ValueError("no current observations returned")

{usdata-0.22.0 → usdata-0.24.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."
     )