shield_lock
JinDaGe
← Back to skills
extension
Category: Data & AnalyticsNo API key required

whonet分析助手

WHONET 细菌耐药监测数据分析工具集。读取用户提供的 WHONET SQLite 数据库（database.sqlite / database_interpreted.sqlite），执行完整分析链路：AMRIE 药敏解释、物种耐药率统计与趋势（Excel/JSON）、CLSI/EUCAST 折点查询、细菌固有耐药查询、耐药表型模式计算。当用户需要分析 WHONET 数据、计算耐药率、查询药敏折点、查看天然耐药、识别耐药模式或处理微生物药敏试验数据时触发此 skill。用户须提供自己的 WHONET 数据文件路径。

personAuthor: user_5510a507hubcommunity
downloadDownload package

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 引擎安装」）。

  1. 耐药模式计算 — 物种-药物类别组合的耐药表型模式（如 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 写文件查看

工作流程建议

  1. 询问使用者其 WHONET 数据文件路径（原始库或解释库）
  2. 首次使用先运行 AMRIE 解释（功能 1）生成解释库
  3. 根据需求选择对应功能脚本，所有数据路径参数传入使用者提供的路径
  4. 结果交付：Excel 用 present_files 展示，JSON 整理成报告
  5. 若需修改折点标准（如换年份），重跑解释步骤 2/3 即可（步骤 1 可跳过复用已有 TSV）