forcingkit 0.1.0__py3-none-any.whl

forcingkit/fetchers/ndbc.py

@@ -0,0 +1,231 @@
+"""NDBC buoy observations for model validation: standard meteorology (sea and air temperature,
+pressure, wind, waves) and near-surface ADCP currents.
+
+Files come from the NDBC data server in the order they are published: the per-month file for
+months of the current year (`data/<product>/<Mon>/<id><m><yyyy>.txt.gz`), then the yearly
+historical file (`data/historical/<product>/<id>h<yyyy>.txt.gz`), then the rolling 45-day
+real-time file (`data/realtime2/<id>.txt` or `.adcp`). Missing-value sentinels (99, 999, 9999,
+MM) become NaN. These observations validate a model; they never force it.
+"""
+
+import gzip
+import json
+import logging
+import math
+import os
+import re
+from typing import Optional
+
+import numpy as np
+import pandas as pd
+import requests
+
+logger = logging.getLogger(__name__)
+
+NDBC = "https://www.ndbc.noaa.gov"
+PRODUCTS = ("stdmet", "adcp")
+REALTIME_SUFFIX = {"stdmet": "txt", "adcp": "adcp"}
+MONTH_ABBR = [
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
+]
+# Column sentinels NDBC uses for "not measured".
+SENTINELS = {99.0, 999.0, 9999.0, 99.00}
+# stdmet columns carried through, with units.
+STDMET_COLUMNS = {
+    "WTMP": "degC",  # sea surface temperature
+    "ATMP": "degC",  # air temperature
+    "PRES": "hPa",  # sea level pressure
+    "WSPD": "m s-1",  # wind speed
+    "WDIR": "degree from true north (direction the wind comes from)",
+    "GST": "m s-1",
+    "WVHT": "m",
+    "DPD": "s",
+}
+
+
+def month_code(month: int) -> str:
+    """NDBC's month code in per-month file names: 1 to 9, then a, b, c for October to December."""
+    return str(month) if month < 10 else "abc"[month - 10]
+
+
+def candidate_urls(station: str, product: str, year: int, month: int) -> list[str]:
+    """URLs that may hold `product` for `station` in the given month, in the order to try."""
+    station = station.lower()
+    return [
+        f"{NDBC}/data/{product}/{MONTH_ABBR[month - 1]}/{station}{month_code(month)}{year}.txt.gz",
+        f"{NDBC}/data/historical/{product}/{station}h{year}.txt.gz",
+        f"{NDBC}/data/realtime2/{station.upper()}.{REALTIME_SUFFIX[product]}",
+    ]
+
+
+def parse_ndbc_text(text: str) -> pd.DataFrame:
+    """Parse an NDBC whitespace-delimited file (two `#` header rows) into a frame indexed by UTC
+    time, sentinels and `MM` as NaN. Handles both four- and two-digit years, with or without a
+    minute column."""
+    lines = [ln for ln in text.splitlines() if ln.strip()]
+    if not lines or not lines[0].startswith("#"):
+        raise ValueError("not an NDBC data file: no header row")
+    names = lines[0].lstrip("#").split()
+    rows = [ln.split() for ln in lines if not ln.startswith("#")]
+    df = pd.DataFrame(rows, columns=names[: len(rows[0])] if rows else names)
+    year_col = names[0]
+    years = df[year_col].astype(int)
+    years = years.where(years >= 100, years + 1900)
+    minutes = df["mm"].astype(int) if "mm" in df else 0
+    df.index = pd.to_datetime(
+        dict(
+            year=years,
+            month=df["MM"].astype(int),
+            day=df["DD"].astype(int),
+            hour=df["hh"].astype(int),
+            minute=minutes,
+        )
+    )
+    df = df.drop(columns=[c for c in (year_col, "MM", "DD", "hh", "mm") if c in df])
+    df = df.replace("MM", np.nan).apply(pd.to_numeric, errors="coerce")
+    return df.mask(df.isin(SENTINELS))
+
+
+def _get(url: str, timeout: float = 60.0) -> Optional[str]:
+    r = requests.get(url, timeout=timeout)
+    if r.status_code == 404:
+        return None
+    r.raise_for_status()
+    if url.endswith(".gz"):
+        return gzip.decompress(r.content).decode("utf-8", errors="replace")
+    return r.text
+
+
+def _utc_naive(t) -> pd.Timestamp:
+    t = pd.Timestamp(t)
+    return t if t.tzinfo is None else t.tz_convert("UTC").tz_localize(None)
+
+
+def station_position(station: str, get=_get) -> tuple[float, float]:
+    """(lat, lon) of an NDBC station from its station page."""
+    html = get(f"{NDBC}/station_page.php?station={station.lower()}") or ""
+    m = re.search(r"(\d+\.\d+)\s*([NS])\s+(\d+\.\d+)\s*([EW])", html)
+    if not m:
+        raise ValueError(f"No position found for NDBC station {station}")
+    lat = float(m.group(1)) * (1 if m.group(2) == "N" else -1)
+    lon = float(m.group(3)) * (1 if m.group(4) == "E" else -1)
+    return lat, lon
+
+
+def fetch_product(
+    station: str, product: str, start: pd.Timestamp, end: pd.Timestamp, get=_get
+):
+    """`product` for `station` over [start, end]: (frame, source URLs). Each month is taken from
+    the first source that has it."""
+    frames, sources = [], []
+    for month_start in pd.date_range(start.normalize().replace(day=1), end, freq="MS"):
+        for url in candidate_urls(
+            station, product, month_start.year, month_start.month
+        ):
+            text = get(url)
+            if text is None:
+                continue
+            df = parse_ndbc_text(text)
+            df = df[(df.index >= start) & (df.index <= end)]
+            if len(df):
+                frames.append(df)
+                sources.append(url)
+                break
+    if not frames:
+        return pd.DataFrame(), sources
+    df = pd.concat(frames)
+    return df[~df.index.duplicated(keep="first")].sort_index(), sources
+
+
+def _list(values) -> list:
+    return [
+        None if (v is None or (isinstance(v, float) and math.isnan(v))) else float(v)
+        for v in values
+    ]
+
+
+def fetch_ndbc(
+    station: str,
+    start_time: str,
+    end_time: str,
+    products: tuple[str, ...] = PRODUCTS,
+    cache_dir: Optional[str] = None,
+    get=_get,
+    position: Optional[tuple[float, float]] = None,
+) -> dict:
+    """Observations at an NDBC station over [start_time, end_time] (UTC) as a JSON-ready dict.
+
+    stdmet: times plus the columns of `STDMET_COLUMNS`. adcp: times, the bin depth and the
+    current as eastward and northward components (m/s); NDBC reports speed in cm/s and the
+    direction the current flows toward, in degrees true. Missing values are null. A window that
+    ended more than two days ago is cached as JSON under `cache_dir`. `get` (a URL to text or
+    None) and `position` exist so tests can run without the network.
+    """
+    start, end = _utc_naive(start_time), _utc_naive(end_time)
+    unknown = set(products) - set(PRODUCTS)
+    if unknown:
+        raise ValueError(f"unknown NDBC products {sorted(unknown)}")
+
+    cache_path = None
+    if cache_dir:
+        os.makedirs(os.path.join(cache_dir, "ndbc"), exist_ok=True)
+        key = f"{station.lower()}_{start:%Y%m%dT%H%M}_{end:%Y%m%dT%H%M}_{'-'.join(sorted(products))}"
+        cache_path = os.path.join(cache_dir, "ndbc", f"{key}.json")
+        if os.path.exists(cache_path):
+            with open(cache_path) as f:
+                return json.load(f)
+
+    lat, lon = position if position is not None else station_position(station, get)
+    out: dict = {
+        "station_id": station.upper(),
+        "lat": lat,
+        "lon": lon,
+        "start_time": f"{start:%Y-%m-%dT%H:%M:%SZ}",
+        "end_time": f"{end:%Y-%m-%dT%H:%M:%SZ}",
+        "products": {},
+        "sources": [],
+    }
+    for product in products:
+        df, sources = fetch_product(station, product, start, end, get=get)
+        out["sources"] += sources
+        times = [f"{t:%Y-%m-%dT%H:%M:%SZ}" for t in df.index]
+        if product == "stdmet":
+            out["products"]["stdmet"] = {
+                "times": times,
+                "units": {c: u for c, u in STDMET_COLUMNS.items() if c in df},
+                **{c: _list(df[c]) for c in STDMET_COLUMNS if c in df},
+            }
+        else:
+            speed = df["SPD01"] / 100.0 if "SPD01" in df else pd.Series(dtype=float)
+            toward = (
+                np.deg2rad(df["DIR01"]) if "DIR01" in df else pd.Series(dtype=float)
+            )
+            out["products"]["adcp"] = {
+                "times": times,
+                "depth_m": _list(df["DEP01"]) if "DEP01" in df else [],
+                "u": _list(speed * np.sin(toward)),
+                "v": _list(speed * np.cos(toward)),
+                "units": {
+                    "u": "m s-1 eastward",
+                    "v": "m s-1 northward",
+                    "depth_m": "m",
+                },
+            }
+
+    if cache_path and end < pd.Timestamp.utcnow().tz_localize(None) - pd.Timedelta(
+        days=2
+    ):
+        with open(cache_path, "w") as f:
+            json.dump(out, f)
+    return out

forcingkit/fetchers/necofs.py

@@ -0,0 +1,369 @@
+import warnings
+import logging
+import pandas as pd
+import numpy as np
+import xarray as xr
+from typing import Optional
+from scipy.spatial import Delaunay
+from forcingkit import settings
+
+
+logger = logging.getLogger(__name__)
+
+
+def get_metadata() -> dict:
+    return {
+        "id": "necofs",
+        "name": "NECOFS FVCOM GOM7",
+        "resolution_approx_m": 200.0,
+        "type_desc": "Unstructured Triangular Mesh",
+        "domain_bbox": [-77.0, 35.0, -65.0, 46.0],
+    }
+
+
+def supports_bbox(bbox: list[float]) -> bool:
+    min_lon, min_lat, max_lon, max_lat = bbox
+    # Rough check for GOM3 bounds (NECOFS FVCOM)
+    if max_lat < 35.0 or min_lat > 46.0 or max_lon < -77.0 or min_lon > -65.0:
+        return False
+    return True
+
+
+NECOFS_GOM7_URL = "http://www.smast.umassd.edu:8080/thredds/dodsC/models/fvcom/NECOFS/Forecasts/NECOFS_GOM7_FORECAST.nc"
+
+
+def get_necofs_url(target_dt: pd.Timestamp) -> str:
+    """
+    Determine best NECOFS GOM7 URL by falling back to daily history archives.
+    SMAST daily archives (e.g. 2026_03_03.nc) contain [Mar 2 01:00 to Mar 3 00:00].
+    """
+    import requests
+
+    # NECOFS GOM7 daily history files contain data for the PREVIOUS day up to 00:00 of the CURRENT day.
+    # Therefore to get data forward-looking from target_dt, we must ALWAYS fetch the file for the NEXT day.
+    file_dt = target_dt.normalize() + pd.Timedelta(days=1)
+
+    date_str = file_dt.strftime("%Y_%m_%d")
+    history_url = f"http://www.smast.umassd.edu:8080/thredds/dodsC/models/fvcom/NECOFS/Archive/necofs_history/NECOFS_GOM7_{date_str}.nc"
+
+    try:
+        resp = requests.get(history_url + ".dds", timeout=5)
+        if resp.status_code == 200:
+            logger.info(f"Using historic NECOFS GOM7 archive: {history_url}")
+            return history_url
+    except requests.RequestException:
+        pass
+
+    logger.info("Falling back to NECOFS GOM7 rolling forecast.")
+    return NECOFS_GOM7_URL
+
+
+# Parent-ocean delivery schema. Bump when the layout or meaning of the boundary store changes, so
+# a cached store built under an older schema can never be served for a newer request.
+OBC_SCHEMA = "z-v2"
+
+
+def necofs_archive_file_date(t: pd.Timestamp) -> pd.Timestamp:
+    """Date stamp of the GOM7 daily history file that holds the record at time `t`.
+
+    File D holds (D-1 01:00, D 00:00], so the record at exactly midnight lives in the file stamped
+    with that same day, and every other hour in the file stamped the following day.
+    """
+    return (t - pd.Timedelta(hours=1)).normalize() + pd.Timedelta(days=1)
+
+
+def z_levels_for_depth(
+    max_depth_m: float, spacing_m: float
+) -> tuple[np.ndarray, np.ndarray]:
+    """Fixed z levels covering 0 to -max_depth_m: (centres, faces), both ordered bottom to top.
+
+    The bottom face sits at or below -max_depth_m, so every wet donor column is spanned.
+    """
+    if spacing_m <= 0:
+        raise ValueError(f"vertical spacing must be positive, got {spacing_m}")
+    nz = max(1, int(np.ceil(max_depth_m / spacing_m)))
+    faces = -spacing_m * np.arange(nz, -1, -1, dtype=np.float64)
+    centres = 0.5 * (faces[:-1] + faces[1:])
+    return centres, faces
+
+
+def sigma_to_z(
+    values: np.ndarray,
+    z_layers: np.ndarray,
+    z_bottom: np.ndarray,
+    z_targets: np.ndarray,
+) -> np.ndarray:
+    """Interpolate sigma-layer columns onto fixed z levels.
+
+    values, z_layers: (nsig, ny, nx), layer index 0 at the surface (FVCOM convention), z negative.
+    z_bottom: (ny, nx), the sea floor (-h); NaN marks land.
+    z_targets: (nz,) target level centres, any order.
+
+    Returns (nz, ny, nx). Between the surface and the shallowest layer centre the shallowest value
+    is used, and between the deepest layer centre and the sea floor the deepest value; levels below
+    the sea floor, and land columns, are NaN.
+    """
+    nsig = values.shape[0]
+    out = np.full((len(z_targets),) + values.shape[1:], np.nan, dtype=np.float64)
+    land = ~np.isfinite(z_bottom)
+    for n, zt in enumerate(z_targets):
+        # Number of layer centres at or above this level; layers are ordered surface first.
+        above = np.sum(z_layers >= zt, axis=0)
+        upper = np.clip(above - 1, 0, nsig - 1)
+        lower = np.clip(above, 0, nsig - 1)
+        zu = np.take_along_axis(z_layers, upper[None], axis=0)[0]
+        zl = np.take_along_axis(z_layers, lower[None], axis=0)[0]
+        vu = np.take_along_axis(values, upper[None], axis=0)[0]
+        vl = np.take_along_axis(values, lower[None], axis=0)[0]
+        span = zu - zl
+        w = np.where(span > 0, (zu - zt) / np.where(span > 0, span, 1.0), 0.0)
+        w = np.clip(w, 0.0, 1.0)
+        level = (1.0 - w) * vu + w * vl
+        level[zt < z_bottom] = np.nan
+        level[land] = np.nan
+        out[n] = level
+    return out
+
+
+class Barycentric:
+    """Linear interpolation from scattered points onto fixed targets, with the simplex search and
+    barycentric weights computed once.
+
+    Equivalent to `LinearNDInterpolator(tri, values)(targets)`, which repeats the search for every
+    call: per parent hour that is one search per layer per variable (181 for LIS), each over every
+    target point. Values may carry leading dimensions: (..., npoints) -> (..., *shape). Targets
+    outside the triangulation are NaN.
+    """
+
+    def __init__(self, tri: Delaunay, targets: np.ndarray, shape: tuple[int, ...]):
+        simplex = tri.find_simplex(targets)
+        self.inside = simplex >= 0
+        s = np.where(self.inside, simplex, 0)
+        transform = tri.transform[s]
+        b = np.einsum("ijk,ik->ij", transform[:, :2], targets - transform[:, 2])
+        self.weights = np.column_stack([b, 1.0 - b.sum(axis=1)])
+        self.vertices = tri.simplices[s]
+        self.shape = shape
+
+    def __call__(self, values: np.ndarray) -> np.ndarray:
+        values = np.asarray(values, dtype=np.float64)
+        out = np.einsum("...pk,pk->...p", values[..., self.vertices], self.weights)
+        out[..., ~self.inside] = np.nan
+        return out.reshape(values.shape[:-1] + self.shape)
+
+
+PARENT_RECORD_DIMS = {
+    "u": ("z", "lat", "lon"),
+    "v": ("z", "lat", "lon"),
+    "temp": ("z", "lat", "lon"),
+    "salt": ("z", "lat", "lon"),
+    "zeta": ("lat", "lon"),
+}
+
+PARENT_UNITS = {
+    "u": ("m s-1", "eastward_sea_water_velocity"),
+    "v": ("m s-1", "northward_sea_water_velocity"),
+    "temp": ("degree_Celsius", "sea_water_temperature"),
+    "salt": ("1e-3", "sea_water_practical_salinity"),
+    "zeta": ("m", "sea_surface_height_above_geoid"),
+    "h": ("m", "sea_floor_depth_below_geoid"),
+}
+
+
+def _parent_static(lon_axis, lat_axis, z_centres, z_faces, h_grid, attrs) -> xr.Dataset:
+    mask = np.isfinite(h_grid).astype(np.int8)
+    ds = xr.Dataset(
+        data_vars={
+            "h": (("lat", "lon"), h_grid.astype(np.float32)),
+            "mask": (("lat", "lon"), mask),
+            "z_face": (("z_face",), z_faces),
+        },
+        coords={"z": z_centres, "lat": lat_axis, "lon": lon_axis},
+        attrs=attrs,
+    )
+    ds["h"].attrs.update(units="m", standard_name="sea_floor_depth_below_geoid")
+    ds["mask"].attrs.update(
+        long_name="1 where NECOFS has ocean, 0 on land or outside the mesh"
+    )
+    ds["z"].attrs.update(
+        units="m", positive="up", axis="Z", long_name="level centre depth"
+    )
+    ds["z_face"].attrs.update(
+        units="m", positive="up", long_name="level faces, bottom to top"
+    )
+    ds["lat"].attrs.update(units="degrees_north", standard_name="latitude", axis="Y")
+    ds["lon"].attrs.update(units="degrees_east", standard_name="longitude", axis="X")
+    return ds
+
+
+def iter_parent(
+    start_date: str,
+    duration_hours: int,
+    bbox: list[float],
+    pad_cells: int = 3,
+    vertical_spacing_m: float = 2.0,
+):
+    """NECOFS GOM7 as a parent ocean, one hourly record at a time.
+
+    Yields `("static", Dataset)` once (lon, lat, z, z_face, h, mask and the store attributes),
+    then `("record", time, {u, v, temp, salt, zeta})` for each of `duration_hours` hours starting
+    at `start_date`, in order. u, v, temp and salt are (z, lat, lon) and zeta (lat, lon) on a
+    regular 0.002 degree grid covering `bbox` plus `pad_cells` donor cells on every side, so the
+    parent brackets the child. The vertical axis is true depth: each FVCOM sigma layer is placed at
+    z = siglay * (h + zeta) + zeta for its column and interpolated onto fixed levels every
+    `vertical_spacing_m` metres, ordered bottom to top. Land, points outside the mesh and levels
+    below the sea floor are NaN.
+
+    Raises rather than returning a short record: an unreachable archive file, a missing hour or a
+    failed interpolation ends the delivery with an error.
+    """
+    import concurrent.futures
+
+    min_lon, min_lat, max_lon, max_lat = bbox
+    if max_lat < 35.0 or min_lat > 46.0 or max_lon < -77.0 or min_lon > -65.0:
+        raise ValueError(f"Bounding box {bbox} outside NECOFS domain.")
+
+    target_dt = pd.to_datetime(start_date)
+    if target_dt.tzinfo is not None:
+        target_dt = target_dt.tz_convert("UTC").tz_localize(None)
+
+    d_spacing = 0.002
+    pad = pad_cells * d_spacing
+    lon_axis = np.arange(min_lon - pad, max_lon + pad + d_spacing / 2, d_spacing)
+    lat_axis = np.arange(min_lat - pad, max_lat + pad + d_spacing / 2, d_spacing)
+    lon_grid, lat_grid = np.meshgrid(lon_axis, lat_axis)
+    target_pts = np.column_stack((lon_grid.ravel(), lat_grid.ravel()))
+    shape = lon_grid.shape
+
+    at_node = at_elem = None
+    h_grid = siglay_grid = None
+    z_centres = None
+    max_workers = settings.max_workers()
+
+    current_dt = target_dt
+    end_dt = target_dt + pd.Timedelta(hours=duration_hours - 1)
+    while current_dt <= end_dt:
+        # get_necofs_url(t) opens the file stamped t.normalize() + 1 day.
+        file_date = necofs_archive_file_date(current_dt)
+        dap_url = get_necofs_url(file_date - pd.Timedelta(days=1))
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            ds_raw = xr.open_dataset(dap_url, engine="pydap", decode_times=False)
+        drop_vars = [v for v in ["Itime", "Itime2"] if v in ds_raw.variables]
+        ds = xr.decode_cf(ds_raw.drop_vars(drop_vars))
+        ds_times = pd.DatetimeIndex(ds.time.values)
+        if ds_times.tz is not None:
+            ds_times = ds_times.tz_convert("UTC").tz_localize(None)
+
+        if at_node is None:
+            logger.info(
+                "Building NECOFS parent interpolation weights and vertical grid..."
+            )
+            at_node = Barycentric(
+                Delaunay(np.column_stack((ds["lon"].values, ds["lat"].values))),
+                target_pts,
+                shape,
+            )
+            at_elem = Barycentric(
+                Delaunay(np.column_stack((ds["lonc"].values, ds["latc"].values))),
+                target_pts,
+                shape,
+            )
+            h_grid = at_node(ds["h"].values)
+            siglay_grid = at_node(np.asarray(ds["siglay"].values))  # surface first
+            if not np.any(np.isfinite(h_grid)):
+                raise ValueError(f"No NECOFS ocean inside {bbox}")
+            z_centres, z_faces = z_levels_for_depth(
+                float(np.nanmax(h_grid)), vertical_spacing_m
+            )
+            yield (
+                "static",
+                _parent_static(
+                    lon_axis,
+                    lat_axis,
+                    z_centres,
+                    z_faces,
+                    h_grid,
+                    {
+                        "type": "NECOFS/FVCOM GOM7 parent ocean",
+                        "source": "UMass Dartmouth SMAST",
+                        "schema": OBC_SCHEMA,
+                        "pad_cells": pad_cells,
+                        "vertical_spacing_m": vertical_spacing_m,
+                        "requested_bbox": list(bbox),
+                    },
+                ),
+            )
+
+        wanted = pd.date_range(current_dt, min(end_dt, ds_times[-1]), freq="1h")
+        idx = ds_times.get_indexer(wanted)
+        if len(wanted) == 0 or (idx < 0).any():
+            raise RuntimeError(
+                f"{dap_url} lacks hourly records from {current_dt} "
+                f"(holds {ds_times[0]} to {ds_times[-1]})"
+            )
+        logger.info(f"Extracting {len(wanted)} hours from {dap_url}...")
+
+        def process(t_idx):
+            snap = ds.isel(time=int(t_idx))
+            zeta_t = at_node(snap["zeta"].values)
+            z_bottom = np.where(np.isfinite(zeta_t), -h_grid, np.nan)
+            z_layers = siglay_grid * (h_grid + zeta_t)[None] + zeta_t[None]
+            fields = {
+                "u": at_elem(snap["u"].values),
+                "v": at_elem(snap["v"].values),
+                "temp": at_node(snap["temp"].values),
+                "salt": at_node(snap["salinity"].values),
+            }
+            out = {
+                k: sigma_to_z(v, z_layers, z_bottom, z_centres).astype(np.float32)
+                for k, v in fields.items()
+            }
+            out["zeta"] = zeta_t.astype(np.float32)
+            return out
+
+        # In batches of max_workers, so at most that many records are held at once.
+        with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
+            for b in range(0, len(idx), max_workers):
+                batch = idx[b : b + max_workers]
+                for t, out in zip(
+                    wanted[b : b + len(batch)], executor.map(process, batch)
+                ):
+                    yield ("record", t, out)
+
+        current_dt = wanted[-1] + pd.Timedelta(hours=1)
+
+
+def fetch_necofs_boundary_conditions(
+    start_date: str,
+    duration_hours: int,
+    bbox: list[float],
+    pad_cells: int = 3,
+    vertical_spacing_m: float = 2.0,
+) -> Optional[xr.Dataset]:
+    """`iter_parent` assembled into one in-memory Dataset, for callers that want it whole. The
+    service streams the records to disk instead (`dispatcher.dispatch_obc_request`)."""
+    static = None
+    times: list = []
+    collected: dict[str, list[np.ndarray]] = {k: [] for k in PARENT_RECORD_DIMS}
+    for item in iter_parent(
+        start_date, duration_hours, bbox, pad_cells, vertical_spacing_m
+    ):
+        if item[0] == "static":
+            static = item[1]
+            continue
+        _, t, rec = item
+        times.append(t)
+        for k in collected:
+            collected[k].append(rec[k])
+    if static is None:
+        return None
+    ds_out = static.assign(
+        {
+            k: (("time",) + dims, np.stack(collected[k]))
+            for k, dims in PARENT_RECORD_DIMS.items()
+        }
+    ).assign_coords(time=times)
+    for name, (unit, standard_name) in PARENT_UNITS.items():
+        ds_out[name].attrs.update(units=unit, standard_name=standard_name)
+    return ds_out

forcingkit/fetchers/noaa.py

@@ -0,0 +1,87 @@
+import os
+import logging
+import requests
+import json
+from datetime import datetime
+from forcingkit import settings
+
+logger = logging.getLogger(__name__)
+
+
+def fetch_noaa_tide_data(
+    station_id: str,
+    start_time: str,
+    end_time: str,
+    cache_dir: str = os.path.join(
+        settings.cache_dir(),
+        "noaa",
+    ),
+    cache_bust: bool = False,
+) -> dict:
+    """
+    Fetches water level data from NOAA CO-OPS API for a specific station and time window.
+    Supports caching to avoid redundant API calls.
+
+    Args:
+        station_id: NOAA station ID (e.g., '8516945' for Kings Point)
+        start_time: ISO8601 string (YYYY-MM-DDTHH:MM:SSZ)
+        end_time: ISO8601 string (YYYY-MM-DDTHH:MM:SSZ)
+        cache_dir: Local directory for caching JSON responses
+    """
+    os.makedirs(cache_dir, exist_ok=True)
+
+    # Generate a cache key based on station and time
+    cache_key = f"{station_id}_{start_time}_{end_time}".replace(":", "-")
+    cache_path = os.path.join(cache_dir, f"{cache_key}.json")
+
+    if not cache_bust and os.path.exists(cache_path):
+        logger.info(f"Cache hit for NOAA station {station_id}: {cache_path}")
+        with open(cache_path, "r") as f:
+            return json.load(f)
+
+    logger.info(
+        f"Fetching NOAA tide data for station {station_id} ({start_time} to {end_time})..."
+    )
+
+    # NOAA API expects yyyyMMdd HH:mm
+    # Note: We assume the input strings are ISO8601 UTC
+    s_dt = datetime.fromisoformat(start_time.replace("Z", ""))
+    e_dt = datetime.fromisoformat(end_time.replace("Z", ""))
+
+    begin_str = s_dt.strftime("%Y%m%d %H:%M")
+    end_str = e_dt.strftime("%Y%m%d %H:%M")
+
+    url = "https://api.tidesandcurrents.noaa.gov/api/prod/datagetter"
+    params = {
+        "begin_date": begin_str,
+        "end_date": end_str,
+        "station": station_id,
+        "product": "water_level",
+        "datum": "NAVD",
+        "units": "metric",
+        "time_zone": "gmt",
+        "format": "json",
+        "application": "lhzn_coastal_sim",
+    }
+
+    try:
+        response = requests.get(url, params=params, timeout=30)
+        response.raise_for_status()
+        data = response.json()
+
+        if "error" in data:
+            logger.warning(
+                f"NOAA API returned error: {data['error'].get('message', 'Unknown error')}"
+            )
+            # Return a dummy fallback or raise? For now, we'll raise to let dispatcher handle it
+            raise RuntimeError(f"NOAA API Error: {data['error'].get('message')}")
+
+        # Cache the successful response
+        with open(cache_path, "w") as f:
+            json.dump(data, f, indent=4)
+
+        return data
+
+    except Exception as e:
+        logger.error(f"Failed to fetch NOAA tide data: {e}")
+        raise e