usdata 0.23.0__tar.gz → 0.25.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: usdata
-Version: 0.23.0
+Version: 0.25.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
@@ -112,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.23.0 → usdata-0.25.0}/README.md

@@ -67,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.23.0 → usdata-0.25.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "usdata"
-version = "0.23.0"
+version = "0.25.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.23.0 → usdata-0.25.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "usdata"
-version = "0.23.0"
+version = "0.25.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.23.0 → usdata-0.25.0}/src/usdata/data/registry.yaml

@@ -209,30 +209,31 @@ datasets:
     system: noaa:goes-r
     domain: weather-satellites
     since: "0.8"
-    title: GOES-R ABI CONUS Cloud and Moisture Imagery
+    title: GOES-R ABI Cloud and Moisture Imagery
     description: >-
-      Single-channel CONUS Cloud and Moisture Imagery (ABI-L2-CMIPC) from
+      Single-channel CONUS (ABI-L2-CMIPC) and mesoscale (ABI-L2-CMIPM) imagery from
       GOES-16, 17, 18, and 19 in anonymous NOAA S3 buckets. Select an explicit
-      satellite, channel, and scan-start interval; each asset is a complete
+      satellite, channel, scan-start interval, and M1 or M2 for mesoscale; each asset is a complete
       NetCDF scene with no geographic or variable subsetting.
-    keywords: [satellite, imagery, goes, abi, clouds, infrared, reflectance, netcdf, conus]
+    keywords: [satellite, imagery, goes, abi, clouds, infrared, reflectance, netcdf, conus, mesoscale]
     protocol: s3
     homepage: https://registry.opendata.aws/noaa-goes/
     license: US Government Work (public domain)
     temporal_extent: { start: "2017-02-28T00:00:00Z" }
     capabilities: { spatial_subset: false, temporal_subset: true, variable_subset: false }
-    summary: GOES CONUS imagery
+    summary: GOES CONUS and mesoscale imagery
     formats: [NetCDF4]
-    selection: Whole single-channel CONUS scenes by inclusive UTC scan-start time
-    inputs: Satellite, channel, and both timestamps
+    selection: Whole single-channel scenes by inclusive UTC scan-start time and explicit mesoscale sector
+    inputs: Satellite, channel, both timestamps; product and sector for mesoscale
     reader: netcdf
     guide: docs/providers/noaa-goes.md
     examples:
       - examples/goes-imagery/example.ipynb
+      - examples/goes-mesoscale/example.ipynb
       - examples/event-context/example.ipynb
     resolution:
       spatial: "0.5 km to 2 km at nadir, by ABI band"
-      temporal: "One CONUS scan every 5 minutes on average"
+      temporal: "CONUS every 5 minutes; two mesoscale sectors every 60 seconds or one every 30 seconds"
     update_frequency: "New data is added as soon as it's available"
     citation: >-
       NOAA Geostationary Operational Environmental Satellites (GOES) 16, 17, 18 & 19 was
@@ -641,6 +642,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

{usdata-0.23.0 → usdata-0.25.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.23.0 → usdata-0.25.0}/src/usdata/providers/noaa/goes.py

@@ -1,8 +1,9 @@
-"""GOES ABI CONUS Cloud and Moisture Imagery from anonymous NOAA S3 buckets.
+"""GOES ABI Cloud and Moisture Imagery from anonymous NOAA S3 buckets.
 
 Require ``satellite`` (16, 17, 18, or 19), ``channel`` (1--16 or C01--C16), and
-both timestamps at most seven days apart. The optional ``product`` must be
-``ABI-L2-CMIPC``. Select whole single-channel NetCDF files by inclusive
+both timestamps at most seven days apart. ``product`` defaults to CONUS
+``ABI-L2-CMIPC``; ``ABI-L2-CMIPM`` requires ``sector=M1`` or ``M2``.
+Select whole single-channel NetCDF files by inclusive
 scan-start time, never by scan overlap.
 Geographic and variable subsetting are not available for these archived files.
 ``list_scans`` is shared with the GLM adapter, which selects files under the
@@ -12,10 +13,10 @@ same bucket layout by the same inclusive start-time rule.
 from __future__ import annotations
 
 import re
-from collections.abc import Callable, Mapping
+from collections.abc import Callable
 from datetime import UTC, datetime, timedelta
 from pathlib import Path
-from typing import Annotated
+from typing import Annotated, Self
 
 import httpx
 from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
@@ -24,13 +25,15 @@ from usdata.models import Asset, Protocol, Query, TimeRange
 from usdata.protocols import s3
 from usdata.providers.base import QueryError
 from usdata.providers.http import HttpProvider
-from usdata.providers.params import int_range
+from usdata.providers.params import choice, int_range
 
 PRODUCT = "ABI-L2-CMIPC"
+MESOSCALE_PRODUCT = "ABI-L2-CMIPM"
 PUBLIC_START = datetime(2017, 2, 28, tzinfo=UTC)
 MAX_WINDOW = timedelta(days=7)
 KEY_RE = re.compile(
-    r"OR_ABI-L2-CMIPC-M[346]C(?P<channel>0[1-9]|1[0-6])_G(?P<satellite>1[6-9])"
+    r"OR_ABI-L2-CMIP(?P<sector>C|M[12])-M[346]C(?P<channel>0[1-9]|1[0-6])"
+    r"_G(?P<satellite>1[6-9])"
     r"_s(?P<start>\d{14})_e(?P<end>\d{14})_c\d{14}\.nc"
 )
 
@@ -54,7 +57,14 @@ class GoesAbiParams(BaseModel):
     channel: Annotated[int, int_range(1, 16)] = Field(
         description="Required ABI channel, 1 to 16 or C01 to C16."
     )
-    product: str = Field(default=PRODUCT, description=f"ABI product; only {PRODUCT} is supported.")
+    product: Annotated[str, choice(PRODUCT, MESOSCALE_PRODUCT)] = Field(
+        default=PRODUCT,
+        description="ABI-L2-CMIPC (CONUS, default) or ABI-L2-CMIPM (mesoscale).",
+    )
+    sector: Annotated[str, choice("M1", "M2")] | None = Field(
+        default=None,
+        description="Required for ABI-L2-CMIPM: M1 or M2. Omit for CONUS.",
+    )
 
     @field_validator("channel", mode="before")
     @classmethod
@@ -63,13 +73,13 @@ class GoesAbiParams(BaseModel):
         text = value.strip() if isinstance(value, str) else value
         return text[1:] if isinstance(text, str) and text.startswith("C") else text
 
-    @model_validator(mode="before")
-    @classmethod
-    def _one_supported_product(cls, data: object) -> object:
-        """This adapter serves one ABI product, so name it rather than list the rest."""
-        if isinstance(data, Mapping) and data.get("product", PRODUCT) != PRODUCT:
-            raise ValueError(f"only product={PRODUCT} is supported")
-        return data
+    @model_validator(mode="after")
+    def _sector_matches_product(self) -> Self:
+        if self.product == MESOSCALE_PRODUCT and self.sector is None:
+            raise ValueError("sector=M1 or M2 is required for product=ABI-L2-CMIPM")
+        if self.product == PRODUCT and self.sector is not None:
+            raise ValueError("sector is only supported with product=ABI-L2-CMIPM")
+        return self
 
 
 def list_scans(
@@ -120,7 +130,7 @@ def list_scans(
 
 
 class GoesAbi(HttpProvider):
-    """Single-channel CONUS ABI imagery; params: satellite, channel, product."""
+    """Single-channel CONUS or mesoscale ABI imagery with explicit sector selection."""
 
     params_model = GoesAbiParams
 
@@ -139,16 +149,20 @@ class GoesAbi(HttpProvider):
             raise QueryError("GOES requests must span at most 7 days; split longer intervals")
         satellite, channel = params.satellite, params.channel
         if end < PUBLIC_START:
-            raise QueryError("GOES CMIPC public observations begin on 2017-02-28")
+            raise QueryError("GOES ABI public observations begin on 2017-02-28")
         start = max(start, PUBLIC_START)
         return list_scans(
             self._http(),
             f"noaa-goes{satellite}",
-            PRODUCT,
+            params.product,
             start,
             end,
             KEY_RE,
-            lambda m: int(m["satellite"]) == satellite and int(m["channel"]) == channel,
+            lambda m: (
+                int(m["satellite"]) == satellite
+                and int(m["channel"]) == channel
+                and m["sector"] == (params.sector or "C")
+            ),
             self.dataset.id,
         )