target-prioritization

靶点优先级排序

用于对基因列表进行排序的多源药物靶点尽职调查流程。

此技能的触发条件

用户提供了一份候选基因列表（通常来自 DE / DEG / scRNA-seq 分析），希望从多个证据维度为每个基因生成档案，并进行综合重新排序。DE 统计排名只是切入点；最终优先级还会参考蛋白质生物学、遗传学、成药性和研究成熟度。

常见输入格式：

• 包含 gene 列的 CSV（例如 DE 输出 expression_table_pass_either_1s.csv）
• 纯文本基因列表（每行一个符号）
• 用户消息中直接列出的符号

输出

在 <output_dir>/ 中生成四个文件：

1. targets_report.md — 每个基因对应一个章节，按综合得分排序，包含简短的 LLM 撰写理由和建议的后续步骤
2. targets_report.html — 自包含的交互式报告（可排序和搜索的摘要表、可按层级筛选的逐基因卡片、得分组成条形图、UniProt 链接）。在 Claude 填写理由栏和执行摘要后，作为最后一步根据 .md 和 .csv 生成。
3. targets_summary.csv — 便于在 Excel/pandas 中排序和筛选的扁平表格
4. raw_data/<source>.json — 原始 API 响应（审计记录，可在未来重新评分时复用）

流程

input gene list
   │
   ▼
scripts/orchestrate.py
   │
   ├─► fetch_uniprot.py        → protein localization, surface, MHC, coding
   ├─► fetch_opentargets.py    → tractability, approved drugs, associated
   │                              diseases (subsumes GWAS Catalog via OT's
   │                              integrated genetics evidence), DepMap CRISPR
   │                              essentiality, gnomAD LOEUF / pLI constraint
   ├─► fetch_pubmed.py         → paper counts (total + focus_disease + cell_context)
   ├─► fetch_hpa.py            → HPA tissue / single-cell specificity + nCPM,
   │                              expression cluster, cancer prognostics
   └─► fetch_chembl.py         → top-potency tool compounds per gene (pIC50,
                                  IC50 nM, mechanism) — dossier-only, no score
   │
   ▼
scripts/aggregate.py
   │
   ▼
output_dir/
  ├─ raw_data/*.json
  ├─ targets_summary.csv       ← composite-score-ranked
  └─ targets_report.md         ← Claude fills the rationale sections
   │
   ▼
scripts/build_html_report.py   ← run AFTER Claude fills rationales
   │
   ▼
output_dir/targets_report.html ← self-contained interactive report

调用方式

python3 ~/myagents/myskills/target-prioritization/scripts/orchestrate.py \
    --input <gene_list.csv_or_txt> \
    --output <output_dir> \
    [--gene-col gene] \
    [--top 50]

• --input 接受 CSV（通过 --gene-col 指定基因列，默认为 gene）、.txt/.tsv 文件，或第一列包含基因符号的任意文件。如果首个单元格为 gene/symbol（不区分大小写），则跳过表头。
• --top 将档案限制为输入基因中的前 N 个（默认为 50）——截取前保留输入顺序，然后在其中按综合得分重新排序。

orchestrate.py 会并行运行五个数据获取器（使用 Python 线程，因为所有调用均受 I/O 限制）。每个获取器都会将自包含的 JSON 写入 <output_dir>/raw_data/<source>.json。随后，aggregate.py 会合并这些文件，使用 weights.yaml 计算综合得分，写入 targets_summary.csv，并生成 targets_report.md 骨架，其中每个基因各有一个章节——理由和风险字段留空，供 Claude 填写。

综合得分

权重定义在 weights.yaml 中，可在每次运行时通过 --weights 覆盖。默认设置旨在“找出具有良好治疗窗、在目标细胞中表达且有遗传证据支持的可成药靶点”：

composite_score = w1 * druggability_score          (approved drugs, tractability, clin trials)
                + w2 * disease_genetics_score      (OpenTargets disease associations + focus-disease bonus)
                + w3 * tractability_bonus          (surface or secreted vs intracellular)
                + w4 * tissue_specificity          (HPA tissue tag — narrow expression = cleaner window)
                + w5 * cell_context_score          (HPA single-cell nCPM rank in FOCUS_CELL_TYPES)
                + w6 * essentiality_score          (DepMap CRISPR % essential, pan-essentials capped)
                + w7 * safety_constraint_score     (gnomAD LOEUF — high = LoF tolerated → safer to inhibit)
                + w8 * expression_score            (from input DE if present)
                + w9 * novelty_bonus               (favors moderately studied)
                - w10 * over_studied_penalty       (PubMed total > cap → diminishing returns)

ChEMBL 会提供档案列（chembl_target_id、chembl_best_pchembl、chembl_best_ic50_nm、chembl_top_compounds），但不参与得分计算——其作用是提供具体的工具化合物，供“建议的后续步骤”栏使用。

每个组成部分都会归一化到 [0, 1]。因此，综合得分大致位于 [-w7, sum(w1..w6)]，并会在报告前进行最小-最大缩放。请阅读 weights.yaml 了解当前默认值。

撰写理由

aggregate.py 生成带有空白理由栏的 targets_report.md 后，Claude 会读取逐基因档案行，并为每个基因撰写 2-3 句话的理由。请使用 prompts/rationale_template.md 中的模板——其中规定了结构（用一句话说明最有说服力的证据，用一句话说明主要风险，再用一句话说明建议的下一步实验）。

对于综合得分最高的前 5–10 个基因，还要在报告开头撰写一段简短的执行摘要。内容应客观，并以档案数据为依据；不要编造 JSON 中没有的信息。

构建 HTML 报告（最后一步）

在 targets_report.md 填写好理由栏和执行摘要后，运行 build_html_report.py，生成自包含的交互式 HTML 报告：

python3 ~/myagents/myskills/target-prioritization/scripts/build_html_report.py \
    --report-dir <output_dir> \
    [--title "Target Prioritization Report"] \
    [--subtitle "<cohort / contrast description>"]

这始终是最后一步。该脚本从 --report-dir 读取 targets_summary.csv 和 targets_report.md，并在同一目录下写入 targets_report.html。输出是单个文件，不依赖任何外部内容：顶部有可排序的摘要表、实时搜索和分层筛选按钮、每个基因对应一张卡片（含表面 / 分泌 / MHC / 重点疾病 / 已获批药物标签）、完整的档案网格，以及每个评分组成项对应的横向条形图。直接在浏览器中打开即可，也可以原样分享。

如果运行时理由栏仍为空，每个基因卡片对应的位置会显示“尚未填写”——这有助于预览布局，但应告知用户，在分享前填写理由。

数据来源说明

全部免费，无需 API 密钥。抓取器会处理速率限制：

• UniProt REST — 每秒 100 个请求，通过 accession 查询批量获取
• OpenTargets GraphQL — 限制宽松，使用单一端点；通过集成的 associatedDiseases 提供疾病遗传学信号
• PubMed E-utilities — 不使用密钥时每秒 3 个请求；抓取器会遵守此限制
• Human Protein Atlas — 使用 search_download.php 将符号映射到 ENSG，然后逐个获取 /<ENSG>.json；未记录速率限制，抓取器每个基因休眠 0.15 秒
• DepMap CRISPR essentiality — 通过 OpenTargets 调用中的 target.depMapEssentiality 获取（无单独端点）
• gnomAD constraint — 通过 OpenTargets 调用中的 target.geneticConstraint 获取（避免 gnomAD 在直接 API 访问时的 WAF 限制）
• ChEMBL REST — 先调用 target/search.json，再调用 activity.json；友好速率约为每秒 5 个请求，抓取器每个基因休眠 0.2 秒

如需了解更深入的 API 详情和字段映射，请参阅 references/api_endpoints.md。

更改重点疾病和细胞背景

此技能默认聚焦自身免疫和 T 细胞，但有意设计为不依赖特定疾病。修改三处即可切换重点：

• scripts/fetch_opentargets.py 和 scripts/aggregate.py — 将 FOCUS_DISEASE_TERMS 改为应将药物或疾病关联标记为“范围内”的小写子字符串（例如，肿瘤学可用 ("cancer", "carcinoma", "lymphoma")；神经退行性疾病可用 ("alzheimer", "parkinson", "huntington", "als")；代谢疾病可用 ("diabetes", "obesity", "fatty liver", "nash")）。
• scripts/aggregate.py — 将 FOCUS_CELL_TYPES 改为用于计算 cell_context_score 的 HPA 单细胞类型名称。必须与 HPA 中的字符串完全一致（区分大小写）；各领域示例见元组上方的注释块。
• scripts/fetch_pubmed.py — 调整 CONTEXTS 中的 focus_disease 和 cell_context 查询（这些查询用于档案中的 PubMed 计数）。

无需更改其他代码；CSV 列名已使用通用的 focus_disease_* / cell_context 前缀。

不适用此技能的情况

• 单基因查询（大材小用——直接让 Claude 网页搜索即可）
• 非人类基因（大多数 API 仅支持人类基因；抓取器会静默返回空结果）
• 不以寻找靶点为目标的纯文献综述——请改用 scholar-deep-research 或 literature-review

迭代提示

此流程设计为可低成本重复运行：

• 原始 JSON 缓存意味着使用不同的 weights.yaml 重新评分时，只需一秒钟即可重新运行 aggregate.py
• 要添加新的证据来源，请添加 scripts/fetch_<source>.py，使其以相同的 {gene: {fields}} 结构写入 raw_data/<source>.json，然后在 aggregate.py::compute_composite_score 中添加对应项。