| 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
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 toolsnetwork_metrics.json for basic network statisticscitation_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
python scripts/init_run.py
This creates a new run folder:
outputs/runs/<timestamp>/
config.json
data/
outputs/
2) Prepare the citation CSV (minimal)
Create citations.csv and place it into:
outputs/runs/<timestamp>/data/citations.csv
Minimal CSV format:
source,target
Paper A,Paper B
Paper A,Paper C
Recommended DOI-based identifiers:
source,target
10.1234/abcd.1,10.1234/abcd.2
10.1234/abcd.1,10.1234/abcd.3
3) Confirm configuration
Open:
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
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:
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.
