oceanarray 0.1.0__py3-none-any.whl

oceanarray/readers.py

@@ -0,0 +1,303 @@
+from pathlib import Path
+from typing import Dict, List, Optional, Union
+
+import numpy as np
+import pandas as pd
+import xarray as xr
+
+from oceanarray.logger import log_info
+from oceanarray.legacy import rodb
+
+DUMMY_VALUES = [1e32, -9.0, -9.9]
+
+
+def load_dataset(
+    source: Union[str, Path, List[Union[str, Path]]],
+) -> Union[xr.Dataset, List[xr.Dataset]]:
+    """Load one or more observational data files and return as xarray Datasets.
+    Dispatches based on file extension or known formats.
+
+    Parameters
+    ----------
+    source : str, Path, or list of str/Path
+        Single file or list of files to load.
+
+    Returns
+    -------
+    xarray.Dataset or list of xarray.Dataset
+        Loaded dataset(s). A single dataset is returned if one file is given;
+        a list of datasets is returned for multiple files.
+
+    Raises
+    ------
+    ValueError
+        If file type is unrecognized.
+
+    """
+    if isinstance(source, (str, Path)):
+        source = [Path(source)]
+    else:
+        source = [Path(f) for f in source]
+
+    datasets = []
+    for f in source:
+        if f.suffix.lower() == ".nc":
+            ds = xr.open_dataset(f)
+        elif rodb.is_rodb_file(f):
+            ds = rodb.rodbload(f)
+        else:
+            raise ValueError(f"Unknown file type: {f}")  # noqa: TRY003
+        datasets.append(ds)
+
+    return datasets if len(datasets) > 1 else datasets[0]
+
+
+def rodbload_old(filepath: Path, variables: list[str]) -> xr.Dataset:
+    """Load a RODB-style file into an xarray.Dataset.
+
+    Parameters
+    ----------
+    filepath : Path
+        Path to the .use, .raw or .dat file
+    variables : list of str
+        Variables to extract (must be present in columns= line)
+
+    Returns
+    -------
+    ds : xr.Dataset
+        Dataset containing requested variables
+
+    """
+    with open(filepath, "r") as f:
+        lines = f.readlines()
+
+    # Extract header lines (up to first data block)
+    header_lines = []
+    data_start_index = None
+
+    for i, line in enumerate(lines):
+        if not line.strip():
+            continue
+        if line.lstrip().startswith("#") or "=" in line:
+            header_lines.append(line.strip())
+        else:
+            data_start_index = i
+            break
+
+    if data_start_index is None:
+        raise ValueError("Could not locate data block in file")  # noqa: TRY003
+
+    # Extract columns
+    col_line = next((line for line in header_lines if "columns" in line.lower()), None)
+    if col_line is None:
+        raise ValueError("No 'columns=' line found in header")  # noqa: TRY003
+
+    columns = col_line.split("=")[-1].strip().split(":")
+    print(columns)
+    log_info("Found columns: %s", columns)
+
+    # Validate requested variables
+    missing = [v for v in variables if v not in columns]
+    if missing:
+        raise ValueError(f"Variables not found in file: {missing}")  # noqa: TRY003
+
+    col_indices = {v: i for i, v in enumerate(columns) if v in variables}
+
+    # Load data block
+    data = np.genfromtxt(lines[data_start_index:], dtype=float)
+    if data.ndim == 1:
+        data = data[np.newaxis, :]  # in case of only 1 line
+
+    # Replace dummy values with NaN
+    for dummy in DUMMY_VALUES:
+        data[data == dummy] = np.nan
+
+    # Build xarray dataset
+    coords = {"obs": np.arange(data.shape[0])}
+    data_vars = {var: (("obs",), data[:, col_indices[var]]) for var in variables}
+
+    ds = xr.Dataset(data_vars, coords=coords)
+    ds.attrs["source_file"] = str(filepath)
+    return ds
+
+
+def _clean_nortek_var_name(col: str) -> str:
+    """Convert a raw Nortek CSV column name to a valid NetCDF variable name."""
+    import re
+
+    name = col.lower().strip()
+    name = re.sub(r"[^\w\s]", " ", name)  # special chars → spaces
+    name = re.sub(r"\s+", "_", name.strip())
+    name = re.sub(r"_+", "_", name)
+    return name
+
+
+def _parse_nortek_csv_columns(df: pd.DataFrame) -> Dict:
+    """Build a complete variable dict from all columns in a Nortek CSV DataFrame.
+
+    Nortek AquaPro exports mix two column-naming styles:
+    - camelCase (``velBeam1#1``, ``speedOfSound``) for the AquaPro velocity block
+    - Title Case (``Pressure``, ``Temperature``, ``Soundspeed``) for the
+      environmental summary block
+
+    Rules applied:
+    - Column matching for canonical names is case-insensitive.
+    - When the same name appears more than once (e.g. ``Pressure`` in dbar then
+      ``Pressure`` in m), the first occurrence maps to the canonical name and
+      all later occurrences are dropped — the second Pressure column is depth
+      (derived from pressure) and is not needed.
+    - All remaining columns are included with cleaned variable names so that
+      no data from the raw file is silently discarded.
+    - Time component columns (Year, Month, Day, Hour, Minute, Second) are
+      dropped because the ``time`` coordinate already captures this information.
+    """
+    # Build case-insensitive lookup: lower_name -> first df column name
+    col_map: Dict[str, str] = {}
+    for col in df.columns:
+        key = col.lower().strip()
+        if key not in col_map:
+            col_map[key] = col  # first occurrence wins
+
+    # Canonical name mappings — covers both camelCase and Title Case spellings
+    canonical: Dict[str, str] = {}  # df_col_name -> var_name
+
+    scalar_mappings = [
+        (["temperature"], "temperature"),
+        (["pressure"], "pressure"),  # first = dbar
+        (["heading"], "heading"),
+        (["pitch"], "pitch"),
+        (["roll"], "roll"),
+        (["soundspeed", "speedofsound"], "speed_of_sound"),
+        (["battery voltage", "batteryvoltage"], "battery_voltage"),
+        (["speed"], "speed"),
+    ]
+    for csv_names, var_name in scalar_mappings:
+        for csv_name in csv_names:
+            if csv_name in col_map:
+                canonical[col_map[csv_name]] = var_name
+                break
+
+    # AquaPro camelCase beam variables
+    for i in [1, 2, 3]:
+        for data_type, prefix in [
+            ("vel", "velocity"),
+            ("amp", "amplitude"),
+            ("corr", "correlation"),
+        ]:
+            df_col = f"{data_type}Beam{i}#1"
+            if df_col in df.columns:
+                canonical[df_col] = f"{prefix}_beam{i}"
+
+    # Columns to drop entirely
+    time_components = {"year", "month", "day", "hour", "minute", "second"}
+    # The second (and any further) occurrence of "pressure" is depth in metres
+    first_pressure_col = col_map.get("pressure")
+    duplicate_pressure = {
+        col
+        for col in df.columns
+        if col.lower().strip() == "pressure" and col != first_pressure_col
+    }
+    drop_cols = time_components | duplicate_pressure | {"datetime"}
+
+    # Build data_vars: canonical names first, then everything else
+    data_vars: Dict = {}
+    assigned_df_cols: set = set(canonical.keys())
+
+    for df_col, var_name in canonical.items():
+        data_vars[var_name] = (["time"], df[df_col].values)
+
+    for df_col in df.columns:
+        if df_col in assigned_df_cols:
+            continue
+        if df_col.lower().strip() in drop_cols or df_col in drop_cols:
+            continue
+        var_name = _clean_nortek_var_name(df_col)
+        if var_name and var_name not in data_vars:
+            data_vars[var_name] = (["time"], df[df_col].values)
+
+    return data_vars
+
+
+def _add_nortek_csv_attributes(ds: xr.Dataset) -> xr.Dataset:
+    """Add units and metadata attributes to variables in a Nortek CSV dataset."""
+    attr_map = {
+        "temperature": {"units": "degrees_C", "long_name": "Water Temperature"},
+        "pressure": {"units": "dbar", "long_name": "Pressure"},
+        "heading": {"units": "degrees", "long_name": "Heading"},
+        "pitch": {"units": "degrees", "long_name": "Pitch"},
+        "roll": {"units": "degrees", "long_name": "Roll"},
+        "speed_of_sound": {"units": "m/s", "long_name": "Speed of Sound"},
+        "battery_voltage": {"units": "V", "long_name": "Battery Voltage"},
+    }
+    for var_name, attrs in attr_map.items():
+        if var_name in ds.data_vars:
+            ds[var_name].attrs.update(attrs)
+
+    for i in [1, 2, 3]:
+        if f"velocity_beam{i}" in ds.data_vars:
+            ds[f"velocity_beam{i}"].attrs.update(
+                {
+                    "units": "m/s",
+                    "long_name": f"Velocity Beam {i}",
+                    "coordinate_system": "BEAM",
+                }
+            )
+        if f"amplitude_beam{i}" in ds.data_vars:
+            ds[f"amplitude_beam{i}"].attrs.update(
+                {"units": "counts", "long_name": f"Amplitude Beam {i}"}
+            )
+        if f"correlation_beam{i}" in ds.data_vars:
+            ds[f"correlation_beam{i}"].attrs.update(
+                {"units": "%", "long_name": f"Correlation Beam {i}"}
+            )
+
+    return ds
+
+
+def load_nortek_csv(
+    file_path: Union[str, Path],
+    header_file: Optional[str] = None,  # noqa: ARG001
+) -> xr.Dataset:
+    """Load Nortek CSV data exported from AquaPro software.
+
+    Parameters
+    ----------
+    file_path : str or Path
+        Path to the semicolon-delimited CSV data file (e.g. "Average Velocity DF3.csv").
+    header_file : str, optional
+        Path to the accompanying Units.csv file (reserved for future metadata use).
+
+    Returns
+    -------
+    xr.Dataset
+        Dataset with time coordinate and variables for velocity beams,
+        amplitude, correlation, and environmental channels.
+
+    """
+    file_path = Path(file_path)
+    if not file_path.exists():
+        raise FileNotFoundError(f"Nortek CSV file not found: {file_path}")  # noqa: TRY003
+
+    df = pd.read_csv(file_path, delimiter=";")
+    df["datetime"] = pd.to_datetime(df["dateTime"])
+    times = df["datetime"].values
+
+    data_vars = _parse_nortek_csv_columns(df)
+    ds = xr.Dataset(data_vars, coords={"time": times})
+
+    ds.attrs.update(
+        {
+            "instrument_type": "Nortek_Aquadopp",
+            "filename": str(file_path),
+            "data_format": "Nortek_CSV_Export",
+            "coordinate_system": "BEAM",
+        }
+    )
+
+    if "serialNumber" in df.columns:
+        ds.attrs["serial_number"] = str(df["serialNumber"].iloc[0])
+
+    ds = _add_nortek_csv_attributes(ds)
+
+    log_info("Nortek CSV: loaded %d samples from %s", len(times), file_path.name)
+    return ds

oceanarray/report/__init__.py

@@ -0,0 +1,5 @@
+"""Mooring report package — public API."""
+
+from ._mooring import MooringReport
+
+__all__ = ["MooringReport"]

oceanarray/report/_array.py

@@ -0,0 +1,386 @@
+"""Array-level HTML summary report.
+
+Reads a ``*.array.yaml`` file, gathers per-mooring metadata from each
+mooring's YAML, draws a simple position map, and writes a single HTML
+index page with clickable links to every mooring's report.
+
+Entry point: :func:`generate_array_report`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import yaml
+
+from ._html_helpers import _duration_str, _fig_to_base64, _parse_dt, _status
+
+
+# ---------------------------------------------------------------------------
+# Lat/lon parsing
+# ---------------------------------------------------------------------------
+
+
+def _parse_decdeg(val: Any) -> Optional[float]:
+    """Parse a latitude or longitude value to decimal degrees.
+
+    Handles:
+    - Numeric types (float / int): returned as-is.
+    - ``"65.567"`` or ``"-27.5"`` — plain decimal-degree strings.
+    - ``"65 43.913"`` — degrees + decimal-minutes, sign for hemisphere.
+    - ``"65 34.004 N"`` / ``"029 25.878 W"`` — DM with hemisphere letter.
+    """
+    if val is None:
+        return None
+    if isinstance(val, (int, float)):
+        return float(val)
+    s = str(val).strip()
+    try:
+        return float(s)
+    except ValueError:
+        pass
+    parts = s.split()
+    if len(parts) >= 2:
+        try:
+            deg = float(parts[0])
+            minutes = float(parts[1])
+            dd = abs(deg) + minutes / 60.0
+            if deg < 0:
+                dd = -dd
+            if len(parts) >= 3:
+                hemi = parts[2].strip(".,").upper()
+                if hemi in ("S", "W"):
+                    dd = -abs(dd)
+        except (ValueError, IndexError):
+            pass
+        else:
+            return dd
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Mooring metadata extraction
+# ---------------------------------------------------------------------------
+
+
+def _lat_lon_from_cfg(cfg: Dict[str, Any]) -> tuple:
+    """Return (lat_dd, lon_dd) decimal degrees from a mooring YAML dict."""
+    lat_raw = (
+        cfg.get("seabed_latitude")
+        or cfg.get("deployment_latitude")
+        or cfg.get("planned_latitude")
+        or cfg.get("latitude")
+    )
+    lon_raw = (
+        cfg.get("seabed_longitude")
+        or cfg.get("deployment_longitude")
+        or cfg.get("planned_longitude")
+        or cfg.get("longitude")
+    )
+    return _parse_decdeg(lat_raw), _parse_decdeg(lon_raw)
+
+
+def _count_instruments(cfg: Dict[str, Any]) -> int:
+    """Count instruments in a mooring YAML (clamp or instruments key)."""
+    entries = cfg.get("clamp") or cfg.get("instruments") or []
+    return sum(1 for e in entries if isinstance(e, dict) and not e.get("skip"))
+
+
+# ---------------------------------------------------------------------------
+# Map figure
+# ---------------------------------------------------------------------------
+
+
+def _make_array_map_b64(
+    rows: List[Dict[str, Any]],
+    array_name: str,
+) -> Optional[str]:
+    """Return a base64-encoded PNG of mooring positions, or None on failure."""
+    try:
+        import matplotlib.pyplot as plt
+        from oceanarray import parameters as P
+
+        plt.style.use(str(P.MPLSTYLE))
+
+        lats = [r["lat"] for r in rows if r["lat"] is not None]
+        if len(lats) < 1:
+            return None
+
+        mean_lat_rad = float(__import__("math").radians(sum(lats) / len(lats)))
+        aspect = 1.0 / __import__("math").cos(mean_lat_rad)
+
+        fig, ax = plt.subplots(figsize=(6, 5))
+        ax.set_aspect(aspect)
+
+        import matplotlib.colors as _mcolors
+
+        _tab20 = plt.get_cmap("tab20")
+        for idx, r in enumerate(rows):
+            if r["lat"] is None or r["lon"] is None:
+                continue
+            color = _tab20(idx % 20)
+            r["color_hex"] = _mcolors.to_hex(color)
+            ax.scatter(r["lon"], r["lat"], s=60, color=color, zorder=3)
+            # Only label moorings that have been recovered
+            if r.get("_recover_dt") is not None:
+                ax.annotate(
+                    r["mooring"],
+                    (r["lon"], r["lat"]),
+                    textcoords="offset points",
+                    xytext=(5, 3),
+                    fontsize=10,
+                    color=color,
+                )
+
+        ax.set_xlabel("Longitude (°)")
+        ax.set_ylabel("Latitude (°)")
+        ax.set_title(array_name, fontsize=9)
+        ax.grid(True, linestyle="--", linewidth=0.3, alpha=0.5)
+        plt.tight_layout()
+        b64 = _fig_to_base64(fig)
+        plt.close(fig)
+    except Exception:  # noqa: BLE001
+        return None
+    else:
+        return b64
+    return None
+
+
+# ---------------------------------------------------------------------------
+# HTML template
+# ---------------------------------------------------------------------------
+
+_ARRAY_HTML_TEMPLATE = """\
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Array report &ndash; {{ array_name }}</title>
+<style>
+  :root { --ocean:#1a3a5c; --seafoam:#e8f4f8; --text:#2c3e50; --muted:#95a5a6; }
+  body { font-family: system-ui, sans-serif; max-width: 1100px; margin: 0 auto; padding: 1rem; color: var(--text); }
+  .masthead { background: var(--ocean); color:#fff; border-radius:6px; padding:1.2rem 1.6rem 1rem; margin-bottom:1.2rem; }
+  .masthead h1 { margin:0 0 0.2rem; font-size:1.6rem; }
+  .masthead p.sub { margin:0; font-size:0.82rem; opacity:0.75; }
+  .meta-grid { display:flex; flex-wrap:wrap; gap:0.5rem 1.4rem; margin-top:0.8rem; }
+  .meta-grid div { font-size:0.82rem; }
+  .meta-grid dt { opacity:0.7; font-size:0.72rem; }
+  .meta-grid dd { margin:0; font-weight:600; }
+  .meta-miss dd { color:#f0ad4e; }
+  table { border-collapse:collapse; width:100%; margin:0.6rem 0 1.2rem; font-size:0.84rem; }
+  th { background:var(--ocean); color:#fff; padding:0.4rem 0.6rem; text-align:left; }
+  td { padding:0.35rem 0.6rem; border-bottom:1px solid #e8ecef; }
+  tr:nth-child(even) td { background:#f7f9fb; }
+  .num { text-align:right; }
+  .btn { display:inline-block; padding:0.15em 0.55em; border-radius:4px; font-size:0.75rem;
+         font-weight:700; text-decoration:none; color:#fff; margin:0 0.15rem 0.2rem 0; }
+  .btn-sum { background:#2c3e50; }
+  .btn-stk { background:#2980b9; }
+  .btn-grd { background:#8e44ad; }
+  .btn-miss { background:#bbb; cursor:default; pointer-events:none; }
+  .note { font-size:0.78rem; color:#555; margin:0.2rem 0 0.6rem; }
+  .fig { max-width:60%; display:block; margin:0.5rem auto 1rem; border:1px solid #e0e4e8; border-radius:4px; }
+  h2 { color:var(--ocean); border-bottom:2px solid var(--seafoam); padding-bottom:0.3rem; margin-top:1.4rem; }
+</style>
+</head>
+<body>
+
+<div class="masthead">
+  <h1>{{ array_name }}</h1>
+  <p class="sub">Array summary &bull; generated {{ generated }}</p>
+  <dl class="meta-grid">
+    {% if year %}<div><dt>Year</dt><dd>{{ year }}</dd></div>{% endif %}
+    {% if cruise %}<div><dt>Cruise</dt><dd>{{ cruise }}</dd></div>{% endif %}
+    {% if ship %}<div><dt>Ship</dt><dd>{{ ship }}</dd></div>{% endif %}
+    {% if project %}<div><dt>Project</dt><dd>{{ project }}</dd></div>{% endif %}
+    {% if deploy_time %}<div><dt>Deployment</dt><dd>{{ deploy_time }}</dd></div>{% endif %}
+    {% if recover_time %}<div><dt>Recovery</dt><dd>{{ recover_time }}</dd></div>{% endif %}
+    <div><dt>Moorings</dt><dd>{{ moorings | length }}</dd></div>
+  </dl>
+</div>
+
+{% if fig_map_b64 %}
+<h2>Mooring positions</h2>
+<img class="fig" src="data:image/png;base64,{{ fig_map_b64 }}" alt="Array map">
+{% endif %}
+
+<h2>Moorings</h2>
+<table>
+  <thead>
+    <tr>
+      <th>#</th>
+      <th>Mooring</th>
+      <th class="num">Latitude</th>
+      <th class="num">Longitude</th>
+      <th class="num">Depth&nbsp;(m)</th>
+      <th>Deployment</th>
+      <th>Recovery</th>
+      <th class="num">Duration</th>
+      <th class="num">Instruments</th>
+      <th>Reports</th>
+    </tr>
+  </thead>
+  <tbody>
+  {% for r in moorings %}
+  <tr>
+    <td class="num">{% if r.color_hex %}<span style="display:inline-block;width:0.75em;height:0.75em;border-radius:50%;background:{{ r.color_hex }};margin-right:0.35em;vertical-align:middle"></span>{% endif %}{{ r.position }}</td>
+    <td><strong>{{ r.mooring }}</strong></td>
+    <td class="num">{{ "%.4f"|format(r.lat) if r.lat is not none else "—" }}</td>
+    <td class="num">{{ "%.4f"|format(r.lon) if r.lon is not none else "—" }}</td>
+    <td class="num">{{ r.waterdepth if r.waterdepth else "—" }}</td>
+    <td>{{ r.deploy_time }}</td>
+    <td>{{ r.recover_time }}</td>
+    <td class="num">{{ r.duration }}</td>
+    <td class="num">{{ r.n_instruments }}</td>
+    <td>
+      {% if r.report_exists %}
+        <a class="btn btn-sum" href="{{ r.mooring }}/report/{{ r.mooring }}_report.html">Summary</a>
+      {% else %}
+        <span class="btn btn-miss">Summary</span>
+      {% endif %}
+      {% if r.stack_exists %}
+        <a class="btn btn-stk" href="{{ r.mooring }}/report/{{ r.mooring }}_stack_report.html">Stack</a>
+      {% endif %}
+      {% if r.grid_exists %}
+        <a class="btn btn-grd" href="{{ r.mooring }}/report/{{ r.mooring }}_grid_report.html">Grid</a>
+      {% endif %}
+    </td>
+  </tr>
+  {% endfor %}
+  </tbody>
+</table>
+
+</body>
+</html>
+"""
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+
+def generate_array_report(
+    array_yaml_path: Path,
+    proc_dir: Path,
+    out_path: Optional[Path] = None,
+    force: bool = False,
+) -> Optional[Path]:
+    """Generate an HTML array-level summary report from an array YAML file.
+
+    Parameters
+    ----------
+    array_yaml_path : Path
+        Path to the ``*.array.yaml`` file.
+    proc_dir : Path
+        Root processing directory.  Each mooring directory is expected to be
+        ``proc_dir / mooring_id``.
+    out_path : Path, optional
+        Output HTML path.  Defaults to
+        ``proc_dir / "{array_name}_array_report.html"``.
+    force : bool
+        Overwrite existing output file.
+
+    Returns
+    -------
+    Path or None
+        Path to the written HTML file, or None on failure.
+
+    """
+    from datetime import datetime, timezone
+
+    from jinja2 import Environment
+
+    array_yaml_path = Path(array_yaml_path)
+    proc_dir = Path(proc_dir)
+
+    if not array_yaml_path.exists():
+        print(f"ERROR: array YAML not found: {array_yaml_path}")
+        return None
+
+    with open(array_yaml_path) as fh:
+        array_cfg = yaml.safe_load(fh)
+
+    array_name = array_cfg.get("name", array_yaml_path.stem)
+
+    if out_path is None:
+        out_path = proc_dir / f"{array_name}_array_report.html"
+
+    if out_path.exists() and not force:
+        _status("skip", str(out_path))
+        return out_path
+
+    mooring_entries = array_cfg.get("moorings", [])
+    rows: List[Dict[str, Any]] = []
+
+    for pos_idx, entry in enumerate(mooring_entries, start=1):
+        mooring_id = entry.get("mooring", "")
+        config_name = entry.get("config", f"{mooring_id}.mooring.yaml")
+        mooring_yaml = proc_dir / mooring_id / config_name
+
+        mcfg: Dict[str, Any] = {}
+        if mooring_yaml.exists():
+            try:
+                with open(mooring_yaml) as fh:
+                    mcfg = yaml.safe_load(fh) or {}
+            except Exception as exc:  # noqa: BLE001
+                print(f"WARNING: could not read {mooring_yaml}: {exc}")
+        else:
+            print(f"WARNING: mooring YAML not found: {mooring_yaml}")
+
+        lat, lon = _lat_lon_from_cfg(mcfg)
+        deploy_dt = _parse_dt(mcfg.get("deployment_time"))
+        recover_dt = _parse_dt(mcfg.get("recovery_time"))
+
+        report_dir = proc_dir / mooring_id / "report"
+        rows.append(
+            {
+                "position": entry.get("position", str(pos_idx)),
+                "mooring": mooring_id,
+                "lat": lat,
+                "lon": lon,
+                "color_hex": None,
+                "waterdepth": mcfg.get("waterdepth"),
+                "deploy_time": deploy_dt.strftime("%Y-%m-%d %H:%M")
+                if deploy_dt
+                else "—",
+                "recover_time": recover_dt.strftime("%Y-%m-%d %H:%M")
+                if recover_dt
+                else "—",
+                "duration": _duration_str(deploy_dt, recover_dt),
+                "_deploy_dt": deploy_dt,
+                "_recover_dt": recover_dt,
+                "n_instruments": _count_instruments(mcfg),
+                "report_exists": (report_dir / f"{mooring_id}_report.html").exists(),
+                "stack_exists": (
+                    report_dir / f"{mooring_id}_stack_report.html"
+                ).exists(),
+                "grid_exists": (report_dir / f"{mooring_id}_grid_report.html").exists(),
+            }
+        )
+
+    fig_map_b64 = _make_array_map_b64(rows, array_name)
+
+    deploy_dt_arr = _parse_dt(array_cfg.get("deployment_time"))
+    recover_dt_arr = _parse_dt(array_cfg.get("recovery_time"))
+
+    ctx = {
+        "array_name": array_name,
+        "year": array_cfg.get("year"),
+        "cruise": array_cfg.get("cruise"),
+        "ship": array_cfg.get("ship"),
+        "project": array_cfg.get("project"),
+        "deploy_time": deploy_dt_arr.strftime("%Y-%m-%d") if deploy_dt_arr else "",
+        "recover_time": recover_dt_arr.strftime("%Y-%m-%d") if recover_dt_arr else "",
+        "moorings": rows,
+        "fig_map_b64": fig_map_b64,
+        "generated": datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC"),
+    }
+
+    env = Environment(autoescape=True)
+    html = env.from_string(_ARRAY_HTML_TEMPLATE).render(**ctx)
+    out_path.write_text(html, encoding="utf-8")
+    _status("file", str(out_path))
+    return out_path