nielytics 0.1.0__py3-none-any.whl

nielytics/__init__.py

@@ -0,0 +1,56 @@
+"""NIElytics: one backend-safe public package for analytics and indicators."""
+
+from .core.visualization import (
+    plot_bar,
+    plot_box,
+    plot_correlation,
+    plot_distribution,
+    plot_geographic,
+    plot_histogram,
+    plot_line,
+    plot_scatter,
+    plot_seasonal,
+    plot_timeseries,
+)
+from .dataset import Dataset
+from .exceptions import (
+    DataLoadError,
+    NIElyticsError,
+    OptionalDependencyError,
+    UnsupportedFormatError,
+    ValidationError,
+)
+from .hazards import (
+    CycloneAnalyzer,
+    DroughtAnalyzer,
+    FloodAnalyzer,
+    HeatwaveAnalyzer,
+    LandslideAnalyzer,
+)
+from .models import AnalysisResult
+
+__version__ = "0.1.0"
+__all__ = [
+    "AnalysisResult",
+    "CycloneAnalyzer",
+    "DataLoadError",
+    "Dataset",
+    "DroughtAnalyzer",
+    "FloodAnalyzer",
+    "HeatwaveAnalyzer",
+    "LandslideAnalyzer",
+    "NIElyticsError",
+    "OptionalDependencyError",
+    "UnsupportedFormatError",
+    "ValidationError",
+    "plot_bar",
+    "plot_box",
+    "plot_correlation",
+    "plot_distribution",
+    "plot_geographic",
+    "plot_histogram",
+    "plot_line",
+    "plot_scatter",
+    "plot_seasonal",
+    "plot_timeseries",
+]

nielytics/climate/__init__.py

@@ -0,0 +1 @@
+"""Verified provider connectors for climate inputs; no network calls on import."""

nielytics/climate/providers/__init__.py

@@ -0,0 +1,47 @@
+"""Verified public climate data connectors. Network is used only when explicitly called.
+
+All online functions accept ``client=HTTPClient(...)`` for injectable transport,
+offline mode, explicit cache TTL and bounded retries; results are AnalysisResult.
+No credentials or forecast APIs are supplied.
+"""
+
+from ._http import HTTPClient, OfflineCacheError, ProviderError, ResponseError
+from .nasa_landslides import (
+    fetch_landslide_events,
+    filter_landslides_by_region,
+    landslide_events_to_geojson,
+    load_landslide_catalog,
+)
+from .nasa_power import fetch_nasa_power_data, fetch_nasa_precipitation
+from .noaa_ibtracs import (
+    cyclone_frequency,
+    cyclone_tracks_to_geojson,
+    get_cyclone_intensity,
+    get_cyclone_tracks,
+    load_ibtracs,
+)
+from .open_meteo import fetch_historical_weather, fetch_rainfall_data, fetch_temperature_data
+from .open_meteo_flood import analyze_discharge_anomalies, fetch_river_discharge
+
+__all__ = [
+    "HTTPClient",
+    "OfflineCacheError",
+    "ProviderError",
+    "ResponseError",
+    "analyze_discharge_anomalies",
+    "cyclone_frequency",
+    "cyclone_tracks_to_geojson",
+    "fetch_historical_weather",
+    "fetch_landslide_events",
+    "fetch_nasa_power_data",
+    "fetch_nasa_precipitation",
+    "fetch_rainfall_data",
+    "fetch_river_discharge",
+    "fetch_temperature_data",
+    "filter_landslides_by_region",
+    "get_cyclone_intensity",
+    "get_cyclone_tracks",
+    "landslide_events_to_geojson",
+    "load_ibtracs",
+    "load_landslide_catalog",
+]

nielytics/climate/providers/_http.py

@@ -0,0 +1,182 @@
+"""Explicit, offline-capable provider HTTP transport. No requests occur on import."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import os
+import time
+from collections.abc import Callable
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+from nielytics.exceptions import NIElyticsError, ValidationError
+
+
+class ProviderError(NIElyticsError):
+    """Provider transport or response failed; inspect the message for context."""
+
+
+class OfflineCacheError(ProviderError):
+    """No acceptable cached response is available in offline mode."""
+
+
+class ResponseError(ProviderError):
+    """Response does not match the documented provider schema."""
+
+
+class HTTPClient:
+    """GET transport with injected ``opener(request, timeout=...)`` and optional disk cache.
+
+    ``cache_dir=None`` disables caching. ``ttl_seconds`` determines when cached
+    data expires, including in offline mode unless ``allow_expired_offline`` is
+    explicitly enabled. ``offline=True`` never contacts the network. Successful
+    responses alone are cached, keyed by full URL and query string. No secrets
+    are stored by these public, credential-free connectors. Retries apply only
+    to 429, 5xx, and connection failures; sleep and clock are injectable.
+    """
+
+    def __init__(
+        self,
+        *,
+        opener: Callable = urlopen,
+        timeout: float = 20,
+        retries: int = 2,
+        backoff: float = 1,
+        cache_dir: str | Path | None = None,
+        ttl_seconds: float = 86400,
+        offline: bool = False,
+        allow_expired_offline: bool = False,
+        sleep: Callable[[float], None] = time.sleep,
+        clock: Callable[[], float] = time.time,
+    ) -> None:
+        if not math.isfinite(timeout) or timeout <= 0:
+            raise ValidationError("timeout must be finite and positive")
+        if isinstance(retries, bool) or not isinstance(retries, int) or not 0 <= retries <= 10:
+            raise ValidationError("retries must be an integer from 0 to 10")
+        if not math.isfinite(backoff) or backoff < 0:
+            raise ValidationError("backoff must be finite and nonnegative")
+        if not math.isfinite(ttl_seconds) or ttl_seconds < 0:
+            raise ValidationError("ttl_seconds must be finite and nonnegative")
+        if offline and cache_dir is None:
+            raise ValidationError("offline mode requires cache_dir")
+        self.opener = opener
+        self.timeout = timeout
+        self.retries = retries
+        self.backoff = backoff
+        self.cache_dir = Path(cache_dir) if cache_dir is not None else None
+        self.ttl_seconds = ttl_seconds
+        self.offline = offline
+        self.allow_expired_offline = allow_expired_offline
+        self.sleep = sleep
+        self.clock = clock
+
+    def get(self, endpoint: str, params: dict[str, str] | None = None) -> tuple[bytes, dict]:
+        """Retrieve bytes and provenance; respect offline/expiry before network."""
+        url = endpoint + ("?" + urlencode(params) if params else "")
+        cache_path = (
+            self.cache_dir / (hashlib.sha256(url.encode("utf-8")).hexdigest() + ".json")
+            if self.cache_dir is not None else None
+        )
+        if cache_path is not None and cache_path.exists():
+            try:
+                cached = json.loads(cache_path.read_text(encoding="utf-8"))
+                fetched = datetime.fromisoformat(cached["retrieved_at"])
+                age = self.clock() - fetched.timestamp()
+                if fetched.tzinfo is None or age < 0 or not isinstance(cached["body"], str):
+                    raise ValueError("invalid cached payload")
+                if age < self.ttl_seconds or (self.offline and self.allow_expired_offline):
+                    return cached["body"].encode("utf-8"), self._provenance(
+                        url, cached["retrieved_at"], True, age >= self.ttl_seconds
+                    )
+            except (OSError, ValueError, TypeError, KeyError) as exc:
+                raise OfflineCacheError(f"Invalid cache entry for {url}") from exc
+        if self.offline:
+            raise OfflineCacheError(f"No unexpired cached response for {url}")
+
+        for attempt in range(self.retries + 1):
+            try:
+                with self.opener(Request(url, headers={"User-Agent": "nielytics/0 (research data client)"}), timeout=self.timeout) as response:
+                    body = response.read()
+                    status = response.status
+                    headers = getattr(response, "headers", {})
+                if status in (429, 500, 502, 503, 504):
+                    raise HTTPError(url, status, "Provider temporarily unavailable", headers, None)
+                if status != 200:
+                    raise ProviderError(f"Provider returned HTTP {status}: {url}")
+                if not body:
+                    raise ResponseError(f"Provider returned an empty response: {url}")
+                retrieved_at = datetime.fromtimestamp(self.clock(), tz=UTC).isoformat()
+                if cache_path is not None:
+                    try:
+                        cache_path.parent.mkdir(parents=True, exist_ok=True)
+                        temporary = cache_path.with_name(cache_path.name + f".{os.getpid()}.tmp")
+                        temporary.write_text(json.dumps({"retrieved_at": retrieved_at, "body": body.decode("utf-8")}), encoding="utf-8")
+                        temporary.replace(cache_path)
+                    except (OSError, UnicodeDecodeError) as exc:
+                        raise ProviderError(f"Cannot save provider cache at {cache_path}") from exc
+                return body, self._provenance(url, retrieved_at, False, False)
+            except HTTPError as exc:
+                if exc.code not in (429, 500, 502, 503, 504) or attempt == self.retries:
+                    raise ProviderError(f"Provider returned HTTP {exc.code}: {url}") from exc
+                retry_after = exc.headers.get("Retry-After") if exc.headers else None
+                delay = self._retry_after(retry_after)
+            except (URLError, TimeoutError, OSError) as exc:
+                if attempt == self.retries:
+                    raise ProviderError(f"Could not retrieve {url}: {exc}") from exc
+                delay = min(60, self.backoff * 2**attempt)
+            self.sleep(delay)
+        raise AssertionError("unreachable")
+
+    def _retry_after(self, value: str | None) -> float:
+        if value:
+            try:
+                return max(0, min(60, float(value)))
+            except ValueError:
+                try:
+                    return max(0, min(60, (parsedate_to_datetime(value) - datetime.fromtimestamp(self.clock(), UTC)).total_seconds()))
+                except (ValueError, TypeError, OverflowError):
+                    pass
+        return min(60, self.backoff)
+
+    @staticmethod
+    def _provenance(url: str, retrieved_at: str, cached: bool, expired: bool) -> dict:
+        return {"source_url": url, "retrieved_at": retrieved_at, "cached": cached, "cache_expired": expired}
+
+
+def parse_json(body: bytes) -> dict:
+    """Decode a provider JSON object and surface provider-specific errors."""
+    try:
+        value = json.loads(body)
+    except (ValueError, UnicodeDecodeError) as exc:
+        raise ResponseError("Provider returned invalid JSON") from exc
+    if not isinstance(value, dict):
+        raise ResponseError("Provider response must be a JSON object")
+    if value.get("error"):
+        raise ResponseError(f"Provider rejected request: {value.get('reason', value['error'])}")
+    return value
+
+
+def coordinates(latitude: float, longitude: float) -> None:
+    """Require finite WGS84 scalar coordinates."""
+    for name, value, limit in (("latitude", latitude, 90), ("longitude", longitude, 180)):
+        if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value) or abs(value) > limit:
+            raise ValidationError(f"{name} must be a finite WGS84 coordinate within ±{limit}")
+
+
+def date_range(start_date: str, end_date: str) -> None:
+    """Validate strict ISO calendar dates in chronological order."""
+    from datetime import date
+
+    try:
+        start = date.fromisoformat(start_date)
+        end = date.fromisoformat(end_date)
+        if start.isoformat() != start_date or end.isoformat() != end_date or start > end:
+            raise ValueError
+    except (ValueError, TypeError) as exc:
+        raise ValidationError("start_date and end_date must be YYYY-MM-DD and ordered") from exc

nielytics/climate/providers/nasa_landslides.py

@@ -0,0 +1,144 @@
+"""NASA's one-time Global Landslide Catalog CSV export (not live warnings)."""
+
+from __future__ import annotations
+
+import csv
+import io
+from datetime import datetime
+from pathlib import Path
+
+from nielytics.exceptions import ValidationError
+from nielytics.models.schemas import AnalysisResult
+
+from ._http import HTTPClient, ResponseError, coordinates
+
+CATALOG_URL = "https://data.nasa.gov/docs/legacy/Global_Landslide_Catalog_Export/Global_Landslide_Catalog_Export_rows.csv"
+CATALOG_PAGE = "https://data.nasa.gov/dataset/global-landslide-catalog-export"
+_REQUIRED = {"event_id", "event_date", "longitude", "latitude", "country_code", "landslide_trigger"}
+_LIMITATIONS = [
+    "NASA labels this a one-time export current as of March 7, 2016, although the published CSV contains later-dated rows; not a live warning feed.",
+    "Media and other reports are incomplete and location/date accuracy varies by event.",
+    "NASA requests agreement to catalog terms and citation of Kirschbaum et al. (2010, 2015) for exports.",
+]
+
+
+def _parse_catalog(body: bytes, provenance: dict) -> AnalysisResult:
+    try:
+        reader = csv.DictReader(io.StringIO(body.decode("utf-8-sig"), newline=""))
+        if not reader.fieldnames or not _REQUIRED.issubset(reader.fieldnames) or len(set(reader.fieldnames)) != len(reader.fieldnames):
+            raise ResponseError("NASA GLC CSV is missing required columns or has duplicate headers")
+        records = []
+        for row in reader:
+            if None in row or any(value is None for value in row.values()):
+                raise ResponseError("NASA GLC CSV contains a row with an inconsistent number of columns")
+            if all(not value for value in row.values()):
+                continue
+            event_id = row["event_id"].strip()
+            if not event_id:
+                raise ResponseError("NASA GLC CSV contains an event without event_id")
+            raw_date = row["event_date"].strip()
+            try:
+                event_date = datetime.strptime(raw_date, "%m/%d/%Y %I:%M:%S %p").date().isoformat() if raw_date else None
+            except ValueError as exc:
+                raise ResponseError(f"NASA GLC event {event_id} has invalid event_date") from exc
+            lon_text, lat_text = row["longitude"].strip(), row["latitude"].strip()
+            longitude = latitude = None
+            if lon_text and lat_text:
+                try:
+                    longitude, latitude = float(lon_text), float(lat_text)
+                    coordinates(latitude, longitude)
+                except (ValueError, ValidationError) as exc:
+                    raise ResponseError(f"NASA GLC event {event_id} has invalid coordinates") from exc
+            records.append({"event_id": event_id, "date": event_date, "event_date_raw": raw_date or None,
+                            "longitude": longitude, "latitude": latitude,
+                            "country_code": row["country_code"].strip() or None,
+                            "landslide_trigger": row["landslide_trigger"].strip() or None,
+                            "location_accuracy": row.get("location_accuracy", "").strip() or None})
+    except (UnicodeDecodeError, csv.Error, AttributeError) as exc:
+        raise ResponseError("NASA GLC catalog is not a valid UTF-8 CSV export") from exc
+    if not records:
+        raise ResponseError("NASA GLC catalog contains no events")
+    dated = [record["date"] for record in records if record["date"] is not None]
+    return AnalysisResult(feature="landslide_events", data={"records": records}, metadata={
+        "source": "NASA Global Landslide Catalog (GLC) one-time export",
+        "source_dataset": CATALOG_PAGE, "data_type": "historical_catalog",
+        "coverage": {"start": min(dated, default=None), "end": max(dated, default=None)},
+        "units": {"longitude": "degrees_east", "latitude": "degrees_north"},
+        "missing_value": "Blank cells normalized to null; a missing coordinate suppresses both coordinates",
+        "event_time_standard": "Catalog times are preserved as supplied; UTC offset is not specified",
+        "attribution": "NASA GLC; cite Kirschbaum et al. (2010) doi:10.1007/s11069-009-9401-4 and Kirschbaum et al. (2015) doi:10.1016/j.geomorph.2015.03.016",
+        "license": "Not specified on NASA Open Data resource page; review catalog terms before use",
+        "limitations": _LIMITATIONS.copy(), **provenance,
+    })
+
+
+def fetch_landslide_events(*, accept_terms: bool = False, client: HTTPClient | None = None) -> AnalysisResult:
+    """Download the verified historic CSV only after user accepts NASA catalog terms."""
+    if accept_terms is not True:
+        raise ValidationError(f"Review {CATALOG_PAGE} and explicitly accept its export terms before downloading")
+    body, provenance = (client or HTTPClient()).get(CATALOG_URL)
+    return _parse_catalog(body, provenance)
+
+
+def load_landslide_catalog(path: str | Path) -> AnalysisResult:
+    """Load a previously downloaded GLC CSV locally without contacting NASA."""
+    try:
+        data = Path(path).read_bytes()
+    except (OSError, TypeError, ValueError) as exc:
+        raise ValidationError(f"Cannot read local GLC catalog: {path}") from exc
+    return _parse_catalog(data, {"source_url": CATALOG_URL, "retrieved_at": None,
+                                 "cached": False, "cache_expired": None, "local_file": str(path)})
+
+
+def filter_landslides_by_region(
+    result: AnalysisResult, *, bbox: tuple[float, float, float, float] | None = None,
+    country_code: str | None = None,
+) -> AnalysisResult:
+    """Filter geolocated catalog events by WGS84 bbox and/or recorded country code."""
+    if result.feature != "landslide_events":
+        raise ValidationError("A landslide_events result is required")
+    if bbox is None and country_code is None:
+        raise ValidationError("Specify bbox and/or country_code")
+    if country_code is not None and (not isinstance(country_code, str) or len(country_code) != 2 or not country_code.isalpha()):
+        raise ValidationError("country_code must be a two-letter ISO code")
+    if bbox is not None:
+        if not isinstance(bbox, (tuple, list)) or len(bbox) != 4:
+            raise ValidationError("bbox must be (west, south, east, north)")
+        west, south, east, north = bbox
+        coordinates(south, west)
+        coordinates(north, east)
+        if west > east or south > north:
+            raise ValidationError("bbox boundaries must be ordered")
+    records = [record for record in result.data["records"] if
+               (country_code is None or record["country_code"] == country_code.upper()) and
+               (bbox is None or (record["longitude"] is not None and west <= record["longitude"] <= east
+                              and south <= record["latitude"] <= north))]
+    dated = [record["date"] for record in records if record["date"] is not None]
+    return AnalysisResult(feature="landslide_events", data={"records": records}, metadata={
+        **result.metadata, "coverage": {"start": min(dated, default=None), "end": max(dated, default=None)},
+        "region_filter": {"bbox": list(bbox) if bbox is not None else None,
+                          "country_code": country_code.upper() if country_code else None},
+    })
+
+
+def landslide_events_to_geojson(result: AnalysisResult) -> dict:
+    """Export only valid catalog point positions; missing positions are omitted."""
+    from nielytics.geospatial.geojson import points_to_geojson
+
+    if result.feature != "landslide_events":
+        raise ValidationError("A landslide_events result is required")
+    records = result.data["records"]
+    points = ({"id": row["event_id"], "longitude": row["longitude"], "latitude": row["latitude"],
+               "properties": {"event_date": row["date"], "event_date_raw": row["event_date_raw"],
+                              "country_code": row["country_code"],
+                              "landslide_trigger": row["landslide_trigger"],
+                              "location_accuracy": row["location_accuracy"]},
+               "provenance": {"source_url": result.metadata["source_url"],
+                              "retrieved_at": result.metadata["retrieved_at"]}}
+              for row in records if row["longitude"] is not None and row["latitude"] is not None)
+    coverage = result.metadata["coverage"]
+    return points_to_geojson(points, crs="EPSG:4326", source=result.metadata["source"],
+                             period=f"{coverage['start']} to {coverage['end']}" if coverage["start"] is not None else None,
+                             units="WGS84 decimal degrees", method="direct catalog event coordinate export",
+                             limitations=[*result.metadata["limitations"],
+                                          f"{sum(row['longitude'] is None or row['latitude'] is None for row in records)} records without coordinates omitted."])

nielytics/climate/providers/nasa_power.py

@@ -0,0 +1,108 @@
+"""NASA POWER modeled daily point precipitation and air temperature."""
+
+from __future__ import annotations
+
+import math
+from datetime import date, datetime
+
+from nielytics.exceptions import ValidationError
+from nielytics.models.schemas import AnalysisResult
+
+from ._http import HTTPClient, ResponseError, coordinates, date_range, parse_json
+
+POWER_URL = "https://power.larc.nasa.gov/api/temporal/daily/point"
+_PARAMETERS = {"PRECTOTCORR": "mm/day", "T2M_MAX": "C"}
+
+
+def fetch_nasa_power_data(
+    latitude: float,
+    longitude: float,
+    start_date: str,
+    end_date: str,
+    *,
+    parameters: tuple[str, ...] = ("PRECTOTCORR", "T2M_MAX"),
+    client: HTTPClient | None = None,
+) -> AnalysisResult:
+    """Fetch verified AG daily parameters in Local Solar Time (LST).
+
+    POWER ``header.fill_value`` is converted to None; returned parameter
+    units must match the documented values. No arbitrary parameter schema is
+    assumed. Historic data are modeled/gridded, not gauge declarations.
+    """
+    coordinates(latitude, longitude)
+    date_range(start_date, end_date)
+    if start_date < "1981-01-01" or date.fromisoformat(end_date) >= date.today():
+        raise ValidationError("POWER daily historical dates must be from 1981-01-01 through yesterday")
+    if (not isinstance(parameters, (tuple, list)) or not parameters or
+            any(not isinstance(parameter, str) for parameter in parameters) or
+            len(set(parameters)) != len(parameters) or any(parameter not in _PARAMETERS for parameter in parameters)):
+        raise ValidationError(f"parameters must be unique values from {tuple(_PARAMETERS)}")
+    params = {"parameters": ",".join(parameters), "community": "AG", "longitude": str(longitude),
+              "latitude": str(latitude), "start": start_date.replace("-", ""), "end": end_date.replace("-", ""),
+              "format": "JSON", "time-standard": "LST"}
+    body, provenance = (client or HTTPClient()).get(POWER_URL, params)
+    payload = parse_json(body)
+    header, props, units_meta = payload.get("header"), payload.get("properties"), payload.get("parameters")
+    if not isinstance(header, dict) or not isinstance(props, dict) or not isinstance(units_meta, dict) or not isinstance(props.get("parameter"), dict):
+        raise ResponseError("POWER response missing header, properties.parameter, or parameters units")
+    if header.get("time_standard") != "LST":
+        raise ResponseError("POWER returned an unexpected time standard")
+    fill = header.get("fill_value")
+    if isinstance(fill, bool) or not isinstance(fill, (int, float)) or not math.isfinite(fill):
+        raise ResponseError("POWER header.fill_value is missing or invalid")
+    values = props["parameter"]
+    dates: set[str] | None = None
+    for parameter in parameters:
+        if not isinstance(values.get(parameter), dict) or not isinstance(units_meta.get(parameter), dict) or units_meta[parameter].get("units") != _PARAMETERS[parameter]:
+            raise ResponseError(f"POWER missing/invalid parameter {parameter} or units")
+        these_dates = set(values[parameter])
+        if dates is not None and dates != these_dates:
+            raise ResponseError("POWER parameter date coverage is inconsistent")
+        dates = these_dates
+    if not dates:
+        raise ResponseError("POWER response contains no daily observations")
+    records = []
+    for raw_date in sorted(dates):
+        try:
+            parsed = datetime.strptime(raw_date, "%Y%m%d").date()
+            if parsed.strftime("%Y%m%d") != raw_date or not start_date <= parsed.isoformat() <= end_date:
+                raise ValueError
+        except (ValueError, TypeError) as exc:
+            raise ResponseError("POWER returned an invalid or out-of-range observation date") from exc
+        row = {"date": parsed.isoformat()}
+        for parameter in parameters:
+            value = values[parameter][raw_date]
+            if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
+                raise ResponseError(f"POWER returned invalid value for {parameter} on {raw_date}")
+            if parameter == "PRECTOTCORR" and value < 0 and value != fill:
+                raise ResponseError("POWER precipitation cannot be negative except declared fill")
+            row[parameter] = None if value == fill else value
+        records.append(row)
+    if records[0]["date"] != start_date or records[-1]["date"] != end_date or len(records) != (date.fromisoformat(end_date) - date.fromisoformat(start_date)).days + 1:
+        raise ResponseError("POWER returned incomplete daily date coverage")
+    geometry = payload.get("geometry")
+    if not isinstance(geometry, dict) or geometry.get("type") != "Point" or not isinstance(geometry.get("coordinates"), list) or len(geometry["coordinates"]) < 2:
+        raise ResponseError("POWER response missing Point geometry")
+    lon, lat = geometry["coordinates"][:2]
+    try:
+        coordinates(lat, lon)
+    except ValidationError as exc:
+        raise ResponseError("POWER response has invalid point coordinates") from exc
+    return AnalysisResult(feature="nasa_power_daily", data={"records": records}, metadata={
+        "source": "NASA POWER Daily Point API", "source_dataset": "POWER daily meteorology",
+        "data_type": "historical_modeled", "requested_location": {"latitude": latitude, "longitude": longitude},
+        "grid_cell": {"latitude": lat, "longitude": lon}, "time_standard": "LST",
+        "units": {parameter: _PARAMETERS[parameter] for parameter in parameters},
+        "coverage": {"start": records[0]["date"], "end": records[-1]["date"]},
+        "missing_value": f"header.fill_value ({fill}) normalized to null", "provider_sources": header.get("sources", []),
+        "service_version": header.get("api", {}).get("version") if isinstance(header.get("api"), dict) else None,
+        "limitations": ["Gridded modeled daily values, not station records or disaster declarations.",
+                        "POWER LST days differ from UTC and civil timezone boundaries.",
+                        "Meteorological parameters generally have 2–3 days of publication latency."],
+        "attribution": "NASA POWER; cite POWER project and Daily service version and accessed date", **provenance,
+    })
+
+
+def fetch_nasa_precipitation(latitude: float, longitude: float, start_date: str, end_date: str, *, client: HTTPClient | None = None) -> AnalysisResult:
+    """Fetch POWER corrected daily precipitation PRECTOTCORR in mm/day."""
+    return fetch_nasa_power_data(latitude, longitude, start_date, end_date, parameters=("PRECTOTCORR",), client=client)