forcingkit 0.1.0__py3-none-any.whl

forcingkit/fetchers/dbofs.py

@@ -0,0 +1,442 @@
+"""
+DBOFS (NOAA Delaware Bay Operational Forecast System) fetcher.
+
+Provides Initial Conditions (IC) and Open Boundary Conditions (OBC) from a
+ROMS structured grid via OPeNDAP. Covers Delaware Bay and the adjacent
+Mid-Atlantic Bight continental shelf, including offshore NJ south of 40°N.
+
+Domain: [-76.5, 37.5, -73.0, 40.0] - domain area 8.75°², finer than the
+NECOFS/MARACOOS 132°² footprint, so DBOFS wins the dispatcher ranking for
+any bbox fully contained in this region.
+"""
+
+import numpy as np
+import xarray as xr
+import pandas as pd
+import logging
+from typing import Optional, Tuple
+from forcingkit import settings
+
+logger = logging.getLogger(__name__)
+
+# Abort NCEI file enumeration after this many consecutive open failures.
+_NCEI_CONSECUTIVE_FAIL_LIMIT = 3
+
+
+def get_metadata() -> dict:
+    """Returns metadata for the DBOFS system."""
+    return {
+        "id": "dbofs",
+        "name": "NOAA DBOFS (Delaware Bay / Offshore NJ)",
+        "resolution_approx_m": 100.0,
+        "type_desc": "Structured curvilinear ROMS grid",
+        "domain_bbox": [-75.875, 37.810, -73.264, 40.206],
+    }
+
+
+def supports_bbox(bbox: list[float]) -> bool:
+    """Check if the requested bbox is fully within the DBOFS active mask domain."""
+    min_lon, min_lat, max_lon, max_lat = bbox
+    domain_bbox = get_metadata()["domain_bbox"]
+    domain_min_lon, domain_min_lat, domain_max_lon, domain_max_lat = domain_bbox
+
+    # 1. Check strict rectangle bounds
+    if not (
+        min_lon >= domain_min_lon
+        and max_lon <= domain_max_lon
+        and min_lat >= domain_min_lat
+        and max_lat <= domain_max_lat
+    ):
+        return False
+
+    # 2. Check curvilinear offshore empty corner (e.g. Barnegat Light Area)
+    # The active mask drops out completely for regions east of -74.0 and north of 39.03
+    if min_lon > -74.0 and min_lat > 39.03:
+        return False
+
+    return True
+
+
+def _to_dap_url(url: str) -> str:
+    """Convert http(s) URL to pydap dap2:// scheme."""
+    return url.replace("https://", "dap2://").replace("http://", "dap2://")
+
+
+def _get_dbofs_url(target_dt: pd.Timestamp) -> Tuple[str, str]:
+    """
+    Resolve DBOFS data access URL and mode.
+
+    Returns (access_mode, url_or_pattern) where access_mode is one of:
+      - "fmrc": single FMRC aggregated OPeNDAP URL (recent data, < 31 days)
+      - "ncei": NCEI THREDDS file pattern (historical data, > 31 days)
+    """
+    now = pd.Timestamp.now(tz="UTC").tz_localize(None)
+    age_days = (now - target_dt).total_seconds() / 86400
+
+    if 0 <= age_days <= 6:
+        fmrc_url = (
+            "https://opendap.co-ops.nos.noaa.gov/thredds/dodsC/"
+            "DBOFS/fmrc/Aggregated_7_day_DBOFS_Fields_Forecast_best.ncd"
+        )
+        return ("fmrc", fmrc_url)
+
+    # Historical: AWS S3 or NCEI file-per-hour. Naming convention changed 2024-09-09
+    # and the archive migrated to AWS S3 starting 2024-01-01.
+    if target_dt >= pd.Timestamp("2024-01-01"):
+        pattern = (
+            "s3://noaa-nos-ofs-pds/dbofs/netcdf/"
+            "{yyyy}/{mm}/{dd}/dbofs.t{cc}z.{yyyymmdd}.fields.{type}{hhh:03d}.nc"
+        )
+        return ("aws_s3", pattern)
+    else:
+        pattern = (
+            "https://www.ncei.noaa.gov/thredds/dodsC/model-dbofs-files/"
+            "{yyyy}/{mm}/nos.dbofs.fields.{type}{hhh:03d}.{yyyymmdd}.t{cc}z.nc"
+        )
+        return ("ncei", pattern)
+
+
+def _enumerate_ncei_dbofs_files(
+    pattern: str, start_dt: pd.Timestamp, end_dt: pd.Timestamp
+) -> list[str]:
+    """
+    Enumerate NCEI DBOFS file URLs for a time range.
+
+    Picks the best 6-hourly cycle (00/06/12/18Z) and builds per-hour file URLs.
+    """
+    cycle_hours = [0, 6, 12, 18]
+    cycle_before = None
+    for ch in reversed(cycle_hours):
+        test_dt = start_dt.replace(hour=ch, minute=0, second=0, microsecond=0)
+        if test_dt <= start_dt:
+            cycle_before = test_dt
+            break
+
+    if cycle_before is None:
+        cycle_before = (start_dt - pd.Timedelta(days=1)).replace(
+            hour=18, minute=0, second=0, microsecond=0
+        )
+
+    files = []
+    current_dt = cycle_before
+    current_cycle_dt = cycle_before
+
+    while current_dt <= end_dt:
+        if (current_dt - current_cycle_dt).total_seconds() >= 6 * 3600:
+            current_cycle_dt = current_dt.replace(minute=0, second=0, microsecond=0)
+            cycle_hour = (current_cycle_dt.hour // 6) * 6
+            current_cycle_dt = current_cycle_dt.replace(hour=cycle_hour)
+
+        hour_offset = int((current_dt - current_cycle_dt).total_seconds() / 3600) + 1
+        forecast_or_nowcast = "f" if current_dt > current_cycle_dt else "n"
+
+        fmt_vars = {
+            "yyyy": current_cycle_dt.strftime("%Y"),
+            "mm": current_cycle_dt.strftime("%m"),
+            "dd": current_cycle_dt.strftime("%d"),
+            "yyyymmdd": current_cycle_dt.strftime("%Y%m%d"),
+            "cc": current_cycle_dt.strftime("%H"),
+            "hhh": hour_offset,
+            "type": forecast_or_nowcast,
+        }
+
+        files.append(pattern.format(**fmt_vars))
+        current_dt += pd.Timedelta(hours=1)
+
+    return files
+
+
+def _open_dbofs_dataset(
+    access_mode: str,
+    url_or_pattern: str,
+    target_dt: pd.Timestamp,
+    end_dt: Optional[pd.Timestamp] = None,
+) -> Optional[xr.Dataset]:
+    """Open DBOFS dataset via OPeNDAP (FMRC or NCEI)."""
+    try:
+        if access_mode == "fmrc":
+            logger.info(f"Opening DBOFS FMRC aggregation: {url_or_pattern}")
+            dap_url = _to_dap_url(url_or_pattern)
+            ds = xr.open_dataset(dap_url, engine="pydap")
+
+            time_var = "time" if "time" in ds.coords else "ocean_time"
+            ds = ds.sortby(time_var)
+
+            if end_dt is None:
+                return ds.sel({time_var: target_dt}, method="nearest")
+            else:
+                ds_t = ds.sel({time_var: slice(target_dt, end_dt)})
+                if ds_t.sizes[time_var] == 0:
+                    logger.warning(
+                        "DBOFS FMRC: exact time range empty, fell back to nearest."
+                    )
+                    return ds.sel({time_var: target_dt}, method="nearest").expand_dims(
+                        time_var
+                    )
+                return ds_t
+
+        elif access_mode in ("ncei", "aws_s3"):
+            mode_name = "AWS S3" if access_mode == "aws_s3" else "NCEI"
+            logger.info(
+                f"Enumerating DBOFS {mode_name} files from {target_dt} to {end_dt}"
+            )
+            if end_dt is None:
+                end_dt = target_dt + pd.Timedelta(hours=1)
+
+            files = _enumerate_ncei_dbofs_files(url_or_pattern, target_dt, end_dt)
+            logger.info(f"Opening {len(files)} DBOFS {mode_name} files...")
+
+            if access_mode == "aws_s3":
+                try:
+                    logger.info("Using xarray.open_mfdataset for parallel S3 access...")
+                    ds_t = xr.open_mfdataset(
+                        files,
+                        engine="h5netcdf",
+                        parallel=True,
+                        storage_options={"anon": True},
+                        data_vars="minimal",
+                        coords="minimal",
+                        compat="override",
+                    )
+                    return ds_t
+                except Exception as e:
+                    logger.error(
+                        f"Failed to open/concat DBOFS S3 files via mfdataset: {e}"
+                    )
+                    return None
+            else:
+                import concurrent.futures
+
+                datasets: list[Optional[xr.Dataset]] = [None] * len(files)
+                fail_counts = [0]
+
+                def _fetch_file(args):
+                    i, f = args
+                    # Optional short-circuit if another thread hit the failure limit
+                    if fail_counts[0] >= _NCEI_CONSECUTIVE_FAIL_LIMIT:
+                        return i, None
+                    try:
+                        if i % 10 == 0 or i == 1 or i == len(files):
+                            logger.info(
+                                f"[{i}/{len(files)}] Fetching/Opening DBOFS {mode_name} file: {f.split('/')[-1] if 's3' in f else f}"
+                            )
+                        ds_file = xr.open_dataset(_to_dap_url(f), engine="pydap")
+                        return i, ds_file
+                    except Exception as e:
+                        logger.warning(
+                            f"Failed to open DBOFS {mode_name} file {f}: {e}"
+                        )
+                        fail_counts[0] += 1
+                        return i, None
+
+                max_workers = settings.max_workers()
+                with concurrent.futures.ThreadPoolExecutor(
+                    max_workers=max_workers
+                ) as executor:
+                    for i, ds_file in executor.map(_fetch_file, enumerate(files, 1)):
+                        datasets[i - 1] = ds_file
+
+                # Filter out failures
+                opened = [ds for ds in datasets if ds is not None]
+
+                if not opened:
+                    logger.error(f"No DBOFS {mode_name} files could be opened.")
+                    return None
+
+                return xr.concat(opened, dim="time", join="override")
+
+        else:
+            logger.error(f"Unknown access_mode: {access_mode}")
+            return None
+
+    except Exception as e:
+        logger.error(f"Failed to open DBOFS dataset ({access_mode}): {e}")
+        return None
+
+
+_VAR_CANDIDATES: dict[str, list[str]] = {
+    "u": ["u", "water_u", "u_eastward"],
+    "v": ["v", "water_v", "v_northward"],
+    "temp": ["temp", "water_temp", "temperature", "sea_water_temperature"],
+    "salt": ["salt", "salinity", "sea_water_salinity"],
+    "zeta": ["zeta", "sea_surface_height", "ssh"],
+}
+
+
+def _resolve_var(ds: xr.Dataset, role: str) -> str:
+    """Return the first candidate name for *role* that exists in *ds*."""
+    for name in _VAR_CANDIDATES[role]:
+        if name in ds:
+            return name
+    raise KeyError(
+        f"No variable found for role '{role}'. "
+        f"Tried: {_VAR_CANDIDATES[role]}. Available: {list(ds.data_vars)}"
+    )
+
+
+def _c_grid_to_rho(
+    u_raw: np.ndarray,
+    v_raw: np.ndarray,
+) -> Tuple[np.ndarray, np.ndarray]:
+    """
+    Interpolate Arakawa C-grid u,v face values to rho-points by averaging
+    adjacent pairs. Output shape always matches input shape (boundary filled
+    by copy-edge extrapolation).
+    """
+    u_rho = np.empty_like(u_raw)
+    u_rho[..., :-1] = 0.5 * (u_raw[..., :-1] + u_raw[..., 1:])
+    u_rho[..., -1] = u_raw[..., -1]
+
+    v_rho = np.empty_like(v_raw)
+    v_rho[..., :-1, :] = 0.5 * (v_raw[..., :-1, :] + v_raw[..., 1:, :])
+    v_rho[..., -1, :] = v_raw[..., -1, :]
+
+    return u_rho, v_rho
+
+
+def fetch_dbofs_boundary_conditions(
+    start_date: str, duration_hours: int, bbox: list[float]
+) -> Optional[xr.Dataset]:
+    """
+    Fetch 4D Ocean State (u, v) from NOAA DBOFS over a time range for OBC.
+
+    Output dimensions: (time, depth, eta, xi) matching the standard OBC contract.
+
+    Args:
+        start_date: ISO format datetime string
+        duration_hours: Duration of the boundary condition period
+        bbox: [min_lon, min_lat, max_lon, max_lat]
+
+    Returns:
+        xr.Dataset with dims (time, depth, eta, xi) or None if fetch fails
+    """
+    min_lon, min_lat, max_lon, max_lat = bbox
+
+    if not supports_bbox(bbox):
+        logger.info(f"Bounding box {bbox} outside DBOFS domain.")
+        return None
+
+    target_dt = pd.to_datetime(start_date)
+    if target_dt.tzinfo is not None:
+        target_dt = target_dt.tz_convert("UTC").tz_localize(None)
+
+    end_dt = target_dt + pd.Timedelta(hours=duration_hours)
+
+    access_mode, url_or_pattern = _get_dbofs_url(target_dt)
+    logger.info(f"Attempting DBOFS OBC ({duration_hours}h) from {access_mode.upper()}")
+
+    ds_t = _open_dbofs_dataset(access_mode, url_or_pattern, target_dt, end_dt)
+    if ds_t is None:
+        return None
+
+    try:
+        lon_var = "lon_rho" if "lon_rho" in ds_t else "lon"
+        lat_var = "lat_rho" if "lat_rho" in ds_t else "lat"
+
+        lon_arr = ds_t[lon_var].values
+        lat_arr = ds_t[lat_var].values
+
+        mask_var = (
+            "mask_rho" if "mask_rho" in ds_t else ("mask" if "mask" in ds_t else None)
+        )
+        mask_arr = ds_t[mask_var].values if mask_var else np.ones_like(lon_arr)
+
+        valid_indices = np.where(
+            (lon_arr >= min_lon)
+            & (lon_arr <= max_lon)
+            & (lat_arr >= min_lat)
+            & (lat_arr <= max_lat)
+            & (mask_arr == 1)
+        )
+
+        if len(valid_indices[0]) == 0:
+            logger.warning("No valid DBOFS ocean points found in bounding box.")
+            return None
+
+        eta_min, eta_max = int(np.min(valid_indices[0])), int(np.max(valid_indices[0]))
+        xi_min, xi_max = int(np.min(valid_indices[1])), int(np.max(valid_indices[1]))
+
+        # Buffer slightly for interpolation
+        eta_min = max(0, eta_min - 2)
+        eta_max = min(lon_arr.shape[0] - 1, eta_max + 2)
+        xi_min = max(0, xi_min - 2)
+        xi_max = min(lon_arr.shape[1] - 1, xi_max + 2)
+
+        slice_dict = {}
+        for d in list(ds_t.dims):
+            if "eta" in str(d):
+                c_max = min(eta_max + 1, ds_t.sizes[d])
+                slice_dict[str(d)] = slice(eta_min, c_max)
+            elif "xi" in str(d):
+                c_max = min(xi_max + 1, ds_t.sizes[d])
+                slice_dict[str(d)] = slice(xi_min, c_max)
+
+        ds_sub = ds_t.isel(slice_dict)  # type: ignore
+
+        # Check if the bounding box yielded zero valid water points
+        if any(size == 0 for size in ds_sub.sizes.values()):
+            logger.warning(
+                "No valid DBOFS ocean points found in bounding box (size is 0)."
+            )
+            return None
+
+        logger.info("Executing OPeNDAP download for DBOFS OBC subset...")
+        ds_sub = ds_sub.compute()
+
+        u_var = _resolve_var(ds_sub, "u")
+        v_var = _resolve_var(ds_sub, "v")
+        logger.info(f"DBOFS OBC variable mapping: u={u_var}, v={v_var}")
+
+        all_dims = list(ds_sub[u_var].dims)
+        time_var = "time" if "time" in ds_sub.coords else "ocean_time"
+        sigma_dim = None
+        for candidate in ["s_rho", "sigma", "depth", "siglay"]:
+            if candidate in all_dims:
+                sigma_dim = candidate
+                break
+
+        if sigma_dim is None:
+            logger.error(
+                f"No recognized sigma dimension in DBOFS OBC. Dims: {all_dims}"
+            )
+            return None
+
+        spatial_dims = [d for d in all_dims if d != time_var and d != sigma_dim]
+        if len(spatial_dims) < 2:
+            logger.error(f"Unexpected spatial dims after subset: {spatial_dims}")
+            return None
+
+        u_rho, v_rho = _c_grid_to_rho(
+            ds_sub[u_var].values.astype(np.float32),
+            ds_sub[v_var].values.astype(np.float32),
+        )
+
+        n_sigma = u_rho.shape[1]
+        depths = np.linspace(-50, 0, n_sigma).astype(np.float32)
+        out_times = ds_sub[time_var].values
+        n_eta = u_rho.shape[2]
+        n_xi = u_rho.shape[3]
+
+        ds_out = xr.Dataset(
+            data_vars={
+                "u": (("time", "depth", "eta", "xi"), u_rho),
+                "v": (("time", "depth", "eta", "xi"), v_rho),
+            },
+            coords={
+                "time": out_times,
+                "depth": depths,
+                "eta": np.arange(n_eta, dtype=np.float32),
+                "xi": np.arange(n_xi, dtype=np.float32),
+            },
+            attrs={"type": "NOAA DBOFS OBC", "source": "NOAA CO-OPS"},
+        )
+
+        logger.info(
+            f"Successfully processed DBOFS OBC. "
+            f"Shape: u{ds_out['u'].shape}, {len(out_times)} time steps"
+        )
+        return ds_out
+
+    except Exception as e:
+        logger.error(f"Failed to process DBOFS OBC data: {e}")
+        return None

forcingkit/fetchers/erddap.py

@@ -0,0 +1,142 @@
+import os
+import logging
+import pandas as pd
+from forcingkit import settings
+
+logger = logging.getLogger(__name__)
+
+BASE_ERDDAP_URL = "http://merlin.dms.uconn.edu:8080/erddap"
+
+
+def fetch_erddap_station_profiles(
+    station_id: str,
+    start_time: str,
+    end_time: str,
+    cache_dir: str = os.path.join(
+        settings.cache_dir(),
+        "erddap",
+    ),
+    cache_bust: bool = False,
+) -> dict:
+    """
+    Fetches 3-depth temperature profiles for a given station.
+    Targeting LIS stations via UConn ERDDAP.
+
+    Args:
+        station_id: Station ID, e.g., "WLIS", "EXRX"
+        start_time: ISO8601 string (e.g., "YYYY-MM-DDTHH:MM:SSZ")
+        end_time: ISO8601 string
+
+    Returns:
+        dictionary with keys: "surface", "mid", "bottom", each containing a dictionary of time (ISO) -> temperature (float)
+    """
+    os.makedirs(cache_dir, exist_ok=True)
+
+    station_upper = station_id.upper()
+    datasets = {
+        "surface": f"{station_upper}_WQ_SFC",
+        "mid": f"{station_upper}_WQ_MID",
+        "bottom": f"{station_upper}_WQ_BTM",
+    }
+
+    # Handle irregular dataset names in LISICOS
+    if station_upper == "ARTG":
+        datasets["bottom"] = "ARTG_WQ_BTM_1"
+
+    profiles = {}
+
+    for level, dataset_name in datasets.items():
+        cache_key = f"{dataset_name}_{start_time}_{end_time}".replace(":", "-").replace(
+            "Z", ""
+        )
+        cache_path = os.path.join(cache_dir, f"{cache_key}.csv")
+
+        if not cache_bust and os.path.exists(cache_path):
+            logger.info(f"Cache hit for {dataset_name}: {cache_path}")
+            df = pd.read_csv(cache_path, index_col=0, parse_dates=True)
+        else:
+            query_url = f"{BASE_ERDDAP_URL}/tabledap/{dataset_name}.csvp?time,sea_water_temperature&time%3E={start_time}&time%3C={end_time}"
+
+            logger.info(
+                f"Fetching ERDDAP data for {dataset_name} ({start_time} to {end_time})..."
+            )
+            try:
+                df = pd.read_csv(query_url)
+                if df is not None and not df.empty:
+                    # The headers will be like "time (UTC)" and "sea_water_temperature (celsius)"
+                    # We can normalize them
+                    df.columns = ["time", "sea_water_temperature"]
+                    df = df.set_index("time")
+                    df.index = pd.to_datetime(df.index, utc=True)
+                    df.to_csv(cache_path)
+            except Exception as e:
+                logger.error(
+                    f"Failed fetching or parsing ERDDAP for {dataset_name}: {e}"
+                )
+                df = None
+
+        if df is not None and not df.empty:
+            df = df.dropna(subset=["sea_water_temperature"])
+            # We must convert timestamp back to isoformat strings to match json expectations if returned by API
+            time_dict = {
+                ts.isoformat(): temp for ts, temp in df["sea_water_temperature"].items()
+            }
+            profiles[level] = time_dict
+
+    return profiles
+
+
+KNOWN_STATIONS = {
+    "WLIS": {"lat": 40.96, "lon": -73.58},
+    "EXRX": {"lat": 40.88, "lon": -73.73},
+    "CLIS": {"lat": 41.14, "lon": -72.66},
+    "ARTG": {"lat": 41.01, "lon": -73.29},
+}
+
+
+def fetch_erddap_stations_in_bbox(
+    bbox: list[float],
+    start_time: str,
+    end_time: str,
+    cache_dir: str = os.path.join(
+        settings.cache_dir(),
+        "erddap",
+    ),
+    cache_bust: bool = False,
+) -> dict:
+    """
+    Finds all known LIS stations within the bounding box and fetches their profiles.
+    bbox: [max_lat, min_lon, min_lat, max_lon] or [min_lon, min_lat, max_lon, max_lat]
+    """
+    # Accept standard Julia order (min_lon, min_lat, max_lon, max_lat)
+    if len(bbox) == 4:
+        min_lon, min_lat, max_lon, max_lat = bbox
+    else:
+        return {}
+
+    stations_to_fetch = []
+    for st_id, coords in KNOWN_STATIONS.items():
+        if min_lat <= coords["lat"] <= max_lat and min_lon <= coords["lon"] <= max_lon:
+            stations_to_fetch.append(st_id)
+
+    # fallback to EXRX if none in bounding box for testing
+    if not stations_to_fetch:
+        logger.warning(
+            f"No stations found in bbox {bbox}. Falling back to default proxy stations (EXRX, WLIS)"
+        )
+        stations_to_fetch = ["EXRX", "WLIS"]
+
+    results = {}
+    for st_id in stations_to_fetch:
+        logger.info(f"Fetching station {st_id} for bounding box request...")
+        profile = fetch_erddap_station_profiles(
+            st_id, start_time, end_time, cache_dir, cache_bust
+        )
+        if profile and any(v for v in profile.values()):
+            results[st_id] = {
+                "lat": KNOWN_STATIONS.get(st_id, {}).get("lat", 0.0),
+                "lon": KNOWN_STATIONS.get(st_id, {}).get("lon", 0.0),
+                "profiles": profile,
+            }
+
+    return results

forcingkit/fetchers/hrrr.py

@@ -0,0 +1,72 @@
+import s3fs
+import logging
+
+
+logger = logging.getLogger(__name__)
+
+# NOAA makes HRRR freely available on AWS S3 without authentication.
+# The same bucket (noaa-hrrr-bdp-pds) holds both the rolling operational
+# window and the full historical archive back to 2014-07-30.
+fs = s3fs.S3FileSystem(anon=True)
+
+
+# First date for which HRRR data exists in the noaa-hrrr-bdp-pds archive.
+# GRIB2 .idx variable patterns for 10-meter wind components.
+# Each HRRR .grib2 on S3 has a sidecar .idx listing byte offsets per message.
+def _parse_idx(
+    idx_text: str, patterns: tuple[str, ...]
+) -> list[tuple[int, int | None]]:
+    """
+    Parse a GRIB2 .idx sidecar file and return byte ranges for matching messages.
+
+    Each .idx line has the format:
+        message_number:byte_offset:date:variable:level:forecast_type:
+
+    Returns a list of (start_byte, end_byte) tuples. end_byte is None for the
+    last message in the file (meaning read-to-EOF).
+    """
+    lines = [line.strip() for line in idx_text.strip().splitlines() if line.strip()]
+
+    # Build list of (message_number, byte_offset, raw_line)
+    entries = []
+    for line in lines:
+        parts = line.split(":")
+        if len(parts) < 3:
+            continue
+        try:
+            offset = int(parts[1])
+        except ValueError:
+            continue
+        entries.append((offset, line))
+
+    # Find matching messages and compute byte ranges
+    ranges = []
+    for i, (offset, line) in enumerate(entries):
+        if any(pattern in line for pattern in patterns):
+            # End byte is the start of the next message, or None for EOF
+            end = entries[i + 1][0] if i + 1 < len(entries) else None
+            ranges.append((offset, end))
+
+    return ranges
+
+
+def _fetch_s3_byte_ranges(
+    s3_path: str, ranges: list[tuple[int, int | None]], output_path: str
+) -> None:
+    """
+    Download specific byte ranges from an S3 object and concatenate into a
+    single valid GRIB2 file. Each GRIB2 message is self-contained, so
+    concatenating selected messages produces a valid file.
+    """
+    with open(output_path, "wb") as f:
+        for start, end in ranges:
+            if end is not None:
+                length = end - start
+                with fs.open(s3_path, "rb") as s3f:
+                    s3f.seek(start)
+                    f.write(s3f.read(length))
+            else:
+                # Read from start to EOF
+                with fs.open(s3_path, "rb") as s3f:
+                    s3f.seek(start)
+                    f.write(s3f.read())