relsa-severity-assessment – Other skill for AI agents

RELSA severity assessment and exploratory score forecasting

Overview

This skill computes reference-relative multivariate scores and exploratory ARIMA forecasts.

It targets the equations and printed example of [RELSA 0.0.1.9000](https://github.com/mytalbot/RELSA)

(commit e68e8451e8719ccc3600179f55900cd7254ede9d, current upstream at review), plus the

published [foRcast methodology](https://doi.org/10.3389/fphys.2026.1869563).

The Python forecast helper is an independent nonseasonal approximation, not an exact R port.

RELSA is the RMS of directional deviations divided by each variable's reference maximum

deviation. Zero means no measured worsening in those directions; it does not establish

normal welfare. One is a reference scale unit, not a universal endpoint or an upper bound.

Different variables may attain their reference extrema in different animals or at different

times, so the reference cohort need not contain a score of exactly one.

Forecasts estimate a score at a specified time, not time-to-endpoint or probability of death.

Keep the approved study's observation schedule and humane endpoint criteria separate from

these exploratory outputs. 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 venv --python 3.13 .venv-relsa
uv pip install --python .venv-relsa/bin/python numpy==2.5.3 pandas==3.0.6 scipy==1.18.1 statsmodels==0.15.0 matplotlib==3.11.2
source .venv-relsa/bin/activate

Run the examples from this skill directory. relsa_score.py needs numpy/pandas;

kde_thresholds.py additionally needs 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 must be finite, with one consistent unit and origin across cohorts. Forecast training and

target times must align with the chosen regular grid; disable interpolation only on regular observations. 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).

• Preserve lexical animal IDs (including leading zeros). Duplicate IDs/times, nonnumeric

measurements and infinities are rejected. 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. Choose a scientifically characterized reference and document its burden; the 2026

forecasting study uses the group assumed to carry the greatest burden in each model. A mild reference can push new scores

above 1; too severe compresses everything toward 0. Save it with --save-reference and reuse

it with --load-reference so later cohorts stay on the same scale. New CLI reference files

also store and reuse normalization, ordinal mappings, baseline selection and rounding; conflicting

options are rejected. Legacy references lack that contract and require the original options.

3. Scores with a zero baseline. A clinical score of 0 in a healthy animal cannot be

ratio-normalized — 0/0 is undefined. Use --score-scale score=8 to map the score's scale

instead (healthy → 100%, worst possible → 200%), which also marks it as turned. This assumes meaningful numeric spacing between ordinal categories. An affine rescaling

applied identically to reference and target cancels in the weight ratio before rounding; the

category encoding, healthy anchor and reference cohort still matter. State those choices. The alternative is to keep the score out of RELSA and use it as an

independent endpoint criterion.

4. Which variables are measured throughout. Because the score averages over whichever

variables are available, a variable that appears or disappears mid-trajectory moves the score

by itself. An intermittent measure joining only at the endpoint can lower or raise the composite

without any change in the other observed measures.

relsa_scores() warns when composition changes; score the variables present throughout.

Workflow

Step 1 — compute RELSA scores

python scripts/relsa_score.py assets/example_cohort.csv \
    --variables weight,temp,score,il6 \
    --normalize weight,temp,il6 \
    --turned il6 \
    --score-scale score=8 \
    --baseline-time -1 \
    --reference-group condition=endpoint \
    --save-reference reference.json \
    --out relsa_scores.csv

The reference model is echoed so the scale is auditable:

reference model: assets/example_cohort.csv [condition=endpoint]
  animals=2  rows=18  baseline_time=-1.0
  variable      turned   max reached   max delta
  weight            no         82.40       17.60
  temp              no         92.79        7.21
  score            yes        187.50       87.50
  il6              yes        797.72      697.72

relsa_scores.csv holds each variable's weight alongside the score, which is what makes a

score explainable — here M01 deteriorating to its endpoint, M03 peaking on day 3 and

recovering:

 id  time  weight  temp  score  il6  n_vars  relsa
M01     1    0.46  0.49   0.57 0.52       4   0.51
M01     3    0.84  0.76   1.00 0.89       4   0.88
M01     5    1.00  1.00   1.00 1.00       4   1.00
M03     3    0.56  0.44   0.57 0.54       4   0.53
M03     5    0.35  0.26   0.43 0.32       4   0.35
M03     7    0.12  0.06   0.14 0.11       4   0.11

A weight of 1.00 means that variable hit the reference maximum; n_vars is how many

variables entered the score at that time point.

Same thing from Python, when you need the objects:

import sys; sys.path.insert(0, "scripts")
from _common import read_relsa_table, score_to_percent
from relsa_score import prepare, build_reference, relsa_scores

frame = read_relsa_table("assets/example_cohort.csv")
frame["score"] = score_to_percent(frame["score"], max_score=8)   # 0-8 clinical score
VARS, TURNED = ["weight", "temp", "score", "il6"], ["score", "il6"]

prepared  = prepare(frame, normalize=["weight", "temp", "il6"], baseline_time=-1)
reference = build_reference(prepared[prepared.condition == "endpoint"],
                           variables=VARS, turned=TURNED, baseline_time=-1,
                           label="endpoint-reaching animals")
scores    = relsa_scores(prepared, reference)

Step 2 — forecast a score at a known evaluation time

For retrospective evaluation, use recorded endpoint times and train only o

… (full content is in the download package)