IC50 分析技能

概述

面向细胞药理学实验的端到端 IC50 分析流程。输入一个含 OD 原始值的 Excel 文件，自动识别任意工作表中"空白组 / 对照组 / 各浓度组"的布局，当复孔数超过 3 个时进行统计异常值剔除（MAD 法为主、Grubbs 检验为辅），通过误差传递计算抑制率及其 SD，用四参数 Logistic（4PL）模型拟合出 IC50 与 95% 置信区间，并输出 Prism 风格的量效曲线图（300 dpi PNG）和规范的 Excel 结果工作簿。

使用场景

在以下情况触发本技能：

• 用户提供含 OD 值的 Excel 文件（来自 MTT、CCK-8、CellTiter-Glo 等细胞活性/增殖实验）
• 文件包含多个工作表（每个工作表代表一组实验：不同细胞系、不同处理时间或生物学重复）
• 典型布局：空白组 / 对照组 / 各浓度列，每浓度 3 个及以上复孔

使用方法

推荐方式：直接运行脚本

python scripts/ic50_analysis.py <输入文件.xlsx> [选项]

选项说明：

• --out 目录 — 输出目录（默认：输入文件同目录下的 ic50_output）
• --y {inhibition,survival} — 纵坐标模式：inhibition（抑制率，默认）或 survival（存活率）
• --unit nM|μM|mM|mg/mL — 手动指定浓度单位（默认：从表头自动识别）
• --dpi 300 — 图片分辨率（默认 300）
• --sheets 工作表1,工作表2 — 只处理指定工作表（默认：自动识别全部，疑似汇总/说明页自动跳过）

编程方式调用

脚本可被 import，scripts/ic50_analysis.py 中的关键入口：

• auto_layout(ws) — 从任意工作表布局自动识别空白/对照/浓度组
• select_replicates_robust(groups, concs_desc) — 统计异常值剔除（MAD + Grubbs）
• fit_ic50(concs, chosen, ctrl_mean, blank_mean, y_mode) — 4PL 拟合，输出 IC50 和 95% CI
• plot_curve(f, chosen, name, out_dir, y_mode, unit, ...) — Prism 风格量效曲线图

数据处理规则（必须遵守）

1. 自动识别布局：通过表头关键词（空白/blank、对照/ctrl/control、数字或数字+单位）识别空白组、对照组、浓度组。识别不确定时先向用户确认，绝不自行臆断。

2. 异常值剔除（仅当某浓度复孔数 > 3 时执行）：

   • 首选 MAD（中位数绝对偏差） 法，采用保守阈值 k=3.0
   • 当 MAD 未检出异常时，用 Grubbs 检验（α=0.05，单轮）复核
   • 剔除后剩余复孔全部参与均值计算，不强制减到 3 孔（否则就是"挑数据"）
   • 每个被剔除的孔必须报告：原始值、所用方法、剔除理由
   • 严格禁止：为了让量效曲线"更好看"而主观挑选或剔除复孔

3. 抑制率公式（y 轴为抑制率时）： 抑制率(%) = (对照均值 − 实验组均值) / (对照均值 − 空白均值) × 100 存活率模式：存活率(%) = 100 − 抑制率(%) 出现负值或超过 100% 属正常实验噪声，如实保留。

4. 四参数 Logistic 拟合模型： y = Bottom + (Top − Bottom) / (1 + 10^(HillSlope × (logIC50 − x)))，其中 x = log10(浓度) Bottom 固定为 0（药理惯例：低浓度端抑制率为 0）。 IC50 = 10^logIC50；95% 置信区间由参数协方差矩阵推导。

5. 科研严谨性判断（必须执行）：

   • 若最高浓度下最大抑制率 < 50%（未达到量效平台），IC50 不能可靠确定，如实报告"IC50 > 最高测试浓度（无法确定）"，不得外推。
   • 若拟合 R² < 0.5，标记拟合质量差，曲线仅作参考展示。

6. 输出文件命名：

   • 图片：IC50_curve_<工作表名>.png（自动清理非法字符）
   • Excel：IC50分析结果.xlsx（若原文件被预览占用，自动保存为 _new.xlsx）

输出规范

1. Excel 结果工作簿

每组实验一个工作表 + 一个汇总工作表。数据结构：

| 浓度(单位) | log10(浓度) | 复孔1 | 复孔2 | 复孔N | 均值 | SD | 抑制率(%) | 剔除的异常值(原始值/方法) |

复孔N 列为动态列（1 到全部浓度中最大的复孔数）。

每张数据表底部附：对照均值、空白均值、IC50、95% CI、R²、Bottom/Top/Hill 参数。

2. 量效曲线图（PNG，300 dpi）

• Prism 风格：深蓝填充数据点 + 黑色描边，浅蓝 SD 误差棒带帽
• 平滑 4PL 拟合曲线
• X 轴：log10(浓度, 单位)
• Y 轴：抑制率 (%)（或按 --y 参数显示 存活率 (%)）
• 图中央标注 IC50 与 95% CI（仅当结果可靠时）
• 拟合不可靠/质量差时显示警示框

3. 对话中返回汇总 Markdown 表格

| 实验/工作表 | IC50 (nM) | 95% CI 下限 | 95% CI 上限 | 最大抑制率(%) | R² | 备注 | |---|---|---|---|---|---|---|

触发关键词

以下任一关键词出现时使用本技能：

• IC50、IC-50、量效曲线、剂量效应曲线、dose-response
• 拟合 IC50、四参数Logistic、4PL
• MTT数据、CCK-8数据、CCK8数据、OD值、吸光度
• 细胞存活率、抑制率、cell viability、inhibition rate
• "帮我算IC50"、"我有一些 OD 值"、"I have OD values from..."

环境依赖

• Python 3.10+
• 依赖包：openpyxl、numpy、scipy、matplotlib
• WorkBuddy Windows 环境下的推荐安装方式（受管 venv）：

  "C:/Users/admin/.workbuddy/binaries/python/versions/3.13.12/python.exe" -m venv "C:/Users/admin/.workbuddy/binaries/python/envs/default"
  "C:/Users/admin/.workbuddy/binaries/python/envs/default/Scripts/python.exe" -m pip install openpyxl numpy scipy matplotlib
  

给未来 WorkBuddy 的注意事项

• 脚本会通过正则（汇总|总表|说明|^sheet1$）自动跳过疑似汇总/说明页。若合法数据表被误跳，可用 --sheets 名称 强制处理。
• 被 WorkBuddy 预览打开的 Excel 可能被锁定，脚本自动保存为 <名称>_new.xlsx 并提示。
• 脚本与浓度单位无关（支持 nM、μM、mM、mg/mL 等），从表头自动识别。
• 若用户提供 96 孔/384 孔酶标仪导出的原始文本，先转换为 Excel（每块板一个工作表）再调用本技能。