WhoCitesMe

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 24 Open GitHub ↗

Find the bigshots who cite me

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">WhoCitesMe</h1>

Discover who cited your papers, find prominent researchers among your citers, and understand how your work is perceived.

<a href="#quick-start">Quick Start</a> •
 <a href="#features">Features</a> •
 <a href="#how-it-works">How It Works</a> •
 <a href="#中文说明">中文说明</a>

---

## What It Does

You published papers. People cited them. But **who** are these people, and **what** did they say?

WhoCitesMe answers this automatically:

```
Your Papers → Semantic Scholar → LLM Analysis → Structured Excel Report
```

## Features

| | Feature | Description |
|---|---------|-------------|
| 🔍 | **Full citation scan** | Fetches ALL citations via Semantic Scholar, not just top-N |
| 👤 | **PI identification** | Identifies the senior/corresponding author (last author = PI) |
| 🏅 | **Title detection** | Two-phase: local name matching + LLM batch identification |
| 📊 | **4-sheet Excel report** | All citations, notable citations, paper summary, PI directory |
| ✓ | **Fellow/Academician stats** | IEEE, ACM, SIAM Fellows; NAE, NAS, CAS, FRS, etc. |
| 💾 | **Resume-safe** | Aggressive caching — safe to interrupt and re-run anytime |

## Quick Start

### 1. Install

```bash
git clone https://github.com/tarpelite/WhoCitesMe.git
cd WhoCitesMe
pip install -r requirements.txt
```

### 2. Configure

```bash
cp config.example.yaml config.yaml
cp papers.example.yaml papers.yaml
```

Edit `config.yaml` — add your LLM API key:

```yaml
llm_api_key: "sk-your-deepseek-key"  # https://platform.deepseek.com
```

Edit `papers.yaml` — add your papers:

```yaml
- title: "My Paper Title As It Appears on Semantic Scholar"
  short_name: "ShortName"
  venue: "ICML 2025"
  year: 2025
  arxiv_id: "2401.12345"  # optional, faster lookup
```

### 3. Run

```bash
# Full pipeline
python scout.py --step all

# Or step-by-step (recommended for first run)
python scout.py --step fetch                       # Free (S2 API only)
python scout.py --step identify --h-threshold 25   # Cheap (~3 LLM calls)
python scout.py --step analyze                     # Main cost
python scout.py --step report                      # Free (local)
```

### 4. Check results

Open `outputs/citation_report.xlsx`:

| Sheet | What's in it |
|-------|-------------|
| **All Citations** | Every citation with PI, scores, quotes, color-coded by importance |
| **Notable Citations** | Filtered to prominent researchers, sorted by h-index |
| **Paper Summary** | Per-paper stats: total, notable, positive, baseline counts |
| **PI Directory** | Deduplicated author list with Fellow/Academician ✓ checkmarks |

## How It Works

```
FETCH (free)              IDENTIFY (cheap)         ANALYZE (main cost)       REPORT (free)
┌──────────────┐         ┌──────────────┐         ┌──────────────┐         ┌──────────────┐
│ Semantic      │         │ Build PI     │         │ Notable cites│         │ 4-sheet      │
│ Scholar API   │────────▶│ registry     │────────▶│ analyzed     │────────▶│ Excel report │
│               │         │              │         │ first        │         │              │
│ • Find papers │         │ • Filter     │         │              │         │ • Color-coded│
│ • Fetch ALL   │         │   h≥25       │         │ • Then top-N │         │   citations  │
│   citations   │         │ • LLM batch  │         │   normal     │         │ • PI         │
│ • Match known │         │   query      │         │ • Extract    │         │   directory  │
│   bigshots    │         │   titles     │         │   quotes &   │         │   with title │
│ • Enrich PIs  │         │ • Auto-tag   │         │   summaries  │         │   checkmarks │
│   (dedup)     │         │   new ones   │         │              │         │              │
└──────────────┘         └──────────────┘         └──────────────┘         └──────────────┘
      ↓                        ↓                        ↓                       ↓
  data/s2_cache/          data/pi_titles.json      data/results.json      outputs/*.xlsx
```

### Two-phase bigshot detection

**Phase 1 — Local matching (0 API calls):** Checks all author names against your `bigshots.yaml`. Instant.

**Phase 2 — LLM identification:** Sends high h-index authors (h ≥ 25 by default) to the LLM to determine if they're Fellows or academicians. Results are cached in `data/pi_titles.json`.

## Cost Estimate

| Step | API | Cost per 300 citations |
|------|-----|----------------------|
| fetch | Semantic Scholar | Free |
| identify | LLM (DeepSeek) | ~$0.01 |
| analyze | LLM (DeepSeek) | ~$0.10 |
| report | None | Free |

**Total: < $0.15 with DeepSeek** for a typical researcher's full publication list.

## Configuration

### config.yaml

| Key | Default | Description |
|-----|---------|-------------|
| `llm_api_key` | — | Any OpenAI-compatible API key |
| `llm_base_url` | `https://api.deepseek.com/v1` | API endpoint |
| `llm_model` | `deepseek-chat` | Model name |
| `s2_api_key` | *(empty)* | [Semantic Scholar key](https://www.semanticscholar.org/product/api) (optional) |
| `max_citations_per_paper` | 500 | Max citations to fetch |
| `top_n_analyze` | 30 | Non-notable citations to analyze per paper |
| `h_threshold` | 25 | h-index cutoff for title identification |

### Environment variables

```bash
export LLM_API_KEY="sk-..."       # or DEEPSEEK_API_KEY
export S2_API_KEY="..."            # optional
```

### Adding known researchers

Edit `bigshots.yaml` to pre-register researchers for instant matching:

```yaml
"some famous professor":
  zh_name: "Display Name"
  titles: ["IEEE Fellow", "Stanford Professor"]
  institution: "Stanford University"
  gs_h_approx: 80
```

## FAQ

<details>
<summary>Can I use OpenAI / Claude / local LLMs?</summary>

Yes. Set `llm_base_url` and `llm_model` in config.yaml to any OpenAI-compatible endpoint. For example, Ollama: `http://localhost:11434/v1`.
</details>

<details>
<summary>The script was interrupted. Did I lose data?</summary>

No. Everything is cached in `data/`. Re-run the same command to resume from where it stopped.
</details>

<details>
<summary>My field uses first-author-as-PI convention.</summary>

The current implementation assumes last author = PI (standard in CS/ML/AI). For other conventions, modify `tag_bigshots_local()` and `enrich_senior_author()`.
</details>

<details>
<summary>Can I analyze more than 500 citations per paper?</summary>

Yes, increase `max_citations_per_paper` in config.yaml. Semantic Scholar returns up to 10,000.
</details>

---

## 中文说明

### 这个工具做什么？

你发了论文，别人引用了你。但是——

- **谁** 引用了你？是普通学生还是领域大佬？
- **怎么** 引用的？正面评价、当baseline、还是综述顺带一提？
- 引用你的人里有多少 **IEEE Fellow**、多少 **院士**？

WhoCitesMe 自动回答以上问题，生成结构化 Excel 报告。

### 快速开始

```bash
git clone https://github.com/tarpelite/WhoCitesMe.git
cd WhoCitesMe
pip install -r requirements.txt

cp config.example.yaml config.yaml    # 填入 DeepSeek API key
cp papers.example.yaml papers.yaml    # 填入你的论文

python scout.py --step all
```

### 输出

`outputs/citation_report.xlsx`，包含 4 个 Sheet：

| Sheet | 内容 |
|-------|------|
| All Citations | 全部引用，含PI识别、评分、引用原文，按重要性颜色标注 |
| Notable Citations | 筛选出知名学者的引用，按h-index排序 |
| Paper Summary | 按论文汇总统计 |
| PI Directory | 去重的PI名录，Fellow / 院士打 ✓ |

### 费用

使用 DeepSeek API，分析 300 条引用不到 ¥1。

### 常见问题

**Q: 支持中文论文吗？**

Semantic Scholar 收录的论文都支持。纯中文期刊论文如果不在 S2 索引中可能无法找到。

**Q: 可以用其他大模型吗？**

可以。修改 `config.yaml` 里的 `llm_base_url` 和 `llm_model`，任何兼容 OpenAI 格式的接口都行（OpenAI、Claude、本地 Ollama 等）。

**Q: 中途断了怎么办？**

不丢数据。所有中间结果缓存在 `data/` 目录，重新运行自动跳过已完成步骤。

---

## Star History

[![Star History Chart](https://api.star-history.com/image?repos=tarpelite/WhoCitesMe&type=date&legend=top-left)](https://www.star-history.com/?repos=tarpelite%2FWhoCitesMe&type=date&legend=top-left)

## Contributing

Contributions are welcome! Feel free to open an issue or submit a PR.

## License

[MIT](LICENSE)

## Acknowledgments

- [Semantic Scholar API](https://www.semanticscholar.org/product/api) for citation data
- [DeepSeek](https://platform.deepseek.com) for affordable LLM API

---

WhoCitesMe

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README