relsa-severity-assessment

用途

该技能面向实验室动物研究中的严重程度评估与人道终点预测，实现两项已发表的方法：

RELSA（Talbot 等，2022）：将多个结局指标合并为每只动物每个时间点的单一评分，并相对于已知负担的参考集表达。RELSA = 0 为基线；RELSA = 1 表示动物已达到参考集的最大偏差。
foRcast（Lutscher 等，2026）：对个体动物的 RELSA 轨迹拟合 ARIMA 模型，预测下一评分及 95% 预测区间，从而在动物到达人道终点前识别风险个体。基于 RELSA 尺度的核密度估计提供候选的关注区和危险区。

其目的是改进（refinement）：更早关注高风险动物，避免对可能恢复的动物实施安乐死。两项方法均为严重程度评估的辅助工具，而非决策规则。

主要能力

将体重下降、体温、临床评分、生物标志物或遥测数据合并为每只动物的单一严重程度评分。
预测队列中哪些动物有到达人道终点的风险，或预测未来时间点的严重程度评分。
在共同的相对尺度上比较处理组、干预措施或动物模型之间的严重程度。
从数据中定义严重程度尺度上的阈值或分区。
支持撰写动物福利报告、3Rs/refinement 分析或 EU Directive 2010/63/EU 申请中的严重程度评估部分。

使用方式

安装

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

relsa_score.py 和 kde_thresholds.py 仅需 numpy/pandas/scipy；预测需要 statsmodels，绘图需要 matplotlib。

数据格式

CSV 文件，每只动物每个时间点一行，包含列：id、treatment、condition、day、temp、weight、score、il6。id 和时间列（day、time、hour 等）为必需；treatment 和 condition 为可选标签，用于分组和选择参考集。时间可为天、小时或分钟，但每只动物需单调递增。RELSA 约定将基线时间点编码为 -1。缺失测量留空，会被丢弃而非插补。

四个关键决策

方向性：哪些变量在恶化时上升？下降为默认（体重、活动、摄食等）。上升的变量必须通过 --turned 声明（临床评分、炎症生物标志物、发热、心动过速）。方向错误会导致该变量静默地贡献为零。体温取决于模型——脓毒症和內毒素血症中下降，发热模型中上升。
参考集：RELSA 评分相对于参考集才有意义。使用假定负担最大的组（已发表研究使用最高剂量或到达终点的处理组）。通过 --save-reference 保存，--load-reference 复用。
零基线评分：健康动物临床评分为 0 无法进行比率归一化（0/0 未定义）。使用 --score-scale score=8 映射评分尺度（健康 → 100%，最差 → 200%），同时标记为 turned。
全程测量的变量：评分对可用变量取平均，中途出现或消失的变量会自行改变评分。应对全程存在的变量评分。

工作流程

步骤 1 — 计算 RELSA 评分

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

输出包含每个变量的权重和评分，使评分可解释。

步骤 2 — 预测终点

python scripts/forecast_relsa.py relsa_scores.csv \
    --animals M01,M02 --endpoints M01=5 --endpoints M02=6 \
    --group-col condition --plot-dir figs --endpoint-line 1.0

报告 RMSE（点精度）、PICP（实际值在区间内的百分比）和 MPIW（平均区间宽度）三项指标。实时监测可使用 --mode rolling 进行单步预测。注意：默认开启插值（--interpolate-step 0.1），ARIMA 无法预测骤降。

步骤 3 — 用严重程度分区提供背景

python scripts/kde_thresholds.py relsa_scores.csv \
    --group treatment=treated --n-thresholds 2 --plot zones.png --json zones.json

阈值是评分密度的极小值。需包含终点动物、存活动物和假手术动物。检查带宽敏感性，报告扫描结果而非单一数值。

适用场景

合并体重下降、体温、临床评分、生物标志物或遥测数据为单一严重程度评分。
识别队列中到达人道终点风险的动物。
在共同相对尺度上比较处理组、干预或模型的严重程度。
从数据定义严重程度阈值或分区。
撰写动物福利报告、3Rs/refinement 分析或 EU Directive 2010/63/EU 申请。

限制

RELSA 是严重程度评估的辅助工具，不是决定性参数。低 RELSA 评分但显示其他痛苦迹象的动物仍须相应处理。两项方法均非经验证的死亡预测器。
KDE 分区不是法规性严重程度分级。EU Directive 2010/63/EU 的分类（非恢复、轻度、中度、重度）由不同流程前瞻性分配，不可直接转换。
评分不可跨参考集或模型比较。RELSA 本质上是相对的，临床评分在实验室间未统一。
已发表证据为概念验证：13 只动物、七个模型，其中五行仅基于一两只动物。总体 RMSE 0.069 和 PICP 96% 来自 13 次终点预测。
低估评分是危险错误，会延迟安乐死决策；高估仅促使额外关注。
ARIMA 假设平稳性和线性，无法预测终点前最后数小时的突然崩溃。
插值会扭曲不确定性。

报告清单

可复现的严重程度分析需说明：结局指标、单位及方向性；基线时间点及归一化变量；序数变量的评分映射及尺度；参考集（哪些动物、哪组、数量及为何假定负担最大）；研究中实际应用的人道终点标准；预测的插值步长、每只动物的 ARIMA 阶数及 RMSE/PICP/MPIW；阈值的带宽、评分数量及带宽敏感性扫描；软件版本，以及阈值是模型特定且非法规分级的声明。

资源

scripts/relsa_score.py — RELSA 流程：prepare()、build_reference()、relsa_scores()、relsa_weights() 及可序列化为 JSON 的 ReferenceModel。
scripts/forecast_relsa.py — foRcast 工具：auto_arima()、forecast_animal()、predict_endpoint()、rolling_forecast()、forecast_indirect()、summarize() 及绘图。
scripts/kde_thresholds.py — 严重程度分区：bw_nrd0()、density_curve()、find_thresholds()、分区分配及密度图。
scripts/_common.py — RELSA 格式 I/O、验证、score_to_percent()、percent_of_baseline() 及 forecast_metrics()。
references/relsa-method.md、references/forecasting.md、references/thresholds-and-zones.md — 详细方法文档。
assets/example_cohort.csv — 合成 6 只小鼠队列，仅作示例，非真实数据。

技能介绍

用途