Skip to content

K-Dense-AI/scientific-agent-skills / skills/relsa-severity-assessment

relsa-severity-assessment

Verified

Supports multivariate severity assessment and exploratory endpoint-time score forecasting for laboratory animal studies using the RELSA (RELative Severity Assessment) score and ARIMA-based foRcast forecasting. Use when combining welfare readouts — body weight or weight loss, body temperature, clinical or nesting scores, biomarkers, activity, heart rate, burrowing, wheel running — into one severity score per animal per day, when asking which animals are at risk of reaching a humane endpoint at a specified future observation time, when defining attention/danger zones or thresholds on a severity scale by kernel density estimation, or when reporting severity for a 3Rs, refinement, animal-welfare, or EU Directive 2010/63/EU severity-assessment context. Covers directionality ("turned" variables), baseline normalization, reference sets, RELSA weights, ARIMA prediction intervals, and RMSE/PICP/MPIW evaluation.

references/relsa-method.md

View on GitHub
# RELSA equations and current upstream contract

Reviewed 2026-10-01 against the [official RELSA repository](https://github.com/mytalbot/RELSA),
version 0.0.1.9000, commit `e68e8451e8719ccc3600179f55900cd7254ede9d`, and the
[primary methods paper](https://doi.org/10.3389/fvets.2022.937711).
This skill implements the equations independently in Python. Source inspection and agreement
with the published worked example do not establish exhaustive native R parity.

## Preparation

For each animal and ratio-compatible variable, use a prespecified healthy baseline:

```
x_norm(t) = 100 * x(t) / mean(x at the selected baseline times)
```

The baseline must be finite and positive for the intended ratio interpretation. Missing or
nonpositive baselines produce missing trajectories with a warning. A multi-time window uses
available finite values; inspect completeness before accepting that mean. Select it before
looking at outcome trajectories and before the forecast cutoff. With no explicit baseline,
the Python helper uses the earliest time per animal. Never silently use a first post-treatment
observation as a healthy baseline. Units must match between cohorts. Ratios of Celsius
temperatures are origin-dependent; preserve and disclose the published unit convention if
replicating it, and do not claim physical percentage temperature loss is unit-invariant.

RELSA expects 100 at baseline. A percentage of baseline of 90 is already suitable; a signed
change of -10 requires `100 + change`, and a positive loss of 10 requires `100 - loss`.
They are not interchangeable input columns.

For an ordinal score use `score_to_percent(values, max_score, baseline_score=0)`:

```
100 + 100 * (score - baseline_score) / (max_score - baseline_score)
```

The mapped variable is always turned (higher mapped values mean worsening). `max_score`
can be below baseline for a lower-is-worse instrument. Out-of-range values are rejected;
missing scores stay missing. This local convention assumes numerical distances between
categories. A common affine multiplier cancels between numerator and reference denominator
before rounding; it does not independently tune the variable's final weight. Category
encoding, healthy anchor, rounding and the chosen reference remain consequential.

## Direction and reference

Declare worsening direction from the experimental model and validated measurement meaning.
Default variables fall; `turned` variables rise. Neither fever nor hypothermia is a universal
temperature direction. A unidirectional score ignores deviation the other way; if both
extremes matter, this implementation does not supply a validated bidirectional transformation.

For a frozen reference cohort on the normalized scale:

```
maxsev_i   = min(reference_i)           # max for turned variables
maxdelta_i = abs(100 - maxsev_i)
delta_i(t) = max(100 - x_norm_i(t), 0)  # max(x_norm_i(t) - 100, 0) if turned
RW_i(t)    = delta_i(t) / maxdelta_i
RELSA(t)   = sqrt(sum(RW_i(t)^2) / n_present)
```

The default rounds deltas, weights and the final score to two decimals, following current
upstream source. `round_digits=None` disables rounding. Fix that choice across cohorts.
Reference variables must be unique and have finite, nonzero denominators. Unknown turned or
dropped variable names fail. A direction mismatch with no baseline row can still produce
an opposite-direction reference extreme; the helper warns. Such a reference requires review.
A reference whose variable never worsens should not be used to calibrate that variable.

Reference extrema may occur in different animals and at different times. Consequently the
largest **observed reference composite** can be below 1. In full precision, reaching 1 while
all component weights are at most 1 requires every present weight to equal 1. A new composite
above 1 implies at least one reference-scaled deviation exceeds 1; a single exceeded component
can still be diluted to a composite below 1. A value of 0.73 is an RMS ratio, not 73% of an
animal's burden or of a legal severity category. Zero also includes observations on the
non-worsening side of baseline; it does not prove normal welfare.

## Missingness and time

Only observed variables enter the RMS. An entirely missing row stays missing. Changing the
panel changes the estimand even if physiology does not change; inspect `n_vars` and the actual
variable identities, and use a stable panel for comparisons. Informative loss to observation,
euthanasia and survival-related censoring affect both trajectories and density estimates.
Do not fill post-endpoint rows with zero, interpolate across an endpoint, or treat unobserved
recovery as established. Preserve reasons for missingness outside the numeric score table.

Use one row per animal per observation interval. Duplicate times are rejected. Aggregate
telemetry using a declared interval and measurement-appropriate rule (e.g. mean temperature,
sum activity); include observation counts and missing intervals in provenance. Aggregation can
hide short severe episodes, which remain relevant to welfare assessment.

## Current R APIs and differences

Official source signatures:

- `relsa_norm(set, normthese=NULL, ontime=1)`: `ontime` is a **one-based within-animal row
  index**, despite its time-point wording, not the day value. Python `baseline_time` instead
  selects actual time values and supports windows.
- `relsa_baselines(dataset=NULL, bslday=-1, variables=NULL, turnvars=NULL)`: `bslday` selects
  stored baseline rows; extrema are computed over the entire supplied normalized dataset.
- `relsa(set, bsl, a=1, drop=NULL, turnvars=NULL, relsaNA=NA)`: `a` indexes the unique IDs;
  measurements are selected positionally after the first metadata columns. The composite is
  returned under `$relsa$rms`, not `$relsa$wf`.
- `relsa_levels(refset, mypath, filename=NULL, bsl=bsl, drops=NULL, turns=NULL, ..., k=4)`:
  documents k-means-derived levels from a reference set. Nested R data-frame column handling
  and this clustering path were not executed here. The original paper's clustering of
  animal-level maxima also differs from KDE of all longitudinal observations.

The checked `relsa()` source divides the auxiliary `wf` by the missing-variable count, then
uses its missingness to mask `rms`. At complete baseline rows this can return NA. The official
README/vignette prints zero, which the Python formula and tests preserve intentionally.
R's positional layout and row-index normalization differ from the Python named-column APIs.

The existing regression fixture transcribes the published `Ca_001` normalized values and
weights, and scores 0.00, 0.73, 0.55, 0.44, 0.44, 0.41. It tests printed-example agreement,
not a fresh R execution or equivalence for arbitrary inputs. This refresh uses only tiny
synthetic runtime data; it does not repeat earlier full published-cohort analyses.

## Persisting a scale

The CLI applies identical ordinal mappings and normalization to `--reference-data` and target
data. New reference JSON stores the preprocessing contract and `--load-reference` reuses it;
conflicting explicit options fail. Legacy JSON or programmatic `ReferenceModel` objects may
lack this contract: reproduce preprocessing explicitly and retain that provenance. JSON
contains extrema, direction, cohort counts and a label, not raw cohort records. Archive the
reference selection, units, specimen population, instrument definitions and input hashes
separately. Changing any of them requires a new declared calibration and evaluation.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall