Citation Network

---
name: citation-network
description: Build and visualize a citation network from a source/target CSV to identify key papers, communities, and emerging hotspots; use when you have citation pairs and need fast literature review or trend analysis.
license: MIT
author: AIPOCH
---
> **Source**: [https://github.com/aipoch/medical-research-skills](https://github.com/aipoch/medical-research-skills)


## When to Use

- You have a citation relationship table (who cites whom) and want to quickly turn it into a directed network for analysis.
- You are conducting a literature review and need to identify influential papers (high in-degree / centrality) and core clusters.
- You want to detect community structures (research subfields) and compare them across time or datasets.
- You need an interactive, shareable visualization (HTML) or a Gephi-importable graph file (GEXF).
- You are positioning a new project and want evidence of research hotspots and bridging papers between communities.

## Key Features

- Builds a directed citation graph from a minimal CSV containing `source` and `target`.
- De-duplicates nodes by identifier (DOI recommended; otherwise unique titles).
- Exports:
  - `citation_network.gexf` for Gephi and other graph tools
  - `network_metrics.json` for basic network statistics
  - `citation_network.html` for interactive browser viewing (auto-generated by the build script)
- Run-directory workflow to keep each execution reproducible and isolated under `outputs/runs/<timestamp>/`.
- Optional input encoding control to avoid garbled characters (e.g., UTF-8 / UTF-8-SIG).

## Dependencies

- Python 3.10+
- pandas >= 2.0
- networkx >= 3.0
- (Optional, for HTML visualization) pyvis >= 0.3

## Example Usage

### 1) Initialize a run directory

```bash
python scripts/init_run.py
```

This creates a new run folder:

```text
outputs/runs/<timestamp>/
  config.json
  data/
  outputs/
```

### 2) Prepare the citation CSV (minimal)

Create `citations.csv` and place it into:

```text
outputs/runs/<timestamp>/data/citations.csv
```

Minimal CSV format:

```csv
source,target
Paper A,Paper B
Paper A,Paper C
```

Recommended DOI-based identifiers:

```csv
source,target
10.1234/abcd.1,10.1234/abcd.2
10.1234/abcd.1,10.1234/abcd.3
```

### 3) Confirm configuration

Open:

```text
outputs/runs/<timestamp>/config.json
```

Ensure the configured input filename and column names match your CSV (at minimum `source` and `target`). If you see garbled characters, set an explicit encoding (e.g., `utf-8` or `utf-8-sig`) via an `input_encoding` field if supported by the config.

### 4) Build the citation network

```bash
python scripts/build_citation_network.py
```

The build script will also generate the HTML automatically (you do not need to run `scripts/export_gexf_html.py` manually).

### 5) Inspect outputs

Expected outputs under the same run directory:

- `citation_network.gexf` (import into Gephi)
- `network_metrics.json` (node/edge counts, density, etc.)
- `citation_network.html` (open in a browser)

## Implementation Details

### Data Model

- **Nodes**: papers, identified by the value in `source`/`target` (DOI preferred; otherwise a unique, consistent title string).
- **Edges**: directed citations `source -> target`.

### Input Requirements and Constraints

- The network builder reads **only** the `source` and `target` columns.
- Additional columns (e.g., author/year/venue) are ignored by the current scripts.
- If you need metadata, maintain a separate table for downstream joining/annotation (not consumed by the builder), for example:

```csv
id,title,authors,year,doi
10.1234/abcd.1,Paper A,"Zhang, Wei; Li, Ming",2021,10.1234/abcd.1
10.1234/abcd.2,Paper B,"Wang, Fang",2019,10.1234/abcd.2
```

### Run Directory Standard

- Always run `python scripts/init_run.py` before an execution to create a new run directory.
- All inputs, configs, and outputs must remain inside `outputs/runs/<timestamp>/`.
- By default, scripts operate on the latest run directory under `outputs/runs/`.

### Metrics and Analysis (Conceptual)

- Basic network statistics are exported to `network_metrics.json` (e.g., node/edge counts, density).
- Typical downstream analyses include:
  - centrality (degree, betweenness)
  - community detection (e.g., Louvain), if enabled/implemented in the pipeline

### Common Failure Modes

- **Garbled characters**: ensure CSV is UTF-8/UTF-8-SIG; set `input_encoding` in `config.json` if available.
- **Duplicate nodes**: identical identifiers are treated as the same node; prefer DOIs or enforce unique titles.
- **Empty or missing output**: verify the CSV header names match the configured `source`/`target` columns.

### Related References

- Data cleaning checklist: `references/data-cleaning-checklist.md`
- Network metrics notes: `references/network-metrics-notes.md`
- Additional documentation: `references/README.md`

## When Not to Use

- Do not proceed when required input files, identifiers, parameters, or context are missing — ask the user to provide them first.
- Do not assume capabilities beyond this skill's declared scope when the user requests external operations or inferences.
- Do not proceed without user confirmation when overwriting existing results, executing high-cost batch operations, or expanding task scope.

## Required Inputs

| Field | Required | Format/Source | Example | If Missing |
|---|---|---|---|---|
| User task description | Yes | Text | Research question, writing goal, analysis objective | Stop and ask user to provide |
| Primary input material | Depends on task | Text, file path, ID, table, or literature | PMID, PDF, CSV, DOCX, keywords, etc. | Specify which material type is missing |
| Output preference | No | Text | Language, format, target journal, template | Use skill default format |

## Output Contract

- Primary output: Structured result or target file aligned with this skill's objective.
- Optional output: Intermediate check notes, issue list, supplementary suggestions, or generated file paths.
- Format requirement: Unless the user specifies otherwise, prefer stable, reviewable Markdown or JSON; if the skill's bundled script requires a fixed format, use that format.
- If partially complete: Must explicitly mark as PARTIAL and state which steps are completed and which remain.

## Failure Handling

- Missing critical input: Explicitly state which fields, files, or identifiers are missing and pause.
- Script, template, or resource execution failure: Report the failing step, likely cause, and recovery suggestions — do not silently degrade.
- Partial completion only: Return the verified portion first, then list remaining blockers and suggested next steps.

## User Checkpoints

- Before executing batch processing, overwriting files, long-running searches, or multi-stage generation, confirm scope and output format with the user.
- Before proceeding when a key judgment is ambiguous, evidence is insufficient, or the workflow is entering the next stage, confirm with the user.


## Input Validation

This skill accepts requests that match the documented purpose of `citation-network` and include enough context to complete the workflow safely.

Do not continue the workflow when the request is out of scope, missing a critical input, or would require unsupported assumptions. Instead respond:

> `citation-network` only handles its documented workflow. Please provide the missing required inputs or switch to a more suitable skill.

## Quick Validation

- Check that key scripts, templates, or reference file paths this skill depends on exist.
- Check that the final output contains the core fields, sections, or files specified for this task.
- Check that results clearly mark assumptions, limitations, and incomplete items.