@pikaa-ai/pikaa 0.3.1 → 0.3.4

package/skills/relsa-severity-assessment/references/relsa-method.md

@@ -1,175 +0,0 @@
-# The RELSA score: algorithm, decisions, and parity with the R package
-
-RELSA (RELative Severity Assessment) turns several welfare outcome measures into one
-interpretable number per animal per time point. It was introduced in Talbot et al. (2022),
-*Front. Vet. Sci.* 9:937711, and implemented in the R package
-[`mytalbot/RELSA`](https://github.com/mytalbot/RELSA) (GPL-3). `scripts/relsa_score.py` is a
-Python port of that implementation.
-
-## The four steps
-
-### 1. Directionality
-
-Every variable must be declared as falling or rising under worsening welfare. The default
-assumption is that a *decrease* means a worse outcome (body weight, activity, burrowing,
-wheel running, food intake). Variables that *increase* are **turned**: clinical scores,
-inflammatory biomarkers, fever, tachycardia.
-
-Directionality is model-specific and getting it wrong silently zeroes a variable's
-contribution, because deviations in the "wrong" direction are floored at 0. Body temperature
-is the classic trap: it falls in CLP sepsis and endotoxaemia (hypothermia predicts death) and
-rises in fever models.
-
-`build_reference()` warns when a variable's *only* observed deviation runs against its declared
-direction, and rejects one that never deviates at all. It cannot do better than that: in the
-published sepsis data activity swings 530% above baseline and 100% below, so "which direction
-is worse" is not recoverable from the data and has to come from the biology of the model.
-
-### 2. Normalization to the individual baseline
-
-Each variable is divided by that animal's own baseline value and expressed as a percentage,
-so every trajectory starts at 100%:
-
-```
-x_norm(t) = 100 * x(t) / x(baseline)
-```
-
-Using each animal's own baseline is what makes RELSA robust to between-animal variation in
-absolute values. The baseline may be one time point (the RELSA convention codes it as
-`day = -1`) or the mean of a baseline window — pass several times to `--baseline-time`.
-
-Two variable types must **not** be normalized again:
-
-- Variables already expressed as percent change from baseline, such as body weight change
-  (`bwc [%]`) in the published datasets.
-- Ordinal severity scores whose healthy baseline is 0. `0/0` is undefined, so ratio
-  normalization cannot represent them at all. Use `score_to_percent()` /
-  `--score-scale COL=MAX`, which maps the score's *scale* instead of its ratio: the healthy
-  score becomes 100, the worst possible score becomes 200, and one score point is worth
-  `100 / (max - baseline)` percent. The variable is then a turned variable like any other.
-
-  This mapping is this skill's convention, not something the paper specifies. It is a
-  choice about how much a score point is worth relative to a percent of body weight, and it
-  should be stated in the methods. The defensible alternative is to keep the score out of
-  RELSA entirely and use it as an independent endpoint criterion, which is what the DSS
-  blood-sampling model in the paper does (its clinical score of 5 is an endpoint trigger,
-  while RELSA is computed from `bwc` and wheel running).
-
-### 3. The reference set
-
-The reference set is the cohort assumed to carry the greatest burden in the model, and it
-fixes the meaning of the scale. For each variable, RELSA records the most extreme normalized
-value reached anywhere in that cohort:
-
-```
-maxsev_i  = min over reference set (or max, for turned variables)
-maxdelta_i = |100 - maxsev_i|
-```
-
-The paper uses "the animal in the treatment group suspected to experience the greatest burden
-under the respective model" — e.g. the highest DSS dose with phlebotomy in the DSS blood
-sampling dataset.
-
-This is the single most consequential choice in the whole procedure. RELSA is *relative*:
-change the reference set and every score changes. A reference cohort that is too mild pushes
-scores above 1; one that is too severe compresses everything toward 0. A score is
-meaningless without the reference set it came from, which is why `ReferenceModel` carries a
-`label` and `--save-reference` writes it to JSON for reuse on later cohorts.
-
-A variable that never deviates in the reference set has `maxdelta = 0`, would divide by zero,
-and is rejected with an error rather than silently dropped.
-
-### 4. Weights and the score
-
-```
-delta_i(t) = 100 - x_norm,i(t)        (turned: x_norm,i(t) - 100), floored at 0
-RW_i(t)    = delta_i(t) / maxdelta_i
-RELSA(t)   = sqrt( (1/n) * sum_i RW_i(t)^2 )     over the n variables measured at t
-```
-
-The root-mean-square, rather than the arithmetic mean, is deliberate: severity is signalled
-by *extremes*, so squaring gives a large deviation in one variable more influence than the
-mean would. A single variable at the reference maximum with three others at baseline gives
-RELSA = 0.5, not 0.25.
-
-Missing values are dropped from the mean, never imputed and never treated as 0 — treating a
-missing measurement as "no deviation" would bias every score downward. This is why a score
-is defined whenever at least one variable was measured.
-
-**Interpretation.** RELSA = 0 is baseline; 0.73 means the animal reached 73% of the reference
-set's maximum deviation; above 1 means it exceeded the reference set. The score is
-dimensionless and comparable *within* a reference frame, not across reference sets or models.
-
-## A trap the published data demonstrates
-
-Because the score averages over whichever variables were measured, **a variable that appears
-or disappears mid-trajectory moves the score by itself.** In the published sepsis dataset,
-body weight is recorded only on the day of euthanasia. Include `bwc` in that model and mouse
-ID_801's endpoint score falls from 0.93 to 0.83 — not because the animal improved, but
-because a variable with a low weight (0.16) joined the mean at exactly that time point. The
-paper's sepsis model uses only the four telemetry parameters, which are present throughout.
-
-Score the variables measured throughout the trajectory; keep the intermittent ones as
-separate endpoint criteria. `relsa_scores()` warns when the composition changes.
-
-## Parity with the R package
-
-`relsa_score.py` reproduces the R package's own published worked example — the `surgery`
-dataset, animal `Ca_001`, variables `bwc, burON, hr, hrv, temp, act`, turned `hr, temp` — to
-the two decimals the package prints: every normalized value, every weight, and the RELSA
-scores 0.00, 0.73, 0.55, 0.44, 0.44, 0.41 for days -1 to 4, including the `NA` weight where
-`burON` is missing. The test suite pins this.
-
-Details worth knowing if you compare against R directly:
-
-- **Rounding is part of the algorithm.** R rounds the deltas and the weights to two decimals
-  *before* the root-mean-square, so the port does too. `round_digits=None` /
-  `--full-precision` skips it, which changes scores in the third decimal — and, because KDE
-  minima are sensitive to the granularity of the score distribution, can change the number of
-  thresholds found. Keep the default when reproducing published work.
-- **`relsa()`'s `wf` column is not the score.** The R function returns both a mean weight
-  factor (`wf`) and the root-mean-square (`rms`); the RELSA score is `rms`. In the released
-  package `wf` divides the weight sum by the count of *missing* variables rather than the
-  count of present ones (the vignette has the intended form), and because `wf` is used to
-  mask `rms`, a complete row sitting exactly at baseline is returned as `NA` instead of 0 by
-  that code path. The rendered vignette prints 0.00 for the baseline day, so the port
-  returns 0.0, matching the published output and the formula.
-- Column order does not matter here. The R functions address `set[, 4:ncol]` positionally;
-  this port uses named `id` / `time` columns.
-
-## Outcome measures and directionality in the published models
-
-From Lutscher et al. (2026) and the studies it re-analyses. Use it as a template for
-declaring your own model, not as a set of defaults to copy.
-
-| Model / intervention | Variables in RELSA | Turned | Humane endpoint criterion |
-| --- | --- | --- | --- |
-| CLP sepsis (telemetry) | `hr`, `hrv`, `temp`, `act` | none | >25% temperature loss over two consecutive monitoring intervals |
-| DSS colitis + restraint stress | `hr`, `hrv`, `temp`, `act`, `bwc` | `hr`, `temp` | 20% body weight loss |
-| DSS colitis + facial vein blood sampling | `bwc`, `vwr` (voluntary wheel running) | none | 20% body weight loss or clinical score 5 |
-| Pancreatic cancer (6606PDA) | `bwc`, `vwr` | none | 20% body weight loss |
-| Neurosurgery (intracranial electrode) | `bwc`, nesting score, Neuro Score (modified Irwin) | nesting, neuro | total clinical score of 7 |
-
-Heart rate, heart rate variability and temperature were averaged per interval; activity was
-summed. Clinical scoring differed between laboratories and models, so the paper states
-plainly that clinical scores are **not directly comparable** across those studies — one of
-its central caveats about a generalized RELSA scale.
-
-## Data for testing against published work
-
-- Sepsis and 1.5% DSS + restraint stress: <https://github.com/mytalbot/RELSA/tree/master/raw_data>
-- DSS with repeated facial vein blood sampling: <https://doi.org/10.1371/journal.pbio.2006159.s002>
-- Pancreatic cancer: <https://doi.org/10.1371/journal.pone.0261662>
-- Neurosurgery: <https://doi.org/10.6084/m9.figshare.26030569>
-
-## Key references
-
-- Talbot, S. R. et al. (2022). RELSA — a multidimensional procedure for the comparative
-  assessment of well-being and the quantitative determination of severity in experimental
-  procedures. *Front. Vet. Sci.* 9:937711.
-- Lutscher, S. et al. (2026). Refining humane endpoint detection by time-series forecasting
-  and threshold definition using a multivariate severity score. *Front. Physiol.*
-  17:1869563. doi:10.3389/fphys.2026.1869563
-- Talbot, S. R. et al. (2020). Defining body-weight reduction as a humane endpoint: a
-  critical appraisal. *Lab. Anim.* 54, 99–110.
-- Russell, W. M. S. & Burch, R. L. (1959). *The Principles of Humane Experimental Technique.*

package/skills/relsa-severity-assessment/references/thresholds-and-zones.md

@@ -1,154 +0,0 @@
-# Severity zones on the RELSA scale via kernel density estimation
-
-A RELSA score of 0.55 is only interpretable once you know where the cut-points lie. Lutscher
-et al. (2026) derive candidate cut-points from the data itself: estimate the probability
-density of all RELSA scores observed in a model, and take the **minima** of that density —
-the sparsely populated valleys between clusters of scores. `scripts/kde_thresholds.py`
-implements this.
-
-## Method
-
-For each observation a Gaussian kernel of bandwidth `h` is placed; averaging them yields the
-density estimate, and interior local minima mark low-occurrence regions that can serve as
-thresholds (Korneev et al., 2022; Gilles & Heal, 2014).
-
-Two minima split the scale into three zones:
-
-| Zone | Meaning |
-| --- | --- |
-| normal | below the lower minimum — within the range the model's animals mostly occupy |
-| attention | between the minima — flag the animal for closer monitoring |
-| danger | above the upper minimum — approaching or at the individual endpoint |
-
-The implementation reproduces R's `stats::density` defaults, because that is what the paper
-used: Gaussian kernel, Silverman's `bw.nrd0` bandwidth
-(`0.9 * min(sd, IQR/1.349) * n^(-1/5)`), and a 512-point grid extended three bandwidths past
-the data range. Note that scipy's own `bw_method='silverman'` is a **different formula** and
-would shift every threshold, which is why `bw_nrd0()` is implemented explicitly.
-
-Include all animals in the model — those that reached the endpoint *and* the survivors and
-sham controls. The zones are meant to separate the trajectories of animals in different
-states, which requires all of those states to be represented.
-
-## Published thresholds
-
-| Model | Thresholds | Notes |
-| --- | --- | --- |
-| Sepsis (CLP) | 0.337 and 0.643 | 7 mice, 239 scores; the paper's Figure 3 |
-| DSS + restraint stress | 0.250 | single threshold |
-| DSS + blood sampling | 0.649 | single threshold |
-
-The pancreatic cancer and neurosurgery models were excluded from this analysis: with one
-animal each, the score distribution is too sparse for a meaningful density.
-
-The abstract of the paper gives the sepsis upper threshold as 0.647 while its Results and
-Figure 3 give 0.643 — a reminder of how little separates two runs of this procedure.
-
-## What this port reproduces, and how fragile it is
-
-On the public sepsis data with the paper's four telemetry variables and the CLP animals as
-reference set, excluding the baseline time point (where RELSA = 0 by construction):
-
-- **239 scores** — exactly the paper's stated 239 data points from 7 mice.
-- Thresholds **0.355 and 0.655** against the published 0.337 and 0.643. Including `bwc` in
-  the score gives 0.363 and 0.644.
-- At 0.9 × `bw.nrd0` the minima move to **0.335 and 0.633**, essentially the published pair.
-
-That last line is the important one. A bandwidth sensitivity sweep on the same 239 scores:
-
-| Bandwidth (× `bw.nrd0` = 0.0732) | Minima found |
-| --- | --- |
-| 0.70 | 0.310, 0.630 |
-| 0.80 | 0.322, 0.628 |
-| 0.90 | 0.335, 0.633 |
-| 1.00 | 0.355, 0.655 |
-| 1.10 | **none — the density is unimodal** |
-| ≥ 1.25 | none |
-
-A 10% change in bandwidth destroys both thresholds. The lower threshold sits in a broad,
-shallow valley and moves by 0.045 across a plausible bandwidth range; the upper one is
-comparatively stable. Two further sensitivities: dropping one variable from the score can
-change the number of minima, and turning off the algorithm's 2-decimal rounding changed this
-dataset from two minima to one.
-
-**Therefore:** never report KDE thresholds as a bare pair of numbers. Report the bandwidth,
-the number of scores, the variables, the reference set, and a sensitivity sweep. Prefer the
-sweep to the point estimate — if a threshold survives only at one bandwidth, you have found a
-property of the smoother, not of the animals.
-
-## These are not regulatory severity gradings
-
-EU Directive 2010/63/EU requires prospective assignment of procedures to four categories:
-non-recovery, mild, moderate, and severe. **KDE zones on the RELSA scale are not those
-categories,** and the paper says so twice: the thresholds "should not be confused with
-regulatory severity gradings" and are "neither generalizable nor directly translatable to
-severity categories under EU Directive 2010/63/EU".
-
-They are also not comparable between models. Because RELSA is relative to a reference set and
-because clinical scoring is not harmonized across laboratories, a threshold of 0.337 in one
-model means nothing in another. The paper's own observation that the sepsis (0.337/0.643) and
-DSS (0.250, 0.649) thresholds are "fairly close" is offered as a hint about where common
-thresholds might eventually lie, not as evidence that they transfer.
-
-What a unified scale would require, per the paper's outlook: the same parameters measured with
-harmonized technical and methodological approaches across models — realistically, automated
-home-cage monitoring at high frequency.
-
-## Practical use
-
-```bash
-# candidate zones for one model, with a figure and a sensitivity check
-python scripts/kde_thresholds.py relsa_scores.csv --n-thresholds 2 \
-    --plot zones.png --json zones.json --label-out zoned.csv
-
-# does the answer survive a different bandwidth?
-for f in 0.8 0.9 1.0 1.1 1.2; do
-  python - "$f" <<'PY'
-import sys, pandas as pd
-sys.path.insert(0, "scripts")
-from kde_thresholds import find_thresholds, bw_nrd0
-v = pd.read_csv("relsa_scores.csv")["relsa"].dropna()
-bw = bw_nrd0(v.to_numpy()) * float(sys.argv[1])
-print(sys.argv[1], [round(t, 3) for t in find_thresholds(v, bandwidth=bw).thresholds])
-PY
-done
-```
-
-An empty threshold list is a real answer: this cohort's scores form one cluster, and there is
-no data-driven place to cut. Do not lower the bandwidth until minima appear.
-
-### The thin-zone filter
-
-A finite sample's density estimate wiggles in its tails, and a wiggle produces a local minimum
-that separates one stray score from the rest. On 300 draws from a single normal distribution
-this implementation finds such a minimum, and it isolates exactly **one** observation — a
-property of the smoother, not a severity zone. `min_zone_fraction` (default 0.02) therefore
-requires every zone to hold at least 2% of the scores, dropping the shallowest threshold
-bounding any zone that does not, until all of them do.
-
-This does not touch the published sepsis result: its three zones hold 68.2%, 22.2%, and 9.6%
-of the 239 scores. Set `--min-zone-fraction 0` to see the raw minima, and expect tail
-artefacts among them.
-
-Two alternatives when KDE gives nothing usable:
-
-- **k-means levels.** The original RELSA package derives `k+1` levels by k-means clustering of
-  the reference set's scores (`relsa_levels`, default `k = 4`). Also data-driven, also
-  reference-set-specific, and it always returns levels — including when there is no real
-  structure to find.
-- **The model's own endpoint criterion.** Compute the RELSA score at the time the humane
-  endpoint was actually reached in previous animals, and use that value as the line to watch.
-  This is directly interpretable and needs no smoother, which is what the "individual
-  endpoint" line in the paper's Figure 1 shows.
-
-## Key references
-
-- Rosenblatt, M. (1956). Remarks on some nonparametric estimates of a density function.
-  *Ann. Math. Stat.* 27, 832–837.
-- Parzen, E. (1962). On estimation of a probability density function and mode.
-  *Ann. Math. Stat.* 33, 1065–1076.
-- Węglarczyk, S. (2018). Kernel density estimation and its application. *ITM Web Conf.* 23, 37.
-- Korneev, A. et al. (2022). Multiclass histogram-based thresholding using kernel density
-  estimation and scale-space representations. arXiv:2202.04785.
-- EU Commission (2010). Directive 2010/63/EU. *Official Journal of the European Union* 53,
-  16–25.

package/skills/relsa-severity-assessment/scripts/_common.py

@@ -1,287 +0,0 @@
-"""Shared I/O, validation, and variable-preparation helpers for the RELSA workflow.
-
-The RELSA long format is one row per animal per time point:
-
-    id   treatment   condition   time   var_1 ... var_n
-
-``id`` and ``time`` are required; ``treatment`` and ``condition`` are optional
-grouping labels carried through untouched. Time may be days, hours, or minutes
-as long as it increases monotonically per animal. The RELSA convention codes the
-baseline time point as -1, but any value works when it is named explicitly.
-"""
-
-from __future__ import annotations
-
-import warnings
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Iterable, Sequence
-
-import numpy as np
-import pandas as pd
-
-ID_COL = "id"
-TIME_COL = "time"
-META_COLS = ("treatment", "condition")
-
-# Time-column aliases accepted on input; all are renamed to ``time`` internally.
-TIME_ALIASES = ("time", "day", "days", "hour", "hours", "timepoint", "t")
-
-
-class RelsaDataError(ValueError):
-    """Raised when input data cannot support a RELSA calculation."""
-
-
-# --------------------------------------------------------------------------- #
-# loading
-# --------------------------------------------------------------------------- #
-def read_relsa_table(
-    path: str | Path,
-    sep: str | None = None,
-    id_col: str = ID_COL,
-    time_col: str | None = None,
-) -> pd.DataFrame:
-    """Read a RELSA-format table from CSV/TSV and return it with canonical names.
-
-    ``sep=None`` sniffs the delimiter. A leading unnamed index column (as written
-    by R's ``write.table``, and present in the published RELSA raw data) is
-    dropped. The time column is detected from ``TIME_ALIASES`` unless named.
-    """
-    path = Path(path)
-    if sep is None:
-        sep = "\t" if path.suffix.lower() in {".txt", ".tsv", ".tab"} else ","
-    frame = pd.read_csv(path, sep=sep)
-
-    unnamed = [c for c in frame.columns if str(c).startswith("Unnamed:")]
-    frame = frame.drop(columns=unnamed)
-
-    return canonicalize(frame, id_col=id_col, time_col=time_col)
-
-
-def canonicalize(
-    frame: pd.DataFrame,
-    id_col: str = ID_COL,
-    time_col: str | None = None,
-) -> pd.DataFrame:
-    """Rename the id/time columns to ``id``/``time`` and sort by animal and time."""
-    frame = frame.copy()
-
-    if id_col != ID_COL:
-        if id_col not in frame.columns:
-            raise RelsaDataError(f"id column {id_col!r} not in {list(frame.columns)}")
-        frame = frame.rename(columns={id_col: ID_COL})
-    if ID_COL not in frame.columns:
-        raise RelsaDataError(f"no {ID_COL!r} column in {list(frame.columns)}")
-
-    if time_col is None:
-        found = [c for c in frame.columns if str(c).lower() in TIME_ALIASES]
-        if not found:
-            raise RelsaDataError(
-                "no time column found; expected one of "
-                f"{TIME_ALIASES} or an explicit time_col"
-            )
-        time_col = found[0]
-    elif time_col not in frame.columns:
-        raise RelsaDataError(f"time column {time_col!r} not in {list(frame.columns)}")
-    if time_col != TIME_COL:
-        frame = frame.rename(columns={time_col: TIME_COL})
-
-    frame[TIME_COL] = pd.to_numeric(frame[TIME_COL], errors="coerce")
-    if frame[TIME_COL].isna().any():
-        raise RelsaDataError("time column contains non-numeric values")
-
-    return frame.sort_values([ID_COL, TIME_COL], kind="stable").reset_index(drop=True)
-
-
-def variable_columns(frame: pd.DataFrame) -> list[str]:
-    """Every numeric measurement column: not id, time, or a metadata label."""
-    reserved = {ID_COL, TIME_COL, *META_COLS}
-    return [c for c in frame.columns if c not in reserved]
-
-
-# --------------------------------------------------------------------------- #
-# validation
-# --------------------------------------------------------------------------- #
-def validate(frame: pd.DataFrame, variables: Sequence[str]) -> None:
-    """Check the invariants RELSA depends on, raising or warning as appropriate.
-
-    Duplicate (id, time) rows are fatal: normalization and forecasting both
-    assume one measurement per animal per time point. Everything else is a
-    warning, because RELSA is explicitly designed to tolerate missing data.
-    """
-    missing = [v for v in variables if v not in frame.columns]
-    if missing:
-        raise RelsaDataError(f"variables not in data: {missing}")
-
-    dup = frame.duplicated([ID_COL, TIME_COL], keep=False)
-    if dup.any():
-        offenders = (
-            frame.loc[dup, [ID_COL, TIME_COL]].astype(str).agg(" @ ".join, axis=1).unique()
-        )
-        raise RelsaDataError(
-            "multiple rows share an (id, time) pair, so normalization would be "
-            f"ambiguous: {list(offenders)[:5]}. Aggregate per time point first "
-            "(the published models average hourly telemetry to one value per day)."
-        )
-
-    for var in variables:
-        col = pd.to_numeric(frame[var], errors="coerce")
-        if col.notna().sum() == 0:
-            warnings.warn(f"variable {var!r} is entirely missing", stacklevel=2)
-
-    per_animal = frame.groupby(ID_COL)[TIME_COL].size()
-    if per_animal.nunique() > 1:
-        warnings.warn(
-            "animals have different numbers of time points; RELSA handles this, "
-            "but check that gaps are genuinely missing data and not misaligned time axes",
-            stacklevel=2,
-        )
-
-
-# --------------------------------------------------------------------------- #
-# variable preparation
-# --------------------------------------------------------------------------- #
-def score_to_percent(
-    values: Iterable[float],
-    max_score: float,
-    baseline_score: float = 0.0,
-) -> np.ndarray:
-    """Map an ordinal severity score onto the RELSA percent scale.
-
-    RELSA normalizes by dividing each measurement by its own baseline, which is
-    undefined for a clinical score whose healthy baseline is 0. This maps the
-    score's *scale* instead of its ratio: ``baseline_score`` becomes 100 and
-    ``max_score`` becomes 200, so the variable behaves like any other "turned"
-    parameter (rises above 100 as the animal worsens) and one full score point
-    is worth ``100 / |max_score - baseline_score|`` percent.
-
-    ``max_score`` may lie *below* ``baseline_score`` for scales where a lower
-    number is worse — a nesting score where a well-built nest scores 5 and no
-    nest scores 0 is ``score_to_percent(nesting, max_score=0,
-    baseline_score=5)``. Either way the mapped variable is "turned".
-
-    Pass the resulting column straight to the RELSA calculation, list it in
-    ``turned``, and leave it out of ``normalize`` — it is already normalized.
-    """
-    values = np.asarray(list(values), dtype=float)
-    span = float(max_score) - float(baseline_score)
-    if span == 0:
-        raise RelsaDataError(
-            f"max_score ({max_score}) must differ from baseline_score ({baseline_score})"
-        )
-    return 100.0 + 100.0 * (values - float(baseline_score)) / span
-
-
-def percent_of_baseline(
-    frame: pd.DataFrame,
-    variables: Sequence[str],
-    baseline_time: float | Sequence[float] | None = None,
-) -> pd.DataFrame:
-    """Express each variable as a percentage of that animal's own baseline.
-
-    ``baseline_time`` selects the baseline: a single time value, several time
-    values (averaged, i.e. a baseline window), or ``None`` for each animal's
-    first time point. Animals whose baseline is missing or zero yield all-NaN
-    for that variable, with a warning — a zero baseline makes the ratio
-    undefined, which is what ``score_to_percent`` exists to avoid.
-    """
-    out = frame.copy()
-    if baseline_time is None:
-        window: list[float] | None = None
-    elif np.isscalar(baseline_time):
-        window = [float(baseline_time)]  # type: ignore[arg-type]
-    else:
-        window = [float(t) for t in baseline_time]  # type: ignore[union-attr]
-
-    for var in variables:
-        out[var] = pd.to_numeric(out[var], errors="coerce")
-
-    problems: list[str] = []
-    for animal, block in out.groupby(ID_COL, sort=False):
-        if window is None:
-            rows = block.index[:1]
-        else:
-            rows = block.index[block[TIME_COL].isin(window)]
-            if len(rows) == 0:
-                problems.append(f"{animal} (no baseline time point)")
-                out.loc[block.index, list(variables)] = np.nan
-                continue
-        for var in variables:
-            window_values = out.loc[rows, var].to_numpy(dtype=float)
-            finite = window_values[np.isfinite(window_values)]
-            base = float(finite.mean()) if finite.size else np.nan
-            if not np.isfinite(base) or base == 0:
-                problems.append(f"{animal}/{var} (baseline {base})")
-                out.loc[block.index, var] = np.nan
-                continue
-            out.loc[block.index, var] = out.loc[block.index, var] / base * 100.0
-
-    if problems:
-        warnings.warn(
-            "baseline missing or zero, variable set to NaN for: "
-            + ", ".join(problems[:8])
-            + ("..." if len(problems) > 8 else "")
-            + ". For scores whose healthy baseline is 0, use score_to_percent().",
-            stacklevel=2,
-        )
-    return out
-
-
-def parse_list(value: str | None) -> list[str]:
-    """Split a comma-separated CLI option into a clean list."""
-    if not value:
-        return []
-    return [item.strip() for item in value.split(",") if item.strip()]
-
-
-# --------------------------------------------------------------------------- #
-# metrics
-# --------------------------------------------------------------------------- #
-@dataclass(frozen=True)
-class ForecastMetrics:
-    """The three error metrics reported in Lutscher et al. (2026), Table 1."""
-
-    n: int
-    rmse: float
-    picp: float
-    mpiw: float
-
-    def as_dict(self) -> dict[str, float]:
-        return {"n": self.n, "rmse": self.rmse, "picp": self.picp, "mpiw": self.mpiw}
-
-
-def forecast_metrics(
-    actual: Iterable[float],
-    predicted: Iterable[float],
-    lower: Iterable[float] | None = None,
-    upper: Iterable[float] | None = None,
-) -> ForecastMetrics:
-    """RMSE, prediction-interval coverage probability, and mean interval width.
-
-    RMSE and PICP answer different questions and are reported together on
-    purpose: a model can widen its intervals until PICP hits 100% without
-    predicting anything, which is why MPIW (the mean width, in RELSA units)
-    has to be read alongside the coverage.
-    """
-    a = np.asarray(list(actual), dtype=float)
-    p = np.asarray(list(predicted), dtype=float)
-    if a.shape != p.shape:
-        raise ValueError(f"actual {a.shape} and predicted {p.shape} differ in length")
-
-    ok = np.isfinite(a) & np.isfinite(p)
-    rmse = float(np.sqrt(np.mean((a[ok] - p[ok]) ** 2))) if ok.any() else float("nan")
-
-    picp = float("nan")
-    mpiw = float("nan")
-    if lower is not None and upper is not None:
-        lo = np.asarray(list(lower), dtype=float)
-        hi = np.asarray(list(upper), dtype=float)
-        band = np.isfinite(lo) & np.isfinite(hi)
-        if band.any():
-            mpiw = float(np.mean(hi[band] - lo[band]))
-        cov = band & np.isfinite(a)
-        if cov.any():
-            inside = (a[cov] >= lo[cov]) & (a[cov] <= hi[cov])
-            picp = float(100.0 * np.mean(inside))
-
-    return ForecastMetrics(n=int(ok.sum()), rmse=rmse, picp=picp, mpiw=mpiw)