usdata 0.20.0__tar.gz → 0.22.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: usdata
-Version: 0.20.0
+Version: 0.22.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
@@ -93,7 +93,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-three datasets are available today and twenty-one more are planned, grouped
+Twenty-five 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.20.0 → usdata-0.22.0}/README.md

@@ -48,7 +48,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-three datasets are available today and twenty-one more are planned, grouped
+Twenty-five 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.20.0 → usdata-0.22.0}/pyproject.toml

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

@@ -1,6 +1,6 @@
 [project]
 name = "usdata"
-version = "0.20.0"
+version = "0.22.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.20.0 → usdata-0.22.0}/src/usdata/__init__.py

@@ -13,7 +13,16 @@ except PackageNotFoundError:  # running from a source tree without an install
 from usdata._fetch import ChecksumMismatch, FetchedAsset, fetch, fetch_asset
 from usdata.cite import Citation, cite_dataset, cite_lockfile
 from usdata.inspect import inspect_asset, inspect_path
-from usdata.models import Asset, BBox, Dataset, Provenance, Query, TemporalSelection, TimeRange
+from usdata.models import (
+    Asset,
+    BBox,
+    Dataset,
+    Place,
+    Provenance,
+    Query,
+    TemporalSelection,
+    TimeRange,
+)
 from usdata.pull import pull, verify
 from usdata.query import build_query
 from usdata.registry import DatasetNotFound, Registry, SearchResult, default_registry
@@ -27,6 +36,7 @@ __all__ = [
     "Dataset",
     "DatasetNotFound",
     "FetchedAsset",
+    "Place",
     "Provenance",
     "Query",
     "Registry",

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

@@ -308,19 +308,21 @@ datasets:
       NCEI's significant-weather event details since 1950, with locations, impacts, and
       narratives. Anonymous whole-year gzipped CSV archives; select the latest creation-date
       revision for each requested year. No server-side row, location, or variable subsetting.
-      Historical event coverage and reporting practices vary; fatalities and locations tables
-      are separate products not included by this adapter. The catalog lists the identifying
-      columns; the full column set is documented in the NCEI bulk format reference.
+      Historical event coverage and reporting practices vary. The default is the details
+      table; the fatalities table (one row per death) and the locations table (points per
+      event, with rows from 1996) are chosen with the table parameter and join to details on
+      EVENT_ID. The catalog lists the identifying columns; the full column set is documented
+      in the NCEI bulk format reference.
     keywords: [storms, tornado, hail, wind, flood, damage, severe weather, events]
     protocol: http
     homepage: https://www.ncei.noaa.gov/access/storm-events-database/
     license: US Government Work (public domain)
     temporal_extent: { start: "1950-01-01T00:00:00Z" }
     capabilities: { spatial_subset: false, temporal_subset: true, variable_subset: false }
-    summary: Storm Events details
+    summary: Storm Events details, fatalities, and locations
     formats: [gzip CSV]
-    selection: Whole annual archives; filter rows locally after downloading
-    inputs: Both dates (selects the containing years)
+    selection: Whole annual archives of one table; filter rows locally after downloading
+    inputs: Both dates (selects the containing years); optionally table
     reader: pandas
     guide: docs/providers/noaa-storm-events.md
     examples:
@@ -358,18 +360,20 @@ datasets:
       or F rating, injuries, fatalities, loss, start and end coordinates, path
       length and width, and FIPS codes. Whole files linked from the SPC page:
       annual from 2008, half-decade for 2000-2007, decade for 1950-1999.
-      Stable names revised in place; no server-side row, location, or
-      variable subsetting.
-    keywords: [tornado, spc, severe weather, storm reports, tracks, ef scale, fujita]
+      The table parameter selects SPC's hail and wind databases instead, which
+      share the layout and start in 1955; mag is then the stone diameter in
+      inches or the wind speed in knots. Stable names revised in place; no
+      server-side row, location, or variable subsetting.
+    keywords: [tornado, hail, wind, spc, severe weather, storm reports, tracks, ef scale, fujita]
     protocol: http
     homepage: https://www.spc.noaa.gov/wcm/#data
     license: US Government Work (public domain)
     temporal_extent: { start: "1950-01-01T00:00:00Z" }
     capabilities: { spatial_subset: false, temporal_subset: true, variable_subset: false }
-    summary: SPC tornado database
+    summary: SPC tornado, hail, and wind databases
     formats: [CSV]
-    selection: Whole annual, half-decade, or decade files; filter rows locally after downloading
-    inputs: Both dates (selects the files covering those years)
+    selection: Whole annual, half-decade, or decade files of one table; filter rows locally after downloading
+    inputs: Both dates (selects the files covering those years); optionally table
     reader: pandas
     guide: docs/providers/noaa-spc-tornado.md
     examples:
@@ -393,7 +397,7 @@ datasets:
       - { name: "tz", description: "Time-zone code: 3 is Central Standard Time, 9 is GMT, ? is unknown" }
       - { name: "st", description: "Two-letter state" }
       - { name: "stf", description: "State FIPS code" }
-      - { name: "mag", description: "F scale through January 2007 and EF scale afterwards; -9 is unknown" }
+      - { name: "mag", description: "Tornado: F scale through January 2007 and EF scale afterwards, -9 unknown. Hail: size in inches. Wind: speed in knots" }
       - { name: "inj", units: "count", description: "Injuries" }
       - { name: "fat", units: "count", description: "Fatalities" }
       - { name: "loss", description: "Property loss: a 0 to 9 category before 1996, millions of dollars from 1996" }
@@ -405,6 +409,7 @@ datasets:
       - { name: "len", units: "miles", description: "Path length" }
       - { name: "wid", units: "yards", description: "Path width" }
       - { name: "sg", description: "Segment code: 1 a whole track, 2 a state segment, -9 extra county codes" }
+      - { name: "mt", description: "Wind only, from 2006: EG estimated gust, MG measured gust, MS measured sustained, ES estimated sustained" }
     adapter: usdata.providers.noaa.spc:SpcTornadoReports
 
   - id: noaa:hurdat2
@@ -1438,13 +1443,14 @@ datasets:
     title: American Community Survey 5-Year Estimates
     description: >-
       Population, housing, income, and demographic estimates for every
-      geography down to block group, via the Census Data API. Anonymous for
-      light use; an API key lifts rate limits.
+      geography down to block group, via the Census Data API, selected by state
+      and county FIPS code rather than by box. Requires a free API key on every
+      data request; only the dataset and variable metadata are served without one.
     keywords: [population, demographics, housing, income, acs, census]
     protocol: http
     homepage: https://www.census.gov/data/developers/data-sets/acs-5year.html
     license: US Government Work (public domain)
-    capabilities: { spatial_subset: true, temporal_subset: true, variable_subset: true }
+    capabilities: { spatial_subset: false, place_subset: true, temporal_subset: true, variable_subset: true }
 
   # ---------------------------------------------------------------- USDA
   - id: usda:cropland-data-layer
@@ -1540,6 +1546,68 @@ datasets:
       temporal_subset: false
       variable_subset: false
 
+  - id: noaa:nws-vtec-events
+    provider: noaa
+    status: available
+    domain: severe-weather
+    since: "0.22"
+    title: NWS Watch, Warning, and Advisory Events by County
+    description: >-
+      National Weather Service watch, warning, and advisory events issued for one county
+      or forecast zone, one row per event with its issuance and expiry, VTEC phenomena and
+      significance, issuing office, and product id, as CSV from the Iowa Environmental
+      Mesonet's archive of NWS products; the NWS API itself keeps no archive. Rows carry no
+      coordinates, so selection is by a named county rather than by box, and a window
+      selects events by when they were issued, not by when they were in effect. A county
+      reaches county-based products (tornado, severe thunderstorm, flash flood); zone-based
+      products need an explicit UGC. Polygons are a separate product, noaa:nws-warnings.
+    keywords: [warnings, watches, advisories, vtec, nws, tornado warning, lead time, county, ugc]
+    protocol: http
+    homepage: https://mesonet.agron.iastate.edu/info/datasets/vtec.html
+    license: Public domain (NWS products; IEM materials are public domain, attribution appreciated)
+    temporal_extent: { start: "1986-01-01T00:00:00Z" }
+    capabilities:
+      spatial_subset: false
+      place_subset: true
+      temporal_subset: true
+      variable_subset: false
+    summary: NWS warnings and watches by county
+    formats: [CSV]
+    selection: Events issued for one county or UGC inside an inclusive UTC window; optionally one event type
+    inputs: Both timestamps; a county location or a ugc; optionally phenomena with significance
+    reader: pandas
+    guide: docs/providers/noaa-nws-vtec-events.md
+    examples:
+      - examples/warning-lead-time/README.md
+    resolution:
+      spatial: "One county, parish, or forecast zone per request, by NWS UGC code"
+      temporal: "Issuance and expiry to the minute"
+    update_frequency: >-
+      Not stated by IEM, which processes the live NWS product stream; events before 2005
+      come from an NWS database dump rather than from VTEC
+    citation: >-
+      National Weather Service watch, warning, and advisory products, as archived and served
+      by the Iowa Environmental Mesonet of Iowa State University, accessed via usdata
+    terms: https://mesonet.agron.iastate.edu/disclaimer.php
+    variables:
+      - { name: vtec_year, description: "Year the event's VTEC event id belongs to" }
+      - { name: iso_issued, units: "ISO 8601 UTC", description: "When the event was issued for this UGC" }
+      - { name: issued, units: "UTC", description: "The same instant as YYYY-MM-DD HH:MM" }
+      - { name: iso_expired, units: "ISO 8601 UTC", description: "When the event expired or was cancelled for this UGC" }
+      - { name: expired, units: "UTC", description: "The same instant as YYYY-MM-DD HH:MM" }
+      - { name: eventid, description: "VTEC event number, unique per office, phenomena, significance, and year; IEM-assigned before VTEC" }
+      - { name: phenomena, description: "Two-letter VTEC phenomena code, such as TO or SV" }
+      - { name: significance, description: "One-letter VTEC significance code, such as W warning, A watch, Y advisory" }
+      - { name: hvtec_nwsli, description: "NWS location identifier of a hydrologic event's forecast point; empty otherwise" }
+      - { name: wfo, description: "Issuing forecast office; the present-day office for events before 2005" }
+      - { name: ugc, description: "The UGC code the row is for" }
+      - { name: product_id, description: "IEM identifier of the issuing text product" }
+      - { name: name, description: "Phenomena and significance in words, such as Tornado Warning" }
+      - { name: ph_name, description: "Phenomena in words" }
+      - { name: sig_name, description: "Significance in words" }
+      - { name: url, description: "Path of the event's page on the IEM site" }
+    adapter: usdata.providers.noaa.nws_vtec:NwsVtecEvents
+
   - id: noaa:nws-warnings
     provider: noaa
     status: planned
@@ -1598,21 +1666,26 @@ datasets:
 
   - id: fema:disaster-declarations
     provider: fema
-    status: planned
+    status: available
     domain: natural-hazards
-    target: later
+    since: "0.21"
     title: FEMA Disaster Declarations Summaries
     description: >-
-      Every federal disaster declaration since 1953, one row per declaration and
-      designated area, with incident type, dates, programs declared, and county
-      FIPS codes, from the OpenFEMA v2 JSON API (70,402 rows on 2026-09-14; OData
-      filters and paging).
+      Every federally declared disaster since 1953, major disaster, emergency, and fire
+      management declarations alike, one row per declaration and designated area, with the
+      incident type and period, the programs declared, and state and county FIPS codes, from
+      the OpenFEMA v2 API as CSV. Rows carry no coordinates, so selection is by named state or
+      county rather than by box, and a window selects declarations whose incident period
+      overlaps it. The dataset is rebuilt every twenty minutes and rows are revised as
+      incidents close.
     keywords:
       - fema
       - disasters
       - declarations
       - tornado
       - impacts
+      - counties
+      - openfema
     protocol: http
     homepage: https://www.fema.gov/openfema-data-page/disaster-declarations-summaries-v2
     license: US Government Work (public domain)
@@ -1620,5 +1693,59 @@ datasets:
       start: "1953-01-01T00:00:00Z"
     capabilities:
       spatial_subset: false
+      place_subset: true
       temporal_subset: true
-      variable_subset: true
+      variable_subset: false
+    summary: Federal disaster declarations by county
+    formats: [CSV]
+    selection: >-
+      Declarations whose incident period overlaps an inclusive UTC window, for a named state or
+      county; a county also returns its state's statewide designations
+    inputs: Both dates; optionally a state or county location, or state or fips, and type filters
+    reader: pandas
+    guide: docs/providers/fema-disaster-declarations.md
+    examples:
+      - examples/disaster-declarations/README.md
+    resolution:
+      spatial: "One row per designated area: a county or county equivalent, a tribal area, or a whole state"
+      temporal: "Calendar dates for the declaration and for the start and end of the incident"
+    update_frequency: Every twenty minutes (R/PT20M); a record's lastRefresh moves only when it changes
+    citation: >-
+      Federal Emergency Management Agency (FEMA), OpenFEMA Dataset: Disaster Declarations
+      Summaries - v2. Retrieved from
+      https://www.fema.gov/api/open/v2/DisasterDeclarationsSummaries on [date, time]. This
+      product uses the Federal Emergency Management Agency's OpenFEMA API, but is not endorsed
+      by FEMA. The Federal Government or FEMA cannot vouch for the data or analyses derived from
+      these data after the data have been retrieved from the Agency's website(s).
+    terms: https://www.fema.gov/about/openfema/terms-conditions
+    variables:
+      - { name: femaDeclarationString, description: "Declaration type, disaster number, and state code joined, such as DR-4393-NC" }
+      - { name: disasterNumber, description: "Sequentially assigned number designating the declared event" }
+      - { name: state, description: "Two-letter code of the state, district, or territory" }
+      - { name: declarationType, description: "DR major disaster, EM emergency, or FM fire management" }
+      - { name: declarationDate, units: "ISO 8601 UTC", description: "Date the disaster was declared" }
+      - { name: fyDeclared, description: "Fiscal year in which the disaster was declared" }
+      - { name: incidentType, description: "Primary type of incident, such as Fire or Flood" }
+      - { name: declarationTitle, description: "Title for the disaster" }
+      - { name: ihProgramDeclared, description: "Whether the Individuals and Households program was declared" }
+      - { name: iaProgramDeclared, description: "Whether the Individual Assistance program was declared" }
+      - { name: paProgramDeclared, description: "Whether the Public Assistance program was declared" }
+      - { name: hmProgramDeclared, description: "Whether the Hazard Mitigation program was declared" }
+      - { name: incidentBeginDate, units: "ISO 8601 UTC", description: "Date the incident itself began" }
+      - { name: incidentEndDate, units: "ISO 8601 UTC", description: "Date the incident itself ended; empty while open" }
+      - { name: disasterCloseoutDate, units: "ISO 8601 UTC", description: "Date all financial transactions for all programs are completed" }
+      - { name: tribalRequest, description: "Whether a Tribal Nation submitted the request directly to the President" }
+      - { name: fipsStateCode, description: "Two-digit FIPS code of the state, district, or territory" }
+      - { name: fipsCountyCode, description: "Three-digit FIPS code of the county; 000 for a statewide or tribal designation" }
+      - { name: placeCode, description: "FEMA's own location code, 99 plus the county code, covering areas with no FIPS county code" }
+      - { name: designatedArea, description: "Name of the geographic area included in the declaration" }
+      - { name: declarationRequestNumber, description: "Number assigned to the declaration request" }
+      - { name: declarationRequestDate, units: "ISO 8601 UTC", description: "Date the declaration request was made" }
+      - { name: lastIAFilingDate, units: "ISO 8601 UTC", description: "Last date Individual Assistance requests can be filed; after 1998 only" }
+      - { name: incidentId, description: "Identifier of the incident, which may or may not become a declared disaster" }
+      - { name: region, description: "FEMA region, 1 to 10, where the disaster occurred" }
+      - { name: designatedIncidentTypes, description: "Comma-separated codes of every incident type designated for the disaster" }
+      - { name: lastRefresh, units: "ISO 8601 UTC", description: "When the record was last updated in the API data store" }
+      - { name: hash, description: "MD5 hash of the record's fields and values" }
+      - { name: id, description: "Unique id assigned to the record" }
+    adapter: usdata.providers.fema.declarations:DisasterDeclarations

{usdata-0.20.0 → usdata-0.22.0}/src/usdata/models.py

@@ -149,6 +149,9 @@ class Capabilities(BaseModel):
 
     ``spatial_subset`` and ``variable_subset`` mean the request narrows the
     bytes served, so a bbox or a variable list changes the files.
+    ``place_subset`` means a named state or county selects what is served, which
+    is a separate question: a source keyed by FIPS code honours a place and
+    must refuse a bare rectangle, which names no place (ADR 0034).
     ``temporal_subset`` means the time window chooses which assets are fetched,
     whether the source crops files to it or serves whole files that cover it.
     ``partial_fetch`` means selected byte ranges of an object can be fetched on
@@ -157,6 +160,7 @@ class Capabilities(BaseModel):
     """
 
     spatial_subset: bool = False
+    place_subset: bool = False
     temporal_subset: bool = False
     variable_subset: bool = False
     partial_fetch: bool = False
@@ -381,18 +385,73 @@ class Dataset(BaseModel):
         return self.id.split(":", 1)[1]
 
 
+class Place(BaseModel):
+    """The state or county a ``location`` named, as the bundled Census table identifies it.
+
+    A rectangle cannot be turned back into the place it was drawn around, so a
+    query keeps this beside its ``bbox`` for the sources that are keyed by FIPS
+    code rather than by coordinates. See ADR 0034.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    kind: Literal["state", "county"]
+    geoid: str = Field(
+        pattern=r"^\d{2}(\d{3})?$",
+        description="Census GEOID: the two-digit state FIPS code, or the five-digit county one",
+    )
+    label: str = Field(description="The place as the table names it, such as 'Osage County, OK'")
+    state: str = Field(
+        pattern=r"^[A-Z]{2}$",
+        description=(
+            "Two-letter postal code of the state, or of the state a county lies in, such as OK; "
+            "some sources key places by it rather than by the state FIPS code"
+        ),
+    )
+
+    @model_validator(mode="after")
+    def _kind_matches_geoid(self) -> Place:
+        if (self.kind == "state") is not (len(self.geoid) == 2):
+            raise ValueError(f"a {self.kind} geoid cannot be {self.geoid!r}")
+        return self
+
+    @property
+    def state_fips(self) -> str:
+        """The two-digit FIPS code of the state, or of the state a county lies in."""
+        return self.geoid[:2]
+
+    @property
+    def county_fips(self) -> str | None:
+        """The three-digit county FIPS code within its state, or None for a state."""
+        return self.geoid[2:] or None
+
+
 class Query(BaseModel):
     """Normalized, provider-agnostic request. Providers translate this into their own terms."""
 
     text: str | None = None
     provider: str | None = None
     bbox: BBox | None = None
+    place: Place | None = Field(
+        default=None,
+        description=(
+            "The state or county the spatial filter named, set only when it was given as a "
+            "location; bbox still holds that place's rectangle"
+        ),
+    )
     time: TimeRange | None = None
     variables: list[str] = Field(default_factory=list)
     params: dict[str, Any] = Field(
         default_factory=dict, description="Provider-specific passthrough parameters"
     )
 
+    @model_validator(mode="after")
+    def _place_has_its_box(self) -> Query:
+        # Most adapters read only bbox, so a place without one would select nothing for them.
+        if self.place is not None and self.bbox is None:
+            raise ValueError("a query naming a place must carry that place's bbox")
+        return self
+
 
 class Asset(BaseModel):
     """A single retrievable object (file, granule, or subset request) from a dataset."""

{usdata-0.20.0 → usdata-0.22.0}/src/usdata/providers/__init__.py

@@ -16,6 +16,7 @@ from usdata.providers.params import (
     StrList,
     UpperStrList,
     choice,
+    flag,
     int_list,
     int_range,
     positive_int,
@@ -30,6 +31,7 @@ __all__ = [
     "StrList",
     "UpperStrList",
     "choice",
+    "flag",
     "int_list",
     "int_range",
     "load_adapter",

{usdata-0.20.0 → usdata-0.22.0}/src/usdata/providers/base.py

@@ -13,7 +13,7 @@ from typing import Any, ClassVar, Literal, Self, TypeVar
 from pydantic import BaseModel, ValidationError
 from pydantic_core import ErrorDetails
 
-from usdata.models import Asset, Dataset, PartialFetch, Provenance, Query
+from usdata.models import Asset, Dataset, PartialFetch, Place, Provenance, Query
 
 QueryField = Literal["text", "bbox", "variables", "time"]
 Params = TypeVar("Params", bound=BaseModel)
@@ -25,6 +25,10 @@ _LABELS: dict[QueryField, str] = {
 }
 
 
+BARE_BOX = "bbox or lat/lon"
+"""How ``Provider.place_of`` names the spatial filter a place-keyed source refuses."""
+
+
 class NotImplementedProvider(NotImplementedError):
     """Raised by adapters that are registered but not yet built."""
 
@@ -179,6 +183,29 @@ class Provider(ABC):
             message = f"{self.dataset.id} does not support {', '.join(present)}"
             raise QueryError(f"{message}; {hint}" if hint else message)
 
+    def place_of(self, query: Query, hint: str = "") -> Place | None:
+        """The state or county a query names, for a source keyed by place rather than by box.
+
+        Such a source cannot honour a rectangle: its rows carry FIPS codes and no
+        coordinates, and a box cannot be turned back into the places it covers.
+        A query whose spatial filter was a ``bbox`` or a ``lat``/``lon`` is
+        therefore refused, in the same words for every such source.
+
+        Args:
+            query: The query being listed.
+            hint: What to do instead, usually naming the adapter's own place parameters.
+
+        Returns:
+            The place, or None when the query sets no spatial filter at all.
+
+        Raises:
+            QueryError: The query carries a box that names no place.
+        """
+        if query.place is None and query.bbox is not None:
+            message = f"{self.dataset.id} does not support {BARE_BOX}; name a state or county"
+            raise QueryError(f"{message} with location, or {hint}" if hint else message)
+        return query.place
+
     def utc_window(self, query: Query) -> tuple[datetime, datetime]:
         """Both time bounds, required, in UTC. Naive bounds are read as UTC."""
         if query.time is None or query.time.start is None or query.time.end is None:

usdata-0.22.0/src/usdata/providers/fema/__init__.py

@@ -0,0 +1 @@
+"""FEMA dataset adapters."""