oceanarray 0.1.0__py3-none-any.whl

oceanarray/logger.py

@@ -0,0 +1,192 @@
+"""Logging configuration and helpers for the oceanarray processing pipeline."""
+
+import datetime
+import logging
+from pathlib import Path
+from typing import Any
+
+# Global logger instance (will be configured by setup_logger)
+log = logging.getLogger("oceanarray")
+log.setLevel(logging.DEBUG)  # capture everything; handlers filter later
+
+# Global logging flag
+# Set to True to enable logging, False to disable
+LOGGING_ENABLED = True
+
+
+def enable_logging() -> None:
+    """Enable logging globally."""
+    global LOGGING_ENABLED
+    LOGGING_ENABLED = True
+
+
+def disable_logging() -> None:
+    """Disable logging globally."""
+    global LOGGING_ENABLED
+    LOGGING_ENABLED = False
+
+
+def log_info(message: str, *args: Any) -> None:
+    """Log an info message, if logging is enabled."""
+    if LOGGING_ENABLED:
+        log.info(message, *args, stacklevel=2)
+
+
+def log_warning(message: str, *args: Any) -> None:
+    """Log a warning message, if logging is enabled."""
+    if LOGGING_ENABLED:
+        log.warning(message, *args, stacklevel=2)
+
+
+def log_error(message: str, *args: Any) -> None:
+    """Log an error message, if logging is enabled."""
+    if LOGGING_ENABLED:
+        log.error(message, *args, stacklevel=2)
+
+
+def log_debug(message: str, *args: Any) -> None:
+    """Log a debug message, if logging is enabled."""
+    if LOGGING_ENABLED:
+        log.debug(message, *args, stacklevel=2)
+
+
+def setup_logger(array_name: str, output_dir: str = "logs") -> None:
+    """Configure the global logger to output to a file for the given array.
+
+    Parameters
+    ----------
+    array_name : str
+        Name of the observing array (e.g., 'move', 'rapid', etc.).
+    output_dir : str
+        Directory to save log files.
+
+    """
+    if not LOGGING_ENABLED:
+        return
+    # Resolve output directory to project root
+    project_root = Path(__file__).resolve().parent.parent
+    output_path = project_root / output_dir
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    timestamp = datetime.datetime.now().strftime("%Y%m%dT%H")
+    log_filename = f"{array_name.upper()}_{timestamp}_read.log"
+    log_path = output_path / log_filename
+
+    # Prevent duplicate handlers in case of multiple calls
+    if not any(
+        isinstance(h, logging.FileHandler) and h.baseFilename == log_path
+        for h in log.handlers
+    ):
+        file_handler = logging.FileHandler(log_path, encoding="utf-8", mode="w")
+        formatter = logging.Formatter(
+            fmt="%(asctime)s %(levelname)-8s %(funcName)s %(message)s",
+            datefmt="%Y%m%dT%H%M%S",
+        )
+        file_handler.setFormatter(formatter)
+
+        # Optional: console handler
+        console_handler = logging.StreamHandler()
+        console_handler.setFormatter(formatter)
+
+        # Clear existing handlers first
+        log.handlers.clear()
+
+        log.addHandler(file_handler)
+        log.addHandler(console_handler)
+
+        log.info(f"Logger initialized for array: {array_name}, writing to {log_path}")
+
+
+def load_logging_config() -> dict:
+    """Load the global logging configuration from config/logging.yaml.
+
+    Returns
+    -------
+    dict
+        Logging configuration dictionary
+
+    Raises
+    ------
+    FileNotFoundError
+        If logging.yaml is not found
+    yaml.YAMLError
+        If logging.yaml cannot be parsed
+
+    """
+    import yaml
+
+    config_path = Path(__file__).parent / "config" / "logging.yaml"
+
+    if not config_path.exists():
+        raise FileNotFoundError(f"Logging config not found: {config_path}")  # noqa: TRY003
+
+    with open(config_path, "r") as f:
+        config = yaml.safe_load(f)
+
+    return config.get("logging", {})
+
+
+def setup_stage_logging(mooring_name: str, stage_name: str, proc_dir: Path) -> Path:
+    """Set up logging for a processing stage using global configuration.
+
+    This creates simple file-based logging for processing stages (stage1, stage2, etc.)
+    using the configuration from config/logging.yaml.
+
+    Parameters
+    ----------
+    mooring_name : str
+        Name of the mooring (e.g., 'dsE_1_2018')
+    stage_name : str
+        Name of the processing stage (e.g., 'stage1', 'stage2', 'time_gridding')
+    proc_dir : Path
+        Processing directory for the mooring
+
+    Returns
+    -------
+    Path
+        Full path to the log file.  When the logging configuration file
+        (``config/logging.yaml``) is missing or unparseable, falls back to
+        ``{proc_dir}/processing_logs/{mooring_name}_{timestamp}_{stage_name}.mooring.log``.
+        This function does not raise; config failures are handled silently.
+
+    """
+    import yaml
+
+    try:
+        config = load_logging_config()
+    except (FileNotFoundError, yaml.YAMLError):
+        # Fallback: place logs in processing_logs/ subdir
+        log_time = datetime.datetime.now().strftime("%Y%m%dT%H")
+        log_dir = proc_dir / "processing_logs"
+        log_dir.mkdir(parents=True, exist_ok=True)
+        return log_dir / f"{mooring_name}_{log_time}_{stage_name}.mooring.log"
+
+    # Extract configuration values with defaults
+    log_directory = config.get("directory", "processing_logs")
+    filename_pattern = config.get(
+        "filename_pattern", "{mooring_name}_{timestamp}_{stage}.log"
+    )
+    timestamp_format = config.get("timestamp_format", "%Y%m%dT%H")
+    create_directory = config.get("create_directory", True)
+
+    # Generate timestamp
+    timestamp = datetime.datetime.now().strftime(timestamp_format)
+
+    # Determine log directory path
+    if Path(log_directory).is_absolute():
+        # Absolute path specified
+        log_dir = Path(log_directory)
+    else:
+        # Relative path - create within mooring proc directory
+        log_dir = proc_dir / log_directory
+
+    # Create directory if requested and it doesn't exist
+    if create_directory:
+        log_dir.mkdir(parents=True, exist_ok=True)
+
+    # Generate filename using pattern
+    filename = filename_pattern.format(
+        mooring_name=mooring_name, timestamp=timestamp, stage=stage_name
+    )
+
+    return log_dir / filename

oceanarray/logsheet/__init__.py

@@ -0,0 +1,60 @@
+"""oceanarray.logsheet
+====================
+Generate fieldwork logsheet PDFs from mooring YAML configuration files.
+
+Bundled defaults
+----------------
+``column_defs.yaml`` and LaTeX templates are bundled with the package.
+Users do **not** need to supply these.
+
+User-supplied config (``--config-dir``)
+----------------------------------------
+- ``cruise_config.yaml`` — cruise metadata, casts list, moorings to recover/deploy,
+  filename conventions, paths.
+- ``instruments.yaml`` — lab instrument registry (serial → model, firmware, owner).
+
+Optionally, place a ``column_defs.yaml`` or ``latex_templates/`` directory in
+``--config-dir`` to override the bundled defaults.
+
+Mooring YAMLs
+-------------
+Each builder looks up the mooring YAML via:
+
+1. ``cruise_config.yaml → mooring_yaml_map`` (explicit path mapping), then
+2. ``{proc_dir}/{mooring}/{mooring}.mooring.yaml`` (oceanarray convention).
+
+Example:
+-------
+::
+
+    from oceanarray.logsheet import build_recovery
+    from oceanarray.logsheet._config import resolve_config
+    from pathlib import Path
+
+    cfg = resolve_config(
+        config_dir=Path("/data/OdB2026/logsheets_config"),
+        output_dir=Path("/data/OdB2026/logsheets_output"),
+        proc_dir=Path("/data/OdB2026/proc"),
+    )
+    build_recovery("dsG3_1_2026", cfg, fmt="tex")
+
+"""
+
+from ._config import LogsheetsConfig, resolve_config
+from .builders import (
+    build_caldip_setup,
+    build_caldip_download,
+    build_recovery,
+    build_mooring_download,
+    build_deployment_setup,
+)
+
+__all__ = [
+    "LogsheetsConfig",
+    "resolve_config",
+    "build_caldip_setup",
+    "build_caldip_download",
+    "build_recovery",
+    "build_mooring_download",
+    "build_deployment_setup",
+]

oceanarray/logsheet/_columns.py

@@ -0,0 +1,97 @@
+"""oceanarray.logsheet._columns
+================================
+Column resolution from the ``column_library``, download-convention
+substitution, and data-path note formatting.
+"""
+
+from ._latex import tex_safe
+
+
+def resolve_columns(col_list: list, col_library: dict) -> list[dict]:
+    """Resolve a raw column list from ``column_defs.yaml`` into full column dicts.
+
+    Each item in *col_list* may be:
+
+    - **plain string** — a key in *col_library*, used as-is.
+    - **{key: {overrides}}** — library key with field overrides.
+    - **{header: …, width: …, input: …}** — inline full definition.
+
+    Parameters
+    ----------
+    col_list:
+        Raw list loaded directly from YAML.
+    col_library:
+        The ``column_library`` section from ``column_defs.yaml``.
+
+    """
+    result = []
+    for item in col_list:
+        if isinstance(item, str):
+            col = col_library.get(item, {}).copy()
+            if not col:
+                print(f"  Warning: column key '{item}' not in column_library")
+            result.append(col)
+        elif isinstance(item, dict):
+            if "header" in item:
+                result.append(item.copy())
+            else:
+                key = next(iter(item))
+                overrides = item[key] or {}
+                col = col_library.get(key, {}).copy()
+                if not col:
+                    print(f"  Warning: column key '{key}' not in column_library")
+                if overrides:
+                    col.update(overrides)
+                result.append(col)
+    return result
+
+
+def apply_download_convention(cols: list[dict], convention: str) -> list[dict]:
+    """Return a copy of *cols* with ``{download_convention}`` in headers replaced."""
+    result = []
+    for col in cols:
+        col = col.copy()
+        if "{download_convention}" in col.get("header", ""):
+            col["header"] = col["header"].replace("{download_convention}", convention)
+        result.append(col)
+    return result
+
+
+def format_data_path_note(
+    note_raw: str,
+    raw_data: str = "",
+    mooring: str = "",
+    caldip_data: str = "",
+    cast_label: str = "",
+    instrument: str = "",
+    download_convention: str = "",
+) -> list[str]:
+    """Substitute path placeholders in a ``data_path_note`` string.
+
+    ``{instrument}`` and ``{mooring}`` are rendered bold in the PDF.
+
+    Returns
+    -------
+    list[str]
+        One LaTeX-escaped string per non-blank line.
+
+    """
+    if not note_raw:
+        return []
+    s = note_raw.strip()
+    s = s.replace("{raw_data}", raw_data)
+    s = s.replace("{caldip_data}", caldip_data)
+    s = s.replace("{cast_label}", cast_label)
+    s = s.replace("{download_convention}", download_convention)
+
+    _B_MOORING = "\x00MOORING\x00"
+    _B_INSTRUMENT = "\x00INSTRUMENT\x00"
+    s = s.replace("{mooring}", _B_MOORING)
+    s = s.replace("{instrument}", _B_INSTRUMENT)
+
+    s = tex_safe(s)
+
+    s = s.replace(_B_MOORING, r"\textbf{" + tex_safe(mooring) + r"}")
+    s = s.replace(_B_INSTRUMENT, r"\textbf{" + tex_safe(instrument) + r"}")
+
+    return [ln for ln in s.split("\n") if ln.strip()]

oceanarray/logsheet/_config.py

@@ -0,0 +1,245 @@
+"""oceanarray.logsheet._config
+=============================
+Path resolution, YAML loading helpers, and instrument registry access.
+
+Two categories of config files:
+
+* **Bundled** (installed with the package, in ``data/``):
+  ``column_defs.yaml`` and ``latex_templates/``.
+
+* **User-supplied** (via ``--config-dir`` or ``LOGSHEETS_CONFIG_DIR`` env var):
+  ``logsheet_config.yaml`` and ``instrument_inventory.csv``.
+
+Mooring YAMLs are resolved from the oceanarray proc directory
+(``{proc_dir}/{mooring}/{mooring}.mooring.yaml``), with an optional
+``mooring_yaml_map`` override in ``logsheet_config.yaml``.
+"""
+
+from __future__ import annotations
+
+import csv
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+# ---------------------------------------------------------------------------
+# Bundled package data
+# ---------------------------------------------------------------------------
+
+_DATA = Path(__file__).parent / "data"
+DEFAULT_COLUMN_DEFS: Path = _DATA / "column_defs.yaml"
+DEFAULT_TEMPLATES_DIR: Path = _DATA / "latex_templates"
+
+
+# ---------------------------------------------------------------------------
+# Config container
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class LogsheetsConfig:
+    """Resolved paths for a logsheet generation run."""
+
+    cruise_config_path: Path
+    instruments_path: Path
+    column_defs_path: Path
+    templates_dir: Path
+    output_dir: Path
+    proc_dir: Optional[Path]
+
+
+def resolve_config(
+    config_dir: Optional[Path] = None,
+    inventory_path: Optional[Path] = None,
+    logsheet_config_path: Optional[Path] = None,
+    output_dir: Optional[Path] = None,
+    proc_dir: Optional[Path] = None,
+) -> LogsheetsConfig:
+    """Build a :class:`LogsheetsConfig` from user-supplied paths.
+
+    Parameters
+    ----------
+    config_dir:
+        Shorthand: directory containing ``logsheet_config.yaml`` and
+        ``instrument_inventory.csv``.  Ignored for any path supplied explicitly
+        via *inventory_path* or *logsheet_config_path*.  Falls back to the
+        ``LOGSHEETS_CONFIG_DIR`` env var, then the current working directory.
+    inventory_path:
+        Explicit path to ``instrument_inventory.csv``.
+        Takes precedence over ``config_dir / instrument_inventory.csv``.
+    logsheet_config_path:
+        Explicit path to ``logsheet_config.yaml``.  Takes precedence over
+        ``config_dir / logsheet_config.yaml``.  Optional; if the file does not
+        exist, path/filename fields are left blank on the sheet.
+    output_dir:
+        Where PDFs are written.  Defaults to ``./logsheets/``.
+    proc_dir:
+        Oceanarray proc directory (parent of per-mooring subdirs).  Used to
+        locate mooring YAMLs when not found via ``mooring_yaml_map``.
+
+    """
+    if config_dir is None and inventory_path is None and logsheet_config_path is None:
+        env = os.environ.get("LOGSHEETS_CONFIG_DIR")
+        config_dir = Path(env) if env else Path.cwd()
+
+    # Resolve cruise_config and instruments from explicit paths or config_dir
+    resolved_cruise = logsheet_config_path or (
+        (config_dir / "cruise_config.yaml")
+        if config_dir
+        else Path("cruise_config.yaml")
+    )
+    resolved_inventory = inventory_path or (
+        (config_dir / "instruments.yaml") if config_dir else Path("instruments.yaml")
+    )
+
+    # Allow user to override bundled column_defs.yaml by placing one in config_dir
+    user_col_defs = (config_dir / "column_defs.yaml") if config_dir else None
+    col_defs_path = (
+        user_col_defs
+        if (user_col_defs and user_col_defs.exists())
+        else DEFAULT_COLUMN_DEFS
+    )
+
+    # Similarly allow a custom templates/ dir alongside cruise_config
+    user_templates = (config_dir / "latex_templates") if config_dir else None
+    templates_dir = (
+        user_templates
+        if (user_templates and user_templates.is_dir())
+        else DEFAULT_TEMPLATES_DIR
+    )
+
+    return LogsheetsConfig(
+        cruise_config_path=resolved_cruise,
+        instruments_path=resolved_inventory,
+        column_defs_path=col_defs_path,
+        templates_dir=templates_dir,
+        output_dir=output_dir or Path("logsheets"),
+        proc_dir=proc_dir,
+    )
+
+
+# ---------------------------------------------------------------------------
+# YAML helpers
+# ---------------------------------------------------------------------------
+
+
+def load_yaml(path: Path) -> dict:
+    """Load and return a YAML file as a dict."""
+    with open(path) as fh:
+        return yaml.safe_load(fh)
+
+
+def _parse_csv_value(val: str) -> object:
+    """Convert a raw CSV string to a Python scalar.
+
+    * ``"true"`` / ``"false"`` (case-insensitive) → ``bool``
+    * Empty string → ``None``
+    * Anything else → left as ``str``
+
+    Integers and floats are intentionally left as strings so that firmware
+    version strings like ``"3.0h"`` or serial suffixes are never miscast.
+    """
+    stripped = val.strip()
+    lower = stripped.lower()
+    if lower == "true":
+        return True
+    if lower == "false":
+        return False
+    if lower == "":
+        return None
+    return stripped
+
+
+def load_instruments(cfg: LogsheetsConfig) -> dict:
+    """Return the instrument registry keyed by ``(type_str, serial_int)``.
+
+    Reads ``instrument_inventory.csv`` or legacy ``instruments.yaml``.
+    CSV files are detected by a ``.csv`` suffix; everything else is treated as
+    YAML.  Boolean-string fields (``"true"``/``"false"``) in CSV rows are
+    converted to Python ``bool`` so that checks like ``entry.get("odo")``
+    behave correctly.  Example key: ``("microcat", 7507)``.
+    """
+    path = cfg.instruments_path
+    lookup = {}
+    if path.suffix.lower() == ".csv":
+        with open(path, newline="") as fh:
+            for row in csv.DictReader(fh):
+                itype = row.get("type", "").strip()
+                serial_str = row.get("serial", "").strip()
+                if not itype or not serial_str:
+                    continue
+                try:
+                    sn = int(serial_str)
+                except ValueError:
+                    continue
+                entry = {
+                    k: _parse_csv_value(v)
+                    for k, v in row.items()
+                    if k not in ("type", "serial")
+                }
+                entry["serial"] = sn
+                lookup[(itype, sn)] = entry
+    else:
+        raw = load_yaml(path)
+        for itype, entries in raw.items():
+            for entry in entries:
+                sn = entry["serial"]
+                lookup[(itype, sn)] = entry
+    return lookup
+
+
+def sn_to_entry(instruments: dict, sn: int) -> tuple[str, dict]:
+    """Look up a serial number across all instrument types.
+
+    Parameters
+    ----------
+    instruments:
+        Registry returned by :func:`load_instruments`.
+    sn:
+        Serial number to look up.
+
+    Returns
+    -------
+    tuple[str, dict]
+        ``(instrument_type, entry_dict)``.
+
+    Raises
+    ------
+    KeyError
+        If the serial number is not found in any type.
+
+    """
+    for itype in ("microcat", "aquadopp", "tr1050", "rbrsolo", "rbrduet", "adcp"):
+        if (itype, sn) in instruments:
+            return itype, instruments[(itype, sn)]
+    raise KeyError(f"SN {sn} not found in instrument_inventory.csv")
+
+
+def resolve_mooring_yaml(
+    mooring: str, cfg: LogsheetsConfig, mooring_yaml_map: dict
+) -> Optional[Path]:
+    """Find the mooring YAML path, trying two strategies in order.
+
+    1. ``mooring_yaml_map`` in ``logsheet_config.yaml`` (relative paths are
+       resolved relative to ``logsheet_config.yaml``'s parent directory).
+    2. Oceanarray convention: ``{proc_dir}/{mooring}/{mooring}.mooring.yaml``.
+
+    Returns ``None`` if neither strategy finds a readable file.
+    """
+    if mooring in mooring_yaml_map:
+        rel = mooring_yaml_map[mooring]
+        p = Path(rel)
+        if not p.is_absolute():
+            p = cfg.cruise_config_path.parent / rel
+        if p.exists():
+            return p
+
+    if cfg.proc_dir is not None:
+        candidate = cfg.proc_dir / mooring / f"{mooring}.mooring.yaml"
+        if candidate.exists():
+            return candidate
+
+    return None

oceanarray/logsheet/_firmware.py

@@ -0,0 +1,43 @@
+"""oceanarray.logsheet._firmware
+================================
+MicroCAT firmware group detection and display labels.
+"""
+
+from packaging.version import Version
+
+#: Section-title strings used in generated logsheets.
+FW_GROUP_LABELS: dict[str, str] = {
+    "old_seaterm": r"MicroCAT --- Firmware $<$ 3.0d (Seaterm v1, 9600 baud)",
+    "seaterm_v2": r"MicroCAT --- Firmware $\geq$ 3.0d (SeatermV2, 38400 baud)",
+    "seaterm_v2_odo": r"MicroCAT --- Firmware $\geq$ 3.0d + ODO (SeatermV2, 38400 baud)",
+}
+
+
+def fw_group(entry: dict, sentinel_str: str = "3.0d") -> str:
+    """Determine the firmware group for a MicroCAT instrument entry.
+
+    Parameters
+    ----------
+    entry:
+        Instrument entry from ``instruments.yaml``.
+    sentinel_str:
+        Version string separating old_seaterm from seaterm_v2
+        (from ``cruise_config.yaml → microcat_firmware_sentinel``).
+
+    Returns
+    -------
+    str
+        One of ``"old_seaterm"``, ``"seaterm_v2"``, ``"seaterm_v2_odo"``.
+
+    """
+    if entry.get("odo"):
+        return "seaterm_v2_odo"
+    fw = entry.get("firmware")
+    if fw is None:
+        return "seaterm_v2"
+    try:
+        if Version(fw) < Version(sentinel_str):
+            return "old_seaterm"
+        return "seaterm_v2"
+    except Exception:  # noqa: BLE001
+        return "old_seaterm" if fw < sentinel_str else "seaterm_v2"