academic-subway

---
name: academic-subway
description: Produce a one-page subway-map-style academic-trajectory PDF for a researcher. Resolves the author on OpenAlex, analyzes career stations (institutions by year) and research threads (topic clusters over time), hand-writes a one-paragraph narrative, and compiles a LaTeX-embedded PNG. Input is either a researcher name (optionally with an affiliation hint) or a paper reconstruction directory from which the author can be extracted.
---

# academic-subway

End-to-end: resolve researcher → fetch OpenAlex data → design subway map (stations + threads) → render PNG → write paragraph → compile one-page PDF → open.

The format: a horizontal "career track" with institutional stations, research threads as colored branch lines above/below, and a single paragraph narrative below the map.

## Arguments

- `<name>` — researcher name (e.g., "Yue Mei", "Madhavan L. Raghavan")
- or `<paper context>` — paper reconstruction directory or DOI, from which the user nominates an author
- `--affiliation <aff>` (optional) — institution substring for disambiguation (e.g., "Dalian", "Iowa")
- `--out <dir>` (optional) — where to write the PDF (defaults to current directory)

## Pipeline

### Step 0 — Parse input

Determine if the input is a raw name or a paper context. For a paper context, read the author list and ask the user which author to profile (default = first / corresponding author).

### Step 1 — Resolve author

```bash
python3 ~/.claude/skills/academic-subway/helpers/fetch_author.py "<name>" \
  --affiliation "<aff>" \
  --out-dir /tmp/<stem>_trajectory
```

The helper searches OpenAlex, scores candidates by name + affiliation + works count, and writes `author.json` + `works.json` to the output dir. It prints candidate list to stderr for sanity-checking. If the top candidate has few works or the affiliation doesn't match, re-run with a different `--affiliation` or pick a candidate manually by reading the stderr output and calling the OpenAlex author endpoint directly.

### Step 2 — Analyze career structure

Read `author.json` and `works.json`. Determine:

1. **Career stations** — institutional affiliations by year. Consolidate "visit" affiliations vs "home" affiliations by frequency. Typical: 2–4 major stations spanning the career.
2. **Top coauthors** — Counter over all works. Group by inferred academic family (PhD advisor institution, postdoc group, current faculty home, external collaborators).
3. **Research threads** — topic clusters (from `topics[0].display_name`) grouped into semantically meaningful buckets. Typically 3–5 threads, some terminated, some continuing.
4. **Disambiguation check** — are all the works actually this person? Filter obvious outliers (wrong field, wrong institution cluster).

### Step 3 — Write the subway-map config

Hand-write a JSON config that reflects the career shape. Example structure:

```json
{
  "title": "RESEARCHER NAME",
  "subtitle": "Academic Trajectory — subway-map view",
  "year_range": [1995, 2026],
  "stations": [
    {"label": "University X", "year": 1998, "sub": "w/ Advisor (PhD)"},
    {"label": "University Y\n(arrives 2001)", "year": 2005, "sub": "faculty"}
  ],
  "threads": [
    {"name": "Main research line", "color": "#c45b4e", "y": 1.4,
     "start": 1995, "end": 2026, "from_station": 0},
    {"name": "Secondary thread", "color": "#4e8bc4", "y": -1.4,
     "start": 2005, "end": 2026, "from_station": 1}
  ],
  "floating": [
    {"name": "External collaboration", "color": "#8b5fbf", "y": 2.8,
     "start": 2017, "end": 2026, "connect_station": 1,
     "note": "(parallel France arm)"}
  ]
}
```

Colors should be distinguishable and muted (no neon). Terminated threads end before the final year (e.g., `end: 2014` when map ends in 2026); continuing threads end at the final year. The renderer automatically marks terminated threads with an X and continuing ones with an arrow.

### Step 4 — Render map

```bash
python3 ~/.claude/skills/academic-subway/helpers/render_subway_map.py \
  /tmp/<stem>_trajectory/config.json \
  /tmp/<stem>_trajectory/subway_map.png
```

### Step 5 — Write the narrative paragraph

Hand-write a single ~150-200 word paragraph describing the arc. Structure: early-career origins, PhD institution/advisor, the big methodological pivot, faculty move, current phase, recent trajectory. Be specific — name advisors, institutions, collaborators. Keep it narrative prose, not bullet points.

### Step 6 — Compile LaTeX → PDF

Write a minimal one-page LaTeX file with the PNG + paragraph + small caveat footer (ORCID, h-index, citations, disambiguation notes). Compile with `pdflatex`. Output: `<out>/<stem>_subway.pdf`.

### Step 7 — Open with Evince

```bash
evince <out>/<stem>_subway.pdf &
```

Print to terminal: a one-sentence summary of the researcher's profile.

## Resources

- `helpers/fetch_author.py` — OpenAlex lookup with scoring + disambiguation
- `helpers/render_subway_map.py` — JSON-config-driven matplotlib subway map

## Do-not-touch rules

- Narrative paragraph is always hand-written by the invoking AI. Do NOT template it.
- Subway-map config (stations, threads, colors) is hand-designed per researcher — the shape reflects their career, not a one-size-fits-all layout.
- Respect OpenAlex rate limits: one sequential author fetch per invocation is fine; don't batch fetch many authors at once.

## Prior-art examples

- Wei paper author: `suresh papers/yue_mei_subway.pdf`
- Raghavan: `suresh papers/raghavan_subway.pdf`