alterlab-citation-graph

引文图谱 — 免费的 ResearchRabbit 替代方案

概述

ResearchRabbit 和 Connected Papers 的免费、无订阅替代方案。提供一个 种子 DOI（或多个种子），此技能会沿着 OpenAlex 引文网络向外双向扩展，并构建本地文献的引文／共引图谱：

• 后向边 — 每篇种子论文引用的作品（其 referenced_works）。
• 前向边 — 引用每篇种子论文的作品（其 cited_by 集合）。

随后，它会按共引强度为发现的邻域排序——候选作品通过共享参考文献、共享引证作品和直接种子链接与种子论文相连的数量——从而找出该主题中最核心的论文，就像 ResearchRabbit 的“Similar Work”面板一样。整个图谱会导出为 GraphML（可在 Gephi、Cytoscape、yEd 或 networkx 中打开）和 JSON（供下游代码使用）。

OpenAlex 数据是开放的（CC0），对于此类规模的使用，其 API 免费；但从 2026 年 2 月起，请求会计入每日额度，旧的 mailto“礼貌池”也已取消。无密钥调用共享每天 $0.10 的额度，按 IP 地址计算——在校园或云网络中，该额度通常早已用完，因此会出现 HTTP 429。免费 API 密钥（OPENALEX_API_KEY，可从 openalex.org/settings/api 获取）可为你提供每天 $1 的额度。一次典型的遍历只需花费不到一美分：种子查询免费，每次列表／筛选调用费用为 $0.0001。

何时使用此技能

• 绘制文献领域图谱：从一篇起始论文出发——“我有一篇关键论文，展示一下它周边的领域。”
• 查找开创性／高共引论文，无需手动追踪参考文献。
• 为综述滚雪球式扩展参考文献网络（沿前向和后向引文追踪）。
• 构建引文图谱或进行共引分析，用于方法／可视化图。
• 可视化研究领域之间的联系——导出到 Gephi／Cytoscape，以制作网络图。

这是用于构建图谱／发现文献的工具；需要从一篇种子作品开始遍历。

不适用场景

场景	改用
没有种子论文的自由文本研究问题	alterlab-research-lookup
检查每条参考文献是否存在／找出疑似虚构或已撤稿的引用	alterlab-citation-verifier
查询 OpenAlex 中的作品、作者、机构或文献计量趋势（不构建图谱）	alterlab-openalex
使用 PRISMA 筛选和偏倚风险评估进行系统综述	alterlab-literature-review
对你自己的（非引文）关系数据进行中心性或社群分析	alterlab-sna

快速开始

export OPENALEX_API_KEY=...   # free at openalex.org/settings/api; recommended

# One seed DOI, default 1-hop walk, write both formats next to a basename:
uv run python scripts/build_graph.py \
    --seed 10.1038/nphys1170 \
    --out graph/seed1
# -> graph/seed1.graphml  +  graph/seed1.json

# Several seeds (DOI / OpenAlex W-id / arXiv id), deeper walk, larger ranking:
uv run python scripts/build_graph.py \
    --seed 10.1038/nphys1170 \
    --seed W2741809807 \
    --seed arXiv:2310.06825 \
    --depth 2 --per-seed 50 --top 40 \
    --out graph/transformer

# Offline smoke test (no network) — verifies the pipeline end-to-end:
uv run python scripts/build_graph.py --self-test

工作原理

1. 解析种子。 每个 --seed 都会规范化为 OpenAlex 选择器。接受的格式包括： 裸 DOI（10.1038/nphys1170）、DOI URL、OpenAlex 作品 ID（W2741809807）、OpenAlex URL，或 arXiv ID（arXiv:1706.03762／1706.03762）。
2. 向后扩展。 从每个种子的 referenced_works 中添加 seed -> reference 边。
3. 向前扩展。 查询 filter=cites:<id>，查找引用种子的作品，并添加 citer -> seed 边（上限为 --per-seed；OpenAlex 每页最多返回 100 条）。
4. 深入遍历。 使用 --depth N 时，对第一跳邻居重复扩展（N >= 2）。
5. 按共引排序。 每个非种子节点的得分为 shared_refs + shared_citers + direct_seed_links——即相对于种子集的文献耦合和共引强度；并以全局 cited_by_count 作为平分时的依据，使经典作品排在前面。
6. 补全信息。 参考文献以裸 W-ID 的形式返回，因此会通过批量 filter=openalex:W…|W… 调用获取排序后作品的标题、年份和 DOI（每次调用 100 个 ID），然后重新排列结果表。
7. 导出。 写入 <out>.graphml 和 <out>.json。

选项

标志	默认值	含义
--seed（可重复指定）	—	种子 DOI、OpenAlex W-id 或 arXiv id。至少需要一个。
--api-key	$OPENALEX_API_KEY	免费的 OpenAlex 密钥，通过 Bearer 请求头发送。建议使用环境变量（避免密钥出现在 shell 历史记录中）。
--mailto	—	已弃用的无操作选项；OpenAlex 自 2026 年 2 月起不再处理 mailto。
--depth	1	要扩展的引用跳数。
--per-seed	25	每篇作品最多获取的引用作品数（OpenAlex 上限为 100）。
--top	25	共引排名表的大小。
--out	citation_graph	输出文件名基准；生成 <out>.graphml 和 <out>.json。
--sleep	0.0	API 调用间隔秒数（OpenAlex 允许每秒最多 100 次请求）。
--self-test	—	运行离线自测并退出（不联网）。

输出

GraphML（<out>.graphml）——有向图，节点属性包括 title、year、 doi、role（seed / reference / citation / neighbor）和 cited_by_count。可直接在 Gephi、Cytoscape、yEd 或 networkx.read_graphml 中打开。

JSON（<out>.json）——架构为 alterlab-citation-graph/1.0：

{
  "schema": "alterlab-citation-graph/1.0",
  "seeds": ["10.1038/nphys1170"],
  "node_count": 142,
  "edge_count": 318,
  "nodes": [ { "id": "W…", "title": "…", "year": 2017, "doi": "…", "role": "citation", "cited_by_count": 8123 } ],
  "edges": [ { "source": "W…", "target": "W…" } ],
  "cocitation_ranking": [
    { "id": "W…", "title": "…", "cocitation": 4, "shared_refs": 2,
      "shared_citers": 1, "direct_seed_links": 1, "cited_by_count": 8123 }
  ]
}

访问与限制

• 使用免费密钥。 请用户设置 OPENALEX_API_KEY（openalex.org/settings/api），而不要将密钥粘贴到聊天中或提交到文件中。没有密钥时，只要共享的每 IP 额度尚有余量，运行仍可正常进行，脚本会打印提示。
• HTTP 429 表示当日额度已用完（于 UTC 午夜重置），或运行超过每秒 100 次请求。脚本会报出明确错误并停止，而不会生成被静默截断的图；请添加密钥或稍后重试。
• 限制遍历范围。 使用较大的 --per-seed 配合 --depth 2 会迅速扩展（每个前沿作品都会调用一次列表接口）；请将 --per-seed 设为合理值，遇到速率限制时调高 --sleep。
• 覆盖范围说明。 OpenAlex 的引用覆盖范围广泛，但并不完美；非常新的预印本可能只有稀疏的 cited_by 集合。
• arXiv 种子。 arXiv:<id> 种子会通过其 DataCite DOI（10.48550/arXiv.<id>）解析。如果预印本后来并入已发表版本的记录，OpenAlex 可能只保留出版商 DOI；此时请改用该 DOI 作为种子。

配套工具

任务	工具
将从排名中选出的论文添加到 Zotero（DOI → 条目、分类集）	alterlab-pyzotero
检查稿件中的链接和 DOI 是否正常	alterlab-link-health
使用 Gephi 默认设置之外的方式绘制网络图或调整样式	alterlab-networkx

AlterLab Academic Skills 套件的一部分。