PyAETNA 4.0.0__py3-none-any.whl

PyAETNA/sampling/config/parser/multigp.py

@@ -0,0 +1,697 @@
+"""multigp.py — Multi-dimensional GP configuration parser for PyAETNA.
+
+This module provides :func:`parse_multi_gp`, which reads the
+``detrending.multi_GP`` subsection of the YAML configuration and builds the
+joint multi-channel GP blocks consumed by the sampling engine.
+
+How this differs from :func:`PyAETNA.sampling.config.parser.gp.parse_gp`
+-----------------------------------------------------------------------
+``parse_gp`` returns a dict keyed by **instrument id**: each instrument gets
+its own independent GP and its own likelihood factor.  A multi-GP block is
+keyed by **block name** instead, because one block deliberately spans several
+observables (and possibly several instruments) under a single joint
+covariance.  That is the whole point of the Rajpaul/Barragán construction and
+is the one thing the per-instrument structure cannot express.
+
+Channel semantics
+-----------------
+``Y`` is a reserved channel name meaning *the observable already being fitted*
+for these instruments: its residual is ``y - mean_function`` (Keplerians,
+systemic velocity, polynomials, Fourier, EIV — all unchanged) and its variance
+is the existing ``dy_total**2``.  Nothing is duplicated; the multi-GP replaces
+only the likelihood term, never the mean model.
+
+Any other channel name is a column of the detrending basis (``plData.dBasis``),
+paired with its ``<NAME>_ERR`` uncertainty column following the convention
+already established by the EIV block.  Such channels carry their own constant
+``offset``, an optional ``log_jitter`` and an optional polynomial trend
+(``c1``, ``c2``, …, centred on the midpoint of each coefficient's scope domain
+over the channel's usable rows).  They receive no Keplerian and no other
+detrending by construction.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import Any
+
+import numpy as np
+
+from ....kernels.multichannel import (
+    MULTIGP_SUPPORTED_KERNELS,
+    get_multigp_param_order,
+)
+from ...centering import TREND_KEY_RE, group_centers, usable_channel_rows
+from .prior_refs import is_resolved_prior_reference, resolve_config_value
+from .scoping import _SCOPE_KEYWORDS, _parse_scoped_param
+
+# The channel name meaning "the observable already being fitted".
+RESERVED_CHANNEL = "Y"
+
+# Per-channel configuration keys, split by how they enter the likelihood.
+#
+# ``A``/``B`` multiply the latent process inside the kernel, indexed by
+# channel, so giving them a per-instrument or per-visit value would need one
+# kernel channel per (channel, group) pair -- the joint covariance itself
+# changes shape.  They stay global.
+#
+# ``offset``/``log_jitter`` never touch the kernel: the first is a constant
+# subtracted from the channel's residual vector, the second is added to the
+# covariance *diagonal*.  Both are per-point quantities, so varying them by
+# instrument or visit is a gather over rows and nothing more.
+#
+# Trend coefficients ``c1``, ``c2``, … (matched by ``TREND_KEY_RE``) are
+# pointwise like ``offset``: together they form the channel mean
+# ``offset + sum_k c_k * (x - x_c)**k`` subtracted from the residual, and never
+# enter the kernel, so they accept the same scopes.
+_KERNEL_CHANNEL_PARAMS = ("A", "B")
+_POINTWISE_CHANNEL_PARAMS = ("offset", "log_jitter")
+_CHANNEL_PARAMS = _KERNEL_CHANNEL_PARAMS + _POINTWISE_CHANNEL_PARAMS
+
+# Total joint-matrix size beyond which a dense Cholesky becomes uncomfortable.
+# The joint matrix is N_total x N_total with N_total summed over ALL channels,
+# so these are reached faster than for a single-instrument GP.
+_SIZE_WARN = 2000
+_SIZE_ERROR = 6000
+
+
+def _normalise_scoped(value: Any) -> Any:
+    """Prepend the implicit ``global`` scope to a bare distribution list."""
+    if isinstance(value, list) and len(value) > 0:
+        first = value[0]
+        if not isinstance(first, str) or first.lower() not in _SCOPE_KEYWORDS:
+            return ["global", *value]
+    return value
+
+
+def _refuse_grouped_kernel_param(
+    value: Any,
+    label: str,
+    block_name: str,
+    channel: str,
+    pname: str,
+    instruments: Sequence[str],
+) -> None:
+    """Reject a grouped scope on ``A``/``B`` with a message that says what to do.
+
+    ``A`` and ``B`` are the linear map from the latent process to the channel,
+    so they sit inside every cross-covariance block of the joint matrix. A
+    per-group value would mean the channel is no longer one channel and the
+    matrix would have to be rebuilt with it split -- which is exactly what one
+    ``multi_GP`` block per group already does, with its own latent process.
+    """
+    if not isinstance(value, list) or not value:
+        return
+    scope = value[0]
+    if not isinstance(scope, str) or scope.lower() == "global":
+        return
+
+    first = instruments[0] if instruments else "INST_A"
+    second = instruments[1] if len(instruments) > 1 else "INST_B"
+    raise ValueError(
+        f"Parameter '{label}.channels.{channel}.{pname}': scope '{scope}' is not "
+        f"allowed. 'A' and 'B' are part of the covariance itself, so they cannot "
+        f"vary within one multi_GP block -- a channel with two projections is "
+        f"two channels.\n"
+        f"  If the projection genuinely differs between groups (e.g. two "
+        f"spectrographs with different {channel} calibrations), split the block "
+        f"instead, giving each group its own latent process:\n"
+        f"      multi_GP:\n"
+        f"        {block_name}_{str(first).lower()}:\n"
+        f"          instruments: [{first}]\n"
+        f"          ...\n"
+        f"        {block_name}_{str(second).lower()}:\n"
+        f"          instruments: [{second}]\n"
+        f"          ...\n"
+        f"  If instead only the zero point or the excess scatter differs, scope "
+        f"'offset' or 'log_jitter' -- those accept per_instrument and per_visit."
+    )
+
+
+def _validate_channel_keys(
+    label: str,
+    channel: str,
+    ch_cfg: dict[str, Any],
+    log: Callable[[str], None],
+) -> None:
+    """Reject channel keys the parser would otherwise silently ignore."""
+    allowed = ", ".join((*_CHANNEL_PARAMS, "c1", "c2", "..."))
+    for key in ch_cfg:
+        skey = str(key)
+        if skey in _CHANNEL_PARAMS or TREND_KEY_RE.match(skey):
+            continue
+        if skey == "c0":
+            msg = (
+                f"{label}: channel '{channel}' sets 'c0'. The constant term of a "
+                f"channel trend is its 'offset'; start trends from c1."
+            )
+        else:
+            msg = (
+                f"{label}: channel '{channel}' has unknown key '{skey}'. "
+                f"Allowed keys: {allowed}."
+            )
+        log(f"ERROR: {msg}")
+        raise ValueError(msg)
+
+
+def _prior_lower_bound(prior_spec: Any) -> float | None:
+    """Best-effort lower bound of a prior spec, or ``None`` if not determinable."""
+    if isinstance(prior_spec, (int, float)):
+        return float(prior_spec)
+    if isinstance(prior_spec, (list, tuple)) and len(prior_spec) >= 2:
+        dist = str(prior_spec[0]).lower()
+        try:
+            if dist in ("uniform", "truncnorm"):
+                return float(prior_spec[1])
+        except (TypeError, ValueError):
+            return None
+    return None
+
+
+def parse_multi_gp(
+    detrending: dict[str, Any],
+    plModel: Any,
+    plData: Any,
+    inst_names: list[str],
+    inst_name_to_id: dict[str, int],
+    free_params: dict[str, Any],
+    fixed_params: dict[str, Any],
+    param_scopes: dict[str, Any],
+    named_priors: dict[str, Any] | None = None,
+    log_func: Callable[..., None] | None = None,
+) -> dict[str, Any]:
+    """Parse ``detrending.multi_GP`` into joint multi-channel GP blocks.
+
+    Args:
+        detrending: The ``detrending`` config section.
+        plModel: PlModel object.
+        plData: PlData object (used to validate channel columns against
+            ``dBasis``).
+        inst_names: All instrument names, in config order.
+        inst_name_to_id: Map from instrument name to internal instrument id.
+        free_params: Mutated in place with sampled parameters.
+        fixed_params: Mutated in place with fixed parameters.
+        param_scopes: Mutated in place with each block's scope summary.
+        named_priors: Top-level ``priors:`` registry for ``@name`` references.
+        log_func: Logging callable, called as ``log_func(plModel, msg)``.
+
+    Returns:
+        Dict keyed by block name.  Each value holds ``kernel_type``,
+        ``x_variable``, ``instruments`` (ids), ``instrument_names``,
+        ``channels`` (ordered list of names), ``channel_index``,
+        ``latent_params`` (name lookup per hyperparameter), ``blocking`` and
+        the per-channel parameter name lookups.
+
+    Raises:
+        ValueError: On any invalid configuration; every gate explains what to
+            change.
+    """
+
+    def _log(msg: str) -> None:
+        if log_func is not None:
+            log_func(plModel, msg)
+
+    section = detrending.get("multi_GP") or {}
+    if not section:
+        return {}
+
+    configs: dict[str, Any] = {}
+    d_basis = getattr(plData, "dBasis", {}) or {}
+
+    _log("Multi-GP configuration:")
+
+    for block_name in sorted(section.keys()):
+        cfg = section[block_name]
+        if not isinstance(cfg, dict):
+            continue
+        label = f"multi_GP '{block_name}'"
+
+        # ---- kernel ---------------------------------------------------
+        kernel_type = cfg.get("kernel")
+        if kernel_type is None:
+            raise ValueError(f"{label}: 'kernel' is mandatory.")
+        supported_lower = {k.lower(): k for k in MULTIGP_SUPPORTED_KERNELS}
+        if str(kernel_type).lower() not in supported_lower:
+            msg = (
+                f"{label}: kernel '{kernel_type}' cannot be used as a multi-GP "
+                f"latent kernel. The latent process must be twice differentiable "
+                f"so that its derivative Gdot exists. Supported: "
+                f"{', '.join(MULTIGP_SUPPORTED_KERNELS)}."
+            )
+            _log(f"ERROR: {msg}")
+            raise ValueError(msg)
+        kernel_type = supported_lower[str(kernel_type).lower()]
+
+        # ---- unit-variance latent process -----------------------------
+        if "log_gp_sigma" in cfg:
+            _log(
+                f"  WARNING: {label} specifies 'log_gp_sigma'; it is ignored and "
+                f"forced to 0 (unit variance). The latent amplitude is carried "
+                f"entirely by the per-channel A/B coefficients — a free sigma "
+                f"would make (G, A, B) and (kG, A/k, B/k) indistinguishable."
+            )
+
+        # ---- x_variable -----------------------------------------------
+        x_variable = cfg.get("x_variable", "TIME")
+        if x_variable != "TIME" and x_variable not in d_basis:
+            msg = (
+                f"{label}: x_variable '{x_variable}' is not a column in the data "
+                f"file. Available extra columns: {sorted(d_basis)}."
+            )
+            _log(f"ERROR: {msg}")
+            raise ValueError(msg)
+        if x_variable != "TIME":
+            _log(
+                f"  WARNING: {label} sets x_variable='{x_variable}' instead of "
+                f"'TIME'. The Ġ term is the time-derivative of the latent process, "
+                f"so the multi-GP construction is only physically meaningful when "
+                f"the GP runs against time. Using a non-time axis (e.g. an orbital "
+                f"phase or another basis column) makes B_c's interpretation "
+                f"(a rate, in 1/time) undefined, and the derivative kernel blocks "
+                f"were derived and tested against time only. This is untested and "
+                f"not recommended; proceed only if you understand what Ġ means "
+                f"against your chosen axis."
+            )
+
+        # ---- instruments ----------------------------------------------
+        instruments = cfg.get("instruments")
+        if instruments is None:
+            msg = (
+                f"{label}: 'instruments' is mandatory. Specify which instruments "
+                f"supply the epochs, e.g.:\n  instruments: [{inst_names[0] if inst_names else 'HARPS'}]"
+            )
+            _log(f"ERROR: {msg}")
+            raise ValueError(msg)
+        if isinstance(instruments, str):
+            instruments = [instruments]
+        for name in instruments:
+            if name not in inst_name_to_id:
+                msg = (
+                    f"{label}: unknown instrument '{name}' in 'instruments'. "
+                    f"Available: {inst_names}."
+                )
+                _log(f"ERROR: {msg}")
+                raise ValueError(msg)
+        inst_ids = [inst_name_to_id[n] for n in instruments]
+        n_block_insts = len(instruments)
+
+        # Visits covered by this block, needed when a channel asks for
+        # per_visit scope on its offset or jitter.
+        block_visits: list[Any] = []
+        try:
+            _inst_arr = np.asarray(plData.instrument)
+            _visit_arr = np.asarray(plData.visit)
+            _blk_ids = [inst_name_to_id[n] for n in instruments]
+            block_visits = sorted(
+                {
+                    v.item() if hasattr(v, "item") else v
+                    for v in np.unique(_visit_arr[np.isin(_inst_arr, _blk_ids)])
+                }
+            )
+        except Exception:
+            block_visits = []
+
+        # True once any channel parameter is resolved to a grouped scope, so
+        # the block's scope summary reflects reality.
+        any_grouped = False
+
+        # ---- channels --------------------------------------------------
+        channels_cfg = cfg.get("channels")
+        if not isinstance(channels_cfg, dict) or not channels_cfg:
+            msg = (
+                f"{label}: a 'channels' mapping is mandatory, with at least two "
+                f"entries. Use the reserved name '{RESERVED_CHANNEL}' for the "
+                f"fitted observable, and a data column name for each indicator."
+            )
+            _log(f"ERROR: {msg}")
+            raise ValueError(msg)
+
+        # Reserved channel first, then the rest in config order: the first
+        # channel is the reference whose A sign fixes the latent sign.
+        channel_names = list(channels_cfg.keys())
+        if RESERVED_CHANNEL in channel_names:
+            channel_names.remove(RESERVED_CHANNEL)
+            channel_names.insert(0, RESERVED_CHANNEL)
+
+        if len(channel_names) < 2:
+            msg = (
+                f"{label}: a multi-GP needs at least two channels — with one it "
+                f"is just an ordinary GP, so use 'detrending.GP' instead."
+            )
+            _log(f"ERROR: {msg}")
+            raise ValueError(msg)
+
+        for channel in channel_names:
+            if channel == RESERVED_CHANNEL:
+                continue
+            if channel not in d_basis:
+                msg = (
+                    f"{label}: channel '{channel}' is not a column in the data "
+                    f"file. Available extra columns: {sorted(d_basis)}."
+                )
+                _log(f"ERROR: {msg}")
+                raise ValueError(msg)
+            err_col = f"{channel}_ERR"
+            if err_col not in d_basis:
+                msg = (
+                    f"{label}: channel '{channel}' has no uncertainty column "
+                    f"'{err_col}'. Every multi-GP channel needs one, following "
+                    f"the same convention as detrending.eiv_linear."
+                )
+                _log(f"ERROR: {msg}")
+                raise ValueError(msg)
+
+        # ---- blocking ---------------------------------------------------
+        blocking = cfg.get("blocking", "none")
+        if isinstance(blocking, str) and blocking.lower() in ("none", "false"):
+            blocking = None
+        elif blocking is True or blocking == "per_visit":
+            blocking = "per_visit"
+        elif isinstance(blocking, dict) and "gap" in blocking:
+            blocking = {"gap": float(blocking["gap"])}
+        elif blocking is not None:
+            msg = (
+                f"{label}: 'blocking' must be 'none', 'per_visit', or "
+                f"{{gap: <days>}}. Got: {blocking!r}."
+            )
+            _log(f"ERROR: {msg}")
+            raise ValueError(msg)
+
+        if blocking is not None and kernel_type == "ExpSineSquared":
+            msg = (
+                f"{label}: 'blocking' cannot be used with an ExpSineSquared "
+                f"latent kernel. Its covariance never decays — gamma(nP) == 1 "
+                f"for any integer n — so dropping the between-block covariance "
+                f"is mathematically wrong, not merely approximate."
+            )
+            _log(f"ERROR: {msg}")
+            raise ValueError(msg)
+
+        # ---- per-channel parameter validation (fail fast, before assembly) --
+        for channel in channel_names:
+            ch_cfg = channels_cfg[channel] or {}
+            if not isinstance(ch_cfg, dict):
+                msg = f"{label}: channel '{channel}' must be a mapping of parameters."
+                _log(f"ERROR: {msg}")
+                raise ValueError(msg)
+
+            for required in ("A", "B"):
+                if required not in ch_cfg:
+                    msg = (
+                        f"{label}: channel '{channel}' is missing '{required}'. "
+                        f"Both projection coefficients are required; set "
+                        f"'B: 0.0' for an amplitude-only channel (Rajpaul's L_c)."
+                    )
+                    _log(f"ERROR: {msg}")
+                    raise ValueError(msg)
+
+            _validate_channel_keys(label, channel, ch_cfg, _log)
+
+            # 'Y' already has its offset (systemic velocity / normalization) and
+            # its jitter from the main model; duplicating them here would create
+            # an exactly degenerate pair of parameters.
+            if channel == RESERVED_CHANNEL:
+                for forbidden in ("offset", "log_jitter"):
+                    if forbidden in ch_cfg:
+                        msg = (
+                            f"{label}: channel '{RESERVED_CHANNEL}' must not set "
+                            f"'{forbidden}'. The fitted observable already takes "
+                            f"its offset from detrending.normalization and its "
+                            f"jitter from log_jitter; a second copy would be "
+                            f"exactly degenerate with the first."
+                        )
+                        _log(f"ERROR: {msg}")
+                        raise ValueError(msg)
+                trend_keys = [k for k in ch_cfg if TREND_KEY_RE.match(str(k))]
+                if trend_keys:
+                    msg = (
+                        f"{label}: channel '{RESERVED_CHANNEL}' must not set trend "
+                        f"coefficients ({', '.join(trend_keys)}). Trends of the "
+                        f"fitted observable belong in detrending.polynomials; a "
+                        f"second copy here would be exactly degenerate with it."
+                    )
+                    _log(f"ERROR: {msg}")
+                    raise ValueError(msg)
+
+        # ---- per-channel parameter parsing -----------------------------------
+        # The insertion order here is the free-parameter order everywhere
+        # downstream (log file, corner plot, MCMC summary table): grouped by
+        # *kind of parameter* across channels, not by channel. For a block
+        # with several channels this reads far better than interleaving four
+        # different kinds of parameter once per channel:
+        #   jitter (one per non-reference channel) -> offset (one per
+        #   non-reference channel) -> trend coefficients (per non-reference
+        #   channel, degrees ascending) -> GP hyperparameters -> A, B (one
+        #   pair per channel, reference channel included).
+        channel_param_names: dict[str, dict[str, Any]] = {
+            channel: {} for channel in channel_names
+        }
+
+        def _parse_channel_param(channel: str, pname: str) -> None:
+            nonlocal any_grouped
+            ch_cfg = channels_cfg[channel] or {}
+            if pname not in ch_cfg:
+                return
+            raw = resolve_config_value(
+                ch_cfg[pname],
+                named_priors,
+                f"detrending.multi_GP.{block_name}.channels.{channel}.{pname}",
+            )
+            tied = raw.canonical_name if is_resolved_prior_reference(raw) else None
+            is_kernel_param = pname in _KERNEL_CHANNEL_PARAMS
+            allowed = (
+                {"global"}
+                if is_kernel_param
+                else {"global", "per_instrument", "per_visit"}
+            )
+            normalised = _normalise_scoped(raw)
+            if is_kernel_param:
+                _refuse_grouped_kernel_param(
+                    normalised, label, block_name, channel, pname, instruments
+                )
+            scope, entries = _parse_scoped_param(
+                normalised,
+                allowed,
+                n_block_insts,
+                f"{label}.channels.{channel}.{pname}",
+            )
+
+            if scope == "global":
+                spec = entries[0]
+                full = tied or f"{pname}_{block_name}_{channel}"
+                if isinstance(spec, (int, float)):
+                    fixed_params[full] = spec
+                elif spec is not None:
+                    free_params.setdefault(full, spec)
+                channel_param_names[channel][pname] = {
+                    "scope": "global",
+                    "names": [full],
+                    "groups": [None],
+                }
+            elif is_kernel_param:
+                # Unreachable via _parse_scoped_param (which only allows
+                # 'global' for these), but kept explicit so the reason
+                # survives if the allowed set is ever widened by mistake.
+                msg = (
+                    f"{label}: '{scope}' scope is not supported for "
+                    f"'{channel}.{pname}'. A/B set how the latent process "
+                    f"projects into the channel, so varying them by group "
+                    f"would need one kernel channel per (channel, group) "
+                    f"pair. Use 'global', or define one multi_GP block per "
+                    f"instrument. Note that 'offset' and 'log_jitter' DO "
+                    f"accept per_instrument and per_visit scope."
+                )
+                _log(f"ERROR: {msg}")
+                raise ValueError(msg)
+            elif scope == "per_instrument":
+                per_names, groups = [], []
+                for i, iname in enumerate(instruments):
+                    spec = entries[i]
+                    full = f"{pname}_{block_name}_{channel}_{iname}"
+                    if isinstance(spec, (int, float)):
+                        fixed_params[full] = spec
+                    elif spec is not None:
+                        free_params[full] = spec
+                    per_names.append(full)
+                    groups.append(inst_name_to_id[iname])
+                channel_param_names[channel][pname] = {
+                    "scope": "per_instrument",
+                    "names": per_names,
+                    "groups": groups,
+                }
+                any_grouped = True
+            else:  # per_visit
+                if not block_visits:
+                    msg = (
+                        f"{label}: 'per_visit' scope requested for "
+                        f"'{channel}.{pname}', but no VISIT information is "
+                        f"available for this block's instruments."
+                    )
+                    _log(f"ERROR: {msg}")
+                    raise ValueError(msg)
+                spec = entries[0]  # one prior, shared by every visit
+                per_names, groups = [], []
+                for v in block_visits:
+                    full = f"{pname}_{block_name}_{channel}_v{v}"
+                    if isinstance(spec, (int, float)):
+                        fixed_params[full] = spec
+                    elif spec is not None:
+                        free_params[full] = spec
+                    per_names.append(full)
+                    groups.append(v)
+                channel_param_names[channel][pname] = {
+                    "scope": "per_visit",
+                    "names": per_names,
+                    "groups": groups,
+                }
+                any_grouped = True
+
+            # Sign degeneracy: (G, A, B) -> (-G, -A, -B) is unobservable and
+            # produces a bimodal posterior that reads as a convergence
+            # failure.  Pinning the reference channel's A to be
+            # non-negative removes the mirror mode.
+            if (
+                pname == "A"
+                and channel == channel_names[0]
+                and scope == "global"
+                and not isinstance(entries[0], (int, float))
+            ):
+                low = _prior_lower_bound(entries[0])
+                if low is None or low < 0.0:
+                    _log(
+                        f"  WARNING: {label} reference channel "
+                        f"'{channel}': the prior on A is not bounded below "
+                        f"at 0. The latent sign is then unidentifiable "
+                        f"((G, A, B) and (-G, -A, -B) fit equally well) and "
+                        f"the posterior will be bimodal, which looks like a "
+                        f"convergence failure. Use e.g. A: [uniform, 0, ...]."
+                    )
+
+        # 1) jitter, one per non-reference channel, in channel order
+        for channel in channel_names:
+            if channel != RESERVED_CHANNEL:
+                _parse_channel_param(channel, "log_jitter")
+
+        # 2) offset, one per non-reference channel, in channel order
+        for channel in channel_names:
+            if channel != RESERVED_CHANNEL:
+                _parse_channel_param(channel, "offset")
+
+        # 3) trend coefficients, per non-reference channel, degrees ascending.
+        # Each gets one centre per scope group, computed here from the real
+        # data over the channel's usable rows, and never recomputed later.
+        for channel in channel_names:
+            if channel == RESERVED_CHANNEL:
+                continue
+            trend_keys = sorted(
+                (k for k in (channels_cfg[channel] or {}) if TREND_KEY_RE.match(k)),
+                key=lambda k: int(k[1:]),
+            )
+            if not trend_keys:
+                continue
+            ch_rows = usable_channel_rows(
+                np.where(np.isin(np.asarray(plData.instrument), inst_ids))[0],
+                d_basis[channel],
+                d_basis[f"{channel}_ERR"],
+            )
+            x_all = np.asarray(
+                plData.time if x_variable == "TIME" else d_basis[x_variable],
+                dtype=float,
+            )
+            for key in trend_keys:
+                _parse_channel_param(channel, key)
+                entry = channel_param_names[channel][key]
+                entry["degree"] = int(key[1:])
+                entry["centers"] = group_centers(
+                    x_all,
+                    ch_rows,
+                    entry["scope"],
+                    entry["groups"],
+                    np.asarray(plData.instrument),
+                    np.asarray(plData.visit),
+                )
+                empty = [
+                    g for g, c in zip(entry["groups"], entry["centers"]) if np.isnan(c)
+                ]
+                if empty:
+                    _log(
+                        f"  WARNING: {label} channel '{channel}' {key}: groups "
+                        f"{empty} have no usable '{channel}' rows; their "
+                        f"coefficients are constrained by the prior only."
+                    )
+
+        # 4) GP latent hyperparameters
+        latent_param_names: dict[str, str] = {}
+        param_order = get_multigp_param_order(kernel_type)
+        for pname in param_order:
+            if pname not in cfg:
+                msg = (
+                    f"{label}: kernel '{kernel_type}' requires '{pname}', which "
+                    f"is missing. Required: {param_order}."
+                )
+                _log(f"ERROR: {msg}")
+                raise ValueError(msg)
+            raw = resolve_config_value(
+                cfg[pname], named_priors, f"detrending.multi_GP.{block_name}.{pname}"
+            )
+            tied = raw.canonical_name if is_resolved_prior_reference(raw) else None
+            _scope, entries = _parse_scoped_param(
+                _normalise_scoped(raw), {"global"}, 1, f"{label}.{pname}"
+            )
+            spec = entries[0]
+            full_name = tied or f"{pname}_{block_name}"
+            if isinstance(spec, (int, float)):
+                fixed_params[full_name] = spec
+            elif spec is not None:
+                free_params.setdefault(full_name, spec)
+            latent_param_names[pname] = full_name
+
+        # 5) A, B per channel (reference channel included), in channel order
+        for channel in channel_names:
+            _parse_channel_param(channel, "A")
+            _parse_channel_param(channel, "B")
+
+        configs[block_name] = {
+            "name": block_name,
+            "kernel_type": kernel_type,
+            "x_variable": x_variable,
+            "instruments": inst_ids,
+            "instrument_names": list(instruments),
+            "channels": channel_names,
+            "channel_index": {c: i for i, c in enumerate(channel_names)},
+            "latent_params": latent_param_names,
+            "channel_params": channel_param_names,
+            "blocking": blocking,
+        }
+        param_scopes[block_name] = "per_group" if any_grouped else "global"
+
+        # ---- logging ------------------------------------------------------
+        # Kept deliberately short: one line of setup, one of channels.  Anything
+        # a user needs to *decide* something (warnings, errors) is logged above;
+        # this is only the "what was configured" record.
+        described = []
+        for channel in channel_names:
+            suffix = ""
+            b_spec = (channels_cfg[channel] or {}).get("B")
+            if isinstance(b_spec, (int, float)) and float(b_spec) == 0.0:
+                suffix = ", B=0"
+            if channel == RESERVED_CHANNEL:
+                described.append(f"{channel} (fitted observable{suffix})")
+            else:
+                described.append(f"{channel}{suffix}")
+        _log(
+            f"  {block_name}: kernel={kernel_type}, x={x_variable}, "
+            f"instruments={list(instruments)}, "
+            f"blocking={blocking if blocking is not None else 'none'}"
+        )
+        _log(f"    channels (reference first): {', '.join(described)}")
+        for channel in channel_names:
+            for key, entry in channel_param_names[channel].items():
+                if "centers" not in entry:
+                    continue
+                where = ", ".join(
+                    f"{x_variable}={c:.6g}" for c in entry["centers"] if np.isfinite(c)
+                )
+                _log(f"    {channel}: {key} ({entry['scope']}) about {where}")
+
+    return configs