WHONET 数据分析
概述
处理 WHONET (World Health Organization Network for Antimicrobial Resistance Surveillance) 导出的 SQLite 数据库，完成从原始药敏数值到临床分析结果的完整链路。
数据链路：database.sqlite（用户原始库）→ AMRIE 解释 → database_interpreted.sqlite（解释库，含合并药物列 S/I/R）→ 各类分析。
支持 6 大功能：
1. AMRIE 药敏解释 — 将原始 MIC/抑菌圈数值解释为 S/I/R（CLSI/EUCAST 2026 折点）⚠️ 需额外安装 AMRIE CLI
2. 物种耐药率统计 — 各菌种-抗菌药物组合的耐药率/中介率，输出 Excel（含年度趋势）✅ 即装即用
3. 单菌种耐药趋势 — 近1/3/5/10年 + 逐年耐药率，输出 JSON ✅ 即装即用
4. 折点查询 — 按物种查询 CLSI/EUCAST 折点值（多代码级别匹配）✅ 即装即用
5. 天然耐药查询 — 细菌固有耐药信息（CLSI/EUCAST 双标准）✅ 即装即用
6. 耐药模式计算 — 物种-药物类别组合的耐药表型模式（如 AMK:S|GEN:R|TOB:R）✅ 即装即用
> 关于 AMRIE 解释功能：因 SkillHub 上传限制（禁止 .dll/.exe 二进制），本发布版未打包 AMRIE 引擎。
> 5 大分析功能（折点/天然耐药/耐药率/趋势/模式）立即可用；AMRIE 药敏解释功能需要使用者本地安装 .NET 8.0+ 与 AMRIE CLI（详见下方「AMRIE 引擎安装」）。
6. 耐药模式计算 — 物种-药物类别组合的耐药表型模式（如 AMK:S|GEN:R|TOB:R）
重要：用户数据文件由使用者指定
本 skill 不内置任何 WHONET 监测数据。使用者调用分析功能时必须指定自己的数据文件：
- 原始库（未解释，用于 AMRIE 解释）：通过
-i/--input-db或环境变量WHONET_INPUT_DB指定 - 解释库（含 S/I/R，用于耐药率/趋势/模式分析）：通过
--db或环境变量WHONET_DB指定
未指定数据文件时，脚本会明确报错提示。字典、折点表、AMRIE 引擎随 skill 自带（assets/），无需使用者准备。
Skill 目录结构
whonet-analysis/
├── SKILL.md
├── scripts/ # 6 个分析脚本
└── assets/
└── md_dict/ # 字典：Antibiotics/Breakpoints/Organisms/天然耐药/字段对照/科室分类
脚本自动定位 skill 自带资源（assets/ 优先，兼容 md_dict/ 平级结构），也可用环境变量覆盖。
AMRIE 引擎安装（仅 AMRIE 解释功能需要）
5 大分析功能（折点/天然耐药/耐药率/趋势/模式）开箱即用，无需 AMRIE。仅「AMRIE 药敏解释」功能（生成 database_interpreted.sqlite）需要使用者本地安装 AMRIE 引擎：
# 1. 安装 .NET 8.0+ 运行时（一次性）
# 验证：dotnet --list-runtimes # 需有 8.x
# 2. 下载 AMRIE 解释 CLI（约 1MB）
# 官方下载：https://amr-interpret.org/download
# 或 GitHub：https://github.com/CDCgov/AMR-Interpret
# 3. 放置到 skill 的 assets/AMRIE/bin/Debug/net8.0/ 目录
mkdir -p ~/.workbuddy/skills/whonet-analysis/assets/AMRIE/bin/Debug/net8.0
cp 'Interpretation CLI/bin/Debug/net8.0/'* ~/.workbuddy/skills/whonet-analysis/assets/AMRIE/bin/Debug/net8.0/
# 验证：目录应包含 Interpretation CLI.dll / .exe / Interpretation Engine.dll / Resources/
# 4. 安装后即可使用 AMRIE 解释
python scripts/generate_interpreted_db.py -i 你的database.sqlite --steps 1,2,3
未安装 AMRIE 时运行 generate_interpreted_db.py 会给出明确错误提示（"请安装 AMRIE 引擎到 assets/AMRIE/bin/Debug/net8.0/"），不影响其他 5 大功能使用。
执行环境
脚本位于本 skill 的 scripts/ 目录，运行时自动定位 skill 根目录下的 assets/（字典与 AMRIE 引擎），无需配置路径。
# 通用执行方式（任意机器）：
# - 将本 skill 解压到任意位置，如 ~/.workbuddy/skills/whonet-analysis/
# - 用任意 Python 3.12+ 解释器执行（需安装 pandas、openpyxl）
python scripts/generate_interpreted_db.py -i <你的 database.sqlite>
python scripts/analyze_db.py --db <你的解释库>
依赖：pandas、openpyxl（Python 3.12+，pip install pandas openpyxl）。AMRIE 解释需要 dotnet 8.0+。
功能使用（数据文件由使用者指定）
1. AMRIE 药敏解释（生成解释库）
前置：使用者提供原始 database.sqlite。产出：解释库（428 列 = 原始列 + _INTERP 列 + 合并药物列 + WARD_GB_* + ORGANISM_CN）。
python scripts/generate_interpreted_db.py -i <用户的 database.sqlite 路径> [-o <输出解释库路径>] --steps 1,2,3
-i/--input-db必填（或环境变量WHONET_INPUT_DB）-o/--output-db缺省时输出到输入文件同级<原名>_interpreted.sqlite- 分步执行：
--steps 1（导出 TSV）→--steps 2（运行 AMRIE）→--steps 3（导入生成库） - 53 万行全程约 4-5 分钟
- 验证产物：合并药物列分布应为 S/I/R 值（如 AMK: S=126807, R=28528, I=4783）
- 排错查看
项目根/amrie_cli_last_run.log
2. 物种耐药率统计（Excel）
python scripts/analyze_db.py --db <用户的解释库路径> [--sample-type "尿液,血液"] [--output 路径.xlsx]
--db必填（或环境变量WHONET_DB），须为已解释库（含 S/I/R 合并列）- 默认输出到 skill 目录
结果/物种分离及耐药率统计.xlsx（自动建目录） - 全量约 3-4 分钟，输出 190+ 工作表（1 汇总 + 各物种明细）
3. 单菌种耐药趋势（JSON）
python scripts/species_resistance_analysis.py <物种代码> --db <用户的解释库路径> [--specimen "尿液"] [--output 结果.json]
- 物种代码示例：
eco（大肠埃希菌）、kpn（肺炎克雷伯菌）、pae（铜绿假单胞菌）、sau（金黄色葡萄球菌） - 输出：各药物近1/3/5/10年 + 逐年 S/I/R 计数与耐药率
4. 折点查询（CLSI/EUCAST）
python scripts/breakpoint_query.py --organism eco --year 2025 --guidelines CLSI [--test-method MIC] [--pretty]
python scripts/breakpoint_query.py --organism 大肠埃希菌 --list-codes # 查看物种代码级别
- 无需数据文件（只查折点字典，随 skill 自带）
- 支持代码/英文名/中文名查询（
eco/Escherichia coli/大肠埃希菌） - 按 SUBKINGDOM→FAMILY→GENUS→SPECIES 多级别匹配，返回折点 S/I/R/SDD、参考表、药物中文名
--guidelines支持 CLSI/EUCAST/BSAC/DIN 等；默认--host Human
5. 天然耐药查询
python scripts/find_intrinsic_resistance.py kpn
python scripts/find_intrinsic_resistance.py 大肠埃希菌
- 无需数据文件（只查天然耐药字典）
- 返回 CLSI/EUCAST 双标准下各代码级别的固有耐药药物列表（含中文名）
6. 耐药模式计算
# 单物种-单类别
python scripts/compute_resistance_patterns.py --db <用户的解释库路径> --organism eco --class Aminoglycosides
# 单物种-Beta-lactams（自动合并 8 个子类别）
python scripts/compute_resistance_patterns.py --db <用户的解释库路径> --organism kpn --beta-lactams
--db必填（或环境变量WHONET_DB）- 结果存入 skill 目录
data/app.sqlite的resistance_patterns表（自动建表），可用--app-db覆盖 - 重要：物种匹配用
ORGANISM代码（勿用中文名——字典中同一代码可能有主名与亚种名两条）
环境变量（全部可选，用于覆盖默认）
| 变量 | 用途 |
|---|---|
WHONET_INPUT_DB |
AMRIE 解释的原始库路径（对应 -i） |
WHONET_DB |
解释库路径（对应 --db） |
WHONET_MD_DICT |
字典目录（默认 skill assets/md_dict/） |
WHONET_APP_DB |
耐药模式结果库（默认 skill data/app.sqlite） |
WHONET_OUTPUT |
耐药率 Excel 输出路径 |
WHONET_DRUG_MD |
药物字段字典 md 路径 |
常见问题与排错
Q1: 耐药率全为 0 或药敏列数量为 0？
- 确认
--db指向已解释库（原始库药敏列是数值，无 S/I/R） - 确认先运行了 AMRIE 解释（功能 1）
Q2: 报错"数据库文件不存在或未指定"？
- 所有分析功能（2/3/6）需要
--db指定解释库；解释功能（1）需要-i指定原始库 - 检查路径拼写与文件是否存在
Q3: 耐药模式返回 0 条？
- 检查物种代码是否正确（
--organism kpn而非中文名） - 确认解释库含该药物合并列（
SELECT AMK FROM Isolates LIMIT 1）
Q4: AMRIE 解释失败？
- 确认
dotnet可用（dotnet --list-runtimes需有 8.x） - 确认 skill 的
assets/AMRIE/bin/Debug/net8.0/存在（含 Interpretation CLI.dll、Interpretation Engine.dll、Resources/） - 查看
amrie_cli_last_run.log
Q5: 折点查询返回空？
- 确认物种代码/中文名在
Organisms_with_cn.txt中存在 - 确认年份与指南组合存在（如 eco + 2025 + CLSI 有效）
Q6: 中文编码问题？
- 所有脚本默认 UTF-8 读写；Windows 终端乱码时用
--output写文件查看
工作流程建议
- 询问使用者其 WHONET 数据文件路径（原始库或解释库）
- 首次使用先运行 AMRIE 解释（功能 1）生成解释库
- 根据需求选择对应功能脚本，所有数据路径参数传入使用者提供的路径
- 结果交付：Excel 用
present_files展示，JSON 整理成报告 - 若需修改折点标准（如换年份），重跑解释步骤 2/3 即可（步骤 1 可跳过复用已有 TSV）
