/relsa-severity-assessment

name: relsa-severity-assessment
description: Multivariate severity assessment and humane endpoint prediction 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 or when one will be reached, 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.
license: MIT
allowed-tools: Read Write Edit Bash
compatibility: Requires Python >=3.10 with numpy, pandas, and scipy; statsmodels >=0.14 for forecasting and matplotlib for figures. Tested with numpy 2.5, pandas 3.0, scipy 1.18, statsmodels 0.14.6. No network access needed.
metadata:
  version: "1.0"
  skill-author: K-Dense Inc.

RELSA severity assessment and humane endpoint forecasting

Overview

Severity assessment in animal research is legally mandatory and scientifically load-bearing: it drives humane endpoint decisions, and poor welfare monitoring degrades reproducibility. The usual practice evaluates each readout in isolation — weight loss here, a clinical score there — which makes it hard to say how badly an individual animal is actually doing.

This skill implements two published procedures that address that:

• **RELSA** (Talbot et al., 2022) combines several outcome measures into one score per animal

per time point, expressed *relative to a reference set of known burden*. RELSA = 0 is baseline; RELSA = 1 means the animal has reached the reference set's maximum deviation.

• **foRcast** (Lutscher et al., 2026) fits an ARIMA model to an individual animal's RELSA

trajectory and forecasts the next score with a 95% prediction interval, so animals heading for a humane endpoint can be identified before they get there. Kernel density estimation on the RELSA scale supplies candidate *attention* and *danger* zones for interpretation.

The point is **refinement**: give at-risk animals attention earlier, and avoid euthanising animals that would have recovered. Both procedures are aids to severity assessment, not decision rules — see [Boundaries](#boundaries-state-these-when-you-report).

When to use this skill

• Combining weight loss, temperature, clinical scoring, biomarkers, or telemetry into a single

per-animal severity score

• Asking which animals in a cohort are at risk of reaching a humane endpoint, or predicting

the severity score at a coming time point

• Comparing severity between treatment groups, interventions, or animal models on a common

relative scale

• Defining thresholds or zones on a severity scale from the data
• Writing the severity-assessment section of an animal welfare report, a 3Rs/refinement

analysis, or an application under EU Directive 2010/63/EU

For general forecasting of a time series that is not a severity score, use **timesfm-forecasting** or **statsmodels**. For study design and sample size, use **experimental-design** and **statistical-power**.

Installation

uv pip install "numpy>=1.26" "pandas>=2.0" "scipy>=1.11" "statsmodels>=0.14" matplotlib

`relsa_score.py` and `kde_thresholds.py` need only numpy/pandas/scipy; statsmodels is required for forecasting and matplotlib only for figures.

Data format

One row per animal per time point, in a CSV:

| id | treatment | condition | day | temp | weight | score | il6 | | --- | --- | --- | --- | --- | --- | --- | --- | | M01 | treated | endpoint | -1 | 37.15 | 25.17 | 0 | 35.1 | | M01 | treated | endpoint | 0 | 37.26 | 25.25 | 0 | 39.5 | | M01 | treated | endpoint | 1 | 35.83 | 23.12 | 4 | 162.0 |

• `id` and a time column (`day`, `time`, `hour`, …) are required; `treatment` and `condition`

are optional labels used for grouping and for selecting the reference set.

• Time may be days, hours, or minutes — just keep it monotonic per animal. The RELSA

convention codes the baseline time point as `-1`.

• **One row per animal per time point.** Average hourly telemetry to one value per interval

first (the published models average heart rate, HRV, and temperature, and sum activity).

• Leave missing measurements empty. They are dropped from the score, never imputed — a

missing value treated as "no deviation" biases severity downward.

`assets/example_cohort.csv` is a small synthetic cohort (6 mice, 9 days, temperature, body weight, an 0–8 clinical score, and an IL-6-like biomarker) used by every command below, so each one is runnable as written.

The four decisions that determine the result

Make these explicitly and write them into the methods. Nothing else about the procedure matters as much.

**1. Directionality — which variables rise under worsening?** Falling is the default (body weight, activity, food intake, burrowing, wheel running). Variables that *rise* must be declared as `--turned`: clinical scores, inflammatory biomarkers, fever, tachycardia. Get this wrong and the variable contributes nothing at all, silently, because deviations in the "wrong" direction are floored at zero. Body temperature is model-dependent — it *falls* in sepsis and endotoxaemia, *rises* in fever models. Nothing in the data can settle this for you: in the published sepsis model activity legitimately swings further above baseline than below, so only a variable that *never once* moves the declared way is detectable, and `build_reference()` warns about exactly that case.

**2. The reference set — relative to what?** RELSA scores mean nothing without it. Use the group assumed to